# Implementation Plan: REV-004 账务处理一期

**Branch**: `001-rev004-accounting` | **Date**: 2026-03-13 | **Spec**: `/specs/001-rev004-accounting/spec.md`
**Input**: Feature specification from `/specs/001-rev004-accounting/spec.md`

## Summary

本轮围绕 `REV-004` 账务处理一期完成文档收敛与计划设计，不直接进入 backend 代码修改。计划目标是基于既有正式文档统一一期范围、接口口径、数据库承接口径、留痕要求与审批边界，并为后续 `/speckit.tasks` 提供可直接拆解的实施顺序、验收入口与追溯依据。

本次计划输出以 spec 约束为准：一期仅覆盖水量调整、金额调整、退款、冲正、坏账申请五类场景；后续实施按“共性能力先统一、场景能力再分批”组织；验收入口限定为文档一致性、计划可拆解性与台账可回写性。

## Technical Context

**Primary Work Product**: REV-004 一期 planning 设计产物，包括实施计划、研究结论、数据模型、合同矩阵、评审与最小校验说明。
**Source of Truth Documents**:
- `specs/001-rev004-accounting/spec.md`
- `.specify/memory/constitution.md`
- `docs/design/01_Overview/03_Summary_Design.md`
- `docs/design/02_Detailed_Design/12_REV_Detailed.md`
- `docs/design/03_Technical_Design/03_Interface_Design.md`
- `docs/design/03_Technical_Design/01_Database_Design.md`
**Reference Sources**:
- `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
- `docs/design/00_Management/01_Project_Progress.md`
- `docs/design/00_Management/02_Delivery_Standards.md`
- `docs/design/00_Management/03_Task_Checklist.md`
- `docs/design/00_Management/15_Legacy_Migration_Gap_Analysis.md`
- `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md`
**Validation Commands**:
- `make validate-file FILE=specs/001-rev004-accounting/spec.md`
- `make validate-file FILE=specs/001-rev004-accounting/plan.md`
- `make check-links`
- `make validate-mermaid`
**Target Scope**:
- `REV-004` 一期范围收敛
- `IF-REV-007` 统一接口合同
- 详细设计 / 接口设计 / 数据库设计之间的追溯关系
- 留痕、原交易校验、审批边界与台账动作约束
**Project Type**: 文档治理仓库
**Constraints**:
- 不新增平行正式主稿
- 不发明超出主文档范围的新业务规则
- Archive 仅作核对与追溯来源，不替代正式结论
- 审批仅保留能力位和边界说明，不展开完整 BPM
- 本轮不写 backend 实施代码
- 仓库内引用保持相对路径口径
**Scale/Scope**: 跨文档 planning 设计，覆盖 1 个 feature spec、1 个 implementation plan、3 个合同/矩阵产物、1 份数据模型和 1 份 quickstart。

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- [x] **主文档归属已确认**：本轮产物落在 `specs/001-rev004-accounting/` 规划目录，后续正式落地仍回写既有主文档，不新增平行正式稿。
- [x] **范围基线已确认**：一期范围限定为 `REV-004` 既有交集场景，统一挂靠 `IF-REV-007`，不扩展到账务平台级重构或其他接口族。
- [x] **Archive 使用方式合规**：Archive 仅作为历史核对与范围基线来源，未直接替代正式设计结论。
- [x] **一致性影响已列出**：已识别并约束系统名称、接口编号、账单承接对象、原交易校验对象、日志留痕对象、审批边界和验收入口。
- [x] **校验与台账动作已规划**：已明确最小校验命令；已明确当前仅生成计划产物时暂不强制更新 `01_Project_Progress.md` / `03_Task_Checklist.md`，待正式主文档修订或任务闭环时再更新。

### Post-Design Re-check

- [x] 设计产物均保持“文档收敛 + 计划准备”定位，未越界到 backend 实施。
- [x] `data-model.md` 采用逻辑实体 + 物理承接双层表达，未误写在线新增独立账务台账表族。
- [x] `contracts/` 中所有合同均回扣 `IF-REV-007`、`biz_charge*`、`bk_transaction*`、`biz_operat_log*` 口径。
- [x] `quickstart.md` 仅定义文档评审与最小校验步骤，未引入超范围构建或发布动作。
- [x] 设计产物中的审批相关内容均仅保留 `approvalRequired` / `PENDING_APPROVAL` 等能力位和边界说明。

## Project Structure

### Documentation (this feature)

```text
specs/001-rev004-accounting/
├── plan.md                              # 本文件，实施计划主文件
├── research.md                          # Phase 0 研究结论
├── data-model.md                        # REV-004 一期逻辑实体与物理承接口径
├── quickstart.md                        # 评审入口与最小校验步骤
├── contracts/
│   ├── if-rev-007-accounting-request.md # IF-REV-007 统一合同
│   ├── rev004-scenario-matrix.md        # 五类场景矩阵
│   └── rev004-traceability-matrix.md    # spec / 详设 / 接口 / 数据库追溯矩阵
└── tasks.md                             # 下一阶段由 /speckit.tasks 生成
```

### Repository Touchpoints

```text
docs/design/
├── 00_Management/
│   ├── 01_Project_Progress.md
│   ├── 02_Delivery_Standards.md
│   └── 03_Task_Checklist.md
├── 01_Overview/
│   └── 03_Summary_Design.md
├── 02_Detailed_Design/
│   └── 12_REV_Detailed.md
├── 03_Technical_Design/
│   ├── 01_Database_Design.md
│   └── 03_Interface_Design.md
└── 04_Appendix/Archive/

