72 lines
3.0 KiB
Markdown
72 lines
3.0 KiB
Markdown
# 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 细化为一期必做实现
|
|
- 是否未误写独立账务台账表族为在线新增对象
|