docs: align rev002 billing generation evidence

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>
2026-03-18 17:52:15 +08:00 · 2026-03-18 17:52:15 +08:00 · 20afae2255
commit 20afae2255
parent f6fd550545
14 changed files with 769 additions and 8 deletions
--- a/docs/design/00_Management/01_Project_Progress.md
+++ b/docs/design/00_Management/01_Project_Progress.md
@ -330,3 +330,8 @@
 - 明确旧“催缴记录 / 停水记录 / 预存短信记录”按历史只读口径承接，不新增同名在线主表；停复水在本轮仅保留联动边界、处置引用和追溯关系。
 - 启动并完成 `REV-007` Speckit feature `004-rev007-revenue-statistics-design` 的 `specify -> plan -> tasks` 工件链，形成统计主题、维度、指标、`IF-REV-010` 与数据库承接口径的正式设计基线。
 - `REV-007` 当前收口结论为“设计补齐推进中、代码入口未见明确实现”；本轮重点是统一正式文档与治理台账，不将预测分析、BI 专题或独立数仓能力写成既成事实。
+- 完成 `REV-002` Speckit feature `005-rev002-billing-generation-gap` 的第一轮正式文档收口，补齐 `12_REV_Detailed.md` 中开账触发前提、规则来源、结果表达、特殊开账统一模型与下游排除项。
+- 完成 `03_Interface_Design.md` 中 `IF-REV-005` 的边界补强，明确请求前提、失败阻断语义、成功/失败结果表达以及与收费、发票、催缴链路的职责边界。
+- 完成 `01_Database_Design.md` 与 `15_SYS002_Requirement_Breakdown.md` 的同步回写，明确 `biz_charge` / `biz_charge_detail`、价格规则对象和历史特殊开账的正式承接口径，并继续维持 `SYS002-REQ-004`“部分实现”的保守判断。
+- 基于 `ChargeController`、`ChargeServiceImpl` 与 `ReadingDataServiceImpl` 的第二轮 backend 证据精修 `REV-002` 结论，确认当前已支持按 `readingDataIds` 批量复核并开账，成功路径会写入 `biz_charge` / `biz_charge_detail` 并回写抄表数据状态。
+- 同步明确 `IF-REV-005` 当前实现缺口：请求仍局限 `readingDataIds`，返回仍为成功条数字符串，失败阻断未形成结构化结果，且仅支持 `ACTUAL_USAGE` 结算方式，因此治理判断继续维持“部分实现”。
--- a/docs/design/00_Management/03_Task_Checklist.md
+++ b/docs/design/00_Management/03_Task_Checklist.md
@ -213,6 +213,11 @@
  - [x] 新增 `15_SYS002_Requirement_Breakdown.md`，形成 `SYS002-REQ-001 ~ 015` 的统一需求拆解口径 ✅
  - [x] 基于 `backend/sw-business` 与 `backend/sw-business-bank` 输出已实现 / 部分实现 / 未见实现评估结果 ✅
  - [x] 形成 TAPD Story/Task 转换建议，可直接用于后续 TAPD 建模与跟踪 ✅
+- [x] **完成 REV-002 开账计费与账单生成缺口第一轮文档收口** ✅ (2026-03-18)
+  - [x] `12_REV_Detailed.md` 已补齐开账触发前提、计费规则来源、结果表达、特殊开账统一模型与下游排除项 ✅
+  - [x] `03_Interface_Design.md` 已补齐 `IF-REV-005` 的请求前提、阻断语义、成功/失败结果表达与与收费/发票/催缴的边界说明 ✅
+  - [x] `01_Database_Design.md`、`15_SYS002_Requirement_Breakdown.md` 已明确 `biz_charge` / `biz_charge_detail`、价格规则对象和历史特殊开账的正式承接口径，并保持 `SYS002-REQ-004` 为“部分实现” ✅
+  - [x] 已结合 `ChargeController`、`ChargeServiceImpl` 与 `ReadingDataServiceImpl` 证据精修 `REV-002` 判断，确认已支持按 `readingDataIds` 批量复核/开账并落库 `biz_charge` / `biz_charge_detail`，但仍保留输入范围、结构化返回与非 `ACTUAL_USAGE` 结算支持缺口 ✅
 - [x] **完成整体架构图模块清单整理与详细设计承接对齐** ✅ (2026-03-18)
  - [x] 新增 `docs/design/01_Overview/05_Module_Inventory.md`，整理整体架构图中的层级、子系统、模块与当前详设承接关系 ✅
  - [x] 更新 `01_Overview/README.md` 与 `02_Detailed_Design/README.md`，明确模块清单作为模块枚举与承接核对入口 ✅
--- a/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md
+++ b/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md
@ -72,7 +72,7 @@
 | SYS002-REQ-001 | 客户主档与账户管理 | 已实现 | `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/cust/CustController.java`、`custcontact/CustContactController.java`、`custmeter/CustMeterController.java`、`custgroup/CustGroupController.java` | 客户主档、联系人、客户分组、水表关系等已有明确后台入口。 |
 | SYS002-REQ-002 | 开票/托收/代扣关系维护 | 已实现 | `custinvoice/CustInvoiceController.java`、`custcollectionrel/CustCollectionRelController.java`、`custwithholdingrel/CustWithholdingRelController.java`、`custappbinds/CustAppBindsController.java`、`custwaterusescheme/CustWaterUseSchemeController.java`、`custwaterschemerel/CustWaterSchemeRelController.java`、`custnorule/CustNoRuleController.java`、`custhubmarks/CustHubMarksController.java` | 开票、托收、代扣、绑定、规则与计划用水方案关系均见独立入口。 |
 | SYS002-REQ-003 | 抄表任务与数据采集 | 已实现 | `meterbook/MeterBookController.java`、`meterread/MeterReadController.java`、`readingdata/ReadingDataController.java`、`readinglogs/ReadingLogsController.java`、`lastreading/LastReadingController.java` | 抄表计划、抄表数据、日志、上次读数均见实现入口。 |
