tangweijie/fujian_water_biz_doc
1
0
Fork 0
Code Issues Pull Requests 12 Actions Packages Projects Releases 1 Wiki Activity
fujian_water_biz_doc/docs/evidence/rev004-accounting/rev004-split-adjust-water-first-mvp-design-2026-04-14.md
tangweijie 3eccab2cf9 docs: 文档治理统一 — AGENTS.md 生命周期规则 + 模块归档 + DDL 修正 
1. AGENTS.md 更新
   - water-docs: 新增 specs/ 与 docs/design/ 生命周期规则章节
   - water-backend: 更新协作引用（建设期/建成后、evidence 模块化）

2. specs/ 重复合并
   - 006-reminder-event-design 合并入 003-rev006-reminder-event-design
   - 001-rev004-accounting 删除冗余 data-model.md + contracts/
   - 002-rev005-invoice-flow 删除冗余 data-model.md + contracts/

3. evidence 按模块归档
   - 35 个 REV-004 文件归入 evidence/rev004-accounting/
   - 7 个通用 bugfix 文件归入 evidence/bugfix/ 和 bugfix/frontend/
   - 新建 rev005-invoice/、rev006-reminder/、rev007-statistics/ 目录

4. guides/ 清理
   - 14 个 REV004_*.md 移入 evidence/rev004-accounting/

5. 遗留文件处理
   - docs/research/ 归档到 Archive/06_Migration_Plans/
   - backend-check detached worktrees 清理

6. 交叉引用修复
   - 006-reminder-event-design → 003-rev006-reminder-event-design
   - docs/guides/REV004_ → docs/evidence/rev004-accounting/REV004_

7. DB 设计文档修正（01_Database_Design.md）
   - biz_invoice 明确为开票配置表，非发票记录表
   - 新增 biz_invoice_record 为发票申请/结果主表
   - 新增 biz_charge_invoice_rel 账单-发票关联说明
   - REV-005 承接口径表名全部修正

8. 发票审计证据
   - 新增 evidence/rev005-invoice/2026-06-16-invoice-document-audit.md
2026-06-16 11:47:16 +08:00

6.0 KiB
Raw Blame History

REV004 / 按水量分账最小闭环设计（2026-04-14）

1. 目标

本设计只覆盖 第一阶段：按水量分账最小闭环。

目标是：

  • 审批通过后，能够把一笔未收费原账单按多笔水量拆分，真正生成多张目标子账单；
  • 先不做“按费用组成分账”；
  • 先把最小可运行闭环打通，再作为后续扩展基础。

2. 为什么第一阶段先做按水量分账

原因：

  1. 规则最清晰：拆分水量之和必须等于原水量。
  2. 业务校验最直接：原账单 -> 多笔子账单，按水量重算金额，容易理解。
  3. 比按费用组成更容易守恒：先处理总水量、总金额守恒，再逐步扩到费用项粒度。
  4. 更适合先做执行态样板：审批通过、执行、回看、失败回滚等流程都能先沉淀下来。

3. 最小闭环边界

本阶段要做到

  • 提交按水量分账申请
  • 保存拆分明细（每笔分账水量）
  • 审批通过后执行拆账
  • 生成多张目标账单
  • 原账单标记为已拆分/失效
  • 日志与查询可回看

本阶段不做

  • 按费用组成分账
  • 目标客户跨户分账（如无强需求，可先默认同客户）
  • 更复杂规则模板
  • 开票联动优化
  • 自动撤销分账执行结果

4. 输入输出定义

4.1 前端最少输入

按水量分账弹窗至少提交：

  • sourceChargeId
  • splitItems[]
    • seqNo
    • splitWater
  • reasonCode
  • remark
  • applicant
  • contactMobile

4.2 关键校验

  • 原账单必须是未收费
  • splitItems.length >= 2
  • 每笔 splitWater > 0
  • sum(splitWater) = source.billWater
  • 必须填写原因

4.3 输出结果

申请提交成功后：

  • adjustmentNo
  • resultStatus = PENDING_APPROVAL

执行成功后应可回看：

  • 原账单摘要
  • 目标子账单列表
  • 每张子账单的：
    • 水量
    • 账单金额
    • 应收金额
    • 违约金（若适用）

5. 数据模型（MVP）

5.1 主表：biz_split_adjust

