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

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 项文档校验或一致性检查。