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>
131 lines
10 KiB
Markdown
131 lines
10 KiB
Markdown
# 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 项文档校验或一致性检查。
|