-| SYS002-REQ-004 | 开账计费与账单生成 | 部分实现 | `charge/ChargeController.java`、`chargedetail/ChargeDetailController.java`、`collection/CollectionController.java` | 已看到账单、明细、收费相关入口，但当前检索结果中未直接看到与文档 `IF-REV-005` 完全对应的“账单生成”专用接口证据。 |
+| SYS002-REQ-004 | 开账计费与账单生成 | 部分实现 | `charge/ChargeController.java`、`service/charge/ChargeServiceImpl.java`、`service/readingdata/impl/ReadingDataServiceImpl.java` | 已见 `/business/charge/charge-batch` 与 `/business/charge/check-charge-batch` 两个后台入口，可按 `readingDataIds` 批量复核/开账，并由 `generateSingleChargeWithCache` 写入 `biz_charge` / `biz_charge_detail`；但当前请求仍只接受 `readingDataIds`，返回值仅为成功条数字符串，单条失败依赖日志/布尔值跳过，且仅支持 `ACTUAL_USAGE` 结算方式，因此与正式 `IF-REV-005` 的结构化契约仍有差距，整体继续按“部分实现”保守判断。 |
 | SYS002-REQ-005 | 收费核销处理 | 已实现 | `charge/ChargeController.java`、`collection/CollectionController.java`、`app/charge/AppChargeController.java`、`src/test/java/.../ChargeControllerTest.java` | 收费、账单、前台查询与基础测试均已存在。 |
 | SYS002-REQ-006 | 支付下单与结果回写 | 部分实现 | `backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/app/bankcollection/BankCollectionController.java`、`transactioncallback` 相关 DO/VO、`bk_transaction_callback` 对应对象 | 银行/支付侧基础能力存在，但当前未在 `sw-business` 中直接看到与 `IF-EXT-004/005` 完全同名的营收主入口定义，整体按部分实现保守判断。 |
 | SYS002-REQ-007 | 账务调整处理 | 已实现 | `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/charge/ChargeServiceImpl.java`、`controller/admin/charge/vo/AccountingAdjustRespVO.java` | 已见 `approvalRequired`、`writeBackStatus`、账务调整响应 VO 与服务逻辑。 |
@ -94,7 +94,7 @@
 | SYS-002：补齐客户主档与账户管理设计 | SYS002-REQ-001 | `sys002-customer-master-design` | 已实现 | 中 | 以文档收口、接口/数据库/详设一致性校核为主。 |
 | SYS-002：统一客户开票/托收/代扣关系口径 | SYS002-REQ-002 | `sys002-customer-billing-relations-alignment` | 已实现 | 中 | 重点核对关系表、主数据边界与上下游依赖。 |
 | SYS-002：补齐抄表任务与数据采集设计 | SYS002-REQ-003 | `sys002-meter-reading-design` | 已实现 | 中 | 适合作为文档与实现追溯收口项。 |
-| SYS-002：补齐开账计费与账单生成规则 | SYS002-REQ-004 | `sys002-billing-generation-rules` | 部分实现 | 高 | 当前最适合继续做文档与代码对齐核查。 |
+| SYS-002：补齐开账计费与账单生成规则 | SYS002-REQ-004 | `sys002-billing-generation-rules` | 部分实现 | 高 | 本轮已核实 backend 具备按 `readingDataIds` 批量复核/开账并落库 `biz_charge` / `biz_charge_detail` 的能力；下一步应补齐正式 `IF-REV-005` 的请求范围扩展、结构化成功/失败结果以及非 `ACTUAL_USAGE` 结算方式支持。 |
 | SYS-002：补齐收费核销设计闭环 | SYS002-REQ-005 | `sys002-payment-writeoff-design` | 已实现 | 中 | 重点补收费规则、凭证、核销边界。 |
 | SYS-002：统一支付下单与结果回写口径 | SYS002-REQ-006 | `sys002-payment-channel-sync` | 部分实现 | 高 | 需继续核实营收主系统与银行/支付子系统的边界。 |
 | SYS-002：补齐账务调整处理规则 | SYS002-REQ-007 | `sys002-accounting-adjustment-rules` | 已实现 | 中 | 以规则闭环和接口字段口径统一为主。 |
--- a/docs/design/02_Detailed_Design/12_REV_Detailed.md
+++ b/docs/design/02_Detailed_Design/12_REV_Detailed.md
@ -153,11 +153,23 @@ flowchart TD

 ### 关键规则

-1. 抄表数据同时校验本次读数、上次读数、用量波动和抄表状态。
-2. 异常抄表支持估抄、补抄、重录、人工复核。
-3. 开账按价格归属、价格模板、费用组成、阶梯规则、计划用水方案综合计算。
-4. 审核通过后的营业账方可进入收费、催缴和发票流程。
-5. 远传抄表数据可由 `SYS-006` / IoT 能力提供采集支撑，但账单生成仍归属 SYS-002。
+1. 抄表数据同时校验本次读数、上次读数、用量波动和抄表状态，只有通过校验或完成异常复核的数据才能进入开账。
+2. 异常抄表支持估抄、补抄、重录、人工复核；异常处理的目标是形成可继续开账或明确阻断的统一结论，而不是绕开开账规则单独落账。
+3. `IF-REV-005` 的正式边界是“抄表校验完成后的账单生成”，不负责收费核销、发票开具、催缴执行和统计分析。
+4. 开账计费按价格归属、价格模板、费用组成、阶梯规则、计划用水方案综合计算；价格配置缺失、费用组成不完整或规则冲突时，必须阻断生成并返回失败原因。
+5. 账单生成结果统一由 `biz_charge` 与 `biz_charge_detail` 承接：主表表达客户、账期、应收日期、账单总金额和主状态，明细表表达费用组成、用量、单价和明细金额。
+6. 特殊开账、无码客户开账、罚款类开账等非标准来源，仍纳入同一营业账主明细模型承接，通过来源类型、业务类型、依据说明和操作留痕区分，不单独扩展平行账表。
+7. 审核通过后的营业账方可进入收费、催缴和发票流程；后续链路只能消费已生成账单结果，不反向改变本接口的生成边界。
+8. 远传抄表数据可由 `SYS-006` / IoT 能力提供采集支撑，但账单生成仍归属 SYS-002。
+
+### 开账触发与结果表达
+
+- 触发前提：正式口径下可按抄表批次、指定客户范围或指定抄表任务范围组织生成；当前 backend 已落地的入口为按 `readingDataIds` 批量复核并开账，对应 `ChargeController.generateCheckChargeBatch`、`ChargeServiceImpl.generateCheckChargeBatch` 与 `ReadingDataServiceImpl.batchReCheckReadingData`。
+- 规则来源：价格归属决定客户适用的价格口径；价格模板、阶梯规则、费用组成和计划用水方案共同决定营业账主表金额与明细拆分方式。
+- 当前承接证据：`ChargeServiceImpl.generateSingleChargeWithCache` 成功路径会写入 `biz_charge` 主表、循环写入 `biz_charge_detail` 明细，并回写抄表数据开账状态，说明现有实现已具备“按抄表数据 ID 生成营业账主明细”的 backend 基础。
+- 结果表达：正式 `IF-REV-005` 应返回成功清单、失败清单、生成汇总及主明细级结果；当前 backend 返回仍为“本次复核成功X条 / 本次开账成功Y条”的字符串拼接，尚未形成结构化成功/失败结果对象。
+- 阻断与限制：价格模板不存在、费用调整配置缺失、结算方式非 `ACTUAL_USAGE` 等场景当前会直接阻断单条生成；其中固定水量、按人口数、最低消费等非实际水量结算方式仍未纳入当前实现。
+- 下游边界：`REV-002` 只负责生成营业账结果并交由后续审核/收费链路消费，不在本章节扩展收费核销、发票申请或催缴执行细节。

 ### 核心数据