建议 MVP 字段：

  • id
  • split_adjust_no
  • source_charge_id
  • split_rule_type = BY_WATER
  • reason_code
  • remark
  • approval_status
  • execute_status
  • execute_message
  • executed_at
  • creator / create_time / updater / update_time

5.2 明细表：biz_split_adjust_detail

建议 MVP 字段：

  • id
  • split_adjust_id
  • seq_no
  • split_water
  • target_charge_id（执行后回填）
  • split_amount（执行后回填）
  • status
  • creator / create_time / updater / update_time

5.3 账单表最小扩展建议

在 biz_charge 里增加追溯字段（二选一或组合）：

  • source_charge_id
  • split_adjust_id
  • charge_origin_type（如：NORMAL / SPLIT_CHILD）

原账单增加状态表达（二选一）：

  • 新字段标记 split_status
  • 或现有字段中增加来源/失效标识

MVP 阶段关键不是状态字段优雅，而是：

后续能稳定区分“原账单”和“拆分生成的子账单”。

6. 执行流程（MVP）

Step 1：申请提交

接口：POST /unsold-split-submit

  • 校验基本参数
  • 保存 biz_split_adjust
  • 保存 biz_split_adjust_detail（只保存水量）
  • 返回待审批

Step 2：审批通过

  • 触发内部执行器
  • 对 biz_split_adjust 加幂等校验：只允许执行一次
  • 锁定原账单 source_charge_id
  • 开事务

Step 3：生成目标账单

对每个 split_adjust_detail：

  1. 复制原账单基础信息
  2. 将 bill_water 改成当前 split_water
  3. 调用现有计价逻辑重新计算：
    • bill_amount
    • extended_amount
    • 若适用则重算 late_fee
  4. 插入新的 biz_charge 记录
  5. 回填 target_charge_id / split_amount

Step 4：处理原账单

  • 原账单置为“已拆分，不可继续收费”
  • 不直接删除原账单
  • 保证历史可追溯

Step 5：收尾

  • biz_split_adjust.execute_status = SUCCESS
  • 写 operat_log / log detail
  • 查询面可见结果

Step 6：失败回滚

  • 任一子账单生成失败：事务回滚
  • 主单置 FAIL
  • 记录失败原因
  • 不允许出现半拆分状态

7. 重算策略建议

MVP 不建议自己重新写一套计价逻辑，建议：

  • 复用已有账单计算能力
  • 输入拆分后的水量
  • 走现有价格模板/费用计算规则

原因：

  • 这样能减少“分账执行”和“普通开账计费”之间的口径偏差
  • 也更容易保证后续账单金额解释一致

关键原则：

分账只是“改变水量输入并生成多张账单”，不要重造一套新的计费引擎。

8. 查询回看（MVP）

建议至少补两个查询面：

8.1 分账详情查询

  • 原账单摘要
  • 分账规则类型（BY_WATER）
  • 每笔拆分水量
  • 每笔生成的目标账单 ID / 金额
  • 执行状态 / 错误原因

8.2 日志页增强

在现有 log-detail / log-process 中，增加：

  • 原账单 -> 子账单映射摘要
  • 执行结果摘要

9. 测试建议（MVP）

9.1 单测

  • 水量守恒校验
  • 拆分笔数边界（<2, >12）
  • 非未收费账单禁止发起
  • 执行幂等

9.2 集成测试

  • 提交按水量分账申请 -> 待审批
  • 审批通过 -> 生成 N 张子账单
  • 子账单水量之和 = 原账单水量
  • 原账单不可继续收费
  • 日志页可回看执行结果
  • 执行失败整体回滚

9.3 验收测试

  • 一张账单拆成 2 笔
  • 一张账单拆成多笔
  • 子账单后续可分别收费/开票（若本期不做全链，可先验证可查询/可识别）

10. MVP 成功标准

MVP 完成时，应满足：

  1. 用户可提交按水量分账申请
  2. 审批通过后，系统真正生成多张目标账单
  3. 子账单水量之和与原账单守恒
  4. 原账单被正确标记，不再继续作为普通未收费账单使用
  5. 查询与日志能回看这次分账执行结果

11. 建议实施顺序

  1. 先补 biz_split_adjust / biz_split_adjust_detail
  2. 再补审批通过后的执行器
  3. 再补查询回看
  4. 最后补前端执行态结果页

一句话：

先把“按水量分账”做成审批后真正能拆出子账单的最小闭环，再考虑按费用组成扩展。