fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/plan.md

Implementation Plan: REV-002 开账计费与账单生成缺口补齐

Branch: 005-rev002-billing-generation-gap | Date: 2026-03-18 | Spec: /Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/spec.md Input: Feature specification from /specs/005-rev002-billing-generation-gap/spec.md

Note: 本计划面向文档治理仓库，交付对象是正式设计文档与治理台账的收口，而不是业务代码实现。

Summary

本 feature 聚焦 REV-002 中“抄表校验后到账单生成”的文档缺口补齐，目标是在不扩展到收费核销、发票、催缴和统计分析的前提下，统一 IF-REV-005 的业务边界、账单生成规则、结果表达、biz_charge / biz_charge_detail 承接口径，以及治理台账中的“部分实现”结论。

Technical Context

Primary Work Product: 正式 Markdown 设计文档、治理台账、speckit 规划工件 Source of Truth 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/design/01_Overview/03_Summary_Design.md
• docs/design/00_Management/15_SYS002_Requirement_Breakdown.md
• docs/design/00_Management/01_Project_Progress.md
• docs/design/00_Management/03_Task_Checklist.md Reference Sources:
• docs/guides/BACKEND_CURRENT_STATUS.md
• docs/guides/BACKEND_TABLE_MAPPING.md
• docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md
• docs/design/04_Appendix/Archive/01_Requirements/ Validation Commands:
• make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md
• make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md
• make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md
• make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.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 Target Scope: REV-002 相关详细设计、接口设计、数据库设计与治理台账的交叉收口 Project Type: 文档治理仓库 Constraints:
• 不新增平行正式稿，只修改既有主文档和治理文档
• 不凭空新增业务规则、接口编号、账单主模型或独立表族
• IF-REV-005 继续作为正式账单生成接口编号
• 正式文档使用中文，仓库内链接使用相对路径
• 治理结论保持“部分实现，账单生成闭环仍需继续校核”的真实状态 Scale/Scope: 跨 6 个正式文档的中等范围一致性修订

Constitution Check

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

• 主文档归属已确认：本次只修改既有主文档与治理文档，不新增平行正式稿。
• 范围基线已确认：REV-002 属于既有 SYS-002 营收业务范围，且本轮仅收口开账计费与账单生成缺口，不跨入 REV-003 收费核销或其他模块。
• Archive 使用方式合规：Archive 与 guides 仅用于核对现状、术语和数据口径，正式结论以主文档回写为准。
• 一致性影响已列出：受影响项包括 IF-REV-005 编号语义、账单生成结果表述、biz_charge / biz_charge_detail 承接口径、特殊开账承接方式、治理台账中的实现状态文字。
• 校验与台账动作已规划：已规划单文件校验与 make check-links，并纳入 01_Project_Progress.md、03_Task_Checklist.md、15_SYS002_Requirement_Breakdown.md 的同步更新。

Project Structure

Documentation (this feature)

specs/005-rev002-billing-generation-gap/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── rev002-billing-contract.md
└── tasks.md

Repository Touchpoints

docs/design/
├── 00_Management/
│   ├── 01_Project_Progress.md
│   ├── 03_Task_Checklist.md
│   └── 15_SYS002_Requirement_Breakdown.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/

Structure Decision:

• docs/design/02_Detailed_Design/12_REV_Detailed.md：补齐 REV-002 的触发前提、规则来源、结果表达、特殊开账统一模型和排除项。
• docs/design/03_Technical_Design/03_Interface_Design.md：补齐 IF-REV-005 的请求前提、输出语义、失败/阻断语义，以及与后续收费链路的边界。
• docs/design/03_Technical_Design/01_Database_Design.md：明确 biz_charge、biz_charge_detail、价格模板、阶梯规则、费用组成和历史开账/特殊开账的正式承接口径。
• docs/design/00_Management/15_SYS002_Requirement_Breakdown.md：保持“部分实现”判断，同时记录本轮文档收口成果与后续建议。
• docs/design/00_Management/01_Project_Progress.md：记录本轮 REV-002 文档治理动作与校验结果。
• docs/design/00_Management/03_Task_Checklist.md：登记本轮任务闭环状态。

Phase 0 Research Output

• research.md 已固定 5 项关键决策：
  • IF-REV-005 继续作为正式账单生成接口
  • 范围只收口“抄表校验后到账单生成”
  • 账单结果统一由 biz_charge + biz_charge_detail 承接
  • 异常语义统一为“阻断生成 + 返回失败原因”
  • 治理台账继续保持“部分实现”

Phase 1 Design Output

• data-model.md：定义 Billing Trigger、Billing Rule Source、Billing Result、Charge Detail、Billing Exception Result、Billing Governance Record
• contracts/rev002-billing-contract.md：定义 IF-REV-005 的 request / response / result boundary / exception contract
• quickstart.md：给出目标落点、建议校验命令与验收检查点
• AGENTS.md：已执行 ./.specify/scripts/bash/update-agent-context.sh codex，完成 agent context 更新

Post-Design Constitution Check

• 主文档承载策略未偏离，所有设计输出都指向既有正式文档修订
• 范围仍限定在 REV-002 账单生成闭环，不涉及跨模块扩写
• Archive 与 guides 仅用于佐证，不直接生成正式结论
• 一致性影响已沉淀到 data model、contract 与 quickstart，可直接支撑下一步 tasks.md
• 校验与台账动作已被明确列入 quickstart 与后续任务拆解基础

Complexity Tracking

本次计划无宪法豁免项。