fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/spec.md

Feature Specification: REV-007 营收统计查询设计

Feature Branch: 004-rev007-revenue-statistics-design Created: 2026-03-18 Status: Draft Input: User description: "docs/design/02_Detailed_Design/12_REV_Detailed.md 中 REV-007 统计分析的设计补齐，明确统计主题、指标口径、查询维度、接口边界、历史/现状承接与治理台账同步"

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/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-007 的正式设计口径、接口边界、统计主题与指标维度、数据库承接口径及治理台账同步；不扩展到 BI 专题、预测模型、独立数仓实现或新增平行正式主稿。

User Scenarios & Testing (mandatory)

User Story 1 - 收口统计业务范围 (Priority: P1)

作为文档维护者，我需要把 REV-007 的统计主题、查询维度、核心指标和边界限制写清楚，使评审者能够明确哪些统计属于营收主系统正式范围，哪些只保留为后续专题或报表层能力。

Why this priority: 当前 REV-007 在详细设计中只有摘要级描述，如果不先收口统计范围，后续接口、数据库和实现评估都会失焦。

Independent Test: 单独评审 12_REV_Detailed.md 中 REV-007 章节，应能明确统计主题、维度、典型指标、导出边界和排除项。

Acceptance Scenarios:

1. Given 当前 REV-007 只有简短说明， When 评审者阅读补齐后的详细设计， Then 能独立回答营收统计包含哪些主题、按哪些维度查询以及不包含哪些专题分析。
2. Given 后续需要把统计设计转为研发任务， When 维护者依据该规格拆解工作， Then 不需要再回到 Archive 才能判断本轮的主题、指标和排除项。

---

User Story 2 - 统一接口与数据承接口径 (Priority: P2)

作为接口与数据设计评审者，我需要看到 IF-REV-010 的查询边界、输入条件、输出主题和数据库承接口径，使统计查询不再停留在“聚合视图/统计结果集”这种过于抽象的表述。

Why this priority: 统计设计的核心风险在于接口口径与数据来源不清，容易把在线交易表、历史查询和报表专题混写在一起。

Independent Test: 单独评审接口主文档和数据库主文档，应能确认 IF-REV-010 的查询主题、筛选条件、最小返回要求和数据来源边界。

Acceptance Scenarios:

1. Given 评审者查看接口设计， When 阅读 IF-REV-010 章节， Then 能明确统计主题、输入维度、输出指标摘要和权限/导出边界。
2. Given 评审者查看数据库设计， When 阅读统计分析相关章节， Then 能明确哪些统计依赖在线主数据聚合、哪些仅作为视图或汇总口径描述，且不误写为已存在独立统计表族。

---

User Story 3 - 同步治理与实现评估结论 (Priority: P3)

作为后续立项和实施跟踪人员，我需要在治理台账中看到 REV-007 的当前实现判断、正式收口结果和后续建议，避免重复把同一统计能力误判为“已实现”或“已设计完成”。

Why this priority: 15_SYS002_Requirement_Breakdown.md 已把 REV-007 评为“未见实现”，正式文档补齐后需要同步治理口径，否则后续跟踪会失真。

Independent Test: 单独检查治理台账，应能明确 REV-007 当前属于“设计收口完成、实现仍未见明确入口”的状态，并能看到后续建议。

Acceptance Scenarios:

1. Given 评审者查看需求拆解与实现评估文档， When 阅读 SYS002-REQ-012 对应内容， Then 能明确设计补齐结果、当前实现状态和下一步建议。
2. Given 项目需要记录本轮重要文档动作， When 查看项目进度与任务清单， Then 能定位 REV-007 的设计收口记录和校验结果。

---

Edge Cases

• 当某类统计主题只在历史需求或 Archive 中出现，而当前主文档未形成正式口径时，应如何判定为本轮正式范围还是后续专题保留项？
• 当统计查询需要同时覆盖在线业务数据与历史只读口径时，如何保持“查询可追溯”但不误写为新增独立统计主表？
• 当不同统计主题共享维度但指标含义不同，例如“收费金额”“实收金额”“应收金额”“欠费余额”时，如何避免同名不同义的口径冲突？
• 当当前 backend 未见明确统计控制器或报表入口时，如何如实表达“设计已补齐、实现未见入口”的状态，而不把文档收口误写成已实现能力？

