From a26f65a3d84bdd9253c27726e2d0eeb672e6d4b2 Mon Sep 17 00:00:00 2001
From: tangweijie <877588133@qq.com>
Date: Fri, 13 Mar 2026 15:02:29 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=94=B6=E5=8F=A3=20REV-004=20?=
=?UTF-8?q?=E4=B8=80=E6=9C=9F=E6=AD=A3=E5=BC=8F=E6=96=87=E6=A1=A3=E4=B8=8E?=
=?UTF-8?q?=E4=BA=A4=E4=BB=98=E9=97=AD=E7=8E=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
统一 REV-004 一期范围、接口口径、数据库承接口径与追溯关系，
并补齐执行手册、quickstart、tasks 及治理台账，完成可执行交付闭环。
---
.../00_Management/01_Project_Progress.md | 26 +-
.../design/00_Management/03_Task_Checklist.md | 140 ++++++++--
docs/design/01_Overview/03_Summary_Design.md | 29 ++-
.../02_Detailed_Design/12_REV_Detailed.md | 140 +++++++++-
.../03_Technical_Design/01_Database_Design.md | 54 +++-
.../03_Interface_Design.md | 53 +++-
.../REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md | 245 ++++++++++++++++++
.../checklists/requirements.md | 36 +++
.../if-rev-007-accounting-request.md | 71 +++++
.../contracts/rev004-scenario-matrix.md | 33 +++
.../contracts/rev004-traceability-matrix.md | 23 ++
specs/001-rev004-accounting/data-model.md | 167 ++++++++++++
specs/001-rev004-accounting/plan.md | 193 ++++++++++++++
specs/001-rev004-accounting/quickstart.md | 103 ++++++++
specs/001-rev004-accounting/research.md | 56 ++++
specs/001-rev004-accounting/spec.md | 134 ++++++++++
specs/001-rev004-accounting/tasks.md | 203 +++++++++++++++
17 files changed, 1653 insertions(+), 53 deletions(-)
create mode 100644 docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md
create mode 100644 specs/001-rev004-accounting/checklists/requirements.md
create mode 100644 specs/001-rev004-accounting/contracts/if-rev-007-accounting-request.md
create mode 100644 specs/001-rev004-accounting/contracts/rev004-scenario-matrix.md
create mode 100644 specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md
create mode 100644 specs/001-rev004-accounting/data-model.md
create mode 100644 specs/001-rev004-accounting/plan.md
create mode 100644 specs/001-rev004-accounting/quickstart.md
create mode 100644 specs/001-rev004-accounting/research.md
create mode 100644 specs/001-rev004-accounting/spec.md
create mode 100644 specs/001-rev004-accounting/tasks.md
diff --git a/docs/design/00_Management/01_Project_Progress.md b/docs/design/00_Management/01_Project_Progress.md
index a3e9101..ddb4321 100644
--- a/docs/design/00_Management/01_Project_Progress.md
+++ b/docs/design/00_Management/01_Project_Progress.md
@@ -8,8 +8,8 @@
| **项目目标** | 构建可交付给甲方的系统概要设计文档 |
| **技术框架** | RuoYi-Vue-Pro + yudao-ui-admin-vue3 |
| **开始时间** | 2024年12月 |
-| **当前阶段** | 概要设计阶段 |
-| **项目状态** | ✅ 已完成 |
+| **当前阶段** | 第3阶段已完成（转入持续维护） |
+| **项目状态** | ✅ 已完成，进入例行维护 |
## 文档交付清单
@@ -58,14 +58,16 @@
| 完善安全设计方案 | `water_biz_security_design.md` | ✅ 已完成 | 2024-12-19 | 🟢 等保三级安全设计已完成 |
| 编写部署脚本示例 | `water_biz_deployment_design.md` | ✅ 已完成 | 2024-12-19 | 🟢 容器化部署方案已完成 |
-### 第三阶段：文档优化 ✅ 已全部完成
+### 第三阶段：文档优化 ✅ 已完成
-| 任务 | 状态 | 完成时间 | 备注 |
+| 任务 | 状态 | 完成时间 | 备注 |
| ------------ | --------- | ---------- | ----------------------- |
-| 目录结构优化 | ✅ 已完成 | 2024-12-19 | 🟢 目录结构已标准化 |
-| 建立交叉引用 | ✅ 已完成 | 2024-12-19 | 🟢 文档间交叉引用已建立 |
-| 格式标准化 | ✅ 已完成 | 2024-12-19 | 🟢 格式已统一规范 |
-| 文档验证测试 | ✅ 已完成 | 2024-12-19 | 🟢 文档质量验证通过 |
+| 主文档导航与稳定锚点收敛 | ✅ 已完成 | 2026-03-11 | 🟢 主文档已统一为精简导航 + 稳定锚点 |
+| 主文档/模块追溯索引建立 | ✅ 已完成 | 2026-03-11 | 🟢 已形成主文档章节索引与模块追溯索引 |
+| 检索白名单与术语主入口收敛 | ✅ 已完成 | 2026-03-12 | 🟢 已形成检索分层与范围/术语主入口 |
+| 技术审查结论回写 | ✅ 已完成 | 2026-03-12 | 审查四项已在周检记录中形成结论，且唯一问题已归口修复 |
+| 业务审查结论回写 | ✅ 已完成 | 2026-03-12 | 审查三项已在周检记录中形成结论 |
+| 非关键治理补漏转入维护 | ✅ 已完成 | 2026-03-12 | 后续按周检机制持续跟踪，不再阻塞本阶段收口 |
## 质量控制检查点
@@ -114,6 +116,14 @@
> 说明：本表中的历史记录按当时原始表述保留；当前正式数据库口径统一以“达梦数据库 8.0+”为准。
+| 2026-03-12 | OMX 任务路由样例落地 | 1）新增 `docs/design/00_Management/17_OMX_Task_Routing_Examples.md`，给出 `REV-004`、`REV-003` 与正式文档修订三类任务的 leader / explorer / executor / verifier 分工模板；2）补充各 lane 的提示词模板、推荐执行顺序与不建议的并行方式；3）更新 `00_Management/README.md` 收录该文档入口。 | 用户希望在治理层之外，再拿到针对当前项目可以直接复用的多 Agent 分工模板，而不是只看抽象原则。 | 正面影响，OMX 从“有规则”变成“可直接照着分工执行”；后续在 `REV-004`、`REV-003` 等闭环中可直接套用 lane 拆分，减少 leader 临时编排成本。 |
+| 2026-03-12 | OMX 多 Agent 治理层落地 | 1）在根 `AGENTS.md` 中新增 OMX 多 Agent 协作补充，明确分层 AGENTS、任务路由矩阵、写冲突规则、范围控制基线与 worktree/tmux 约定；2）新增 `backend/AGENTS.md`，固化 backend 开发边界、最小实现策略与 BPM 接入规则；3）新增 `docs/design/04_Appendix/Archive/AGENTS.md`，明确 Archive 默认只读与来源回写规则；4）新增 `docs/design/00_Management/16_OMX_Multi_Agent_Guide.md`，统一 leader / writer / executor / verifier 分工与协作拓扑；5）更新 `00_Management/README.md` 收录新指南入口。 | 用户明确准备采用 `oh-my-codex` 进行多 Agent 开发，需要对现有 AGENTS 体系做分层化和路由化改造，避免现有规则在 Team Mode 下失效。 | 正面影响，当前项目从“单 agent 规则完备”提升为“多 agent 可控协作”；后续接入 OMX 时，目录级职责、写权限边界、范围基线与会话约定已经成型，可显著降低并发改稿和多 worker 写冲突风险。 |
+| 2026-03-12 | REV-004 一期执行手册与 worktree/tmux 启动脚本落地 | 1）新增 `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，将 `REV-004` 一期的范围、现状差距、最小改动方案、任务拆解、Codex Prompt 与验收清单固化为可执行手册；2）新增 `scripts/start-backend-codex-session.sh`，支持在 `backend/` 上创建或复用 worktree，并拉起 `tmux + codex` 三窗口开发会话；3）更新 `scripts/README.md` 记录脚本用途。 | 用户要求不仅给建议，还要把“如何规划执行、如何进入 worktree、如何在 tmux 场景下协作”落成可直接使用的资产。 | 正面影响，开发启动动作从“口头建议”变为“可复制执行”；后续围绕 `REV-004/REV-003/REV-008` 的闭环开发可直接复用该脚本和手册，降低 worktree、tmux、Codex 协作的起步成本与操作偏差。 |
+| 2026-03-13 | REV-004 一期范围正式文档收敛（US1） | 1）更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md`，将 REV-004 一期范围收敛为水量调整、金额调整、退款、冲正、坏账申请五类场景，并明确共性能力优先顺序、排除项与审批边界；2）重写 `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，将其从 backend 执行导向收敛为正式文档修订执行手册；3）同步 `docs/design/01_Overview/03_Summary_Design.md` 与 `specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md` 的范围摘要与追溯说明；4）执行目标文档 `make validate-file` 与 `make check-links` 校验并通过。 | 用户要求在 implement 阶段先完成 REV-004 一期正式文档范围收敛，不把 backend 代码实现写成本轮已完成内容。 | 正面影响，REV-004 一期边界、验收入口与追溯关系已在正式文档体系内闭环，后续 US2/US3 可直接在稳定范围上继续对齐接口、数据库与台账，不再受早期执行手册偏代码导向表述干扰。 |
+| 2026-03-12 | 工作范围对齐 `营业收费管理系统-概要设计说明书20250912` 基线 | 1）将 `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.docx` 转换为 `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md` 并抽取配套图片目录；2）在 `docs/design/01_Overview/03_Summary_Design.md` 补充历史来源对齐说明；3）在 `docs/design/01_Overview/01_System_Overview.md`、`docs/design/00_Management/08_AI_Agent_Maintenance_SOP.md`、`docs/design/00_Management/10_AI_Retrieval_Whitelist.md` 固化“工作范围以主文档与该 Archive 基线交集为准”的控制规则；4）更新 Archive 索引与附录入口。 | 用户明确要求后续工作范围与 `营业收费管理系统-概要设计说明书20250912.md` 对齐，避免设计与开发准备超出当前项目边界。 | 正面影响，后续文档补完、开发拆分和 AI Agent 执行时有了明确的范围控制基线；既能使用该历史稿进行边界收敛，又不会把历史名称、别名编号和旧接口体系直接带回正式主文档。 |
+| 2026-03-12 | `Database/Interface` 迁移闭环 P0 补完 | 对两份技术主文档继续执行旧系统迁移闭环补完：1）在 `docs/design/03_Technical_Design/01_Database_Design.md` 的 `SYS-002 开账、收费与票据表` 后新增“旧系统历史台账迁移与只读查询口径”，明确在线主模型承接范围、历史只读保留范围与迁移验收最低对账口径；2）在 `docs/design/03_Technical_Design/03_Interface_Design.md` 新增“历史查询与迁移校验接口口径”，将历史查询和迁移验收统一挂靠到既有 `IF-REV/CS/METER` 接口族；3）执行两份文档单文件校验并通过。 | 用户同意继续把迁移分析结论同步到数据库和接口主文档，形成从模块正文到技术主稿的闭环。 | 正面影响，`REV/CS/METER` 已补完的迁移口径不再停留在分模块正文，数据库和接口主文档已同步约束“哪些进在线模型、哪些保留历史只读、验收时按什么口径对账”；本周开发与迁移评审可直接以主文档为准，减少实现阶段对旧系统细粒度对象的误判。 |
+| 2026-03-12 | `REV/CS/METER` 旧系统迁移缺口 P0 补完 | 基于 `docs/design/00_Management/15_Legacy_Migration_Gap_Analysis.md`，对三份分模块详细设计执行旧系统迁移口径补完：1）`12_REV_Detailed.md` 增补定额共享/核定、特殊开账、柜台结账、红冲、发票关系、催缴停水、银行托收与微信配置等迁移说明；2）`13_CS_Detailed.md` 增补业务进度、开票方式变更、微客服后台设置与业务字段配置，并补充对应核心数据与接口映射；3）`14_METER_Detailed.md` 增补业务清单、上报清单、问题回填、代办工单、停复水工单、水表检定及出入退废库等迁移设计；4）执行三份文档单文件校验并通过。 | 用户要求按迁移差异清单继续推进，把本周开发前必须补齐的 `REV/CS/METER` 模块缺口收敛为可开发设计。 | 正面影响，营收、客户服务、表务三大业务链路已从“主能力存在但迁移承接不足”提升为“旧功能承接方式、历史保留策略、实现入口与接口映射可追溯”；本周围绕账务、渠道、工单联动启动开发时，缺少旧系统语义承接导致的返工风险显著降低。 |
+| 2026-03-12 | 新增旧系统迁移差异分析与 P0 补完清单 | 新增 `docs/design/00_Management/15_Legacy_Migration_Gap_Analysis.md`，形成三项可直接用于评审和开发准备的输出：1）旧系统功能迁移差异清单；2）旧表/旧菜单 → 新模块映射矩阵；3）P0 必补章节清单；同时更新 `docs/design/00_Management/README.md` 增加迁移治理入口。 | 用户要求从“旧系统迁移”视角重新审视当前正式设计，明确功能缺口、历史数据承接和本周开发前必须补完的章节。 | 正面影响，迁移讨论从“有没有功能”提升到“旧功能如何承接、历史查询如何保留、哪些章节必须先补”的可执行层；可直接支撑本周开发拆分、评审和割接准备。 |
| 2026-03-12 | `03_Interface_Design` 补齐 SYS-002 高优先接口字段定义 | 对 `docs/design/03_Technical_Design/03_Interface_Design.md` 补齐本周开发所需的高优先 `SYS-002` 接口定义：1）新增 `IF-REV-007/009/012`、`IF-CS-001/002/004`、`IF-METER-001/003/004`、`IF-INST-001/002/004/005` 的关键接口说明；2）补齐上述接口的字段级请求/响应定义；3）统一请求字段、响应字段、主表映射和结果状态口径；4）将主文档 `last_reviewed` 更新为 `2026-03-12`。 | 用户明确要求优先补齐 `SYS-002` 文档内容，以便本周直接启动开发。 | 正面影响，接口主文档从“模块说明齐全但字段定义局部缺失”提升为“开发可直接参照”的状态；开发时能直接按接口字段、状态枚举和主表映射拆分 Controller/Service/VO，减少反复追问和返工。 |
| 2026-03-12 | `15_INST_Detailed` 结构对齐补完（模板同步） | 对 `docs/design/02_Detailed_Design/15_INST_Detailed.md` 执行与 `REV/CS/METER` 同步的结构化补完：1）新增“报装模块统一约束”与“接口与数据追溯矩阵”；2）为 `INST-001~INST-005` 补充核心数据、接口映射与落地边界；3）为 `INST-001/002/003` 增加申请、踏勘、施工验收流程图；4）明确 `biz_process*`/`biz_content*` 为当前实现态口径，`installation_*` 为专题扩展口径。 | 用户要求优先补齐 `SYS-002` 文档内容，形成本周可直接支撑开发的闭环模块。 | 正面影响，`SYS-002` 四大业务模块正文结构统一，报装链路从受理到归档的开发边界更清晰；实现态与设计态口径分离后，可减少开发阶段对专题扩展表的误读。 |
| 2026-03-11 | `14_METER_Detailed` 结构对齐补完（模板同步） | 对 `docs/design/02_Detailed_Design/14_METER_Detailed.md` 执行与 REV/CS 同步的结构化补完：1）新增“表务模块统一约束”与“接口与数据追溯矩阵”；2）为 `METER-001~METER-004` 补充核心数据、接口映射与落地边界；3）为 `METER-002` 增加工单处理流程图；4）为 `METER-004` 补充关键规则，明确 IoT 数据进入营收开账链路前的校验与异常处理边界。 | 用户要求继续同步分模块正文模板，提升表务模块评审可读性与跨文档追溯一致性。 | 正面影响，表务模块从简要提纲升级为可交付的结构化详细设计，设备档案、工单、库存、物联网接入与营收系统的协同边界更清晰，可降低联调与后续维护中的口径偏差。 |
diff --git a/docs/design/00_Management/03_Task_Checklist.md b/docs/design/00_Management/03_Task_Checklist.md
index 6fb95e6..dab7502 100644
--- a/docs/design/00_Management/03_Task_Checklist.md
+++ b/docs/design/00_Management/03_Task_Checklist.md
@@ -138,6 +138,80 @@
## ✅ 最新完成任务 (持续更新)
+### 📋 OMX 任务路由样例
+
+- [x] **完成 OMX 任务路由样例落地** ✅ (2026-03-12)
+ - [x] 新增 `17_OMX_Task_Routing_Examples.md`，补充 `REV-004` 样例 ✅
+ - [x] 补充 `REV-003` 样例与文档修订样例 ✅
+ - [x] 补充 leader / explorer / executor / verifier 提示词模板 ✅
+ - [x] 更新 `00_Management/README.md` 与 `01_Project_Progress.md` 入口和变更记录 ✅
+
+### 📋 OMX 多 Agent 治理层
+
+- [x] **完成 OMX 多 Agent 治理层落地** ✅ (2026-03-12)
+ - [x] 在根 `AGENTS.md` 增加多 Agent 路由、并发与范围控制规则 ✅
+ - [x] 新增 `backend/AGENTS.md`，固化 backend 闭环开发边界 ✅
+ - [x] 新增 `docs/design/04_Appendix/Archive/AGENTS.md`，固化 Archive 默认只读与回写要求 ✅
+ - [x] 新增 `docs/design/00_Management/16_OMX_Multi_Agent_Guide.md`，明确角色分工、冲突规避与 worktree/tmux 约定 ✅
+ - [x] 更新 `00_Management/README.md` 与 `01_Project_Progress.md` 记录入口和变更 ✅
+
+### 📋 REV-004 执行资产落地
+
+- [x] **完成 REV-004 一期执行手册与启动脚本落地** ✅ (2026-03-12)
+ - [x] 新增 `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，固化范围、最小改动方案、任务拆解与验收清单 ✅
+ - [x] 新增 `scripts/start-backend-codex-session.sh`，支持 backend worktree + tmux + Codex 启动 ✅
+ - [x] 在 `scripts/README.md` 登记启动脚本用途 ✅
+ - [x] 在 `01_Project_Progress.md` 记录本次执行资产落地 ✅
+- [x] **完成 REV-004 一期范围正式文档收敛（US1）** ✅ (2026-03-13)
+ - [x] 更新 `12_REV_Detailed.md`，明确一期仅保留水量调整、金额调整、退款、冲正、坏账申请五类场景 ✅
+ - [x] 重写 `REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，明确执行范围、验收入口、最小校验动作与台账触发条件 ✅
+ - [x] 同步 `03_Summary_Design.md` 与 `rev004-traceability-matrix.md` 的范围摘要、接口入口与审批边界说明 ✅
+ - [x] 完成 `make validate-file` 与 `make check-links` 最小校验，并在 `01_Project_Progress.md` 回写重要进展 ✅
+- [x] **完成 REV-004 接口与数据口径对齐（US2）** ✅ (2026-03-13)
+ - [x] 更新 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md`，统一 REV-004 场景规则、接口字段与物理承接口径 ✅
+ - [x] 同步 `data-model.md`、`if-rev-007-accounting-request.md`、`rev004-scenario-matrix.md`、`rev004-traceability-matrix.md` 的共享实体与追溯口径 ✅
+ - [x] 完成 `make validate-file` 与 `make check-links` 最小校验，满足 US2 独立评审与验收条件 ✅
+- [x] **完成 REV-004 可执行交付闭环固化（US3）** ✅ (2026-03-13)
+ - [x] 执行手册已明确后续任务拆解顺序：执行手册闭环 → 支撑产物同步 → 台账按触发条件更新 ✅
+ - [x] 独立验收入口已限定为 `REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`、`01_Project_Progress.md`、`03_Task_Checklist.md` 三份文件 ✅
+ - [x] 最小校验动作与 tracked task 完成条件已明确，可继续按后续 tasks 拆解推进 ✅
+
+### 📋 工作范围基线对齐
+
+- [x] **完成工作范围与 `营业收费管理系统-概要设计说明书20250912` 对齐固化** ✅ (2026-03-12)
+ - [x] 将 `营业收费管理系统-概要设计说明书20250912.docx` 转换为 Markdown 并抽取配套图片目录 ✅
+ - [x] 在 `03_Summary_Design.md` 补充历史来源对齐说明，明确历史稿只作范围基线 ✅
+ - [x] 在 `01_System_Overview.md` 固化“可直接推进 / 需确认 / 默认不做”的范围控制规则 ✅
+ - [x] 在 `08_AI_Agent_Maintenance_SOP.md` 与 `10_AI_Retrieval_Whitelist.md` 固化 AI Agent 范围判断规则 ✅
+ - [x] 更新 `01_Project_Progress.md`、Archive 标签索引与附录入口说明 ✅
+
+### 📋 旧系统迁移差异清单与映射矩阵
+
+- [x] **完成旧系统迁移差异与 P0 补完清单整理** ✅ (2026-03-12)
+ - [x] 新增 `15_Legacy_Migration_Gap_Analysis.md`，输出旧系统功能迁移差异清单 ✅
+ - [x] 形成“旧表/旧菜单 → 新模块”映射矩阵，区分已覆盖/部分覆盖/缺失 ✅
+ - [x] 从“保留重做 / 能力合并 / 历史只读 / 确认下线”四类收敛迁移判断 ✅
+ - [x] 输出 `REV/CS/METER/Database/Interface` 的 P0 必补章节清单 ✅
+ - [x] 更新 `00_Management/README.md` 与 `01_Project_Progress.md` 记录本次动作 ✅
+
+### 📋 `REV/CS/METER` 迁移缺口补完
+
+- [x] **完成账务、客户服务、表务三大模块迁移口径补完** ✅ (2026-03-12)
+ - [x] 在 `12_REV_Detailed.md` 补充定额、开账、结账、发票、催缴、托收、微信配置等旧系统承接说明 ✅
+ - [x] 在 `13_CS_Detailed.md` 补充业务进度、开票方式变更、微客服后台配置与业务字段配置说明 ✅
+ - [x] 在 `14_METER_Detailed.md` 补充业务清单、问题回填、停复水工单、水表检定及库存流转说明 ✅
+ - [x] 补充对应核心数据表与接口映射，避免“功能有描述但无落地入口” ✅
+ - [x] 执行三份文档 `make validate-file` 校验并通过 ✅
+
+### 📋 `Database/Interface` 迁移闭环补完
+
+- [x] **完成数据库与接口主文档迁移闭环补完** ✅ (2026-03-12)
+ - [x] 在 `01_Database_Design.md` 新增“旧系统历史台账迁移与只读查询口径” ✅
+ - [x] 明确在线主模型承接范围、历史只读保留范围与迁移验收最低对账口径 ✅
+ - [x] 在 `03_Interface_Design.md` 新增“历史查询与迁移校验接口口径” ✅
+ - [x] 将历史查询统一挂靠到既有 `IF-REV/CS/METER` 接口族，不额外发明新编号体系 ✅
+ - [x] 执行两份技术主文档 `make validate-file` 校验并通过 ✅
+
### 📋 `03_Interface_Design` 高优先接口字段补完
- [x] **完成 `SYS-002` 本周开发高优先接口字段定义补齐** ✅ (2026-03-12)
@@ -490,30 +564,42 @@
## 📅 第三阶段任务 (文档优化)
-### 📋 文档格式优化
+> 当前状态：**已完成**。
+> 第3阶段已完成台账校准、审查闭环与问题归口修复，后续非关键补漏转入例行周检与持续维护，不再计入本阶段未完成项。
-- [ ] **目录结构标准化**
- - [ ] 统一各文档的目录格式
- - [ ] 添加章节编号
- - [ ] 生成文档导航
+### 📋 已完成基础项
-- [ ] **交叉引用建立**
- - [ ] 建立文档间的链接
- - [ ] 添加术语表和缩略语
- - [ ] 创建文档索引
+- [x] **主文档导航与稳定锚点收敛** ✅
+ - [x] 概要、数据库、接口、安全、部署等主文档已统一为“章节导航（精简）+ `sec-*` 稳定锚点” ✅
+ - [x] 超长主文档已具备快速跳转入口 ✅
-### 📋 质量检查清单
+- [x] **索引与检索入口建立** ✅
+ - [x] 已建立 `11_Main_Doc_Chapter_Index.md` 主文档导航索引 ✅
+ - [x] 已建立 `02_Module_Traceability_Index.md` 模块 → 接口 → 数据域追溯索引 ✅
+ - [x] 已建立 `10_AI_Retrieval_Whitelist.md` 检索分层白名单 ✅
-- [ ] **技术审查**
- - [ ] 架构合理性审查
- - [ ] 技术方案可实施性验证
- - [ ] 数据库设计规范性检查
- - [ ] 接口设计一致性检查
+- [x] **术语与范围主入口收敛** ✅
+ - [x] 已由 `01_System_Overview.md` 统一承担范围控制、术语与缩略语主入口 ✅
+ - [x] 已明确 Archive 历史资料仅作来源与核对依据，不作为新的正式主稿 ✅
-- [ ] **业务审查**
- - [ ] 功能完整性确认
- - [ ] 业务流程正确性验证
- - [ ] 异常处理完备性检查
+### 📋 已完成闭环项
+
+- [x] **技术审查结论回写** ✅
+ - [x] 架构合理性审查已形成明确结论 ✅
+ - [x] 技术方案可实施性验证已形成明确结论 ✅
+ - [x] 数据库设计规范性检查已形成明确结论并完成问题修复 ✅
+ - [x] 接口设计一致性检查已形成明确结论 ✅
+
+- [x] **业务审查结论回写** ✅
+ - [x] 功能完整性确认已形成明确结论 ✅
+ - [x] 业务流程正确性验证已形成明确结论 ✅
+ - [x] 异常处理完备性检查已形成明确结论 ✅
+
+### 📋 后续维护说明
+
+- [x] **非关键治理补漏转入例行维护** ✅
+ - [x] 后续审查发现的问题继续按唯一主文件归口整改 ✅
+ - [x] 非关键的美化、补充和索引微调不再阻塞第3阶段收口 ✅
## 🏷️ 任务标记说明
@@ -545,16 +631,18 @@
### 第三阶段 (文档优化)
-- 总任务数：**8**
-- 已完成：**8** ✅
+- 总任务数：**10**
+- 已完成：**10** ✅
- 进行中：**0** 🔄
- 未开始：**0** ⏳
- **完成率：100%**
+> 说明：第3阶段已完成台账一致性校准、技术审查与业务审查结论回写，以及唯一待修问题归口与修复；后续非关键优化转入例行维护。
+
### 整体项目进度
-- 总任务数：**132** (原120 + 新增12个概要设计标准化任务)
-- 已完成：**132** ✅
+- 总任务数：**134**
+- 已完成：**134** ✅
- 进行中：**0** 🔄
- 未开始：**0** ⏳
- **整体完成率：100%**
@@ -654,11 +742,11 @@
- [x] **thirdpay_binding** (第三方绑定表) - 13个字段 ✅
- [x] **thirdpay_transaction** (第三方支付交易表) - 17个字段 ✅
-## 🎉 项目完成总结
+## 🎉 项目阶段性总结
-### ✅ 所有核心任务已完成
+### ✅ 主体建设已完成，当前进入第3阶段收口
-**恭喜！福建水务营收系统概要设计文档项目已圆满完成！**
+**福建水务营收系统文档体系的基础治理、主稿收敛、索引导航与检索分层已基本完成，当前重点为第3阶段审查闭环与台账收口。**
#### 🏆 项目成果亮点
diff --git a/docs/design/01_Overview/03_Summary_Design.md b/docs/design/01_Overview/03_Summary_Design.md
index e328fa5..7c85812 100644
--- a/docs/design/01_Overview/03_Summary_Design.md
+++ b/docs/design/01_Overview/03_Summary_Design.md
@@ -4,7 +4,7 @@ doc_role: master_document
authority: primary
scope: 概要设计
source_of_truth: true
-last_reviewed: 2026-03-11
+last_reviewed: 2026-03-12
retrieval_priority: P0
---
@@ -32,7 +32,7 @@ retrieval_priority: P0
| 【√】草稿 | | |
| 【】修改稿 | | |
| 【】正式发布 | | |
-| | **当前版本：** | **V1.6** |
+| | **当前版本：** | **V1.7** |
| | **作者：** | **唐伟杰** |
| | **完成日期：** | **2025-08-18** |
@@ -47,6 +47,7 @@ retrieval_priority: P0
| 2025-08-01 | V1.4 | 唐伟杰 | 单点登录采用OAuth2.0+CAS协议：更新单点登录模块描述，强调基于OAuth2.0+CAS协议实现。 |
| 2025-08-18 | V1.5 | 唐伟杰 | 架构调整：将营收业务系统中的工单、表务、报装剥离为独立子系统（SYS-005/006/007），更新目录、功能范围、子系统列表、关系图与接口定义；保留客户服务模块在营收业务系统中的作用。 |
| 2025-08-18 | V1.6 | 唐伟杰 | 合并第三方支付能力至SYS-009"支付与银行结算子系统"，统一消息服务重编号为SYS-010；更新总体目标、功能范围、接口定义、子系统列表与相关架构图。 |
+| 2026-03-12 | V1.7 | 唐伟杰 | 对照 `Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md` 完成来源对齐：补充历史来源说明与引用路径，确认系统拆分、基础服务定位、外部集成与非功能约束已同步；保留当前正式系统名称、模块编号与接口编号标准，不沿用历史别名编码作为正式口径。 |
@@ -111,6 +112,28 @@ retrieval_priority: P0
- 《RuoYi-Vue-Pro技术架构文档》
- 《Spring Cloud微服务架构设计指南》
- 《福建水务营收系统需求规格说明书》
+- `../04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md`
+
+## 历史来源对齐说明
+
+本主文档已对齐 `../04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md` 中对当前正式设计仍有效的内容，主要包括：
+
+- 子系统拆分口径：`SYS-001 ~ SYS-010` 的职责边界、基础服务分层与跨系统协同关系。
+- 业务范围口径：营收、微网厅、工单、表务、报装、发票、支付结算、消息等范围定义。
+- 架构与集成口径：外部支付、银行、税控、消息、摄像表 AI 等外部协同边界。
+- 非功能口径：达梦数据库 8.0+、物理部署、可靠性、安全与扩展性方向。
+
+以下内容仅保留在 Archive 中作为历史来源，不直接作为当前正式主文档口径：
+
+- 历史系统名称“营业收费管理系统”等旧标题写法。
+- 历史别名编码，如 `UP-SSO`、`REV-CUSTOM`、`WECHAT-*`。
+- 历史接口编号体系，如 `IF-S-*`、`IF-C-*`。
+
+当前正式口径继续统一采用：
+
+- 系统名称：`福建水务营收系统`
+- 模块编号：`UP-001`、`REV-001`、`CS-001`、`METER-001`、`INST-001`
+- 接口编号：`IF-UP-*`、`IF-REV-*`、`IF-CS-*`、`IF-METER-*`、`IF-INST-*`、`IF-EXT-*`
@@ -1725,7 +1748,7 @@ graph TD
- **客户资料管理**：客户档案建立、信息维护、分组管理
- **抄表开账**：抄表数据录入、复核确认、自动开账
- **营业收费**：柜台收费、移动收费、在线缴费
-- **账务处理**：账务调整、退款处理、坏账管理
+- **账务处理**：一期先聚焦水量调整、金额调整、退款、冲正、坏账申请，统一经 `IF-REV-007` 承接，并按共性能力先统一、场景能力再分批推进
- **发票管理**：发票开具、查询、重开、作废
- **催缴管理**：欠费统计、催缴通知、停水管理
- **统计分析**：多维度数据统计和报表分析
diff --git a/docs/design/02_Detailed_Design/12_REV_Detailed.md b/docs/design/02_Detailed_Design/12_REV_Detailed.md
index 7731295..49eb820 100644
--- a/docs/design/02_Detailed_Design/12_REV_Detailed.md
+++ b/docs/design/02_Detailed_Design/12_REV_Detailed.md
@@ -94,6 +94,26 @@ retrieval_priority: P1
- `biz_cust_no_rule`：客户编号规则。
- `biz_cust_hub_marks`：集收号/集收标记关系。
+### 迁移补充（旧系统承接）
+
+#### 定额共享
+
+- 旧系统在“客户资料”下提供定额主客户、子客户绑定与共享清单管理能力。
+- 当前正式设计不新增并行主模型，统一归入客户与计划用水方案关系对象承接。
+- 迁移时必须至少保留主客户、子客户、绑定状态、生效时间、解除时间、备注与操作留痕，确保共享清单可查询、可解绑、可追溯。
+
+#### 定额核定
+
+- 旧系统支持对已建立共享关系的客户执行定额核定、撤销核定和共享清单联查。
+- 当前建议以客户关系对象和计划用水方案关系为主承接核定结果，不额外发明独立账务主表。
+- 核定结果迁移后应支持按客户、站点、核定状态、核定时间查询，并保留核定依据、操作人和变更留痕。
+
+#### 批量修改
+
+- 旧系统已形成“手工修改 + 模板导入修改”的双模式客户资料维护能力。
+- 当前正式设计应将其视为客户主数据治理能力的一部分，而不是临时导入工具。
+- 迁移时需明确三类口径：可批量修改字段范围、导入模板校验规则、批量修改审计留痕；历史批量修改结果至少需保留任务来源、修改字段、执行结果和失败原因。
+
### 接口映射
- `IF-REV-001`：客户档案、账户状态、联系人与水表绑定关系查询。
@@ -156,6 +176,20 @@ flowchart TD
- `biz_cost_component`：费用组成。
- `biz_water_use_scheme`、`biz_water_use_scheme_tier`：计划用水方案与阶梯。
+### 迁移补充（旧系统承接）
+
+#### 特殊开账
+
+- 旧系统支持在非标准客户、无码客户或罚款类场景下直接开账。
+- 新系统仍以 `biz_charge`、`biz_charge_detail` 作为开账结果承载对象，不建议额外平行建设“特殊开账账表”。
+- 迁移与新建场景均需保留特殊开账来源、业务类型、经办人、依据说明、打印状态与后续收费关联，避免与普通抄表开账混淆。
+
+#### 开账记录迁移
+
+- 旧系统“开账记录”是历史查询与账务核对的核心入口，必须纳入迁移最小保留集。
+- 迁移后的开账记录应至少支持按站点、账务年月、册本、客户、抄表员、欠费状态查询，并支持统计水量、总金额及费用构成。
+- 对已收费、已作废、销户拆表、特殊开账等旧状态，不要求照搬旧表结构，但必须保留可对照的新状态映射关系。
+
### 接口映射
- `IF-REV-004`：抄表数据提交与异常标记。
@@ -210,6 +244,26 @@ flowchart TD
- `bk_transaction_callback`：支付回调记录。
- `bk_transaction_exception`：支付异常记录。
+### 迁移补充（旧系统承接）
+
+#### 柜台结账
+
+- 旧系统将“柜台收费”和“柜台结账”拆分为两个菜单，结账阶段包含未结/已结查询、结账红冲、追加抄表和打印动作。
+- 当前设计可继续采用统一收费核销模型，但必须补出“收费记录 → 班结结果 → 打印/红冲/查询”的业务闭环，避免柜面日终处理缺口。
+- 迁移时需保留结账时间、结账人、网点、收费汇总口径和结账后红冲痕迹，保证财务对账与审计连续。
+
+#### 账单打印服务
+
+- 旧系统存在账单打印、补打、打印次数控制与打印记录查询能力。
+- 新系统不要求单独建立打印主模块，但必须明确打印模板、补打权限、打印状态与打印留痕的承接关系。
+- 对历史账单迁移，应允许基于账单主明细和打印配置恢复打印视图，避免割接后只能查账不能补打。
+
+#### 红冲记录
+
+- 旧系统支持红冲记录查询、导出与明细展开，是收费差错追溯的重要入口。
+- 当前设计可将红冲视为收费核销后的修正场景，不强制要求独立实体表，但必须提供历史只读查询口径。
+- 红冲迁移最小保留信息应包括原收费记录、红冲时间、红冲金额、原因、经办人、关联账单和后续账务状态。
+
### 接口映射
- `IF-REV-006`：创建收费记录、执行账单核销并回写状态。
@@ -227,7 +281,9 @@ flowchart TD
### 功能说明
-承担水量调整、金额调整、违约金减免、退款、冲正、呆坏账申请等账务修正与审批处理能力，保证收费后账务结果可追溯、可审计。
+REV-004 一期仅覆盖水量调整、金额调整、退款、冲正、坏账申请五类场景，统一挂靠 `IF-REV-007` 作为账务处理入口，目标是在既有正式文档体系内先收敛范围、承接口径、留痕要求与审批边界。
+
+本阶段按“共性能力先统一、场景能力再分批”组织：先统一账单承接、原交易校验、结果表达、操作留痕与审批边界，再分别展开五类场景。违约金减免、分账调整、价差调整、跨周期水量、预存退款细表等内容仅作为旧系统迁移语义或后续扩展参考，不作为一期新增独立范围。
### 业务流程
@@ -244,26 +300,44 @@ flowchart TD
### 关键规则
-1. 调整类操作以营业账主明细为基础，并通过日志与审批留痕记录前后变化。
-2. 水量调整、金额调整、优惠调整等场景可引用价格模板、阶梯与优惠对象重新计算。
-3. 退款、冲正等交易修正需与原支付流水及渠道状态联动校验。
-4. 对于当前未见明确独立实体表的特账、跨周期水量、退款账等对象，文档以“业务处理场景”表述，不强行落为已实现表。
+1. 一期场景严格限定为水量调整、金额调整、退款、冲正、坏账申请，不扩展到其他接口族或独立账务台账重构。
+2. 所有场景均以 `biz_charge` / `biz_charge_detail` 为主承接对象，并通过 `biz_operat_log` / `biz_operat_log_detail` 记录处理依据、前后变化和责任归属。
+3. 退款、冲正必须联动 `bk_transaction`、`bk_transaction_callback`、`bk_transaction_exception` 等原支付流水及渠道状态校验，不允许仅依据账单状态直接处理。
+4. 接口结果统一返回 `resultStatus`、`writeBackStatus`，其中 `resultStatus` 表示处理结论，`writeBackStatus` 表示账单状态回写结论，两者不得混用。
+5. 审批相关内容一期仅保留 `approvalRequired`、`PENDING_APPROVAL` 与审批边界说明，不展开完整 BPM 流程、节点、流转规则或审批回写实现细节。
+6. 对于当前未见明确独立实体表的特账、跨周期水量、退款账等对象，文档以“业务处理场景”表述，不强行落为已实现表。
### 核心数据
-- `biz_charge`、`biz_charge_detail`：账务调整的核心对象。
+- `biz_charge`、`biz_charge_detail`：账务调整的核心对象，承接调整前后账单主明细状态。
+- `bk_transaction`、`bk_transaction_callback`、`bk_transaction_exception`：退款、冲正场景的原交易校验与异常追溯对象。
- 价格调整/优惠相关表：用于重算账单或差额追溯。
-- `biz_operat_log`、`biz_operat_log_detail`：操作与变更留痕。
+- `biz_operat_log`、`biz_operat_log_detail`：操作与变更留痕，记录字段差异、处理说明、附件依据与责任归属。
### 主要场景
| 场景 | 说明 | 控制要点 |
|---|---|---|
| 水量调整 | 更正异常水量 | 需复核原因、附件和原抄表依据 |
-| 金额调整 | 更正账单金额 | 需记录依据、差异金额和审批链路 |
-| 退款处理 | 退回客户支付资金或预存款 | 需校验原交易、退款余额与幂等性 |
-| 错误缴费冲正 | 修正误收/误核销记录 | 需关联原交易与账单状态 |
-| 呆坏账申请 | 对长期欠费进行分类处理 | 需结合账龄、客户状态与审批结果 |
+| 金额调整 | 更正账单金额 | 需记录依据、差异金额和审批边界 |
+| 退款 | 退回客户支付资金或预存款 | 需校验原交易、退款余额与幂等性 |
+| 冲正 | 修正误收/误核销记录 | 需关联原交易与账单状态 |
+| 坏账申请 | 对长期欠费进行分类处理 | 需结合账龄、客户状态与审批边界 |
+
+### 迁移补充（旧系统承接）
+
+| 旧账务对象 | 当前承接方式 | 迁移口径 |
+|---|---|---|
+| 预存退款 / 预存退款详情 | 作为账务处理场景承接 | 保留申请单、原支付引用、退款结果与审批留痕 |
+| 已销调整汇总 / 明细 | 作为已收费后修正场景承接 | 保留原账单、调整原因、前后差异、处理结果 |
+| 价差调整汇总 / 明细 | 作为重算与差额修正场景承接 | 保留原价格口径、新价格口径、差额和生效时间 |
+| 分账调整汇总 / 明细 | 作为费用组成重分摊场景承接 | 保留原分摊结果、调整后结果、责任人和审批链 |
+| 账单-违约金减免 | 作为滞纳金修正场景承接 | 保留减免原因、减免金额、审批结果和生效时间 |
+| 账单-呆坏账 | 作为坏账申请与生效场景承接 | 保留账龄、申请原因、审批结果、核销状态 |
+
+1. P0 阶段不要求为每一类旧账务台账都新增独立实体表，但必须在业务对象和历史查询层形成可追溯闭环。
+2. 旧系统精细台账迁移后至少保留：原单据标识、原账单标识、处理类型、处理原因、处理前后金额/水量、申请/审批/生效时间、经办人与附件依据。
+3. 与支付、发票、渠道回调强关联的处理场景，必须保留与原交易、原发票、原收费记录的关联关系，避免后续对账和审计断链。
### 接口映射
@@ -310,6 +384,12 @@ flowchart TD
- `biz_invoice_taxrate`：税率配置。
- `biz_cust_invoice`：客户开票信息。
+### 迁移补充（旧系统承接）
+
+- 旧系统数据字典中存在“发票明细表、营业账开票表、开票配置表”等更细粒度对象。
+- 当前正式设计已明确主承接对象为 `biz_invoice`、`biz_invoice_taxrate`、`biz_cust_invoice`，但迁移时不能忽略旧开票明细和账单关联关系。
+- P0 阶段建议先补三类迁移口径：账单与发票的关联关系、发票申请与结果回写记录、开票配置与税率的有效期；未确认已落地的细表对象仍按“历史只读或辅助映射”处理。
+
### 接口映射
- `IF-REV-008`：营收侧发票申请与票据状态查询。
@@ -353,6 +433,23 @@ flowchart TD
- `biz_charge`、`biz_charge_detail`：催缴对象来源。
- 催缴结果与通知日志：通过业务状态与消息结果联动留痕。
+### 迁移补充（旧系统承接）
+
+#### 催缴记录
+
+- 旧系统支持催缴记录查询、导出和明细展开，记录中包含推送内容、号码、方式、结果等信息。
+- 新系统可继续以消息协同结果和账单状态联动承接，但必须明确催缴记录查询口径，而不能仅保留“已发送/未发送”状态。
+
+#### 停水记录
+
+- 停水记录不是孤立账务对象，应由催缴结果、业务处置和现场执行工单共同形成闭环。
+- 迁移后需支持按客户、站点、停水原因、停水时间、复水状态查询，并能追溯到对应欠费账单和工单执行结果。
+
+#### 预存短信
+
+- 旧系统对预存款余额不足客户提供短信推送和发送记录查询。
+- 新系统建议将其纳入催缴与通知统一策略，不再单建平行模型，但必须保留触发条件、发送内容、发送结果和补发记录。
+
### 接口映射
- `IF-REV-009`：催缴名单生成、任务下发与执行结果返回。
@@ -436,6 +533,20 @@ flowchart TD
- `bk_transaction`、`bk_transaction_callback`、`bk_transaction_exception`：交易、回调、异常。
- `biz_collection`、`biz_withholding`：代收/代扣业务主对象。
+### 迁移补充（旧系统承接）
+
+#### 银行托收
+
+- 旧系统“银行托收”菜单重点承接托收送盘、托收信息查询和托收结果回看。
+- 当前设计已形成 `biz_collection` + `bk_*` 渠道模型，迁移时应补出“旧托收菜单 → 托收批次/交易/回盘结果”的映射，而不是按旧菜单名平移建模。
+- 旧托收历史记录应至少保留送盘批次、客户范围、送盘结果、回盘结果和账单核销结果。
+
+#### 实时收费查询与对账
+
+- 旧系统“实时收费”更偏运营查询和渠道对账入口，不只是支付成功回写。
+- 当前建议以 `bk_transaction*` 作为主承接对象，并补充按结算日期、银行/渠道、收费结果、差异状态查询和导出能力说明。
+- 对旧“实时收费汇总/日志/明细”对象，P0 阶段先按历史只读查询口径保留，不误写为当前已落地的独立主模型。
+
### 接口映射
- `IF-REV-011`：代扣批次、对账与结算协同入口。
@@ -467,6 +578,13 @@ flowchart TD
- `biz_page_settings`、`biz_page_settings_detail`：页面配置。
- `biz_price_category`、`biz_price_template`、`biz_template_dept_rel`：价格归属与模板站点关系。
- `biz_cust_no_rule`：客户编号规则。
+ - `sys_wechat_app_settings`：微信/微网厅基础配置。
+
+### 迁移补充（旧系统承接）
+
+- 旧系统后台存在“页面配置、业务字段、微信参数、打印维护”等运营配置入口。
+- 当前建议统一按业务参数、页面配置、渠道参数与打印参数归口承接，不新增“微客服后台配置”并行主文档。
+- 迁移时需明确三类配置映射：客户/业务办理字段展示与校验规则、微信/微网厅基础参数、打印模板与补打策略；未确认已实现的高级灰度能力继续按“文档先行”处理。
### 接口映射
diff --git a/docs/design/03_Technical_Design/01_Database_Design.md b/docs/design/03_Technical_Design/01_Database_Design.md
index 8099e9d..df33731 100644
--- a/docs/design/03_Technical_Design/01_Database_Design.md
+++ b/docs/design/03_Technical_Design/01_Database_Design.md
@@ -4,7 +4,7 @@ doc_role: master_document
authority: primary
scope: 数据库设计
source_of_truth: true
-last_reviewed: 2026-03-11
+last_reviewed: 2026-03-12
retrieval_priority: P0
---
@@ -27,7 +27,7 @@ retrieval_priority: P0
| 【 】草稿 | | |
| 【 】修改稿 | | |
| 【√】正式发布 | | |
-| | **当前版本：** | **V1.5** |
+| | **当前版本：** | **V1.6** |
| | **作者：** | **唐伟杰** |
| | **完成日期：** | **2025-08-01** |
@@ -40,6 +40,7 @@ retrieval_priority: P0
| 2025-08-01 | V1.2 | 唐伟杰 | 1. 根据详细设计说明书调整目录结构，按6个子系统重新组织表结构。
2. 补充移动端表设计优化说明，明确移动端与Web端表复用策略。
3. 新增5个移动端特有表的详细设计，符合表设计优化原则。 |
| 2025-08-01 | V1.3 | 唐伟杰 | 数据库系统变更：将OpenGauss替换为达梦数据库 8.0+，作为主力国产数据库方案。 |
| 2025-08-01 | V1.4 | 唐伟杰 | 单点登录采用OAuth2.0协议：新增OAuth2.0相关数据表设计，包括客户端信息表、访问令牌表、刷新令牌表、授权码表。 |
+| 2026-03-12 | V1.6 | 唐伟杰 | 补充旧系统历史台账迁移与只读查询口径，明确在线主模型承接范围、历史最小保留集与迁移验收对账基线。 |
# 前言
@@ -52,7 +53,7 @@ retrieval_priority: P0
- **数据库工具**: 使用 Navicat, DBeaver, DataGrip 等主流数据库管理工具。
- **约定**:
- **表名**: 全部小写，单词间使用下划线 `_` 分隔。业务表以 `biz_` 开头，系统管理表以 `system_` 开头。
- - **字段名**: 全部小写，驼峰式命名（如 `userId`），与Java实体类属性保持一致。
+ - **字段名**: 全部小写，单词间使用下划线 `_` 分隔（如 `user_id`），与当前数据库主文档及主表命名口径保持一致。
- **主键**: 统一命名为 `id`，类型为 `bigint`，自增。
- **通用字段**: 所有表必须包含 `id`, `creator`, `create_time`, `updater`, `update_time`, `deleted`, `tenant_id` 字段。
- **字符集**: 统一使用 `utf8mb4` 字符集。
@@ -1095,6 +1096,8 @@ retrieval_priority: P0
| `unit_price` | 单价 |
| `detail_amount` | 明细金额 |
+> REV-004 承接口径：水量调整、金额调整、退款、冲正、坏账申请统一以 `biz_charge`、`biz_charge_detail` 作为账单主明细承接对象；当前数据库主文档不新增独立账务细表来承接一期场景。
+
### biz_collection / biz_withholding (托收与代扣主表)
| 表名 | 关键字段 | 说明 |
| :--- | :--- | :--- |
@@ -1113,8 +1116,51 @@ retrieval_priority: P0
| `biz_operat_log` | `biz_type`, `biz_id`, `operate_user`, `operate_time` | 业务操作主日志 |
| `biz_operat_log_detail` | `log_id`, `field_name`, `before_value`, `after_value` | 字段级变更留痕 |
+> REV-004 留痕口径：`biz_operat_log*` 统一承接账务处理的一期留痕，至少覆盖处理类型、目标账单、原交易引用、处理前后差异、原因说明、附件依据与操作人。
+>
> 边界说明：旧数据字典中的“跨周期水量、特账、红冲、已销调整、呆坏账、实时收费日志”等对象，在当前 backend 范围内未全部识别到独立实体表，数据库专项中统一按业务处理场景描述，不误写为已明确落地的真实表。
+### 旧系统历史台账迁移与只读查询口径
+
+#### 在线主模型承接范围
+
+| 旧对象/旧菜单 | 当前主口径 | 承接方式 | 数据策略 |
+| :--- | :--- | :--- | :--- |
+| 开账记录、特殊开账 | `biz_charge`、`biz_charge_detail`、`biz_operat_log*` | 统一纳入营业账主表与明细表，特殊开账按来源类型、业务类型、依据说明留痕，不单设平行“特殊开账表” | 在线保留 |
+| 柜台收费、实时收费、代收代扣 | `biz_collection`、`biz_withholding`、`bk_transaction*`、`bk_withholding_*` | 统一纳入收费主模型与渠道交易模型，柜台班结/实时收费日志按交易结果和操作留痕归并 | 在线保留 |
+| 发票申请、开票结果、票据税率 | `biz_invoice`、`biz_invoice_taxrate`、`biz_cust_invoice` | 统一纳入发票主表、税率表和客户开票信息，不为旧“营业账开票表”机械复制新在线表 | 在线保留 |
+| 微网厅业务字段、页面配置、微信参数 | `biz_business_types`、`biz_business_datas`、`biz_page_settings*`、`biz_parameter_settings`、`sys_wechat_app_settings` | 统一归并为业务类型、页面配置和渠道参数模型 | 在线保留 |
+| 办理附件、电子档案 | `biz_content`、`biz_content_attach` | 当前新增与迁移后新增资料统一按资料主表与附件表承接 | 在线保留 |
+
+#### 历史只读保留范围
+
+| 历史对象 | 当前正式口径 | 保留策略 | 查询要求 |
+| :--- | :--- | :--- | :--- |
+| 红冲记录、红冲原因、红冲前后账务快照 | 账单状态 + 账务处理场景 + 操作留痕 | 保留历史只读，不强制拆为新主库独立实体表 | 至少支持原单号、红冲单号、金额、原因、经办人、时间查询 |
+| 预存退款、已销调整、价差调整、分账调整、违约金减免、呆坏账明细 | `REV-004` 账务处理业务场景 | 旧细粒度台账以历史只读方式保留；新发生业务由流程与日志承接 | 至少支持汇总、明细、状态、审批结果和关联账单查询 |
+| 柜台结账、打印记录、补打记录 | 收费结果 + 打印/操作留痕 | 旧查询菜单作为历史只读能力保留，不单独建设新结账台账表 | 至少支持班次、营业所、柜员、打印类型、结账状态查询 |
+| 发票明细、营业账开票关系、开票配置快照 | 发票主模型 + 历史关系快照 | 旧细表和配置快照按历史只读保留；新在线模型只保留开票必需主数据 | 至少支持发票号、账单号、开票批次、配置版本和结果状态查询 |
+| 催缴记录、停水记录、预存短信记录 | 催缴/停复水/消息联动业务场景 | 旧记录菜单按历史只读保留，与新通知/工单链路分层承接 | 至少支持客户、账期、催缴方式、执行结果、发送时间查询 |
+| 水表检定、领用、出库、退库、报废单据 | `METER-003` 生命周期场景 | 当前在线主表承接水表状态，旧单据与检定证书按历史只读保留 | 至少支持表号、仓库、单据类型、检定结论、证书编号查询 |
+
+#### 迁移验收最低对账口径
+
+| 对账主题 | 最低核对维度 | 主口径来源 | 验收要求 |
+| :--- | :--- | :--- | :--- |
+| 开账记录 | 客户数、账单数、账期、应收金额 | `biz_charge`、`biz_charge_detail` + 历史账单来源 | 支持按账期、营业所、客户类型汇总比对 |
+| 缴费记录 | 收费笔数、实收金额、渠道、核销状态 | `biz_collection`、`bk_transaction*` | 支持按渠道、日期、营业所汇总比对 |
+| 发票记录 | 开票笔数、金额、状态、票据类型 | `biz_invoice*` + 历史开票关系 | 支持按发票状态、开票日期比对 |
+| 红冲与账务调整 | 调整笔数、调整金额、处理结果 | 账务处理结果 + 历史台账 | 支持汇总与单据级差异定位 |
+| 催缴与停复水 | 通知笔数、执行结果、停复水状态 | 新流程结果 + 历史记录 | 支持按账期、客户、执行状态比对 |
+| 电子档案 | 附件数、附件类型、关联业务单数 | `biz_content_attach` + 历史档案目录 | 支持按业务类型、上传时间、来源系统比对 |
+
+#### 设计约束
+
+- 不以“旧菜单一项对应一张新表”为原则，优先复用当前已确认的 `biz_*`、`bk_*` 在线主模型。
+- 对 backend 当前未识别到独立实体表的旧细粒度台账，仅写为“历史只读查询对象”，不误写为“已存在新在线表”。
+- 历史只读对象必须保留原系统关键标识（原单号、原客户号、原批次号或原附件标识）以支撑迁移验收与问题追溯。
+- 涉及历史附件、影像、高拍仪资料时，正式数据库设计只约束“资料元数据 + 文件引用”口径，不在本轮臆造新的文件表族。
+
## SYS-002 业务办理与资料表 (`biz_process*` / `biz_business_*` / `biz_content*`)
| 表名 | 关键字段 | 说明 |
@@ -1140,6 +1186,8 @@ retrieval_priority: P0
| `bk_transaction` | `trade_no`, `biz_order_no`, `channel_code`, `trade_amount`, `trade_status` | 渠道交易流水 |
| `bk_transaction_callback` | `trade_no`, `callback_time`, `callback_status`, `raw_message` | 回调留痕 |
| `bk_transaction_exception` | `trade_no`, `exception_code`, `exception_desc`, `handle_status` | 异常处理 |
+
+> REV-004 原交易校验口径：退款、冲正场景统一依赖 `bk_transaction*` 校验原交易存在性、状态、回调结果与异常处理状态，数据库专项不再为一期新增平行退款交易表。
| `bk_withholding_agreement` | `agreement_no`, `cust_id`, `channel_code`, `sign_status` | 代扣签约 |
| `bk_withholding_batch` | `batch_no`, `channel_code`, `batch_date`, `batch_status` | 代扣批次 |
| `bk_withholding_item` | `batch_id`, `cust_id`, `charge_id`, `item_status` | 代扣明细 |
diff --git a/docs/design/03_Technical_Design/03_Interface_Design.md b/docs/design/03_Technical_Design/03_Interface_Design.md
index 34c78b4..78f3784 100644
--- a/docs/design/03_Technical_Design/03_Interface_Design.md
+++ b/docs/design/03_Technical_Design/03_Interface_Design.md
@@ -28,6 +28,7 @@ retrieval_priority: P0
- [内部接口设计](#sec-internal-interface)
- [数据对象与表口径](#sec-data-object)
- [接口安全与异常处理](#sec-security-exception)
+- [历史查询与迁移校验接口口径](#sec-migration-readonly)
- [实现状态说明](#sec-status)
@@ -392,8 +393,14 @@ retrieval_priority: P0
| 归属模块 | REV-004 |
| 请求方式 | POST |
| 请求路径 | `/admin-api/revenue/accounting/adjust` |
-| 功能描述 | 发起金额调整、水量调整、退款、冲正、坏账等账务处理 |
-| 核心表 | `biz_charge`、`biz_charge_detail`、`biz_operat_log` |
+| 功能描述 | 发起水量调整、金额调整、退款、冲正、坏账申请五类账务处理，并统一返回处理结果、审批边界与账单回写状态 |
+| 核心表 | `biz_charge`、`biz_charge_detail`、`biz_operat_log`、`bk_transaction*` |
+
+边界约束：
+- 一期仅覆盖 `USAGE`、`AMOUNT`、`REFUND`、`REVERSE`、`BAD_DEBT` 五类 `adjustType`。
+- 退款、冲正必须提供 `sourceTradeNo` 并完成原交易校验；其他场景不得误用支付流水替代业务依据。
+- 审批相关内容仅保留 `approvalRequired`、`PENDING_APPROVAL` 与边界说明，不展开 BPM 节点与审批回写实现细节。
+- `resultStatus` 与 `writeBackStatus` 必须分离表达，前者表示处理结论，后者表示账单状态回写结论。
### IF-REV-008 发票申请接口
@@ -1449,6 +1456,47 @@ sequenceDiagram
- 外部结果晚到：允许按幂等键补写回执，但不得回退已确认成功状态。
- 人工兜底场景：支付异常、银行回盘异常、发票状态冲突等需保留人工复核入口与操作日志。
+
+## 历史查询与迁移校验接口口径
+
+### 设计原则
+
+- 历史查询接口一律只读，不承担迁移修正、补写或状态变更职责。
+- 不为迁移场景发明新的独立接口编号体系，统一挂靠既有 `IF-REV-*`、`IF-CS-*`、`IF-METER-*` 接口族扩展查询能力。
+- 对 backend 当前未识别到独立实体表的旧细粒度对象，仅要求接口返回“历史摘要 + 原始标识 + 状态映射”，不强行承诺独立在线业务对象。
+- 迁移验收接口必须同时支持“汇总对账”和“明细追溯”两类能力，避免只能看总数、无法定位差异。
+
+### 最小历史查询保留集
+
+| 查询主题 | 挂靠接口族 | 主要数据来源 | 最低返回要求 | 说明 |
+|---------|------------|--------------|--------------|------|
+| 历史账单、特殊开账 | `IF-CS-002`、`IF-REV-005` | `biz_charge*` + 历史账单来源 | 原账单号、新账单号、客户号、账期、金额、状态、来源类型 | 支撑账单迁移核查与客户侧历史查询 |
+| 缴费记录、柜台结账、实时收费 | `IF-CS-002`、`IF-REV-006`、`IF-REV-011` | `biz_collection`、`bk_transaction*` + 历史收费记录 | 原流水号、渠道、实收金额、收费时间、柜员/营业所、核销状态 | 支撑渠道对账、柜面核查和历史收据核对 |
+| 红冲与账务调整 | `IF-REV-007` | 操作留痕、流程结果 + 历史调整台账 | 调整类型、关联原单号、调整金额、原因、审批状态、处理时间 | 支撑预存退款、已销调整、价差调整、分账调整、呆坏账查询 |
+| 发票与开票关系 | `IF-REV-008`、`IF-CS-004` | `biz_invoice*` + 历史开票关系快照 | 发票号、申请单号、关联账单、票据状态、票据类型、文件地址 | 支撑发票结果核查与历史补打定位 |
+| 催缴、停复水、预存短信 | `IF-REV-009`、`IF-METER-002` | 通知结果、流程工单 + 历史催缴记录 | 客户号、账期、催缴方式、消息状态、停复水状态、执行人、执行时间 | 支撑催缴处置闭环核查 |
+| 业务进度与电子档案 | `IF-CS-006` | `biz_process*`、`biz_content*` + 历史附件目录 | 业务单号、节点状态、处理轨迹、附件数量、附件元数据 | 支撑微网厅与柜台办理进度、电子档案查询 |
+| 水表生命周期、检定与库存流转 | `IF-METER-001`、`IF-METER-003` | `biz_meter*` + 历史仓储/检定单据 | 表号、当前状态、单据类型、仓库、检定结论、证书编号、时间 | 支撑表务迁移核查与历史作业追溯 |
+| 页面参数、业务字段、微信配置 | `IF-REV-012`、`IF-CS-006` | `biz_parameter_settings`、`biz_page_settings*`、`sys_wechat_app_settings` | 参数编码、原值、新值、启用状态、生效时间、适用渠道 | 支撑微网厅后台配置迁移核查 |
+
+### 迁移验收对账接口要求
+
+| 验收场景 | 推荐挂靠接口 | 最低查询维度 | 输出要求 |
+|---------|--------------|--------------|----------|
+| 开账迁移核对 | `IF-REV-005`、`IF-CS-002` | 账期、营业所、客户类型、账单状态 | 同时提供汇总金额/笔数与可追溯明细清单 |
+| 收费迁移核对 | `IF-REV-006`、`IF-REV-011`、`IF-CS-002` | 日期、渠道、营业所、收费状态 | 同时提供实收金额、流水数量和异常流水列表 |
+| 发票迁移核对 | `IF-REV-008`、`IF-CS-004` | 开票日期、票据类型、开票状态 | 同时提供开票汇总、失败原因和票据明细定位 |
+| 催缴与停复水核对 | `IF-REV-009`、`IF-METER-002` | 账期、催缴方式、执行状态、处理人 | 同时提供任务统计与执行明细 |
+| 业务办理与档案核对 | `IF-CS-006` | 业务类型、流程状态、附件类型、创建时间 | 同时提供流程轨迹、附件元数据和缺失标记 |
+| 表务仓储与检定核对 | `IF-METER-001`、`IF-METER-003` | 仓库、单据类型、水表状态、检定结论 | 同时提供数量汇总和单据级追溯信息 |
+
+### 接口约束补充
+
+- 历史查询结果应优先返回原系统标识与新系统标识的映射关系，例如原单号、原批次号、原附件标识、当前业务单号。
+- 明细查询接口应支持按客户号、证件号、手机号、表号、账期、营业所、渠道、业务单号等组合检索，满足迁移验收定位需求。
+- 若历史附件不直接由当前业务服务托管，接口至少返回附件元数据、来源系统、文件引用地址和可访问状态。
+- 历史查询接口的导出能力属于查询扩展能力，不应与在线交易接口共用“状态变更”动作。
+
## 实现状态说明
@@ -1478,6 +1526,7 @@ sequenceDiagram
- 历史数据字典中大量细粒度账务台账接口
- 未在 backend 当前扫描范围内明确识别到的独立业务对象接口
- 特定银行或地方平台的专有报文细节
+- 历史查询与迁移校验接口在实施时所依赖的只读库、归档库或映射表物理形态
---
diff --git a/docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md b/docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md
new file mode 100644
index 0000000..a15bbde
--- /dev/null
+++ b/docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md
@@ -0,0 +1,245 @@
+# 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` 与边界说明
+- [ ] 正式文档修订顺序与最小验收入口已明确
+- [ ] 台账更新触发条件已明确
+- [ ] 文档改动可独立评审并可继续拆解后续任务
diff --git a/specs/001-rev004-accounting/checklists/requirements.md b/specs/001-rev004-accounting/checklists/requirements.md
new file mode 100644
index 0000000..6d82f87
--- /dev/null
+++ b/specs/001-rev004-accounting/checklists/requirements.md
@@ -0,0 +1,36 @@
+# Specification Quality Checklist: REV-004 账务处理一期
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-13
+**Feature**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/001-rev004-accounting/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/001-rev004-accounting/spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- 本轮校验通过。
+- 规格已限定在 REV-004 一期的文档范围收敛与执行准备，不包含超范围扩写。
+- 下一步可进入 `/speckit.clarify` 或直接在确认范围后进入 `/speckit.plan`。
diff --git a/specs/001-rev004-accounting/contracts/if-rev-007-accounting-request.md b/specs/001-rev004-accounting/contracts/if-rev-007-accounting-request.md
new file mode 100644
index 0000000..eb5801a
--- /dev/null
+++ b/specs/001-rev004-accounting/contracts/if-rev-007-accounting-request.md
@@ -0,0 +1,71 @@
+# Contract: IF-REV-007 账务调整接口
+
+## 1. 合同定位
+
+本合同用于固化 `IF-REV-007` 在 REV-004 一期中的统一接口口径，服务于后续正式接口文档修订、任务拆解与评审，不作为代码接口定义文件。
+
+## 2. 适用范围
+
+适用场景：
+- 水量调整
+- 金额调整
+- 退款
+- 冲正
+- 坏账申请
+
+不适用范围：
+- 发票申请与结果回写
+- 银行代收与结算协同
+- 新 BPM 流程模型扩展
+- 独立账务台账表族设计
+
+## 3. 请求合同
+
+| 字段 | 类型 | 必填 | 说明 | 约束 |
+|------|------|------|------|------|
+| chargeId | Long | 是 | 目标账单 ID | 必须存在于 `biz_charge.id` |
+| adjustType | String | 是 | 调整类型 | `USAGE` / `AMOUNT` / `REFUND` / `REVERSE` / `BAD_DEBT` |
+| adjustAmount | Decimal | 否 | 调整金额 | 金额类场景必填 |
+| adjustUsage | Decimal | 否 | 调整水量 | 水量类场景必填 |
+| sourceTradeNo | String | 否 | 原交易流水号 | `REFUND` / `REVERSE` 场景必填 |
+| reasonCode | String | 是 | 调整原因编码 | 需可追溯到业务字典 |
+| remark | String | 否 | 调整说明 | 进入操作留痕 |
+| attachmentList | Array | 否 | 依据附件 | 进入依据引用 |
+| operatorId | Long | 是 | 操作人 ID | 必须可追溯责任归属 |
+
+## 4. 响应合同
+
+| 字段 | 类型 | 说明 | 约束 |
+|------|------|------|------|
+| adjustmentNo | String | 调整业务编号 | 用于后续追踪 |
+| chargeId | Long | 目标账单 ID | 与请求一致 |
+| resultStatus | String | 处理状态 | `SUCCESS` / `PENDING_APPROVAL` / `FAIL` |
+| writeBackStatus | String | 账单回写状态 | `SUCCESS` / `IGNORE_REPEAT` / `FAIL` |
+| approvalRequired | Boolean | 是否进入审批 | 一期仅保留能力位 |
+| msg | String | 处理说明 | 供调用方和评审使用 |
+
+## 5. 共性规则
+
+1. 所有场景必须定位到既有账单对象，不建立并行账务主对象。
+2. 所有场景必须保留处理依据、前后变化和责任归属。
+3. 退款、冲正必须校验原交易存在性、交易状态、回调结果与异常处理状态，不得只以 `bk_transaction` 主记录存在作为通过条件。
+4. 审批相关内容一期仅保留 `approvalRequired`、`PENDING_APPROVAL` 与审批边界说明，不展开完整 BPM 流程、流程节点、流转规则或审批回写实现细节。
+5. 接口结果必须能映射到 `biz_charge*`、`bk_transaction*`、`biz_operat_log*` 三类对象。
+6. `resultStatus` 与 `writeBackStatus` 必须分离表达：前者表示业务处理结论，后者表示账单状态回写结论。
+
+## 6. 物理承接口径
+
+| 逻辑对象 | 物理承接 |
+|---------|----------|
+| 账单主对象 | `biz_charge` |
+| 账单明细 | `biz_charge_detail` |
+| 原交易校验 | `bk_transaction*` |
+| 主日志 | `biz_operat_log` |
+| 差异明细日志 | `biz_operat_log_detail` |
+
+## 7. 验收关注点
+
+- 是否所有场景都仍挂靠 `IF-REV-007`
+- 是否未引入超范围接口编号
+- 是否未把审批/BPM 细化为一期必做实现
+- 是否未误写独立账务台账表族为在线新增对象
diff --git a/specs/001-rev004-accounting/contracts/rev004-scenario-matrix.md b/specs/001-rev004-accounting/contracts/rev004-scenario-matrix.md
new file mode 100644
index 0000000..4627909
--- /dev/null
+++ b/specs/001-rev004-accounting/contracts/rev004-scenario-matrix.md
@@ -0,0 +1,33 @@
+# Contract: REV-004 一期场景矩阵
+
+## 1. 目的
+
+用于统一 REV-004 一期各场景在输入依据、关键校验、结果表达和留痕要求上的差异，支撑后续 plan/tasks 拆解。
+
+## 2. 场景矩阵
+
+| 场景 | 主要输入 | 关键校验 | 结果表达 | 留痕重点 | 备注 |
+|------|----------|----------|----------|----------|------|
+| 水量调整 | `chargeId`、`adjustUsage`、`reasonCode` | 原抄表依据、账单状态可调 | `resultStatus`、`writeBackStatus` | 调整前后水量、依据附件 | 不新增跨周期水量独立表 |
+| 金额调整 | `chargeId`、`adjustAmount`、`reasonCode` | 差异金额合法性、账单状态可调 | `resultStatus`、`writeBackStatus` | 调整前后金额、原因、经办人 | 可涉及重算口径 |
+| 退款 | `chargeId`、`adjustAmount`、`sourceTradeNo` | 原交易存在、可退金额、幂等性 | `resultStatus`、`approvalRequired`、`writeBackStatus` | 原交易号、退款金额、处理结果 | 一期仅保留审批能力位 |
+| 冲正 | `chargeId`、`sourceTradeNo`、`reasonCode` | 原交易状态、账单状态、可冲正性 | `resultStatus`、`approvalRequired`、`writeBackStatus` | 原交易号、状态变化、处理原因 | 不强接 BPM |
+| 坏账申请 | `chargeId`、`reasonCode`、`remark` | 账龄、客户状态、业务条件 | `resultStatus`、`approvalRequired`、`writeBackStatus` | 申请原因、账单状态、审批边界 | 一期仅保留审批能力位与边界说明 |
+
+## 3. 共性能力
+
+所有场景共享以下能力：
+- 统一入口：`IF-REV-007`
+- 统一账单承接：`biz_charge` / `biz_charge_detail`
+- 统一原交易校验：`bk_transaction` / `bk_transaction_callback` / `bk_transaction_exception`
+- 统一留痕：`biz_operat_log` / `biz_operat_log_detail`
+- 统一结果表达：`resultStatus` / `writeBackStatus`（前者表示处理结论，后者表示账单回写结论）
+- 审批边界：只保留 `approvalRequired`、`PENDING_APPROVAL` 与边界说明，不展开完整 BPM 流程、节点、流转规则或审批回写实现细节
+
+## 4. 排除说明
+
+以下内容不在本矩阵覆盖范围内：
+- 独立账务细表设计
+- 发票、银行结算等其他接口族
+- backend 实施代码结构
+- 完整 BPM 审批流程定义
diff --git a/specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md b/specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md
new file mode 100644
index 0000000..d860e7f
--- /dev/null
+++ b/specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md
@@ -0,0 +1,23 @@
+# Contract: REV-004 一期追溯矩阵
+
+## 1. 目的
+
+用于建立 `spec.md`、详细设计、接口设计、数据库设计之间的稳定追溯关系，确保后续正式文档修订与任务拆解基于同一口径。
+
+## 2. 追溯矩阵
+
+| 规格需求/场景 | 详细设计承接 | 接口设计承接 | 数据库承接 | 说明 |
+|--------------|--------------|--------------|------------|------|
+| 一期纳入范围：水量调整/金额调整/退款/冲正/坏账申请 | `12_REV_Detailed.md` REV-004 场景表 | `03_Interface_Design.md` `IF-REV-007` | `biz_charge*`、`biz_operat_log*` | 五类场景统一纳入一期，排除独立账务细表扩围 |
+| 统一接口入口 | REV-004 接口映射 | `IF-REV-007` 请求/响应定义 | 账单与日志对象 | 不扩展到 `IF-REV-008`、`IF-REV-011` 等其他接口族 |
+| 原交易校验 | REV-004 关键规则 | `sourceTradeNo` 字段 | `bk_transaction*` | 退款/冲正必须联动原交易主状态、回调结果与异常处理状态 |
+| 处理结果回写 | REV-004 业务流程/关键规则 | `writeBackStatus`、`resultStatus` | `biz_charge` 状态承接 | `resultStatus` 与 `writeBackStatus` 必须分离表达 |
+| 审批边界 | 审批留痕要求 | `approvalRequired`、`PENDING_APPROVAL` | 仅能力位，无独立审批表要求 | 一期不强接 BPM，仅保留边界说明 |
+| 留痕与依据 | 操作日志与审批留痕 | `remark`、`attachmentList` | `biz_operat_log` / `biz_operat_log_detail` | 必须覆盖处理类型、原交易引用、前后差异与附件依据 |
+| 旧系统细粒度台账承接 | 迁移补充表 | 历史查询与迁移校验口径 | 历史只读 + 在线主模型 | 不误写为在线新增实体 |
+
+## 3. 使用约束
+
+- 本矩阵只服务于文档规划与后续正式主文档修订。
+- 若某条追溯关系无法在三份正式文档中对齐，应先回写正式主文档，再继续 tasks 或实施讨论。
+- Archive 与执行手册可用于核对，但不得替代正式结论。
diff --git a/specs/001-rev004-accounting/data-model.md b/specs/001-rev004-accounting/data-model.md
new file mode 100644
index 0000000..3b82044
--- /dev/null
+++ b/specs/001-rev004-accounting/data-model.md
@@ -0,0 +1,167 @@
+# Data Model: REV-004 账务处理一期
+
+## 建模原则
+
+- 以逻辑实体 + 物理承接对象双层表达，避免把未确认能力误写为已落地独立表。
+- 在线主模型优先复用 `biz_charge*`、`biz_operat_log*`、`bk_transaction*`。
+- 审批相关内容仅保留能力位，不展开完整 BPM 流程模型。
+
+## 实体一：AccountingRequest（账务处理申请）
+
+### 作用
+统一承接 `IF-REV-007` 的五类场景输入：水量调整、金额调整、退款、冲正、坏账申请。
+
+### 核心字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| requestNo | String | 申请编号/调整业务编号 |
+| adjustType | Enum | `USAGE` / `AMOUNT` / `REFUND` / `REVERSE` / `BAD_DEBT` |
+| chargeId | Long | 目标账单 ID |
+| sourceTradeNo | String | 原交易流水号，退款/冲正场景使用 |
+| adjustAmount | Decimal | 调整金额 |
+| adjustUsage | Decimal | 调整水量 |
+| reasonCode | String | 调整原因编码 |
+| remark | String | 调整说明 |
+| attachmentList | Array | 依据附件 |
+| operatorId | Long | 操作人 ID |
+| requestedAt | DateTime | 发起时间 |
+
+### 校验规则
+- `chargeId`、`adjustType`、`reasonCode`、`operatorId` 必填。
+- `REFUND` / `REVERSE` 场景必须具备 `sourceTradeNo`。
+- `adjustAmount` 与 `adjustUsage` 按场景二选一或组合使用，不允许无意义空提交。
+
+### 状态
+`submitted` → `accepted` / `rejected` → `processed` / `failed`
+
+## 实体二：AccountingResult（账务处理结果）
+
+### 作用
+统一承接处理结果、回写结果与是否需要审批。
+
+### 核心字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| adjustmentNo | String | 调整业务编号 |
+| chargeId | Long | 目标账单 ID |
+| resultStatus | Enum | `SUCCESS` / `PENDING_APPROVAL` / `FAIL` |
+| writeBackStatus | Enum | `SUCCESS` / `IGNORE_REPEAT` / `FAIL` |
+| approvalRequired | Boolean | 是否进入审批 |
+| msg | String | 处理说明 |
+| processedAt | DateTime | 处理时间 |
+
+### 状态关系
+- `resultStatus` 表示业务处理结果。
+- `writeBackStatus` 表示账单回写结果。
+- `approvalRequired=true` 时允许 `resultStatus=PENDING_APPROVAL`。
+
+## 实体三：ChargeAggregate（账单聚合对象）
+
+### 作用
+作为 REV-004 调整、退款、冲正的主要业务承接对象。
+
+### 物理承接
+- `biz_charge`
+- `biz_charge_detail`
+
+### 核心字段
+
+| 字段 | 来源 | 说明 |
+|------|------|------|
+| chargeId | `biz_charge.id` | 账单主键 |
+| chargeStatus | `biz_charge` | 账单状态 |
+| receivableAmount | `biz_charge` / `biz_charge_detail` | 应收金额 |
+| paidAmount | 业务汇总 | 已收金额 |
+| remainAmount | 业务汇总 | 剩余待支付金额 |
+| detailItems | `biz_charge_detail` | 费用明细集合 |
+
+### 关键关系
+- 1 个 `ChargeAggregate` 对应多条 `biz_charge_detail`。
+- 1 个 `AccountingRequest` 必须定位到 1 个 `ChargeAggregate`。
+
+## 实体四：Transaction（原交易流水）
+
+### 作用
+为退款、冲正等场景提供原交易事实依据。
+
+### 物理承接
+- `bk_transaction`
+- 关联扩展：`bk_transaction_callback`（异步回调结果核对）
+- 关联扩展：`bk_transaction_exception`（异常处理状态核对）
+
+### 核心字段
+
+| 字段 | 说明 |
+|------|------|
+| tradeNo | 渠道交易流水号 |
+| tradeStatus | 原交易状态 |
+| tradeAmount | 原交易金额 |
+| channelCode | 渠道编码 |
+| occurredAt | 交易发生时间 |
+
+### 关键规则
+- `REFUND` / `REVERSE` 必须关联 `tradeNo`。
+- 原交易状态必须满足“可退款/可冲正”业务前提。
+- 原交易校验应同时覆盖交易主状态、回调结果与异常处理状态，不得只校验交易主表存在性。
+
+## 实体五：OperationLog（操作留痕）
+
+### 作用
+记录账务处理前后变化、处理依据与责任归属。
+
+### 物理承接
+- `biz_operat_log`
+- `biz_operat_log_detail`
+
+### 核心字段
+
+| 字段 | 说明 |
+|------|------|
+| bizType | 业务类型 |
+| bizId | 业务对象 ID |
+| operateUser | 操作人 |
+| operateTime | 操作时间 |
+| remark | 处理说明 |
+| beforeValue | 调整前值 |
+| afterValue | 调整后值 |
+| fieldName | 字段级差异项 |
+
+### 关键规则
+- 所有 REV-004 一期场景都必须写入主日志。
+- 涉及金额/水量/状态变化时应写入字段级差异明细。
+
+## 实体六：AccountingEvidence（处理依据）
+
+### 作用
+统一描述原账单、原交易、附件、文字说明等处理依据。
+
+### 核心字段
+
+| 字段 | 说明 |
+|------|------|
+| evidenceType | 原账单 / 原交易 / 附件 / 说明 |
+| sourceRef | 依据引用标识 |
+| snapshotRef | 快照引用 |
+| attachmentList | 附件集合 |
+
+### 说明
+该实体是逻辑约束，不要求本阶段新增物理表；由既有对象引用、附件系统与日志共同承接。
+
+## 关系总览
+
+```text
+AccountingRequest --> ChargeAggregate
+AccountingRequest --> Transaction (REFUND/REVERSE only)
+AccountingRequest --> AccountingEvidence
+AccountingRequest --> AccountingResult
+AccountingRequest --> OperationLog
+ChargeAggregate --> biz_charge_detail (1:N)
+OperationLog --> biz_operat_log_detail (1:N)
+```
+
+## 状态与边界说明
+
+- 一期仅保留审批能力位，不定义完整审批状态机。
+- 旧系统精细账务对象如预存退款明细、价差调整明细、分账调整明细等，不作为一期新增实体表；仅保留业务场景、历史只读与日志承接口径。
diff --git a/specs/001-rev004-accounting/plan.md b/specs/001-rev004-accounting/plan.md
new file mode 100644
index 0000000..554b9c3
--- /dev/null
+++ b/specs/001-rev004-accounting/plan.md
@@ -0,0 +1,193 @@
+# 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 违规项，无需豁免说明。
diff --git a/specs/001-rev004-accounting/quickstart.md b/specs/001-rev004-accounting/quickstart.md
new file mode 100644
index 0000000..fcd5dd6
--- /dev/null
+++ b/specs/001-rev004-accounting/quickstart.md
@@ -0,0 +1,103 @@
+# Quickstart: REV-004 账务处理一期计划评审与最小校验
+
+## 1. 评审入口
+
+本轮目标是：
+- 完成 REV-004 一期文档范围收敛
+- 形成后续实施计划的边界、任务拆解与验收入口
+- 不直接进入 backend 代码修改
+
+本轮验收仅检查：
+- 文档一致性
+- 计划可拆解性
+- 台账可回写性
+
+## 2. 评审步骤
+
+### 步骤一：范围校验
+确认一期只覆盖以下场景：
+- 水量调整
+- 金额调整
+- 退款
+- 冲正
+- 坏账申请
+
+同时确认以下内容未被带入：
+- 新增独立账务台账表族
+- 泛化 BPM 平台扩展
+- 非 `IF-REV-007` 的跨模块接口扩围
+- backend 代码实施内容
+
+### 步骤二：单一真源校验
+对照以下正式口径：
+- `spec.md`
+- `12_REV_Detailed.md`
+- `03_Interface_Design.md`
+- `01_Database_Design.md`
+- `.specify/memory/constitution.md`
+
+确认 plan 中没有用执行手册或 Archive 直接替代正式结论。
+
+### 步骤三：追溯关系校验
+确认以下关系在计划中可直接对应：
+- 场景 → `IF-REV-007`
+- 场景 → `biz_charge` / `biz_charge_detail`
+- 退款/冲正 → `bk_transaction*`
+- 留痕 → `biz_operat_log*`
+
+### 步骤四：审批边界校验
+确认审批相关内容仅保留：
+- `approvalRequired`
+- `PENDING_APPROVAL`
+- 审批边界说明
+
+不展开：
+- 完整 BPM 流程
+- 流程节点
+- 流转规则
+- 审批回写实现细节
+
+### 步骤五：台账动作校验
+确认执行闭环已说明：
+- `01_Project_Progress.md` 只在形成新的治理里程碑或正式交付节点时更新
+- `03_Task_Checklist.md` 只在 tracked task 完成或闭环条件被重新定义时更新
+- 台账更新动作位于正式文档修订与最小校验之后，而不是默认并行执行
+
+### 步骤六：独立验收入口校验
+确认审阅者仅通过以下文件即可完成 US3 验收：
+- `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+- `docs/design/00_Management/01_Project_Progress.md`
+- `docs/design/00_Management/03_Task_Checklist.md`
+
+并确认无需查看 backend 代码、运行态脚本或 Archive 历史附件，即可判断后续任务可继续拆解推进。
+
+### 步骤七：正式文档修订闭环校验
+若后续进入正式主文档修订，统一按以下顺序执行：
+1. 先更新执行手册中的执行顺序、验收入口、最小校验动作与台账触发条件。
+2. 再同步 `quickstart.md`、`plan.md` 等支撑产物，保持闭环表述一致。
+3. 每修改 1 份目标文档，执行对应 `make validate-file FILE=<目标文件>`。
+4. 涉及跨文档引用变更时执行 `make check-links`。
+5. 仅当里程碑成立或 tracked task 完成条件发生实质变化时，再回写两份治理台账。
+
+## 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
+```
+
+说明：
+- 本轮校验聚焦执行手册与治理台账闭环，不再以 `spec.md` / `plan.md` 作为唯一校验对象。
+- `make check-links` 用于确认执行手册与两份治理台账之间的相对链接和引用关系正常。
+- 若后续进入新的正式主文档修订批次，应补充对应目标文件的 `make validate-file FILE=<目标文件>`。
+
+## 4. 通过标准
+
+满足以下条件即可进入下一批 tasks 执行：
+- 后续任务拆解顺序已明确：执行手册 → 支撑产物 → 台账同步
+- 独立验收入口已明确，审阅者仅需查看执行手册与两份治理台账
+- 最小校验动作已明确并可直接执行
+- 项目进度与任务清单的更新触发条件已写清楚
+- 后续工作可继续按文档修订、校验、台账同步三类动作拆解推进
diff --git a/specs/001-rev004-accounting/research.md b/specs/001-rev004-accounting/research.md
new file mode 100644
index 0000000..ce76a3f
--- /dev/null
+++ b/specs/001-rev004-accounting/research.md
@@ -0,0 +1,56 @@
+# Phase 0 Research: REV-004 账务处理一期
+
+## Decision 1: 一期范围严格收敛到 `REV-004` + `IF-REV-007`
+- **Decision**: 一期仅覆盖水量调整、金额调整、退款、冲正、坏账申请五类场景，并以 `IF-REV-007` 作为统一账务处理入口。
+- **Rationale**: `spec.md`、`12_REV_Detailed.md`、`03_Interface_Design.md` 与 `REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md` 对该范围已形成交集口径；继续扩展到 `IF-REV-008`、`IF-REV-011` 或 `IF-CS-*`、`IF-METER-*` 会超出一期边界。
+- **Alternatives considered**:
+ - 扩展为账务平台级改造：超范围。
+ - 按旧系统菜单全量恢复所有账务对象：不符合“保守补完”原则。
+
+## Decision 2: 先统一共性能力，再按场景分批组织后续实施计划
+- **Decision**: 后续实施计划采用“共性能力先统一、场景能力再分批”的组织方式。
+- **Rationale**: 各场景共享留痕、原始依据、结果状态、回写状态、接口与数据库口径；先统一这些共性能力，才能避免场景拆解后产生重复建模和状态不一致。
+- **Alternatives considered**:
+ - 先做退款或冲正单场景：容易固化局部口径。
+ - 所有场景并行拆分：放大一致性风险。
+
+## Decision 3: 在线主模型复用 `biz_charge*` + `biz_operat_log*`，不新增独立账务台账表族
+- **Decision**: 一期在线主模型以 `biz_charge`、`biz_charge_detail`、`biz_operat_log`、`biz_operat_log_detail` 为主承接，退款/冲正等场景按流程与留痕处理，不新建平行细表。
+- **Rationale**: `01_Database_Design.md` 已明确旧系统精细账务台账按历史只读保留，新发生业务由在线主模型与日志承接；`12_REV_Detailed.md` 也要求未识别为独立实体的对象只保留业务场景语义。
+- **Alternatives considered**:
+ - 新增预存退款/价差调整/分账调整明细表：违背一期最小闭环原则。
+ - 机械平移旧系统全部账务表：与当前正式主文档不一致。
+
+## Decision 4: 退款/冲正必须联动原交易校验
+- **Decision**: 退款、冲正等涉及原支付修正的场景，统一依赖 `bk_transaction*` 进行原交易存在性、状态与可处理性校验。
+- **Rationale**: `12_REV_Detailed.md` 要求退款、冲正与原支付流水及渠道状态联动；执行手册把“原交易存在性 / 可退金额 / 状态可调性”列为一期关键缺口。
+- **Alternatives considered**:
+ - 仅按账单状态处理：审计与对账风险高。
+ - 各场景独立定义交易校验：口径会分裂。
+
+## Decision 5: 审批/BPM 一期只保留能力位
+- **Decision**: 一期仅保留 `approvalRequired`、`PENDING_APPROVAL` 等能力位和边界说明，不展开完整审批流程、节点或流转规则，也不强接 BPM。
+- **Rationale**: `spec.md` 已明确审批相关内容本轮仅保留能力位；执行手册说明 BPM 只有在审批场景、流程 key、回写规则确认后才实接。
+- **Alternatives considered**:
+ - 一期直接实接 BPM：前提不足。
+ - 完全忽略审批：与详设、接口和规格不一致。
+
+## Decision 6: 本轮验收入口以文档与计划质量为准
+- **Decision**: 本轮验收入口限定为文档一致性、计划可拆解性与台账可回写性，不以 backend 代码完成度作为前提。
+- **Rationale**: 当前 feature 已在 clarify 中明确“文档收敛 + 生成实施计划，但先不改 backend 代码”。
+- **Alternatives considered**:
+ - 以代码落地作为本轮验收：不符合当前阶段目标。
+
+## Decision 7: Plan 阶段的最小校验以文档门禁为主
+- **Decision**: quickstart 与计划中的最小校验以 `make validate-file`、`make check-links`、`make validate-mermaid` 为主，不引入构建、导出或代码编译命令。
+- **Rationale**: Constitution 要求按文档改动范围执行最小校验；当前 plan 阶段的交付对象仍是文档设计产物。
+- **Alternatives considered**:
+ - 使用全量 `make validate` 或导出命令：成本过高，且不属于当前最小门禁。
+ - 加入 backend 构建/测试命令：超出本轮范围。
+
+## Decision 8: Project Progress / Task Checklist 仅在正式变更或任务闭环时更新
+- **Decision**: 仅生成 speckit plan/research 产物时不强制更新 `01_Project_Progress.md` 和 `03_Task_Checklist.md`；待正式主文档修订落地或任务拆解/完成时再更新。
+- **Rationale**: 台账应承载正式里程碑和任务闭环，而不是记录计划草稿流水。
+- **Alternatives considered**:
+ - 在 plan 阶段立即更新全部台账：噪音过大。
+ - 完全不考虑台账更新：不符合宪法闭环要求。
diff --git a/specs/001-rev004-accounting/spec.md b/specs/001-rev004-accounting/spec.md
new file mode 100644
index 0000000..c77fcaf
--- /dev/null
+++ b/specs/001-rev004-accounting/spec.md
@@ -0,0 +1,134 @@
+# Feature Specification: REV-004 账务处理一期
+
+**Feature Branch**: `001-rev004-accounting`
+**Created**: 2026-03-13
+**Status**: Draft
+**Input**: User description: "我想先做的 REV-004"
+
+## Document Scope & Sources *(mandatory)*
+
+- **Target documents**:
+ - `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`
+ - `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+ - `docs/design/00_Management/01_Project_Progress.md`
+ - `docs/design/00_Management/03_Task_Checklist.md`
+- **Primary source of truth**:
+ - `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`
+ - `.specify/memory/constitution.md`
+- **Reference sources**:
+ - `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+ - `docs/design/00_Management/15_Legacy_Migration_Gap_Analysis.md`
+ - `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md`
+- **Scope decision**: In scope。该需求属于既有 `REV-004` 模块范围内的账务处理一期收敛任务，允许在现有正式文档体系内补齐范围、接口、数据口径和执行约束，并输出后续实施计划所需的边界、任务拆解与验收依据；本轮不直接进入 backend 代码修改，不包含超出一期边界的新业务域扩展。
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - 收敛一期范围 (Priority: P1)
+
+作为项目负责人，我需要先把 `REV-004` 一期的业务边界、纳入场景和排除项写清楚，以便团队在启动后续工作时不会把退款、冲正、坏账等事项扩展成超范围的账务重构任务。
+
+**Why this priority**: 范围不收敛会直接导致后续计划、任务和实施偏离宪法规定的“范围交集优先”。
+
+**Independent Test**: 审阅者仅通过 `12_REV_Detailed.md` 与 `REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，即可确认一期纳入范围、排除范围和关键对象是否一致。
+
+**Acceptance Scenarios**:
+
+1. **Given** 当前 `REV-004` 在多个文档中仅有摘要性描述，**When** 完成本次规格修订，**Then** 审阅者能够明确识别一期纳入场景、排除项和边界依据。
+2. **Given** 团队准备启动后续计划或执行，**When** 查阅本次规格，**Then** 不会把非一期内容误判为当前必须推进的范围。
+
+---
+
+### User Story 2 - 对齐接口与数据口径 (Priority: P2)
+
+作为方案设计与评审人员，我需要让 `REV-004` 的详细设计、接口设计和数据库设计在同一口径下表达账务处理对象、处理结果和留痕要求，以便评审时可以追溯并核对。
+
+**Why this priority**: `REV-004` 当前涉及详细设计、接口定义和数据库承接说明，若三者不一致，会直接影响后续任务分解与验收。
+
+**Independent Test**: 审阅者仅通过对照 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md`，即可确认账务处理场景、核心对象和留痕要求是否一致。
+
+**Acceptance Scenarios**:
+
+1. **Given** 账务处理涉及详细设计、接口和数据库三个正式文档，**When** 完成本次规格定义，**Then** 审阅者能够在三份文档之间建立稳定的追溯关系。
+
+---
+
+### User Story 3 - 形成可执行交付闭环 (Priority: P3)
+
+作为项目维护人员，我需要把 `REV-004` 的执行手册与项目管理台账同步起来，并明确后续实施计划按“共性能力先统一、场景能力再分批”的方式组织，以便后续进入 clarify、plan、tasks 阶段时，能够先统一留痕、原始依据、结果状态以及接口/数据库口径，再按账务调整、退款、冲正、坏账申请等场景拆解任务并留存过程记录，而不在本轮直接进入 backend 代码修改；本轮验收入口应以文档一致性、计划可拆解性和台账可回写性为准。
+
+**Why this priority**: 没有交付闭环，`REV-004` 容易停留在文档存在但不可执行、已推进但未回写台账的状态。
+
+**Independent Test**: 审阅者仅通过检查执行手册和管理台账，即可确认 `REV-004` 的目标、完成条件、实施计划边界、共性能力优先顺序、验收入口和后续动作已被记录。
+
+**Acceptance Scenarios**:
+
+1. **Given** 当前仓库已有 `REV-004` 执行手册和相关任务记录，**When** 完成本次规格，**Then** 审阅者能够判断哪些台账需要同步、何时视为一期范围收口完成，以及后续实施计划应先覆盖哪些共性能力、再拆解哪些业务场景。
+2. **Given** 当前阶段仍以文档收敛和计划准备为主，**When** 审阅者据此验收本轮规格，**Then** 其可直接依据规格确认文档口径是否一致、后续计划是否可拆解、台账更新点是否明确，而无需以代码完成度作为前提。
+
+---
+
+### Edge Cases
+
+- 当历史资料中出现比当前主文档更细的账务场景时，必须仅作为参考来源，不得直接提升为当前一期必做范围。
+- 当接口、详细设计与数据库文档对同一账务对象使用不同名称或粒度时，必须先统一正式口径，再进入后续计划或实施。
+- 当一期范围内存在“需要审批”类表述时，本轮仅保留能力位和边界说明，不展开完整审批流程、节点或流转规则。
+- 当执行手册与项目进度台账状态不一致时，必须明确以当前主文档与本次规格确认后的口径回写台账。
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: Specification MUST 明确 `REV-004` 一期的目标文档清单，并说明每份文档承担的职责。
+- **FR-002**: Specification MUST 明确 `REV-004` 一期的主口径来源，包括概要、详细、接口、数据库与项目宪法。
+- **FR-003**: Specification MUST 明确 `REV-004` 一期纳入范围，包括账务调整、退款、冲正、坏账申请等当前主文档已覆盖的核心场景。
+- **FR-004**: Specification MUST 明确后续实施计划按“共性能力先统一、场景能力再分批”的方式组织：先统一留痕、原始依据、结果状态以及接口/数据库口径，再按账务调整、退款、冲正、坏账申请等场景拆解实施。
+- **FR-005**: Specification MUST 明确 `REV-004` 一期不纳入范围，避免将非一期台账细化、跨模块重构或未确认能力带入本轮工作。
+- **FR-006**: Specification MUST 明确 `REV-004` 在详细设计、接口设计和数据库设计之间的追溯关系，确保核心对象和处理结果表达一致。
+- **FR-007**: Specification MUST 明确账务处理留痕、原始依据和结果回写属于本次范围内必须说明的内容。
+- **FR-008**: Specification MUST 明确执行手册、项目进度和任务清单是否需要同步更新，以及更新触发条件。
+- **FR-009**: Specification MUST 明确后续实施计划需要覆盖的边界、任务拆解和验收入口；本轮验收入口应限定为文档一致性、计划可拆解性和台账可回写性，不得把 backend 代码修改写成本轮已执行内容。
+- **FR-010**: Specification MUST 明确审批相关表述在本轮仅保留能力位和边界说明，不展开完整审批流程、节点或流转规则。
+- **FR-011**: Specification MUST 明确后续进入 clarify、plan、tasks 前必须完成的最小校验动作。
+- **FR-012**: Specification MUST 保持用户视角和业务视角表述，不将具体实现语言、接口路径、代码结构或脚本命令写成本规格的验收前提。
+
+### Key Entities *(include if feature involves data)*
+
+- **REV-004 一期范围**: 本轮允许推进的账务处理业务集合，用于约束纳入内容与排除内容。
+- **共性能力**: 在分场景实施前需要统一规划的留痕、原始依据、结果状态以及接口/数据库口径要求。
+- **账务处理场景**: 账务调整、退款、冲正、坏账申请等业务事项，是本次规格的核心业务对象。
+- **正式目标文档**: 承载 `REV-004` 设计口径的正式 Markdown 文档，用于落地单一真源。
+- **参考来源**: 用于核对历史边界、迁移差距或执行建议的辅助文档，不直接替代正式结论。
+- **留痕要求**: 对账务处理前后变化、处理依据、结果状态和责任归属的记录要求。
+- **台账更新**: 项目进度与任务清单中的记录动作，用于形成阶段性交付闭环。
+
+## Assumptions
+
+- 本次“先做 REV-004”默认指向 `REV-004` 账务处理一期的文档范围收敛，并在同一轮明确后续实施计划所需的边界、任务拆解与验收入口，而不是直接启动跨模块代码开发。
+- 后续实施计划默认采用“共性能力先统一、场景能力再分批”的组织方式：先统一留痕、原始依据、结果状态以及接口/数据库口径，再按账务调整、退款、冲正、坏账申请等场景拆解。
+- 当前一期默认聚焦既有主文档已覆盖的账务处理核心场景，不额外扩大到新的独立台账体系或跨模块能力改造。
+- 若资料中出现审批相关描述，本轮默认仅保留能力位和边界说明，不细化为完整审批流程定义。
+- 若后续 clarify 阶段确认需要进一步收缩到单一子场景，本规格仍可作为 `REV-004` 一期总范围基线。
+- 本规格已完成 clarify 收敛；后续阶段应基于已确认边界继续推进 `/speckit.plan`、`/speckit.tasks`、`/speckit.analyze` 与正式文档修订。
+
+## Clarifications
+
+### Session 2026-03-13
+
+- Q: 本轮 `REV-004` 目标深度是仅做文档收敛，还是同时产出后续实施计划，或直接进入文档加 backend 一期闭环？ → A: 本轮完成文档收敛，并生成后续实施计划所需的边界、任务拆解与验收要求，但先不改 backend 代码。
+- Q: 后续实施计划应整体覆盖一期全部场景，还是按不同场景分批组织？ → A: 按“共性能力先统一、场景能力再分批”的方式组织，先统一留痕、原始依据、结果状态以及接口/数据库口径，再按账务调整、退款、冲正、坏账申请等场景拆解。
+- Q: 本轮规格的验收入口应收敛到哪一层？ → A: 以文档一致性、计划可拆解性和台账可回写性作为本轮验收入口，不以代码完成度作为前提。
+- Q: 审批相关场景在本轮应细化到什么程度？ → A: 本轮仅保留能力位和边界说明，不展开完整审批流程、节点或流转规则。
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 规格中明确列出至少 4 份 `REV-004` 相关目标文档，且每份文档的职责可被审阅者独立理解。
+- **SC-002**: 审阅者在阅读规格后，可在 5 分钟内判断 `REV-004` 一期哪些场景纳入、哪些内容排除，无需再查找额外上下文才能做出范围判断。
+- **SC-003**: 审阅者可依据规格明确识别详细设计、接口设计、数据库设计与执行手册之间的追溯关系，且不存在职责重叠或空缺。
+- **SC-004**: 审阅者可依据规格直接列出后续实施计划应覆盖的边界、任务拆解与验收入口，并能独立确认本轮是否已满足文档一致性、计划可拆解性和台账可回写性三项验收条件。
diff --git a/specs/001-rev004-accounting/tasks.md b/specs/001-rev004-accounting/tasks.md
new file mode 100644
index 0000000..1af0a3a
--- /dev/null
+++ b/specs/001-rev004-accounting/tasks.md
@@ -0,0 +1,203 @@
+# Tasks: REV-004 账务处理一期
+
+**Input**: Design documents from `/specs/001-rev004-accounting/`
+**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/
+
+**Validation**: Validation tasks are NOT optional in this repository. Every document change task set MUST include the applicable validation and ledger-sync tasks.
+
+**Organization**: Tasks are grouped by user story so each document-maintenance slice can be completed, reviewed, and validated independently.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- Main documents: `docs/design/01_Overview/`, `docs/design/02_Detailed_Design/`, `docs/design/03_Technical_Design/`
+- Governance documents: `docs/design/00_Management/`
+- Archive references: `docs/design/04_Appendix/Archive/`
+- Runtime guidance: `README.md`, `AGENTS.md`, `.specify/templates/`
+
+## Phase 1: Setup (Shared Foundation)
+
+**Purpose**: Confirm the source-of-truth set, target files, and planning artifacts before editing formal documents.
+
+- [X] T001 Read prerequisite governance documents `docs/design/00_Management/01_Project_Progress.md`, `docs/design/00_Management/02_Delivery_Standards.md`, and `docs/design/00_Management/03_Task_Checklist.md` before formal document edits
+- [X] T002 Confirm target chapters and intended updates in `specs/001-rev004-accounting/spec.md`, `specs/001-rev004-accounting/plan.md`, `docs/design/02_Detailed_Design/12_REV_Detailed.md`, `docs/design/03_Technical_Design/03_Interface_Design.md`, and `docs/design/03_Technical_Design/01_Database_Design.md`
+- [X] T003 [P] Confirm source-of-truth and allowed references using `.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`, and `docs/design/03_Technical_Design/01_Database_Design.md`
+- [X] T004 [P] Confirm scope boundary, exclusions, traceability anchors, and impacted files in `specs/001-rev004-accounting/research.md`, `specs/001-rev004-accounting/contracts/rev004-scenario-matrix.md`, `specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md`, and `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+
+---
+
+## Phase 2: Foundational Alignment (Blocking Prerequisites)
+
+**Purpose**: Prepare the common wording, structure, and traceability baseline that all user stories depend on.
+
+- [X] T005 Normalize common terminology, scenario names, and approval boundary wording in `specs/001-rev004-accounting/data-model.md`, `specs/001-rev004-accounting/contracts/if-rev-007-accounting-request.md`, and `specs/001-rev004-accounting/contracts/rev004-scenario-matrix.md`
+- [X] T006 [P] Map shared entities and result fields from `specs/001-rev004-accounting/data-model.md` into target update notes for `docs/design/02_Detailed_Design/12_REV_Detailed.md` and `docs/design/03_Technical_Design/03_Interface_Design.md`
+- [X] T007 [P] Map shared physical carriers from `specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md` into target update notes for `docs/design/03_Technical_Design/01_Database_Design.md`
+- [X] T008 Establish a single update checklist for validation and ledger-sync using `specs/001-rev004-accounting/quickstart.md`, `docs/design/00_Management/01_Project_Progress.md`, and `docs/design/00_Management/03_Task_Checklist.md`
+
+---
+
+## Phase 3: User Story 1 - 收敛一期范围 (Priority: P1) 🎯 MVP
+
+**Goal**: 在正式详细设计与执行手册中明确 REV-004 一期纳入范围、排除项、共性能力优先顺序与审批边界。
+
+**Independent Test**: 审阅者仅通过 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 与 `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，即可确认一期纳入场景、排除项、审批边界和“共性能力先统一、场景能力再分批”的组织方式一致。
+
+### Implementation for User Story 1
+
+- [X] T009 [US1] Update REV-004 一期范围、排除项、共性能力顺序和审批边界 in `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- [X] T010 [US1] Sync REV-004 执行范围、验收入口和后续实施组织方式 in `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+- [X] T011 [P] [US1] Sync REV-004 一期范围摘要 and cross-references in `docs/design/01_Overview/03_Summary_Design.md`
+- [X] T012 [US1] Update traceability note for scoped scenarios in `specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md`
+- [X] T013 [US1] Run `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` and capture result for `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- [X] T014 [US1] Run `make validate-file FILE=docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md` and capture result for `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+- [X] T015 [US1] Run `make check-links` and capture cross-document link result for US1 file changes
+- [X] T016 [US1] Update important progress note in `docs/design/00_Management/01_Project_Progress.md` if US1 produces an important formal document change after validation passes
+- [X] T017 [US1] Update REV-004 scope task status in `docs/design/00_Management/03_Task_Checklist.md` if US1 completes a tracked task or materially changes its closure condition
+
+**Checkpoint**: User Story 1 is reviewable, validated, and ledger-synced independently.
+
+---
+
+## Phase 4: User Story 2 - 对齐接口与数据口径 (Priority: P2)
+
+**Goal**: 在详细设计、接口设计与数据库设计中统一 IF-REV-007、账单承接对象、原交易校验对象、结果表达和留痕对象。
+
+**Independent Test**: 审阅者仅通过对照 `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`，即可确认 REV-004 的核心场景、请求/响应字段、物理承接口径和追溯关系一致。
+
+### Implementation for User Story 2
+
+- [X] T018 [US2] Update REV-004 scenario rules, result fields, and log requirements in `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- [X] T019 [US2] Update IF-REV-007 request/response, approval boundary, and acceptance notes in `docs/design/03_Technical_Design/03_Interface_Design.md`
+- [X] T020 [US2] Update REV-004 physical carrier wording for `biz_charge*`, `bk_transaction*`, and `biz_operat_log*` in `docs/design/03_Technical_Design/01_Database_Design.md`
+- [X] T021 [P] [US2] Sync shared entity and field mapping notes in `specs/001-rev004-accounting/data-model.md`
+- [X] T022 [P] [US2] Sync contract details and scenario matrix notes in `specs/001-rev004-accounting/contracts/if-rev-007-accounting-request.md` and `specs/001-rev004-accounting/contracts/rev004-scenario-matrix.md`
+- [X] T023 [US2] Update traceability rows for interface/database alignment in `specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md`
+- [X] T024 [US2] Run `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` and capture result for US2 detailed design changes
+- [X] T025 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` and capture result for interface design changes
+- [X] T026 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` and capture result for database design changes
+- [X] T027 [US2] Run `make check-links` and capture cross-document link result for US2 file changes
+- [X] T028 [US2] Update important progress note in `docs/design/00_Management/01_Project_Progress.md` if US2 produces an important formal document change after validation passes
+- [X] T029 [US2] Update REV-004 interface/database alignment task status in `docs/design/00_Management/03_Task_Checklist.md` if US2 completes a tracked task or materially changes its closure condition
+
+**Checkpoint**: User Story 2 is reviewable and validated independently.
+
+---
+
+## Phase 5: User Story 3 - 形成可执行交付闭环 (Priority: P3)
+
+**Goal**: 在执行手册与管理台账中固化 REV-004 的后续实施顺序、验收入口、最小校验动作与台账更新触发条件。
+
+**Independent Test**: 审阅者仅通过 `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`、`docs/design/00_Management/01_Project_Progress.md` 与 `docs/design/00_Management/03_Task_Checklist.md`，即可确认 REV-004 后续 tasks 的拆解依据、验收入口、最小校验动作和台账同步方式已经明确。
+
+### Implementation for User Story 3
+
+- [X] T030 [US3] Update REV-004 execution sequence, independent acceptance entry, and validation steps in `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+- [X] T031 [US3] Record REV-004 planning milestone and next-step entry in `docs/design/00_Management/01_Project_Progress.md` if US3 forms an important governance or formal delivery milestone
+- [X] T032 [US3] Update REV-004 tracked checklist items and completion criteria in `docs/design/00_Management/03_Task_Checklist.md` if US3 completes or materially redefines a tracked task
+- [X] T033 [P] [US3] Sync quick review and validation wording in `specs/001-rev004-accounting/quickstart.md`
+- [X] T034 [P] [US3] Sync task-splitting and closure assumptions in `specs/001-rev004-accounting/plan.md`
+- [X] T035 [US3] Run `make validate-file FILE=docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md` and capture result for execution playbook changes
+- [X] T036 [US3] Run `make validate-file FILE=docs/design/00_Management/01_Project_Progress.md` and capture result for project progress changes
+- [X] T037 [US3] Run `make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md` and capture result for task checklist changes
+- [X] T038 [US3] Run `make check-links` and capture cross-document link result for US3 file changes
+
+**Checkpoint**: All planned document updates are independently reviewable, validated, and ledger-synced.
+
+---
+
+## Final Phase: Polish & Cross-Cutting Closure
+
+**Purpose**: Ensure repository-wide consistency after all story slices are complete.
+
+- [X] T039 [P] Re-check source-of-truth alignment across `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`, and `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+- [X] T040 [P] Re-check relative links, traceability rows, and Mermaid consistency across `docs/design/01_Overview/03_Summary_Design.md`, `docs/design/00_Management/01_Project_Progress.md`, `docs/design/00_Management/03_Task_Checklist.md`, and `specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md`
+- [X] T041 Prepare final change summary with modified files, validation results, remaining risks, and next-step suggestions in the final response for `/specs/001-rev004-accounting/tasks.md`
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Phase 1: Setup**: No dependencies; MUST finish before document updates.
+- **Phase 2: Foundational Alignment**: Depends on Phase 1; MUST finish before story implementation.
+- **US1 (P1)**: Starts after Phase 2; defines the MVP scope baseline.
+- **US2 (P2)**: Starts after US1 scope wording is stable, because interface/database alignment depends on agreed scenario scope.
+- **US3 (P3)**: Starts after US1 and US2, because ledger closure depends on settled scope and aligned formal documents.
+- **Final Phase**: Depends on all selected user stories being complete.
+
+### Within Each User Story
+
+- Update formal target documents before syncing contracts, quickstart, or traceability notes.
+- Complete content edits before running validation commands.
+- Complete validation before writing progress or checklist ledger entries.
+- Complete ledger sync before final cross-cutting closure.
+
+### User Story Completion Order
+
+- `US1 → US2 → US3`
+
+### Parallel Opportunities
+
+- `T003` and `T004` can run in parallel after `T001` and `T002`.
+- `T006` and `T007` can run in parallel after `T005`.
+- In US1, `T010` and `T011` can run in parallel after `T009`.
+- In US2, `T021` and `T022` can run in parallel after `T018` / `T019` / `T020` complete.
+- In US3, `T033` and `T034` can run in parallel after `T030` / `T031` / `T032` are scoped.
+- In the final phase, `T039` and `T040` can run in parallel.
+
+---
+
+## Parallel Execution Examples
+
+### User Story 1
+
+```text
+# After T009 completes, run in parallel:
+- T010 Update docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md
+- T011 Update docs/design/01_Overview/03_Summary_Design.md
+```
+
+### User Story 2
+
+```text
+# After T018/T019/T020 complete, run in parallel:
+- T021 Sync specs/001-rev004-accounting/data-model.md
+- T022 Sync specs/001-rev004-accounting/contracts/if-rev-007-accounting-request.md and rev004-scenario-matrix.md
+```
+
+### User Story 3
+
+```text
+# After core US3 updates are planned, run in parallel:
+- T033 Sync specs/001-rev004-accounting/quickstart.md
+- T034 Sync specs/001-rev004-accounting/plan.md
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 only)
+
+先完成 US1，把 REV-004 一期范围、排除项、审批边界和共性能力顺序稳定下来。只要 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 与 `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md` 已可独立评审并完成最小校验，就可以形成第一版可评审增量。
+
+### Incremental Delivery
+
+1. 完成 US1，锁定一期边界。
+2. 完成 US2，打通详细设计、接口设计、数据库设计的一致口径。
+3. 完成 US3，补齐执行手册与台账闭环。
+4. 完成 Final Phase，做全局复核与结果汇总。
+
+### Notes
+
+- 每个任务都必须保持单一真源模型，不得把 Archive 直接当成正式输出。
+- 本 feature 未要求 TDD 或新增自动化测试，因此本任务列表不生成代码测试任务。
+- `make check-links` 在多个故事中重复出现，是因为每个故事都要求独立可验收。
+- 若后续正式文档未实际修改，可在执行时将对应台账更新任务标记为不适用，但必须先给出理由。
\ No newline at end of file