# 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 最小校验动作

```bash
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 第一轮：先收敛范围

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

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

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

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

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

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

## 10. 验收清单

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