fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/contracts/rev002-billing-contract.md

Contract: REV-002 开账计费与账单生成缺口补齐

1. Formal Interface Allocation

Interface	Role	Direction
IF-REV-005	REV-002 开账计费与账单生成的正式业务接口	SYS-002 内部正式业务接口

约束：

• IF-REV-005 保持为 REV-002 的正式账单生成接口编号，不新增新的开账生成接口编号。
• 本接口只承接开账计费与账单生成，不扩展到收费核销、发票申请或催缴触发。

2. Request Contract

Field	Meaning	Required
billPeriod	账期	是
readingBatchNo	抄表批次号	否
customerIds	客户集合	否
meterReadIds	抄表任务集合	否
dueDate	应收截止日期	是
operatorId	发起人	否

补充约束：

• 请求前提是抄表数据已通过校验或异常复核允许进入开账。
• 至少应提供批次、客户范围或抄表任务范围中的一种有效筛选条件。

3. Response Contract

Field	Meaning
generateCount	成功生成账单数量
successList	成功明细集合
successList[].chargeId	账单主键
successList[].chargeCode	账单编号
successList[].custId	客户标识
successList[].totalAmount	账单总金额
failureList	失败明细集合
failureList[].reason	失败原因

4. Result Boundary Contract

• 账单生成结果统一以 biz_charge 作为主结果、biz_charge_detail 作为明细结果承接。
• 特殊开账、无码客户开账或罚款类开账应通过来源类型、业务类型或依据说明纳入统一账单主模型，不单独发明平行主表。
• 账单生成成功后只表达“已生成营业账”的结果边界，后续收费、催缴、开票由下游模块继续承接。

5. Exception Contract

• 当价格模板、阶梯规则、费用组成、计划用水方案或必要来源数据缺失时，应阻断生成并返回失败原因。
• 失败语义必须与现有抄表开账类错误码口径一致，不得仅写日志而不在接口结果中表达。
• 异常复核、估抄、补抄、重录等场景只定义“是否允许进入生成”边界，不展开具体实现细节。