Requirements (mandatory)

Functional Requirements

• FR-001: Specification MUST identify the exact target documents for REV-007 design 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 REV-007 formal design closure and follow-up implementation preparation, not for independent BI platform, data warehouse, or predictive analytics implementation.
• FR-004: Specification MUST preserve the single-source-of-truth model and MUST NOT create a parallel formal statistics design document.
• FR-005: Specification MUST define the main statistics themes for REV-007, including at minimum revenue, billing, payment, arrears, customer, channel, meter-reading completion, and operational work-order related summary topics where applicable.
• FR-006: Specification MUST define the query dimensions and filtering scope for REV-007, including at minimum time, bill period, region/department, customer category, channel, account/customer, and status-oriented filters where relevant.
• FR-007: Specification MUST define the key indicators or result sets for the supported themes, and MUST distinguish similar but non-equivalent concepts such as receivable amount, actual collected amount, arrears balance, transaction count, and completion rate.
• FR-008: Specification MUST define the formal boundary of IF-REV-010, including request conditions, output themes, permission/export constraints, and what remains outside this interface.
• FR-009: Specification MUST define the database-side retention and aggregation boundary for REV-007, clarifying what is based on existing online business data aggregation, what may be expressed as views or summary results, and what must not be written as confirmed standalone statistics tables without evidence.
• FR-010: Specification MUST define exclusions for REV-007, including predictive models,专题深度分析、跨系统经营大屏专题、以及无实现证据的独立报表引擎能力。
• FR-011: Specification MUST capture cross-document consistency impacts for statistics terminology, indicators, interface numbering, data sources, implementation status wording, and ledger updates.
• 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 REV-007 as “设计补齐中 / 代码入口未见明确实现” unless stronger evidence is found during later phases.

Assumptions

• 本 feature 以正式文档补齐和后续研发立项准备为目标，默认不在本轮直接修改 backend 代码。
• IF-REV-010 继续作为 REV-007 的正式统计查询接口编号，不新发明新的 IF-* 编号体系。
• 当前 backend 检索范围内未见明确统计/报表控制器或服务骨架，因此本轮默认按“设计先行、实现待立项”处理。
• 统计查询主要依托现有在线业务主数据聚合与汇总结果承接，本轮不臆造独立统计仓库、离线批处理或专题分析引擎。
• 导出能力属于统计查询的扩展能力，应受权限控制，但不要求本轮展开具体导出实现细节。

Key Entities (include if feature involves data)

• Statistics Theme: 统计主题，如营收、收费、欠费、客户、渠道、抄表完成率、工单概览等查询域。
• Statistics Dimension: 统计维度，如时间、账期、片区、营业所、客户类别、渠道、状态、人员或册本。
• Statistics Indicator: 统计指标，如应收金额、实收金额、欠费余额、客户数、账单数、完成率、渠道占比等。
• Statistics Query Contract: IF-REV-010 的输入条件、输出摘要、权限与导出边界定义。
• Aggregation Source: 支撑统计结果的在线业务表、视图或汇总口径来源。
• Ledger Update: 当 REV-007 文档收口后，需要同步回写到项目进度和任务清单的治理记录。

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 评审者可在 5 分钟内从规格中定位 REV-007 的目标文档、统计主题范围、核心维度与排除项。
• SC-002: 规格中至少覆盖 3 类独立可评审内容：统计业务范围、IF-REV-010 接口边界、数据库承接口径/实现评估。
• SC-003: 规格明确区分至少 5 个核心指标或口径，并避免“应收/实收/欠费/笔数/完成率”混写。
• SC-004: 后续执行 /speckit.plan 时，规划者无需再补充范围澄清即可将工作拆分为详细设计补齐、接口补齐、数据库口径补齐和治理台账同步四类任务。
• SC-005: 规格明确列出全部必要验证动作，审阅者可直接据此执行至少 4 项文档校验或一致性检查。