# 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

本次计划无宪法豁免项。