# REV004 / 分账执行态后端设计草案（2026-04-14）

## 1. 目标
在当前“分账申请态”基础上，补齐“审批通过后真正执行拆账”的后端能力，使系统可以：
- 将一笔原始未收费账单拆成多笔目标账单
- 支持两类分账策略：
  - 按水量分账
  - 按费用组成分账
- 保证金额/水量守恒、状态可追踪、失败可回滚
- 被后续收费、开票、日志、查询完整承接

---

## 2. 当前现状
### 已有
- 统一对象类型：`SPLIT_ADJUST`
- 统一提交入口：`unsold-split-submit`
- 当前结果：`PENDING_APPROVAL`
- 已有原因、审批、日志、查询承接能力

### 缺失
- 审批通过后的执行器
- 分账主表/明细表落库
- 目标账单生成
- 原账单与目标账单关系链
- 按水量/按费用组成的规则明细
- 执行态查询回看

---

## 3. 设计原则
1. **先审批、后执行**：分账执行必须挂在审批通过之后，不在申请提交时直接拆账。
2. **守恒原则**：
   - 按水量分账：子账单水量之和 = 原账单水量
   - 按费用组成分账：子账单金额之和 = 原账单金额
3. **原账单可追溯**：必须保留原账单与所有目标账单关系。
4. **执行幂等**：同一分账单不得重复执行。
5. **失败可回滚**：执行中任一步失败，必须整体回滚。
6. **查询可回看**：日志页/分账页必须能看到申请、审批、执行结果、目标账单明细。

---

## 4. 结果对象建议
### 最终业务真值
建议以：
- **多张目标子账单**
为正式业务真值；
- “多笔待收费结果”只是前台呈现视角。

### 原因
- 文档原始语义就是“由一笔账单分成两笔独立账单信息”
- 后续还要支持分别收费、分别开票、分别承担
- 若没有目标账单实体，后续业务承接会变得模糊

---

## 5. 数据模型草案

### 5.1 主表：`biz_split_adjust`
建议字段：
- `id`
- `split_adjust_no`：分账单号
- `source_charge_id`：原账单 ID
- `split_rule_type`：分账规则类型（`BY_WATER` / `BY_COMPONENT`）
- `reason_code`
- `remark`
- `approval_status`
- `execute_status`：`PENDING / PROCESSING / SUCCESS / FAIL`
- `execute_message`
- `executed_at`
- `accounting_case_id`（如继续挂统一骨架）
- 通用审计字段

### 5.2 明细表：`biz_split_adjust_detail`
建议字段：
- `id`
- `split_adjust_id`
- `seq_no`
- `target_cust_id` / `target_cust_code`（若允许拆给不同客户）
- `target_charge_id`（执行后生成）
- `split_basis`：拆分依据描述
- `split_ratio`
- `split_water`
- `split_amount`
- `component_code`（按费用组成分账时必填）
- `component_amount`
- `status`
- 通用审计字段

### 5.3 与现有 `biz_charge` 的关系
- 原账单：`source_charge_id`
- 子账单：执行后在 `biz_charge` 新增多条记录
- 子账单增加来源追踪字段（建议二选一）：
  - `source_charge_id`
  - 或 `split_adjust_id`

建议至少有一个能让后续查询直接知道：
> 这张账单是由哪次分账生成的。

---

## 6. 执行流程草案

### Phase 1：申请提交
接口：`POST /unsold-split-submit`
- 校验未收费、`splitCount`、原因等
- 保存申请主单/明细草稿（如果前端已能提供拆分明细）
- 状态置为 `PENDING_APPROVAL`

> 若当前前端还没有真正提交拆分明细，只是申请头信息，则需在后续补充“审批前明细维护”或“审批时确认明细”能力。

### Phase 2：审批通过
触发点：审批系统回调/人工审批通过
- 校验该分账单仍未执行
- 锁定原账单
- 进入执行事务

