tangweijie
20afae2255
Document the existing REV-002 backend billing-generation path and preserve a conservative partial-implementation judgment so the design stays aligned with current code evidence. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
124 lines
6.7 KiB
Markdown
124 lines
6.7 KiB
Markdown
# 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](/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.*
|
||
|
||
- [x] **主文档归属已确认**：本次只修改既有主文档与治理文档，不新增平行正式稿。
|
||
- [x] **范围基线已确认**：`REV-002` 属于既有 `SYS-002` 营收业务范围，且本轮仅收口开账计费与账单生成缺口，不跨入 `REV-003` 收费核销或其他模块。
|
||
- [x] **Archive 使用方式合规**：Archive 与 guides 仅用于核对现状、术语和数据口径，正式结论以主文档回写为准。
|
||
- [x] **一致性影响已列出**：受影响项包括 `IF-REV-005` 编号语义、账单生成结果表述、`biz_charge` / `biz_charge_detail` 承接口径、特殊开账承接方式、治理台账中的实现状态文字。
|
||
- [x] **校验与台账动作已规划**：已规划单文件校验与 `make check-links`，并纳入 `01_Project_Progress.md`、`03_Task_Checklist.md`、`15_SYS002_Requirement_Breakdown.md` 的同步更新。
|
||
|
||
## Project Structure
|
||
|
||
### Documentation (this feature)
|
||
|
||
```text
|
||
specs/005-rev002-billing-generation-gap/
|
||
├── plan.md
|
||
├── research.md
|
||
├── data-model.md
|
||
├── quickstart.md
|
||
├── contracts/
|
||
│ └── rev002-billing-contract.md
|
||
└── tasks.md
|
||
```
|
||
|
||
### Repository Touchpoints
|
||
|
||
```text
|
||
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
|
||
|
||
- [x] 主文档承载策略未偏离，所有设计输出都指向既有正式文档修订
|
||
- [x] 范围仍限定在 `REV-002` 账单生成闭环，不涉及跨模块扩写
|
||
- [x] Archive 与 guides 仅用于佐证，不直接生成正式结论
|
||
- [x] 一致性影响已沉淀到 data model、contract 与 quickstart，可直接支撑下一步 `tasks.md`
|
||
- [x] 校验与台账动作已被明确列入 quickstart 与后续任务拆解基础
|
||
|
||
## Complexity Tracking
|
||
|
||
本次计划无宪法豁免项。
|