fujian_water_biz_doc/specs/001-rev004-accounting/contracts/if-rev-007-accounting-request.md

Contract: IF-REV-007 账务调整接口

1. 合同定位

本合同用于固化 IF-REV-007 在 REV-004 一期中的统一接口口径，服务于后续正式接口文档修订、任务拆解与评审，不作为代码接口定义文件。

2. 适用范围

适用场景：

• 水量调整
• 金额调整
• 退款
• 冲正
• 坏账申请

不适用范围：

• 发票申请与结果回写
• 银行代收与结算协同
• 新 BPM 流程模型扩展
• 独立账务台账表族设计

3. 请求合同

字段	类型	必填	说明	约束
chargeId	Long	是	目标账单 ID	必须存在于 biz_charge.id
adjustType	String	是	调整类型	USAGE / AMOUNT / REFUND / REVERSE / BAD_DEBT
adjustAmount	Decimal	否	调整金额	金额类场景必填
adjustUsage	Decimal	否	调整水量	水量类场景必填
sourceTradeNo	String	否	原交易流水号	REFUND / REVERSE 场景必填
reasonCode	String	是	调整原因编码	需可追溯到业务字典
remark	String	否	调整说明	进入操作留痕
attachmentList	Array	否	依据附件	进入依据引用
operatorId	Long	是	操作人 ID	必须可追溯责任归属

4. 响应合同

字段	类型	说明	约束
adjustmentNo	String	调整业务编号	用于后续追踪
chargeId	Long	目标账单 ID	与请求一致
resultStatus	String	处理状态	SUCCESS / PENDING_APPROVAL / FAIL
writeBackStatus	String	账单回写状态	SUCCESS / IGNORE_REPEAT / FAIL
approvalRequired	Boolean	是否进入审批	一期仅保留能力位
msg	String	处理说明	供调用方和评审使用

5. 共性规则

1. 所有场景必须定位到既有账单对象，不建立并行账务主对象。
2. 所有场景必须保留处理依据、前后变化和责任归属。
3. 退款、冲正必须校验原交易存在性、交易状态、回调结果与异常处理状态，不得只以 bk_transaction 主记录存在作为通过条件。
4. 审批相关内容一期仅保留 approvalRequired、PENDING_APPROVAL 与审批边界说明，不展开完整 BPM 流程、流程节点、流转规则或审批回写实现细节。
5. 接口结果必须能映射到 biz_charge*、bk_transaction*、biz_operat_log* 三类对象。
6. resultStatus 与 writeBackStatus 必须分离表达：前者表示业务处理结论，后者表示账单状态回写结论。

6. 物理承接口径

逻辑对象	物理承接
账单主对象	biz_charge
账单明细	biz_charge_detail
原交易校验	bk_transaction*
主日志	biz_operat_log
差异明细日志	biz_operat_log_detail

7. 验收关注点

• 是否所有场景都仍挂靠 IF-REV-007
• 是否未引入超范围接口编号
• 是否未把审批/BPM 细化为一期必做实现
• 是否未误写独立账务台账表族为在线新增对象