--- a/docs/design/03_Technical_Design/01_Database_Design.md
+++ b/docs/design/03_Technical_Design/01_Database_Design.md
@ -1096,6 +1096,23 @@ retrieval_priority: P0
 | `unit_price` | 单价 |
 | `detail_amount` | 明细金额 |

+#### REV-002 账单生成承接口径
+
+| 对象 | 正式口径 | 承接说明 |
+| :--- | :--- | :--- |
+| `biz_charge` | 账单生成主结果对象 | 统一表达客户、账期、抄表/开账来源、账单总金额、收费状态与应缴日期，不单独发明新的在线账单主模型 |
+| `biz_charge_detail` | 账单生成明细对象 | 统一表达费用组成、用量、单价、明细金额，与主表通过 `charge_id` 建立主明细关系 |
+| `biz_price_category`、`biz_price_template`、`biz_price_adjustment_snap`、`biz_price_tier_adjustment` | 计费规则来源对象 | 用于表达价格归属、基础价格、调价快照与阶梯规则来源，支撑账单金额计算与追溯 |
+| `biz_cost_component` | 费用组成定义对象 | 用于表达水费、污水费、附加费、罚款类费用等明细分类，不将费用组成直接硬编码到主表 |
+| `biz_water_use_scheme`、`biz_water_use_scheme_tier`、`biz_exceed_water_use_scheme` | 计划用水与超计划规则对象 | 用于承接计划用水、超计划与阶梯类扩展规则，不额外发明平行的特殊开账规则表 |
+| 历史开账记录、特殊开账 | 历史只读 / 同模型承接对象 | 统一纳入 `biz_charge`、`biz_charge_detail` 与操作留痕承接，通过来源类型、业务类型、依据说明区分，不单设“特殊开账表” |
+
+> REV-002 承接口径：账单生成结果统一由 `biz_charge`、`biz_charge_detail` 承接，关键规则来源继续由 `biz_price_*`、`biz_cost_component` 与计划用水相关对象提供；当价格模板、费用组成或规则关系不完整时，应按“阻断生成”口径处理。
+>
+> 当前 backend 证据：`ChargeServiceImpl.generateSingleChargeWithCache` 成功路径已执行 `chargeMapper.insert(charge)`、`chargeDetailService.insertChargeDetail(detail)` 与 `updateReadingDataCheckState(readingDataId, 1)`，说明现有实现已能把按 `readingDataIds` 复核/开账的结果落入 `biz_charge`、`biz_charge_detail`。
+>
+> 当前承接缺口：接口层返回仍为成功条数字符串，失败阻断主要依赖日志与布尔值，且仅支持 `ACTUAL_USAGE` 结算方式；`biz_charge` / `biz_charge_detail` 的主明细结果、失败对象范围和结构化原因尚未提升为正式 `IF-REV-005` 契约返回。
+>
 > REV-004 承接口径：水量调整、金额调整、退款、冲正、坏账申请统一以 `biz_charge`、`biz_charge_detail` 作为账单主明细承接对象；当前数据库主文档不新增独立账务细表来承接一期场景。

 ### biz_collection / biz_withholding (托收与代扣主表)
--- a/docs/design/03_Technical_Design/03_Interface_Design.md
+++ b/docs/design/03_Technical_Design/03_Interface_Design.md
@ -372,9 +372,21 @@ retrieval_priority: P0
 | 归属模块 | REV-002 |
 | 请求方式 | POST |
 | 请求路径 | `/admin-api/revenue/charge/generate` |
-| 功能描述 | 基于抄表结果、水价模板、阶梯规则、费用组成生成账单 |
+| 功能描述 | 基于抄表结果、水价模板、阶梯规则、费用组成生成账单，并返回成功清单、失败清单与生成汇总 |
 | 核心表 | `biz_charge`、`biz_charge_detail`、`biz_price_template`、`biz_price_tier_adjustment`、`biz_cost_component` |

+边界约束：
+- 本接口只负责抄表校验完成后的账单生成，不直接承接收费核销、发票申请、催缴执行或统计汇总。
+- 正式请求范围可按抄表批次、客户集合或抄表任务集合组织；当前 backend 已实现入口为 `/business/charge/charge-batch` 与 `/business/charge/check-charge-batch`，请求体仅接受 `readingDataIds`。
+- 价格模板、费用组成、阶梯规则、计划用水方案等任一关键规则缺失时，应阻断生成并返回失败原因，而不是生成不完整账单。
+- 特殊开账、无码客户开账、罚款类开账等非标准来源仍沿用同一 `biz_charge` / `biz_charge_detail` 承接口径，不单设平行在线账表。
+- 当前实现仅支持 `SettleTypeEnum.ACTUAL_USAGE`；固定水量、按人口数、最低消费等结算方式暂未纳入现有开账链路。
+
+当前 backend 证据与契约缺口：
+- `ChargeServiceImpl.generateCheckChargeBatch` 已支持“批量复核 + 批量开账”，并通过 `generateSingleChargeWithCache` 写入 `biz_charge`、`biz_charge_detail`，说明主明细承接路径已存在。
+- 返回值当前为 `CommonResult<String>`，仅表达“本次复核成功X条 / 本次开账成功Y条”，尚未提供正式契约要求的成功清单、失败清单、生成汇总和主明细结果对象。
+- 单条失败当前主要以 `log.warn` + `false` 跳过处理，尚未形成可直接对外返回的结构化阻断码、失败原因集合与对象范围。
+
 ### IF-REV-006 缴费处理接口

 | 项目 | 说明 |
