fujian_water_biz_doc/docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md

REV-004 账务处理一期执行手册

1. 文档目的

本文档用于将 REV-004 账务处理一期从“范围确认”转为“正式文档可执行修订计划”，用于指导：

• 一期纳入范围与排除项确认
• 正式主文档修订顺序
• 最小校验动作与验收入口
• 台账回写触发条件
• 后续实施任务拆解方式

本文档只服务于 REV-004 一期文档收敛与执行准备，不扩展到未确认范围，也不把 backend 代码修改作为本轮已执行内容。

2. 范围基线

本次执行范围以以下文档交集为准：

1. docs/design/01_Overview/03_Summary_Design.md
2. docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md
3. docs/design/02_Detailed_Design/12_REV_Detailed.md
4. docs/design/03_Technical_Design/01_Database_Design.md
5. docs/design/03_Technical_Design/03_Interface_Design.md

2.1 一期纳入范围

类别	范围
模块	REV-004
接口	IF-REV-007
场景	水量调整、金额调整、退款、冲正、坏账申请
共性能力优先	先统一账单承接、原交易校验、结果表达、操作留痕、审批边界
核心对象	biz_charge、biz_charge_detail、biz_operat_log*
外部校验	原交易校验（bk_transaction*）
审批边界	只保留 approvalRequired、PENDING_APPROVAL 与边界说明，不展开完整审批流

2.2 一期不纳入范围

类别	不纳入内容
独立台账表族	预存退款明细表、价差调整明细表、分账调整明细表等新增细表
非本模块接口	IF-REV-008、IF-REV-011、IF-CS-*、IF-METER-*
泛化流程平台扩展	新 BPM 模型体系、新审批平台抽象
跨模块大改	支付全链路重构、发票后处理重构、历史库统一改造
本轮不做	backend 代码实现、联调测试、worktree/tmux/Codex 执行编排

3. 当前代码落点

3.1 主业务模块

角色	文件路径
Controller	backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/charge/ChargeController.java
Service 接口	backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/charge/ChargeService.java
Service 实现	backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/charge/ChargeServiceImpl.java
Mapper	backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/mysql/charge/ChargeMapper.java
DO	backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/charge/ChargeDO.java
操作日志服务	backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/operatlog/OperatLogService.java

3.2 银行交易校验模块

角色	目录
交易 Controller	backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/admin/transaction
交易 Service	backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/transaction
交易 Mapper/DO	backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/dal/mysql/transaction

3.3 BPM 接入点

角色	文件路径
BPM API	backend/sw-module-bpm/sw-module-bpm-api/src/main/java/cn/com/emsoft/sw/module/bpm/api/task/BpmProcessInstanceApi.java

4. 当前文档差距判断

4.1 已有基础

• docs/design/02_Detailed_Design/12_REV_Detailed.md 已具备 REV-004 账务处理章节与主要场景说明。
• docs/design/03_Technical_Design/03_Interface_Design.md 已具备 IF-REV-007 接口定义与字段口径。
• docs/design/03_Technical_Design/01_Database_Design.md 已具备 biz_charge*、biz_operat_log*、bk_transaction* 的主承接口径。
• specs/001-rev004-accounting/ 已形成范围、数据模型、场景矩阵、追溯矩阵与最小校验说明。

4.2 一期文档缺口

• 正式详细设计仍需明确“一期仅五类场景”的范围边界与排除项。
• 执行手册仍需从代码落地视角收敛回“正式文档修订 + 最小校验 + 台账触发条件”的执行口径。
• 正式主文档之间仍需进一步统一共性能力优先顺序、审批边界和受影响对象说明。
• 台账文件仍需在正式文档校验通过后按触发条件更新，而不是默认同步。

5. 一期最小文档改动方案

5.1 正式主文档修订顺序

按以下顺序执行：

1. docs/design/02_Detailed_Design/12_REV_Detailed.md
2. docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md
3. docs/design/01_Overview/03_Summary_Design.md
4. specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md

5.2 必须统一的共性口径

一期必须先统一以下共性能力：

• 统一入口：IF-REV-007
• 统一账单承接：biz_charge / biz_charge_detail
• 统一原交易校验：bk_transaction*
• 统一留痕：biz_operat_log / biz_operat_log_detail
• 统一结果表达：resultStatus / writeBackStatus
• 统一审批边界：approvalRequired / PENDING_APPROVAL

5.3 最小验收入口

本轮验收仅检查：

• 文档一致性
• 计划可拆解性
• 台账可回写性

5.4 台账更新触发条件

• 仅当正式文档重要变更完成且对应校验通过后，才更新 docs/design/00_Management/01_Project_Progress.md。
• 仅当 tracked task 完成或完成条件发生实质变化时，才更新 docs/design/00_Management/03_Task_Checklist.md。
• 如果正式文档未发生实质变化，可将对应台账任务标记为不适用，但必须说明理由。