### Phase 3：执行拆账
#### 3.1 按水量分账
- 读取原账单水量、单价/模板/费用构成
- 根据各子项 `split_water` 重新计算子账单金额
- 生成 N 条目标账单
- 校验：
  - `sum(split_water) = source.bill_water`
  - `sum(target.bill_amount)` 与可接受计算误差范围内守恒

#### 3.2 按费用组成分账
- 读取原账单明细 `biz_charge_detail`
- 按费用项将金额拆入不同子账单
- 汇总生成 N 条目标账单及其明细
- 校验：
  - 各费用项总额守恒
  - 原账单总金额守恒

### Phase 4：收尾
- 原账单标记为：
  - 已拆分 / 已失效 / 不可继续收费（建议新增状态或来源标识）
- 分账主单置为 `SUCCESS`
- 明细回填 `target_charge_id`
- 写 operat_log / 业务日志 / 查询投影

### Phase 5：失败回滚
- 任一步失败：回滚事务
- 主单置 `FAIL`
- 保留失败原因
- 不产生部分子账单残留

---

## 7. 接口草案

### 7.1 申请接口（保留）
- `POST /unsold-split-submit`

### 7.2 明细查询接口（建议新增）
- `GET /split-adjust-detail?adjustmentNo=...`
- 返回：
  - 原账单摘要
  - 分账规则类型
  - 子项明细
  - 目标账单（若已执行）

### 7.3 明细维护接口（建议新增，若前端需要）
- `POST /split-adjust-draft-save`
- 在审批前保存：
  - 按水量拆分行
  - 按费用组成拆分行

### 7.4 审批通过执行接口（内部）
- `POST /internal/split-adjust/execute`
- 由审批流或业务服务调用，不暴露给前端

### 7.5 查询接口增强（建议）
- `log-detail` / `log-process`
  - 增加目标账单摘要
- `unsold-page`
  - 原账单若已提交分账且审批中/已执行，要有能力位变化提示

---

## 8. 状态机建议
### 申请主单状态
- `PENDING_APPROVAL`
- `APPROVED_PENDING_EXECUTE`
- `PROCESSING`
- `SUCCESS`
- `FAIL`
- `REVOKED`（如审批前允许撤销）

### 原账单状态建议
原账单不建议简单删除，建议新增可追溯状态：
- `UNPAID`
- `SPLIT_PENDING`
- `SPLIT_DONE`
- `SPLIT_INVALIDATED`

若不想改老字段，可用额外来源标记字段表达。

---

## 9. 与前端配合建议
### 前端最少补充信息
若要真正进入执行态，前端弹窗至少要能提交：
- 分账方式：按水量 / 按费用组成
- 子项列表
  - 按水量：每笔 `split_water`
  - 按费用组成：每笔目标费用项/金额归属
- 申请人 / 联系电话 / 原因 / 备注

### 前端结果回看
执行态落地后，前端需要新增：
- 原账单 -> 目标账单列表
- 子账单金额/水量/费用项明细
- 分账执行结果与失败原因

---

## 10. 分阶段落地建议
### 第一阶段（最小闭环）
目标：审批通过后真正生成子账单，但先只支持**按水量分账**
- 优先原因：
  - 规则相对更直观
  - 守恒约束明确
  - 更容易先做闭环

### 第二阶段
扩展支持：**按费用组成分账**
- 需要补足 `biz_charge_detail` 级别重分摊能力

### 第三阶段
增强：
- 目标客户维度分账
- 更复杂的规则模板
- 开票/收费联动优化查询

---

## 11. 最终建议
若项目要正式推进“分账执行态”，建议：
1. 先把 **按水量分账** 做成最小执行闭环
2. 明确 `biz_split_adjust` / `biz_split_adjust_detail` 模型
3. 把审批通过后的执行器作为独立服务落地
4. 再补按费用组成的二阶段能力

一句话：
> 不建议继续在当前“统一 adjustAccounting 申请态”里硬塞执行逻辑，而应把 `SplitAdjust` 升级成独立正式业务对象来建设。