--- a/specs/005-rev002-billing-generation-gap/checklists/requirements.md
+++ b/specs/005-rev002-billing-generation-gap/checklists/requirements.md
@ -0,0 +1,34 @@
+# Specification Quality Checklist: REV-002 开账计费与账单生成缺口补齐
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-18
+**Feature**: [/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)
+
+## 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-002` 默认按“部分实现，但账单生成闭环仍需进一步收口”处理。
--- a/specs/005-rev002-billing-generation-gap/contracts/rev002-billing-contract.md
+++ b/specs/005-rev002-billing-generation-gap/contracts/rev002-billing-contract.md
@ -0,0 +1,53 @@
+# Contract: REV-002 开账计费与账单生成缺口补齐
+
+## 1. Formal Interface Allocation
+
+| Interface | Role | Direction |
+|---|---|---|
+| `IF-REV-005` | `REV-002` 开账计费与账单生成的正式业务接口 | `SYS-002` 内部正式业务接口 |
+
+约束：
+
+- `IF-REV-005` 保持为 `REV-002` 的正式账单生成接口编号，不新增新的开账生成接口编号。
+- 本接口只承接开账计费与账单生成，不扩展到收费核销、发票申请或催缴触发。
+
+## 2. Request Contract
+
+| Field | Meaning | Required |
+|---|---|---|
+| `billPeriod` | 账期 | 是 |
+| `readingBatchNo` | 抄表批次号 | 否 |
+| `customerIds` | 客户集合 | 否 |
+| `meterReadIds` | 抄表任务集合 | 否 |
+| `dueDate` | 应收截止日期 | 是 |
+| `operatorId` | 发起人 | 否 |
+
+补充约束：
+
+- 请求前提是抄表数据已通过校验或异常复核允许进入开账。
+- 至少应提供批次、客户范围或抄表任务范围中的一种有效筛选条件。
+
+## 3. Response Contract
+
+| Field | Meaning |
+|---|---|
+| `generateCount` | 成功生成账单数量 |
+| `successList` | 成功明细集合 |
+| `successList[].chargeId` | 账单主键 |
+| `successList[].chargeCode` | 账单编号 |
+| `successList[].custId` | 客户标识 |
+| `successList[].totalAmount` | 账单总金额 |
+| `failureList` | 失败明细集合 |
+| `failureList[].reason` | 失败原因 |
+
+## 4. Result Boundary Contract
+
+- 账单生成结果统一以 `biz_charge` 作为主结果、`biz_charge_detail` 作为明细结果承接。
+- 特殊开账、无码客户开账或罚款类开账应通过来源类型、业务类型或依据说明纳入统一账单主模型，不单独发明平行主表。
+- 账单生成成功后只表达“已生成营业账”的结果边界，后续收费、催缴、开票由下游模块继续承接。
+
+## 5. Exception Contract
+
+- 当价格模板、阶梯规则、费用组成、计划用水方案或必要来源数据缺失时，应阻断生成并返回失败原因。
+- 失败语义必须与现有抄表开账类错误码口径一致，不得仅写日志而不在接口结果中表达。
+- 异常复核、估抄、补抄、重录等场景只定义“是否允许进入生成”边界，不展开具体实现细节。
--- a/specs/005-rev002-billing-generation-gap/data-model.md
+++ b/specs/005-rev002-billing-generation-gap/data-model.md
@ -0,0 +1,137 @@
+# Data Model: REV-002 开账计费与账单生成缺口补齐
+
+## 1. Billing Trigger
+
+### Purpose
+
+定义从抄表校验结果进入开账计费流程的正式触发条件。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `billPeriod` | 账期 | 必填 |
+| `readingBatchNo` | 抄表批次号 | 可为空 |
+| `meterReadIds` | 抄表任务集合 | 至少存在批次或任务范围 |
+| `validatedFlag` | 是否已通过校验 | 必填；未校验不得生成 |
+| `dueDate` | 应收截止日期 | 必填 |
+| `operatorId` | 发起人 | 可为空 |
+
+### Relationships
+
+- 来源于 `biz_meter_read`、`biz_reading_data`、`biz_last_reading`
+- 可触发一个或多个 `Billing Result`
+
+## 2. Billing Rule Source
+
+### Purpose
+
+定义账单生成过程依赖的价格和费用规则来源。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `priceCategoryCode` | 价格归属编码 | 必填 |
+| `priceTemplateCode` | 价格模板编码 | 必填 |
+| `tierRuleRef` | 阶梯规则引用 | 可为空；按场景适用 |
+| `costComponentSet` | 费用组成集合 | 至少 1 项 |
+| `waterUseSchemeRef` | 计划用水方案引用 | 可为空；按场景适用 |
+| `ruleEffectiveFlag` | 规则是否完整有效 | 必填；无效时阻断生成 |
+
+### Relationships
+
+- 一个 `Billing Rule Source` 可服务多个 `Billing Trigger`
+- 一个 `Billing Rule Source` 可生成多个 `Charge Detail`
+
+## 3. Billing Result
+
+### Purpose
+
+定义账单生成后的主结果表达。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `chargeId` | 账单主键 | 唯一 |
+| `chargeCode` | 账单编号 | 唯一 |
+| `custId` | 客户标识 | 必填 |
+| `accountId` | 账户标识 | 可为空；按账户体系承接 |
+| `billPeriod` | 账期 | 必填 |
+| `totalAmount` | 账单总金额 | 必填 |
+| `sourceType` | 来源类型 | 必填；普通开账/特殊开账等 |
+| `chargeStatus` | 账单状态 | 必填 |
+| `dueDate` | 应收截止日期 | 必填 |
+
+### Relationships
+
+- 由一个 `Billing Trigger` 触发产生
+- 包含多个 `Charge Detail`
+- 后续可流转到收费、催缴、发票等下游模块
+
+## 4. Charge Detail
+
+### Purpose
+
+定义营业账明细中的费用组成表达。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `chargeId` | 所属账单 ID | 必填 |
+| `costComponentCode` | 费用组成代码 | 必填 |
+| `usageAmount` | 用量 | 可为空；按费用项适用 |
+| `unitPrice` | 单价 | 可为空；按费用项适用 |
+| `detailAmount` | 明细金额 | 必填 |
+| `detailRemark` | 明细说明 | 可为空 |
+
+### Relationships
+
+- 归属于一个 `Billing Result`
+- 引用一个 `Billing Rule Source`
+
+## 5. Billing Exception Result
+
+### Purpose
+
+定义账单生成失败时的正式异常返回表达。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `reasonCode` | 失败原因编码 | 必填 |
+| `reasonText` | 失败说明 | 必填 |
+| `relatedCustomer` | 相关客户 | 可为空 |
+| `relatedMeterRead` | 相关抄表任务 | 可为空 |
+| `blockingFlag` | 是否阻断生成 | 固定为是 |
+
+### Relationships
+
+- 与一个 `Billing Trigger` 关联
+- 不生成 `Billing Result`
+
+## 6. Billing Governance Record
+
+### Purpose
+
+用于在治理台账中记录 `REV-002` 的设计状态、实现评估和后续建议。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `requirementCode` | 对应需求编号 | 固定为 `SYS002-REQ-004` |
+| `featureName` | Speckit feature 名称 | 必填 |
+| `designStatus` | 设计状态 | 必填；设计收口中/已收口 |
+| `implementationStatus` | 实现评估 | 必填；当前为部分实现 |
+| `nextAction` | 后续动作 | 必填 |
+| `validationRecord` | 校验记录 | 必填 |
+
+### Relationships
+
+- 关联 `01_Project_Progress.md`
+- 关联 `03_Task_Checklist.md`
+- 关联 `15_SYS002_Requirement_Breakdown.md`
--- a/specs/005-rev002-billing-generation-gap/plan.md
+++ b/specs/005-rev002-billing-generation-gap/plan.md
@ -0,0 +1,123 @@
+# 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
+
+本次计划无宪法豁免项。
--- a/specs/005-rev002-billing-generation-gap/quickstart.md
+++ b/specs/005-rev002-billing-generation-gap/quickstart.md
@ -0,0 +1,51 @@
+# Quickstart: REV-002 开账计费与账单生成缺口补齐
+
+## 目标
+
+本 quickstart 用于指导评审者和文档维护者快速完成 `REV-002` 开账计费与账单生成缺口补齐的检查，不涉及 backend 实施。
+
+## 步骤 1：阅读规格与计划结论
+
+1. 阅读 `spec.md`，确认本轮范围只覆盖 `IF-REV-005`、开账规则、结果表达、数据库承接口径与治理同步。
+2. 阅读 `research.md`，确认以下决策已固定：
+   - `IF-REV-005` 保持为正式账单生成接口
+   - 开账生成闭环只覆盖“抄表校验后到账单生成”
+   - 账单结果统一由 `biz_charge` + `biz_charge_detail` 承接
+   - 异常采用“阻断生成 + 返回失败原因”的口径
+
+## 步骤 2：执行文档改动时的目标落点
+
+1. 在 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 补齐：
+   - 开账计费规则来源
+   - 账单生成结果表达
+   - 特殊开账与异常边界
+   - 排除项与文档先行边界
+2. 在 `docs/design/03_Technical_Design/03_Interface_Design.md`：
+   - 补齐 `IF-REV-005` 的正式接口定义
+   - 明确请求条件、输出结果和异常语义
+3. 在 `docs/design/03_Technical_Design/01_Database_Design.md`：
+   - 明确 `biz_charge`、`biz_charge_detail` 与价格规则对象的承接口径
+4. 在治理台账中回写：
+   - `15_SYS002_Requirement_Breakdown.md`
+   - `01_Project_Progress.md`
+   - `03_Task_Checklist.md`
+
+## 步骤 3：建议校验命令
+
+```bash
+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
+```
+
+## 步骤 4：验收检查点
+
+- `REV-002` 的开账规则和结果表达不再停留在摘要级表述
+- `IF-REV-005` 的请求输出和异常语义已明确
+- 数据库主文档未把特殊开账误写为平行在线主表
+- 治理台账明确保持“部分实现，账单生成闭环仍需继续校核”的真实结论
+- 正式文档与台账同步更新
--- a/specs/005-rev002-billing-generation-gap/research.md
+++ b/specs/005-rev002-billing-generation-gap/research.md
@ -0,0 +1,56 @@
+# Phase 0 Research: REV-002 开账计费与账单生成缺口补齐
+
+## 决策 1：`IF-REV-005` 继续作为正式账单生成接口
+
+- **Decision**: `REV-002` 继续使用 `IF-REV-005` 作为正式账单生成接口编号，不新增新的 `IF-*` 编号。
+- **Rationale**:
+  - 当前正式接口总表和接口章节都已使用 `IF-REV-005`，缺的是闭环内容而不是编号本身。
+  - 保持现有编号可以减少与其他模块编号治理的耦合。
+  - 本轮重点是补齐规则、结果表达和数据库承接口径。
+- **Alternatives considered**:
+  - 新增新的账单生成接口编号：否决，因为没有编号冲突，只会制造额外扰动。
+  - 维持总表项不补详细定义：否决，因为不足以支撑后续实现和评审。
+
+## 决策 2：开账生成闭环仅覆盖“抄表校验后到账单生成”
+
+- **Decision**: 本 feature 的正式范围只覆盖从抄表校验结果进入开账计费、生成营业账及其结果表达的闭环，不扩展到收费核销、发票申请、催缴或统计分析链路。
+- **Rationale**:
+  - 当前缺口明确聚焦在 `IF-REV-005` 和账单生成规则。
+  - 收费、发票、催缴都已有单独模块和接口编号，不应混入本轮。
+  - 先收口“账单生成前后边界”更有利于后续对实现进行准确评估。
+- **Alternatives considered**:
+  - 把收费核销一起纳入：否决，因为会扩大到 `REV-003`。
+  - 把发票和催缴后续链路一起写入：否决，因为超出当前缺口范围。
+
+## 决策 3：账单结果以 `biz_charge` + `biz_charge_detail` 主明细表达
+
+- **Decision**: 账单生成结果统一以 `biz_charge` 作为主表、`biz_charge_detail` 作为明细表承接，不新增平行“特殊开账表”或独立账单结果模型。
+- **Rationale**:
+  - 数据库主文档已明确 `biz_charge*` 是开账结果承接口径。
+  - 当前 backend 也已见 `charge/chargedetail` 相关入口。
+  - 这样既能覆盖普通开账，也能把特殊开账作为来源类型或业务类型扩展纳入统一表达。
+- **Alternatives considered**:
+  - 单独新增“特殊开账表”：否决，因为没有正式主文档或实现证据支持。
+  - 仅描述账单主表、不写明细关系：否决，因为会削弱费用组成表达。
+
+## 决策 4：异常与阻断场景采用“阻断生成 + 返回失败原因”的口径
+
+- **Decision**: 当价格模板、阶梯规则、费用组成或必要来源数据缺失时，`IF-REV-005` 采用“阻断生成 + 返回失败原因”的统一异常语义。
+- **Rationale**:
+  - 现有接口主文档已经有 `1_002_002_003` 这类错误码线索。
+  - 对账单生成而言，缺规则时继续生成不符合正式业务口径。
+  - 统一异常语义有助于详细设计、接口设计和治理文档表达一致。
+- **Alternatives considered**:
+  - 自动降级生成部分账单：否决，因为缺乏正式依据且风险高。
+  - 只在日志中记录、不在接口返回中表达：否决，因为不利于评审和实现。
+
+## 决策 5：治理台账保持“部分实现，闭环未完全收口”
+
+- **Decision**: `REV-002` 的当前实现判断继续保持“部分实现”，但增加“账单生成规则与结果表达已完成文档收口”的说明。
+- **Rationale**:
+  - 当前治理台账已明确部分实现，且 backend 未见完整“账单生成专用闭环接口”证据。
+  - 文档补齐不应被误读为实现已完成。
+  - 这种表述更利于后续继续校核实现入口与缺口。
+- **Alternatives considered**:
+  - 改成“已实现”：否决，因为证据不足。
+  - 保持“部分实现”但不提设计进展：否决，因为无法体现本轮交付价值。
--- a/specs/005-rev002-billing-generation-gap/spec.md
+++ b/specs/005-rev002-billing-generation-gap/spec.md
@ -0,0 +1,130 @@
+# Feature Specification: REV-002 开账计费与账单生成缺口补齐
+
+**Feature Branch**: `005-rev002-billing-generation-gap`
+**Created**: 2026-03-18
+**Status**: Draft
+**Input**: User description: "docs/design/02_Detailed_Design/12_REV_Detailed.md 中 REV-002 开账计费与账单生成缺口补齐，明确 IF-REV-005 的业务边界、账单生成规则、结果表达、数据承接口径与治理台账同步"
+
+## 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/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+  - `docs/design/00_Management/01_Project_Progress.md`
+  - `docs/design/00_Management/03_Task_Checklist.md`
+- **Primary source of truth**:
+  - `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/04_Writing_Guide.md`
+  - `AGENTS.md`
+- **Reference sources**:
+  - `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+  - `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/`
+- **Scope decision**: In scope. 本 feature 仅补齐 `REV-002` 中“开账计费与账单生成”缺口，重点收口 `IF-REV-005`、计费规则来源、账单生成结果表达、数据承接口径和治理台账同步；不扩展到整个抄表采集链路、收费核销链路或新增平行正式主稿。
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - 收口开账生成规则 (Priority: P1)
+
+作为文档维护者，我需要把 `REV-002` 的开账计费规则、账单生成触发条件、费用组成和结果表达写清楚，使评审者能够明确“抄表数据如何转为营业账”和“账单生成结果如何表达”。
+
+**Why this priority**: 当前 `REV-002` 已具备抄表与开账摘要，但“IF-REV-005` 的闭环规则和结果表达”仍偏概括，后续接口、数据库和实现评估都依赖这部分先收口。
+
+**Independent Test**: 单独评审 `12_REV_Detailed.md` 中 `REV-002` 相关章节，应能明确账单生成入口、价格规则来源、费用组成、异常处理和生成结果表达。
+
+**Acceptance Scenarios**:
+
+1. **Given** 当前文档只说明“按价格模板和费用组成计费”， **When** 评审者阅读补齐后的详细设计， **Then** 能明确开账计费的输入、规则来源、结果对象和后续流转边界。
+2. **Given** 后续需要将账单生成闭环拆为研发任务， **When** 维护者依据该规格拆解工作， **Then** 不需要再回到 Archive 才能判断本轮正式范围和排除项。
+
+---
+
+### User Story 2 - 统一 IF-REV-005 与数据承接口径 (Priority: P2)
+
+作为接口与数据设计评审者，我需要看到 `IF-REV-005` 的输入输出、状态语义、异常口径和数据库承接口径，使账单生成不再停留在“生成账单”这种过于抽象的描述。
+
+**Why this priority**: `REV-002` 当前被评为“部分实现”，核心风险就在于接口闭环和数据承接口径不够清楚，容易导致文档与已有 `charge/chargedetail` 实现映射失真。
+
+**Independent Test**: 单独评审接口主文档和数据库主文档，应能确认 `IF-REV-005` 的查询/生成边界、结果字段语义和 `biz_charge*` 承接口径。
+
+**Acceptance Scenarios**:
+
+1. **Given** 评审者查看接口设计， **When** 阅读 `IF-REV-005` 章节， **Then** 能明确请求条件、生成结果、异常语义和状态表达。
+2. **Given** 评审者查看数据库设计， **When** 阅读开账与账单相关章节， **Then** 能明确 `biz_charge`、`biz_charge_detail`、价格模板和费用组成在账单生成中的承接关系。
+
+---
+
+### User Story 3 - 同步治理与实现评估结论 (Priority: P3)
+
+作为后续立项和实施跟踪人员，我需要在治理台账中看到 `REV-002` 的当前缺口、设计收口结果和后续建议，避免继续把“部分实现”的范围说得过宽或过窄。
+
+**Why this priority**: `15_SYS002_Requirement_Breakdown.md` 已明确 `REV-002` 的开账计费与账单生成为高优先缺口，文档收口后必须同步治理结论。
+
+**Independent Test**: 单独检查治理台账，应能明确 `REV-002` 当前属于“文档收口后仍为部分实现”的状态，并能看到后续建议。
+
+**Acceptance Scenarios**:
+
+1. **Given** 评审者查看需求拆解与实现评估文档， **When** 阅读 `SYS002-REQ-004` 对应内容， **Then** 能明确设计收口结果、当前实现状态和下一步建议。
+2. **Given** 项目需要记录本轮重要文档动作， **When** 查看项目进度与任务清单， **Then** 能定位 `REV-002` 的开账计费规则收口记录和校验结果。
+
+---
+
+### Edge Cases
+
+- 当抄表数据存在异常复核、估抄、补抄或重录场景时，账单生成规则如何保持正式文档口径一致，而不展开实现细节？
+- 当特殊开账、无码客户开账或罚款类开账进入同一账单主模型时，如何定义结果表达而不误写为独立平行主表？
+- 当价格模板、阶梯规则、费用组成缺失或冲突时，如何在接口和详细设计中统一表达“阻断生成”的异常语义？
+- 当当前 backend 已有 `charge/chargedetail` 入口但未见明确“专用账单生成闭环接口”证据时，如何如实表达“部分实现”而不夸大为完整闭环？
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: Specification MUST identify the exact target documents for `REV-002` billing-generation closure and ledger sync.
+- **FR-002**: Specification MUST identify `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md` as the main source-of-truth documents for this feature.
+- **FR-003**: Specification MUST record that the feature is in scope only for `IF-REV-005` business boundary, billing-rule source, result expression, database-side retention, and governance sync, not for the entire meter-reading or payment domain.
+- **FR-004**: Specification MUST preserve the single-source-of-truth model and MUST NOT create a parallel formal document for billing generation.
+- **FR-005**: Specification MUST define the billing-generation trigger path from validated reading result to charge creation, including rule sources such as price category, price template, tier rule, cost component, and water-use scheme where applicable.
+- **FR-006**: Specification MUST define the minimum result expression for generated charge outputs, including master/detail relationship, period, customer/account linkage, amount composition, and downstream handoff boundary.
+- **FR-007**: Specification MUST define the formal boundary of `IF-REV-005`, including request preconditions, output result semantics, exception semantics, and what remains outside the interface.
+- **FR-008**: Specification MUST define how abnormal reading and special-billing scenarios relate to the normal billing flow without requiring a new standalone online billing model.
+- **FR-009**: Specification MUST define the database-side retention and mapping boundary for billing generation, clarifying the role of `biz_charge`、`biz_charge_detail` and related pricing objects.
+- **FR-010**: Specification MUST define exclusions for this feature, including payment write-off, invoice issuance, reminder follow-up, and unrelated statistics/reporting concerns.
+- **FR-011**: Specification MUST capture cross-document consistency impacts for `IF-REV-005`, billing terminology, result-state wording, historical “特殊开账/开账记录”承接 and governance wording.
+- **FR-012**: Specification MUST list the validation actions required after document updates, including single-file validation for impacted docs and link consistency checks.
+- **FR-013**: Specification MUST state that formal document changes under this feature require synchronized updates to `01_Project_Progress.md` and `03_Task_Checklist.md`.
+- **FR-014**: Specification MUST record the current implementation judgment for this gap as “部分实现，需进一步收口账单生成闭环” unless stronger evidence is found later.
+
+### Assumptions
+
+- 本 feature 以正式文档补齐和后续研发立项准备为目标，默认不在本轮直接修改 backend 代码。
+- `IF-REV-005` 继续作为 `REV-002` 的正式账单生成接口编号，不新发明新的 `IF-*` 编号体系。
+- 当前 backend 已见 `charge/chargedetail/collection` 相关入口，因此本轮默认按“部分实现，闭环未完全收口”处理。
+- 账单生成结果主要由 `biz_charge`、`biz_charge_detail` 和价格/费用规则对象承接，本轮不臆造新的独立账单主模型。
+- 特殊开账属于营业账主模型下的来源类型或业务类型扩展，不默认要求新建平行表族。
+
+### Key Entities *(include if feature involves data)*
+
+- **Billing Trigger**: 从抄表校验结果进入开账计费的正式触发条件集合。
+- **Billing Rule Source**: 价格归属、价格模板、阶梯规则、费用组成和计划用水方案等规则来源。
+- **Billing Result**: 账单生成后的主单/明细结果表达，包括账期、客户、金额组成和状态边界。
+- **Billing Query Contract**: `IF-REV-005` 的输入条件、输出结果和异常语义定义。
+- **Charge Master/Detail Mapping**: `biz_charge` 与 `biz_charge_detail` 的正式承接口径。
+- **Ledger Update**: 当 `REV-002` 文档收口后，需要同步回写到项目进度和任务清单的治理记录。
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 评审者可在 5 分钟内从规格中定位 `REV-002` 的目标文档、开账计费边界、规则来源和排除项。
+- **SC-002**: 规格中至少覆盖 3 类独立可评审内容：开账规则闭环、`IF-REV-005` 接口边界、数据库承接口径/实现评估。
+- **SC-003**: 规格明确区分至少 5 项关键生成口径或结果要素，如账期、客户/账户、应收金额、费用组成、主明细关系、异常阻断语义。
+- **SC-004**: 后续执行 `/speckit.plan` 时，规划者无需再补充范围澄清即可将工作拆分为详细设计补齐、接口补齐、数据库口径补齐和治理台账同步四类任务。
+- **SC-005**: 规格明确列出全部必要验证动作，审阅者可直接据此执行至少 4 项文档校验或一致性检查。
--- a/specs/005-rev002-billing-generation-gap/tasks.md
+++ b/specs/005-rev002-billing-generation-gap/tasks.md
@ -0,0 +1,126 @@
+# Tasks: REV-002 开账计费与账单生成缺口补齐
+
+**Input**: Design documents from `/specs/005-rev002-billing-generation-gap/`
+**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/, quickstart.md
+
+**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
+
+## Phase 1: Scope & Source Confirmation (Shared Foundation)
+
+**Purpose**: Confirm the source-of-truth set, scope boundaries, and cross-document impact before editing.
+
+- [x] T001 Confirm target documents and target sections in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/spec.md`
+- [x] T002 Confirm authoritative sources and allowed reference inputs in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/plan.md`
+- [x] T003 [P] Confirm fixed decisions for `IF-REV-005`、账单结果承接和异常语义 in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/research.md`
+- [x] T004 [P] Confirm entities, contract fields, and validation commands in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/data-model.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/contracts/rev002-billing-contract.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/quickstart.md`
+
+---
+
+## Phase 2: User Story 1 - 收口开账生成规则 (Priority: P1) 🎯 MVP
+
+**Goal**: 补齐 `REV-002` 详细设计中的开账触发前提、规则来源、结果表达、特殊开账统一模型和排除项。
+
+**Independent Test**: 单独评审 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 的 `REV-002` 章节，应能明确账单生成入口、价格规则来源、费用组成、异常阻断语义和下游边界。
+
+### Implementation for User Story 1
+
+- [x] T005 [US1] Read `docs/design/00_Management/01_Project_Progress.md`, `docs/design/00_Management/02_Delivery_Standards.md`, `docs/design/00_Management/03_Task_Checklist.md`, and `docs/design/02_Detailed_Design/12_REV_Detailed.md` before editing
+- [x] T006 [US1] Update `docs/design/02_Detailed_Design/12_REV_Detailed.md` to define `REV-002` billing trigger path, billing rule sources, result expression, special-billing inclusion, and explicit exclusions
+- [x] T007 [US1] Sync `REV-002` wording in `docs/design/01_Overview/03_Summary_Design.md` only if detailed-design terms or boundaries need matching references
+- [x] T008 [US1] Run `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` and capture the result in work notes
+- [x] T009 [US1] Run `make check-links` if `docs/design/02_Detailed_Design/12_REV_Detailed.md` headings, anchors, or cross-document links changed and capture the result in work notes
+
+**Checkpoint**: `REV-002` detailed design is independently reviewable and no longer stops at summary-level billing wording.
+
+---
+
+## Phase 3: User Story 2 - 统一 IF-REV-005 与数据承接口径 (Priority: P2)
+
+**Goal**: 统一接口主文档和数据库主文档中的 `IF-REV-005`、账单结果承接和异常边界口径。
+
+**Independent Test**: 单独评审 `docs/design/03_Technical_Design/03_Interface_Design.md` 与 `docs/design/03_Technical_Design/01_Database_Design.md`，应能明确请求条件、结果语义、异常阻断逻辑以及 `biz_charge` / `biz_charge_detail` 承接口径。
+
+### Implementation for User Story 2
+
+- [x] T010 [US2] Update `docs/design/03_Technical_Design/03_Interface_Design.md` to define `IF-REV-005` request preconditions, response semantics, exception semantics, and boundary with downstream charging flow
+- [x] T011 [US2] Update `docs/design/03_Technical_Design/01_Database_Design.md` to align `biz_charge`, `biz_charge_detail`, pricing-rule objects, and historical/special billing retention with the approved `REV-002` model
+- [x] T012 [P] [US2] Sync numbering, terminology, and cross-references between `docs/design/03_Technical_Design/03_Interface_Design.md` and `docs/design/03_Technical_Design/01_Database_Design.md`
+- [x] T013 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` and capture the result in work notes
+- [x] T014 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` and capture the result in work notes
+- [x] T015 [US2] Run `make check-links` after interface/database cross-reference updates and capture the result in work notes
+
+**Checkpoint**: `IF-REV-005` and database retention are independently reviewable and use one consistent billing-generation model.
+
+---
+
+## Phase 4: User Story 3 - 同步治理与实现评估结论 (Priority: P3)
+
+**Goal**: 在治理台账中回写 `REV-002` 本轮设计收口结果，并保持“部分实现”的真实实现评估。
+
+**Independent Test**: 单独评审治理文档，应能明确本轮已完成的是文档收口，不是 backend 闭环实现完成，并能看到后续建议与校验记录。
+
+### Implementation for User Story 3
+
+- [x] T016 [US3] Update `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` to retain the `部分实现` judgment and add this round's design-closure result and next-step recommendation
+- [x] T017 [US3] Update `docs/design/00_Management/01_Project_Progress.md` to record the `REV-002` documentation alignment action and validation outcome
+- [x] T018 [US3] Update `docs/design/00_Management/03_Task_Checklist.md` to reflect the completed `REV-002` document-maintenance tasks
+- [x] T019 [US3] Run `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` and capture the result in work notes
+- [x] T020 [US3] Run `make validate-file FILE=docs/design/00_Management/01_Project_Progress.md` and `make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md` and capture the results in work notes
+
+**Checkpoint**: Governance documents are independently reviewable and preserve the correct “部分实现” narrative.
+
+---
+
+## Final Phase: Cross-Cutting Closure
+
+**Purpose**: Ensure repository-wide consistency after all story slices are complete.
+
+- [x] T021 [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/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- [x] T022 [P] Re-check relative links, stable anchors, and numbering consistency across all modified files with `make check-links`
+- [x] T023 Prepare final summary from `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/quickstart.md` and actual validation results, including modified files, remaining risks, and next-step suggestions
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Phase 1**: No dependencies; MUST finish before document edits
+- **User Story 1**: Depends on Phase 1 and provides the billing-rule baseline for later phases
+- **User Story 2**: Depends on User Story 1 wording being stable
+- **User Story 3**: Depends on User Story 1 and User Story 2 conclusions being fixed
+- **Final Phase**: Depends on all selected user stories being complete
+
+### Within Each User Story
+
+- Read required governance and target docs before editing
+- Complete target document edits before terminology and reference sync
+- Complete content edits before validation
+- Complete validation before governance ledgers are considered closed
+
+### Parallel Opportunities
+
+- `T003` and `T004` can run in parallel during foundation review
+- `T012` can run in parallel with validation preparation once interface and database edits are drafted
+- `T021` and `T022` can run in parallel during final closure
+
+## Implementation Strategy
+
+- **MVP first**: 先完成 User Story 1，使 `REV-002` 详细设计具备独立评审价值
+- **Incremental delivery**: 再完成 User Story 2 收口接口与数据库，最后完成 User Story 3 的治理同步
+- **Validation-first closure**: 每个 story 完成后立即执行对应校验，再推进下一阶段，避免跨文档口径回滚
+
+## Notes
+
+- 本 feature 只做文档治理，不默认修改 backend 代码
+- 不得新发明 `IF-*` 编号或“特殊开账平行主表”
+- Archive 仅用于核对来源，不直接替代正式结论
+- `specs/001-rev004-accounting/checklists/scope-alignment.md` 与本轮无关，不应纳入本 feature 变更