6. 文档任务拆解

6.1 P0-1 范围与边界收敛

项目	内容	输出
范围收敛	明确一期五类场景、排除项、审批边界	REV-004 范围基线
共性能力排序	明确“共性能力先统一、场景能力再分批”	修订顺序说明
追溯锚点	明确详细设计 / 接口 / 数据库 / 执行手册的对应关系	追溯基线

6.2 P0-2 正式文档修订

分类	必做项
详细设计	更新 REV-004 一期范围、排除项、审批边界
执行手册	更新执行范围、验收入口、后续组织方式
概要设计	同步一期范围摘要与交叉引用
追溯矩阵	回写范围与正式文档承接关系

6.3 P0-3 校验与台账

场景	要求
单文件校验	对修改过的正式文档执行 make validate-file FILE=<目标文件>
跨文档校验	存在交叉引用变更时执行 make check-links
项目进度	仅在重要正式文档变更校验通过后回写
任务清单	仅在 tracked task 完成或完成条件变化时回写

7. 评审与执行分工

7.1 评审者负责

• 确认是否超出一期范围
• 确认审批边界是否仍停留在能力位层
• 审核正式文档之间是否口径一致
• 审核台账是否满足触发条件再更新

7.2 执行者负责

• 按既定顺序修订正式主文档
• 同步 contracts / quickstart / traceability 等支撑产物
• 执行最小校验并记录结果
• 汇总剩余风险与下一步建议

8. 执行顺序与最小校验

8.1 推荐执行顺序

1. 先确认 12_REV_Detailed.md、03_Interface_Design.md、01_Database_Design.md 已形成一期统一口径，再进入执行闭环收口。
2. 更新本执行手册，明确后续 tasks 的拆解顺序、独立验收入口、最小校验动作与台账同步条件。
3. 如执行手册对评审步骤、校验说明或闭环顺序有实质性调整，再同步 quickstart.md 与 plan.md 的支撑表述。
4. 仅在治理台账形成新的里程碑或 tracked task 完成条件被重新定义时，再回写 01_Project_Progress.md 与 03_Task_Checklist.md。
5. 每完成一组正式文档或台账修订，立即执行最小校验，确保当前增量可独立评审。

8.2 独立验收入口

US3 的独立验收只检查以下内容：

1. docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md 是否明确后续任务拆解顺序：先执行手册闭环，再按正式主文档 / 支撑产物 / 台账同步三类动作推进。
2. docs/design/00_Management/01_Project_Progress.md 是否记录了 REV-004 从“范围确认 / 口径对齐”进入“可执行交付闭环”的里程碑。
3. docs/design/00_Management/03_Task_Checklist.md 是否记录了 REV-004 当前 tracked task 的闭环条件：执行手册更新、最小校验通过、台账按触发条件同步。
4. 审阅者无需查看 backend 代码或额外 Archive 材料，即可判断 REV-004 后续工作可继续按 tasks 拆解推进。

8.3 最小校验动作

make validate-file FILE=docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md
make validate-file FILE=docs/design/00_Management/01_Project_Progress.md
make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md
make check-links

补充说明：

• make check-links 仅用于确认执行手册、项目进度、任务清单之间的相对链接与引用未被破坏。
• 本轮仍不引入 backend 构建、导出、联调或自动化测试命令。
• 若后续进入新的正式主文档修订批次，应在该批次内补充对应目标文件的 make validate-file FILE=<目标文件>。

9. 文档执行提示模板

9.1 第一轮：先收敛范围

请先只做 REV-004 一期正式文档范围收敛，不进入 backend 代码修改。

范围严格限制：
- IF-REV-007
- 水量调整、金额调整、退款、冲正、坏账申请
- 不新增独立账务台账表族

重点输出：
1. 一期纳入范围
2. 一期排除项
3. 共性能力优先顺序
4. 审批边界
5. 需要同步的正式文档清单

9.2 第二轮：确认后再修订正式文档

按已确认的 REV-004 一期范围开始修订正式文档。

要求：
- 先改详细设计与执行手册
- 再同步概要摘要和追溯矩阵
- 审批只保留 approvalRequired / PENDING_APPROVAL / 边界说明
- 不把 backend 代码实现写成本轮已完成内容
- 每次修订后执行最小校验并汇总剩余风险

10. 验收清单

• 一期范围仅保留水量调整、金额调整、退款、冲正、坏账申请
• 独立账务细表、其他接口族、泛化 BPM 与 backend 代码实施未被带入本轮
• 共性能力优先顺序已写清楚
• 审批边界仅保留 approvalRequired、PENDING_APPROVAL 与边界说明
• 正式文档修订顺序与最小验收入口已明确
• 台账更新触发条件已明确
• 文档改动可独立评审并可继续拆解后续任务