# 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<String> | 否 | 依据附件 | 进入依据引用 |
| 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 细化为一期必做实现
- 是否未误写独立账务台账表族为在线新增对象