.specify/memory/constitution.md
docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md
CLAUDE.md
```

**Structure Decision**:
- `specs/001-rev004-accounting/spec.md`：作为本 feature 的需求与验收边界总源。
- `specs/001-rev004-accounting/plan.md`：承接当前计划阶段的实施组织、门禁与结构决策。
- `specs/001-rev004-accounting/research.md`：沉淀范围、承接对象、审批边界、台账动作等关键选择。
- `specs/001-rev004-accounting/data-model.md`：把统一接口、结果表达、账单承接、原交易校验、日志留痕固化为逻辑模型。
- `specs/001-rev004-accounting/contracts/if-rev-007-accounting-request.md`：统一 `IF-REV-007` 的请求/响应与共性规则。
- `specs/001-rev004-accounting/contracts/rev004-scenario-matrix.md`：把五类场景的输入、校验、结果和留痕差异收敛成统一矩阵。
- `specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md`：建立规格、详细设计、接口设计和数据库设计的稳定追溯关系。
- `specs/001-rev004-accounting/quickstart.md`：为计划评审和后续 tasks 生成提供统一的最小校验入口。
- `CLAUDE.md`：已通过 agent context 更新脚本同步当前计划的文档治理工作模式。

## Phase 0 Research Summary

1. 一期范围严格收敛到 `REV-004` + `IF-REV-007`，只覆盖水量调整、金额调整、退款、冲正、坏账申请。
2. 后续实施先统一共性能力，再按场景分批拆解，避免不同场景各自固化状态与承接口径。
3. 在线主模型复用 `biz_charge*`、`biz_operat_log*` 和 `bk_transaction*`，不新增独立账务台账表族。
4. 退款/冲正必须联动原交易校验，不能只依赖账单状态。
5. 审批/BPM 一期只保留能力位与边界说明，不强接完整审批流。
6. 本轮验收只看文档与计划质量，不以 backend 代码完成度为前提。
7. 最小校验以文档门禁命令为主，不引入构建、导出或代码测试步骤。
8. 管理台账仅在正式主文档修订或任务闭环时更新，当前计划产物阶段暂不强制回写。

## Phase 1 Design Outputs

### Data Model
- `data-model.md` 已定义：
  - `AccountingRequest`
  - `AccountingResult`
  - `ChargeAggregate`
  - `Transaction`
  - `OperationLog`
  - `AccountingEvidence`
- 其中明确区分逻辑实体与物理承接口径，避免把历史精细台账误写为在线新增实体。

### Contracts
- `contracts/if-rev-007-accounting-request.md`
  - 固化 `IF-REV-007` 的请求字段、响应字段、共性规则、物理承接口径与验收关注点。
- `contracts/rev004-scenario-matrix.md`
  - 固化五类场景的输入、校验、结果表达和留痕重点。
- `contracts/rev004-traceability-matrix.md`
  - 固化 `spec.md`、详设、接口设计、数据库设计之间的追溯关系。

### Quickstart
- `quickstart.md` 已给出：
  - 范围校验
  - 单一真源校验
  - 追溯关系校验
  - 审批边界校验
  - 台账动作校验
  - 最小校验命令

### Agent Context
- 已执行 `.specify/scripts/bash/update-agent-context.sh claude`
- 已同步更新 `CLAUDE.md` 的 agent context。

## Implementation Strategy for Next Phase

下一阶段 `/speckit.tasks` 应按以下顺序拆解：

1. **执行闭环收口任务**
   - 更新执行手册中的执行顺序、独立验收入口、最小校验动作
   - 明确 `01_Project_Progress.md` 与 `03_Task_Checklist.md` 的触发式同步条件
   - 保证审阅者仅通过执行手册与两份治理台账即可判断后续任务可继续推进
2. **共性能力对齐任务**
   - 统一一期纳入/排除范围
   - 统一 `IF-REV-007` 接口合同
   - 统一 `biz_charge*` / `bk_transaction*` / `biz_operat_log*` 承接口径
   - 统一 `resultStatus` / `writeBackStatus` / `approvalRequired` 表达
3. **分场景修订任务**
   - 水量调整
   - 金额调整
   - 退款
   - 冲正
   - 坏账申请
4. **追溯与验收任务**
   - 追溯矩阵复核
   - 执行手册 / quickstart / plan / 台账之间的闭环一致性校验
   - 文档链接 / 单文件校验
   - 正式主文档修订落地后再决定是否更新项目进度与任务清单

补充约束：
- `quickstart.md` 负责沉淀评审步骤、最小校验命令与独立验收入口说明。
- `01_Project_Progress.md` 仅记录新的治理里程碑或正式交付节点，不重复记录普通校验动作。
- `03_Task_Checklist.md` 仅记录 tracked task 的完成状态与闭环条件，不承担过程性执行日志。

## Complexity Tracking

本计划未发生 Constitution 违规项，无需豁免说明。