docs: close rev007 statistics design alignment

2026-03-18 16:30:23 +08:00 · 2026-03-18 16:30:23 +08:00 · f6fd550545
commit f6fd550545
parent 53ebab5f51
14 changed files with 879 additions and 16 deletions
--- a/docs/design/00_Management/01_Project_Progress.md
+++ b/docs/design/00_Management/01_Project_Progress.md
@ -328,3 +328,5 @@
 - 完成 `REV-006` Speckit feature `003-rev006-reminder-event-design` 的 implement 阶段文档收口，统一 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md` 与治理台账口径。
 - `REV-006` 正式业务接口编号确定为 `IF-REV-013`，不再复用 `IF-REV-009`；催缴结果状态统一为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态。
 - 明确旧“催缴记录 / 停水记录 / 预存短信记录”按历史只读口径承接，不新增同名在线主表；停复水在本轮仅保留联动边界、处置引用和追溯关系。
+- 启动并完成 `REV-007` Speckit feature `004-rev007-revenue-statistics-design` 的 `specify -> plan -> tasks` 工件链，形成统计主题、维度、指标、`IF-REV-010` 与数据库承接口径的正式设计基线。
+- `REV-007` 当前收口结论为“设计补齐推进中、代码入口未见明确实现”；本轮重点是统一正式文档与治理台账，不将预测分析、BI 专题或独立数仓能力写成既成事实。
--- a/docs/design/00_Management/03_Task_Checklist.md
+++ b/docs/design/00_Management/03_Task_Checklist.md
@ -526,6 +526,14 @@
  - [x] 更新 `docs/design/03_Technical_Design/03_Interface_Design.md`，新增 `IF-REV-013` 正式接口定义，并统一 `IF-EXT-008` 协同字段、异常码、幂等键与历史查询口径 ✅
  - [x] 更新 `docs/design/03_Technical_Design/01_Database_Design.md`，明确历史只读保留策略、最小查询字段与处置引用边界 ✅
  - [x] 更新 `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`、`01_Project_Progress.md` 与本任务清单，完成 implement 阶段治理回写 ✅
+
+### 📋 REV-007 营收统计查询设计
+
+- [x] **完成 REV-007 设计工件初始化与正式文档收口启动** ✅ (2026-03-18)
+  - [x] 已生成 `specs/004-rev007-revenue-statistics-design/` 下的 `spec.md`、`plan.md`、`research.md`、`data-model.md`、`contracts/`、`quickstart.md`、`tasks.md` ✅
+  - [x] 已补齐 `12_REV_Detailed.md` 中 `REV-007` 的统计主题、维度、指标与范围边界 ✅
+  - [x] 已补齐 `03_Interface_Design.md` 中 `IF-REV-010` 的输入输出、权限与导出边界，且不扩写为 BI / 预测分析能力 ✅
+  - [x] 已补齐 `01_Database_Design.md` 的统计承接口径，并在治理台账中保持“代码入口未见明确实现”的真实结论 ✅
  - [x] 补齐一级目录 `README.md` 索引（7/7） ✅
  - [x] 新增 AI 检索优先白名单：`docs/design/00_Management/10_AI_Retrieval_Whitelist.md` ✅
 - [x] **第 2 周：主文档元数据统一** ✅ (2026-03-11)
--- a/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md
+++ b/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md
@ -80,7 +80,7 @@
 | SYS002-REQ-009 | 发票结果查询与补偿 | 已实现 | `InvoiceServiceImpl.java` 中 `applicationNo`、`sysRequestNo`、`lastTryTime`、`nextTryTime`、`tryCount`、`latestResult`、`latestError` 等字段与补偿逻辑 | 与文档中“查询补偿、回写优先、主动查询兜底”口径高度一致。 |
 | SYS002-REQ-010 | 发票结果回写 | 已实现 | `controller/admin/invoice/vo/InvoiceWriteBackReqVO.java`、`InvoiceServiceImpl.java`、`InvoiceMapper.java` | 已见回写入参与主键查询、回写及状态保护相关实现痕迹。 |
 | SYS002-REQ-011 | 催缴与通知协同 | 未见实现 | 当前在 `backend/sw-business` 中未检索到明确的 `Reminder/Message/Notice` 业务控制器 | 本轮已完成 `IF-REV-013`、四态状态集、历史只读边界和停复水联动边界的正式文档收口，但 backend 仍未见明确催缴/通知业务实现骨架。 |
-| SYS002-REQ-012 | 营收统计查询 | 未见实现 | 当前在 `backend/sw-business` 中未检索到明确的 `Statistic/Report/Analysis` 控制器 | 文档已有统计口径，但代码层未见明显统计查询实现入口。 |
+| SYS002-REQ-012 | 营收统计查询 | 未见实现 | 当前在 `backend/sw-business` 中未检索到明确的 `Statistic/Report/Analysis` 控制器 | 本轮已补齐 `REV-007` 统计主题、维度、指标、`IF-REV-010` 和数据库承接口径，但代码层仍未见明显统计查询实现入口。 |
 | SYS002-REQ-013 | 银行代扣与回盘 | 已实现 | `backend/sw-business-bank/.../withholdingbatch/WithholdingBatchController.java`、`withholdingitem/WithholdingItemController.java`、`withholdingagreement/WithholdingAgreementController.java`、`app/bankwithholding/BankWithholdingController.java` | 代扣批次、明细、协议、应用侧代扣入口均已存在。 |
 | SYS002-REQ-014 | 对账与结算处理 | 已实现 | `backend/sw-business-bank/.../reconcilebatch/ReconcileBatchController.java`、`reconcilediff/ReconcileDiffController.java`、`settlementbatch/SettlementBatchController.java`、`ReconcileStatusEnum.java`、`SettlementBatchDO.java` | 对账批次、差异、结算批次与状态枚举均已具备。 |
 | SYS002-REQ-015 | 业务参数配置 | 已实现 | `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/parametersettings/ParameterSettingsController.java`、`controller/app/parametersettings/AppParameterSettingsController.java` | 后台与 App 侧参数配置入口均已存在。 |
@ -102,7 +102,7 @@
 | SYS-002：补齐发票结果查询与补偿规则 | SYS002-REQ-009 | `sys002-invoice-result-query-rules` | 已实现 | 高 | 已进入完成态，适合转为验收/归档类 Story。 |
 | SYS-002：统一发票结果回写口径 | SYS002-REQ-010 | `sys002-invoice-writeback-sync` | 已实现 | 高 | 已进入完成态，适合转为验收/归档类 Story。 |
 | SYS-002：补齐催缴事件与通知协同设计 | SYS002-REQ-011 | `sys002-reminder-event-design` | 未见实现 | 高 | 设计口径已完成第一轮收口，可继续按 `IF-REV-013` 和四态状态集推进后续实现立项。 |
-| SYS-002：补齐营收统计查询设计 | SYS002-REQ-012 | `sys002-revenue-statistics-design` | 未见实现 | 中 | 建议先确认范围，再决定是否立项。 |
+| SYS-002：补齐营收统计查询设计 | SYS002-REQ-012 | `sys002-revenue-statistics-design` | 未见实现 | 中 | 设计口径已完成第一轮收口，建议按 `IF-REV-010` 和统计主题口径继续立项实现。 |
 | SYS-002：统一银行代扣与回盘协同口径 | SYS002-REQ-013 | `sys002-bank-withholding-sync` | 已实现 | 中 | 已有银行子系统实现，建议做跨文档口径收口。 |
 | SYS-002：补齐对账与结算处理规则 | SYS002-REQ-014 | `sys002-reconcile-settlement-rules` | 已实现 | 中 | 重点收口对账差异分类与结算边界。 |
 | SYS-002：补齐业务参数配置设计 | SYS002-REQ-015 | `sys002-parameter-config-design` | 已实现 | 中 | 适合做参数配置与统一平台边界校核。 |
@ -131,7 +131,7 @@
 | `REV-004` 账务处理 | 已实现 | 以规则收口、二期扩展或历史台账映射为主 |
 | `REV-005` 发票与税务处理 | 已实现 | 以验收归档和细粒度对象补证为主 |
 | `REV-006` 催缴与通知 | 未见实现 | 已完成 Speckit `specify -> clarify -> plan -> tasks`，当前进入 `implement` 阶段的正式文档收口与台账同步。 |
-| `REV-007` 统计分析 | 未见实现 | 建议完整走 Speckit：`specify -> clarify -> plan -> tasks` |
+| `REV-007` 统计分析 | 未见实现 | 已完成 Speckit `specify -> plan -> tasks`，当前进入 `implement` 阶段的正式文档收口与治理同步。 |
 | `REV-008` 代收与银行业务 | 已实现 | 以跨系统口径收口和扩展台账补证为主 |
 | `REV-009` 业务参数配置 | 已实现 | 以参数边界收口和治理能力补充为主 |

@ -154,7 +154,7 @@
 | `REV-005` | 否 | `rev005-detail-reconciliation` | 中 | 仅在补发票细表/批次缺口时使用 |
 | `REV-006` | 是 | `rev006-reminder-event-design` | 最高 | 已作为未实现模块的首个完整 Speckit feature 启动，当前重点转向实现闭环与后续研发立项。 |
 | `REV-006` | 是 | `rev006-notice-result-writeback` | 高 | 可作为 `REV-006` 拆分子 feature |
-| `REV-007` | 是 | `rev007-revenue-statistics-design` | 高 | 建议先补经营统计主查询能力 |
+| `REV-007` | 是 | `rev007-revenue-statistics-design` | 高 | 已启动并完成第一轮设计工件，当前建议继续收口正式文档并形成后续研发切入点 |
 | `REV-007` | 是 | `rev007-channel-analysis-query` | 中 | 适合作为统计分析子 feature |
 | `REV-008` | 否 | `rev008-reconcile-closure` | 中 | 仅在对账闭环出现明确 gap 时使用 |
 | `REV-009` | 否 | `rev009-parameter-governance` | 低 | 仅在参数治理能力需补齐时使用 |
@ -259,13 +259,13 @@
 - 当前实现状态：`未见实现`
 - Story 描述：
  - 目标：补齐营收、收费、欠费、渠道、客户维度统计查询能力与口径定义。
-  - 当前判断：文档已定义统计范围，但当前代码检索中未见明确统计/报表后台入口。
+  - 当前判断：文档已定义摘要级统计范围，但本轮需进一步补齐统计主题、维度、指标、`IF-REV-010` 和数据库承接口径；当前代码检索中仍未见明确统计/报表后台入口。
 - 推荐 Task：
  - `T-012-01` 对齐统计主题、维度、指标口径
-  - `T-012-02` 对齐统计接口与查询条件定义
-  - `T-012-03` 对齐统计视图/汇总表与数据来源
+  - `T-012-02` 对齐 `IF-REV-010` 接口与查询条件定义
+  - `T-012-03` 对齐统计视图/汇总口径与数据来源
  - `T-012-04` 校核代码是否已有隐含统计实现或需新增模块
-  - `T-012-05` 输出统计专题立项建议
+  - `T-012-05` 输出统计专题立项建议和最小研发切入点

 #### Story 5

--- a/docs/design/02_Detailed_Design/12_REV_Detailed.md
+++ b/docs/design/02_Detailed_Design/12_REV_Detailed.md
@ -528,30 +528,42 @@ flowchart TD

 ### 功能说明

-提供营收、抄表、收费、欠费、渠道、客户、工单等多维度统计分析能力，为经营分析和业务监管提供数据支撑。
+提供营收、抄表、收费、欠费、渠道、客户等多维度统计查询能力，为经营分析、业务监管和迁移核查提供统一的数据口径支撑；本模块以经营查询为主，不扩展到预测分析、专题大屏或独立 BI 平台实现。

 ### 关键设计

-1. 报表统计基于客户、账单、收费、渠道、时间、片区等维度聚合。
-2. 常用统计口径包括售水量、收费金额、欠费规模、渠道占比、客户类型分布、抄表完成率等。
-3. 导出与查询结果受数据权限控制，重点报表可采用预聚合或物化结果提升查询性能。
+1. 统计查询按“主题 + 维度 + 指标”三层口径组织，避免仅以报表名称堆砌需求。
+2. 主题范围至少包括营收汇总、收费与实收统计、欠费规模与账龄统计、客户结构统计、渠道交易统计、抄表完成率统计以及营收相关业务概览类摘要。
+3. 查询维度至少包括时间区间、账期、营业所/片区、客户类别、渠道、客户/账户、状态等，并支持必要的分组汇总。
+4. 指标口径需明确区分应收金额、实收金额、欠费余额、账单数、客户数、交易笔数、渠道占比、抄表完成率等相近但不等价的统计概念。
+5. 导出与查询结果受数据权限控制；导出属于查询扩展能力，但不在本轮展开具体导出实现细节。
+6. 重点查询可按聚合视图、汇总口径或预聚合结果承接，但不将未确认存在的统计表、专题分析表或离线数仓对象写成已实现事实。

 ### 核心数据

 - 客户维度：`biz_cust`、`biz_account`。
 - 抄表维度：`biz_meter_book`、`biz_reading_data`、`biz_last_reading`。
 - 账务与收费维度：`biz_charge`、`biz_charge_detail`。
+- 收费与交易维度：`biz_collection`、`bk_transaction`。
 - 渠道维度：`bk_transaction`、`bk_payment_channel`。
+- 组织与权限维度：`system_dept`、数据权限控制结果。
+
+#### 统计主题与口径摘要
+
+- `Statistics Theme`：按经营主题组织查询，至少覆盖营收、收费、欠费、客户、渠道、抄表完成率和必要的业务概览。
+- `Statistics Dimension`：按时间、账期、营业所/片区、客户类别、渠道、客户/账户、状态等条件筛选或分组。
+- `Statistics Indicator`：至少明确应收金额、实收金额、欠费余额、账单数、客户数、交易笔数、渠道占比、完成率等指标含义和单位。
+- `Aggregation Source`：统计结果以现有在线主数据聚合、视图或汇总口径承接，不反推为已存在独立统计表族。

 ### 接口映射

- `IF-REV-010`：营收、收费、欠费、渠道、客户等统计查询接口。
+- `IF-REV-010`：营收、收费、欠费、渠道、客户等统计查询接口，承接主题查询、维度筛选、指标汇总和权限/导出边界。

 ### 落地边界

- **已落地**：主要统计源数据在客户、抄表、收费、渠道等领域均已具备。
- **部分落地**：部分分析结果更多依赖报表层实现，而非单独分析表。
- **文档先行**：预测类、专题分析类深度模型暂不写成后端已实现能力。
+- **已落地**：主要统计源数据在客户、抄表、账单、收费、交易和渠道等领域均已具备，足以支撑经营统计口径设计。
+- **部分落地**：部分统计结果可能依赖聚合视图、汇总查询或报表层实现，当前未见明确的 backend 统计控制器或独立统计模型入口。
+- **文档先行**：预测类、专题分析类深度模型、BI 大屏和独立数仓能力暂不写成后端已实现能力。

 <a id="mod-rev-008"></a>

--- a/docs/design/03_Technical_Design/01_Database_Design.md
+++ b/docs/design/03_Technical_Design/01_Database_Design.md
@ -1890,6 +1890,32 @@ WHERE t.deleted = 0
 GROUP BY t.id, t.name;
 ```

+### REV-007 统计承接口径
+
+#### 设计定位
+
+- `REV-007` 以在线业务主数据聚合、视图或汇总口径支撑经营统计查询，不在本轮确认独立统计仓库、离线批处理表或专题分析表族。
+- 统计结果必须能够追溯到现有客户、账单、收费、交易、抄表和组织维度数据来源。
+- 当前数据库主文档仅约束“统计查询如何承接”，不反推 backend 已存在专门统计模块或已固化全部统计视图。
+
+#### 最小统计主题承接口径
+
+| 统计主题 | 主数据来源 | 最低维度要求 | 最低指标要求 | 承接方式 |
+| :--- | :--- | :--- | :--- | :--- |
+| 营收汇总 | `biz_charge`、`biz_charge_detail` | 时间、账期、营业所、客户类别 | 应收金额、账单数、用水量 | 在线聚合 / 汇总口径 |
+| 收费与实收统计 | `biz_collection`、`bk_transaction` | 时间、渠道、营业所、收费状态 | 实收金额、收费笔数、成功率 | 在线聚合 / 汇总口径 |
+| 欠费规模与账龄统计 | `biz_charge`、`biz_charge_detail` | 账期、账龄、客户类别、区域 | 欠费余额、欠费户数、账龄分布 | 在线聚合 / 汇总口径 |
+| 客户结构统计 | `biz_cust`、`biz_account` | 客户类别、区域、状态 | 客户数、账户数、活跃状态分布 | 在线聚合 / 视图口径 |
+| 渠道交易统计 | `bk_transaction`、`bk_payment_channel` | 渠道、日期、结果状态 | 交易笔数、交易金额、渠道占比 | 在线聚合 / 汇总口径 |
+| 抄表完成率统计 | `biz_meter_book`、`biz_reading_data`、`biz_last_reading` | 抄表周期、册本、片区、人员 | 应抄户数、已抄户数、完成率 | 在线聚合 / 汇总口径 |
+
+#### 设计约束
+
+- 统计查询可以由视图、临时汇总结果或聚合 SQL 承接，但未确认存在的 `stat_*`、`report_*` 或专题报表表不得写成正式已实现对象。
+- 若某类统计仅在历史资料中出现而当前主文档未形成正式口径，应先作为后续专题保留项，不直接扩写为当前正式范围。
+- 涉及历史迁移核查的统计比对时，历史来源只承担补充核对职责，不替代在线主数据统计结果。
+- 导出能力属于查询扩展能力，数据库设计不单独为导出动作臆造新的物理表。
+
 <a id="sec-index-performance"></a>
 # 索引设计与性能优化

--- a/docs/design/03_Technical_Design/03_Interface_Design.md
+++ b/docs/design/03_Technical_Design/03_Interface_Design.md
@ -448,6 +448,23 @@ retrieval_priority: P0
 - 接口状态固定为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态，不在本轮扩展“已阅读”“已补发”等细粒度业务状态。
 - 停复水仅作为联动边界与处置引用承接项，不在本接口中展开停复水内部流程。

+### IF-REV-010 统计查询接口
+
+| 项目 | 说明 |
+|------|------|
+| 接口编号 | IF-REV-010 |
+| 归属模块 | REV-007 |
+| 请求方式 | POST |
+| 请求路径 | `/admin-api/revenue/statistics/query`（导出：`/admin-api/revenue/statistics/export`） |
+| 功能描述 | 面向营收经营分析场景查询统计主题、维度汇总和指标结果，并在权限范围内支持导出 |
+| 核心表 | `biz_charge`、`biz_charge_detail`、`biz_collection`、`bk_transaction`、`biz_cust`、`biz_account`、`biz_meter_book`、`biz_reading_data` |
+
+边界约束：
+- `IF-REV-010` 只承接经营统计查询，不扩展到预测分析、BI 专题大屏或独立数仓查询。
+- 统计口径按“主题 + 维度 + 指标”组织，避免仅以报表名称表达接口范围。
+- 导出属于查询扩展能力，必须受数据权限和导出权限控制。
+- 没有明确实现证据的独立统计表、专题分析表或离线汇总表不得写成既成事实。
+
 ### IF-REV-011 银行代收协同接口

 | 项目 | 说明 |
@ -923,6 +940,49 @@ retrieval_priority: P0
 - 当外部结果长期未定、历史回执不足或人工核查已确认结果时，可将任务补记为 `MANUAL_VERIFIED`，并保留核查人和核查说明。
 - 接口返回的 `relatedDisposalRef` 仅用于追溯停复水、复水或工单处置引用，不表示本接口承担下游流程控制。

+### IF-REV-010 统计查询接口
+
+#### 请求参数
+
+| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 |
+|------|------|------|------|---------------|
+| themeCode | String | 是 | 统计主题编码 | 查询主题 |
+| dateFrom | Date | 是 | 开始日期 | 时间维度 |
+| dateTo | Date | 是 | 结束日期 | 时间维度 |
+| billPeriod | String | 否 | 账期 | `biz_charge.bill_period` |
+| deptId | Long | 否 | 营业所/部门 | `system_dept.id` |
+| regionCode | String | 否 | 片区/区域编码 | 区域维度 |
+| customerCategory | String | 否 | 客户类别 | 客户标签/分类 |
+| channelCode | String | 否 | 收费/交易渠道 | `bk_payment_channel.channel_code` |
+| accountId | Long | 否 | 账户标识 | `biz_account.id` |
+| custId | Long | 否 | 客户标识 | `biz_cust.id` |
+| statusSet | Array<String> | 否 | 状态集合 | 账单/收费/抄表等状态筛选 |
+| groupBy | Array<String> | 否 | 分组维度集合 | 结果分组 |
+| exportFlag | Boolean | 否 | 是否导出 | 导出控制 |
+
+#### 响应参数
+
+| 字段 | 类型 | 说明 | 主要来源 |
+|------|------|------|----------|
+| themeCode | String | 统计主题编码 | 查询主题 |
+| themeName | String | 统计主题名称 | 主题定义 |
+| dimensionSummary | Object | 查询维度摘要 | 查询条件 |
+| indicatorList | Array | 指标结果集合 | 聚合结果 |
+| indicatorList[].indicatorCode | String | 指标编码 | 指标定义 |
+| indicatorList[].indicatorName | String | 指标名称 | 指标定义 |
+| indicatorList[].indicatorValue | Decimal/String | 指标值 | 聚合结果 |
+| indicatorList[].unit | String | 指标单位 | 指标定义 |
+| groupRows | Array | 分组结果集合 | 维度分组结果 |
+| exportAllowed | Boolean | 是否允许导出 | 权限结果 |
+| msg | String | 处理说明 | 返回消息 |
+
+#### 查询主题与口径约束
+
+- 本接口至少支持营收汇总、收费与实收、欠费规模与账龄、客户结构、渠道交易、抄表完成率等主题查询。
+- 应收金额、实收金额、欠费余额、账单数、客户数、交易笔数、渠道占比、完成率等指标必须按业务含义区分，不得混写。
+- 当查询涉及历史只读口径时，历史数据仅作为补充来源或迁移核查辅助，不替代在线主数据统计结果。
+- 权限边界必须同时作用于在线查询和导出动作；不允许越过现有数据权限返回全量统计结果。
+
 ### IF-REV-011 银行代收协同接口

 #### 请求参数
--- a/specs/004-rev007-revenue-statistics-design/checklists/requirements.md
+++ b/specs/004-rev007-revenue-statistics-design/checklists/requirements.md
@ -0,0 +1,34 @@
+# Specification Quality Checklist: REV-007 营收统计查询设计
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-18
+**Feature**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/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-007` 默认按“设计先行、实现待立项”处理。
--- a/specs/004-rev007-revenue-statistics-design/contracts/rev007-interface-contract.md
+++ b/specs/004-rev007-revenue-statistics-design/contracts/rev007-interface-contract.md
@ -0,0 +1,68 @@
+# Contract: REV-007 营收统计查询设计
+
+## 1. Formal Interface Allocation
+
+| Interface | Role | Direction |
+|---|---|---|
+| `IF-REV-010` | `REV-007` 统计主题查询、指标汇总和结果导出边界的正式业务接口 | `SYS-002` 内部正式业务接口 |
+
+约束：
+
+- `IF-REV-010` 保持为 `REV-007` 的正式接口编号，不新增新的统计接口编号。
+- 本接口只承接经营统计查询，不扩展到 BI 专题、预测分析或独立数据仓库查询。
+
+## 2. Statistics Themes
+
+`IF-REV-010` 本轮至少覆盖以下主题：
+
+- 营收汇总
+- 收费与实收统计
+- 欠费规模与账龄统计
+- 客户结构统计
+- 渠道交易统计
+- 抄表完成率统计
+- 业务概览类工单/办理量摘要（仅限营收业务相关概览）
+
+## 3. Request Contract
+
+| Field | Meaning | Required |
+|---|---|---|
+| `themeCode` | 统计主题编码 | 是 |
+| `dateFrom` | 开始日期 | 是 |
+| `dateTo` | 结束日期 | 是 |
+| `billPeriod` | 账期 | 否 |
+| `deptId` | 营业所/部门 | 否 |
+| `regionCode` | 片区/区域编码 | 否 |
+| `customerCategory` | 客户类别 | 否 |
+| `channelCode` | 收费/交易渠道 | 否 |
+| `statusSet` | 状态集合 | 否 |
+| `groupBy` | 分组维度集合 | 否 |
+| `exportFlag` | 是否导出 | 否 |
+
+## 4. Response Contract
+
+| Field | Meaning |
+|---|---|
+| `themeCode` | 统计主题编码 |
+| `themeName` | 统计主题名称 |
+| `dimensionSummary` | 查询维度摘要 |
+| `indicatorList` | 指标结果集合 |
+| `indicatorList[].indicatorCode` | 指标编码 |
+| `indicatorList[].indicatorName` | 指标名称 |
+| `indicatorList[].indicatorValue` | 指标值 |
+| `indicatorList[].unit` | 单位 |
+| `groupRows` | 分组结果集合 |
+| `exportAllowed` | 是否允许导出 |
+| `msg` | 结果说明 |
+
+## 5. Data Boundary Contract
+
+- 统计结果基于现有在线业务主数据、视图或汇总口径承接。
+- 没有明确实现证据的独立统计表、专题报表表或离线数仓对象不得写成既成事实。
+- 当历史查询口径参与对账或对比时，只能作为补充来源，不替代在线主数据统计口径。
+
+## 6. Permission and Export Contract
+
+- 查询结果必须受现有数据权限控制。
+- 导出属于查询扩展能力，必须在权限允许范围内执行。
+- 本轮只定义“是否允许导出”和导出边界，不展开导出实现细节。
--- a/specs/004-rev007-revenue-statistics-design/data-model.md
+++ b/specs/004-rev007-revenue-statistics-design/data-model.md
@ -0,0 +1,135 @@
+# Data Model: REV-007 营收统计查询设计
+
+## 1. Statistics Theme
+
+### Purpose
+
+定义 `REV-007` 支持的统计主题，是统计查询的一级分类。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `themeCode` | 统计主题编码 | 唯一 |
+| `themeName` | 统计主题名称 | 必填 |
+| `scopeDescription` | 范围说明 | 必填；说明包含与排除项 |
+| `indicatorSet` | 指标集合 | 至少 1 个核心指标 |
+| `dimensionSet` | 维度集合 | 至少 1 个查询维度 |
+| `exportAllowed` | 是否允许导出 | 必填 |
+
+### Relationships
+
+- 一个 `Statistics Theme` 包含多个 `Statistics Indicator`
+- 一个 `Statistics Theme` 可复用多个 `Statistics Dimension`
+- 一个 `Statistics Theme` 由一个 `Statistics Query Contract` 承接
+
+## 2. Statistics Dimension
+
+### Purpose
+
+定义统计查询的筛选维度和分组维度。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `dimensionCode` | 维度编码 | 唯一 |
+| `dimensionName` | 维度名称 | 必填 |
+| `dimensionType` | 维度类型 | 必填；时间/组织/客户/渠道/状态等 |
+| `filterMode` | 查询方式 | 必填；范围/枚举/模糊/精确 |
+| `groupable` | 是否支持分组 | 必填 |
+| `sourceFieldRef` | 来源字段引用 | 必填；来源表或视图字段 |
+
+### Relationships
+
+- 可被多个 `Statistics Theme` 复用
+- 可映射到一个或多个 `Aggregation Source`
+
+## 3. Statistics Indicator
+
+### Purpose
+
+定义统计结果中返回的核心业务指标。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `indicatorCode` | 指标编码 | 唯一 |
+| `indicatorName` | 指标名称 | 必填 |
+| `indicatorMeaning` | 指标含义 | 必填；避免同名不同义 |
+| `unit` | 单位 | 可为空；金额/笔数/户数/百分比等 |
+| `aggregationRule` | 聚合规则 | 必填；求和/计数/占比/完成率 |
+| `sourceMetricRef` | 来源指标引用 | 必填 |
+
+### Relationships
+
+- 归属于一个或多个 `Statistics Theme`
+- 依赖一个或多个 `Aggregation Source`
+
+## 4. Statistics Query Contract
+
+### Purpose
+
+描述 `IF-REV-010` 的输入条件、输出摘要、权限控制和导出边界。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `interfaceCode` | 接口编号 | 固定为 `IF-REV-010` |
+| `themeCode` | 统计主题编码 | 必填 |
+| `queryConditionSet` | 查询条件集合 | 必填 |
+| `resultIndicatorSet` | 输出指标集合 | 必填 |
+| `permissionScope` | 权限范围 | 必填；数据权限/导出权限 |
+| `exportConstraint` | 导出约束 | 必填 |
+
+### Relationships
+
+- 一个 `Statistics Query Contract` 服务一个 `Statistics Theme`
+- 引用多个 `Statistics Dimension` 和 `Statistics Indicator`
+
+## 5. Aggregation Source
+
+### Purpose
+
+表示统计结果依赖的在线业务数据来源、视图或汇总口径。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `sourceCode` | 来源编码 | 唯一 |
+| `sourceName` | 来源名称 | 必填 |
+| `sourceType` | 来源类型 | 必填；在线表/视图/汇总口径 |
+| `primaryObjects` | 主数据对象 | 必填 |
+| `retentionBoundary` | 承接口径边界 | 必填；说明是否仅逻辑口径 |
+| `implementationStatus` | 实现状态说明 | 必填；不得夸大为已存在独立表 |
+
+### Relationships
+
+- 支撑多个 `Statistics Indicator`
+- 可映射到多个 `Statistics Dimension`
+
+## 6. Statistics Governance Record
+
+### Purpose
+
+用于在治理台账中记录 `REV-007` 的设计状态、实现评估和后续建议。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `requirementCode` | 对应需求编号 | 固定为 `SYS002-REQ-012` |
+| `featureName` | Speckit feature 名称 | 必填 |
+| `designStatus` | 设计状态 | 必填；设计收口中/已收口 |
+| `implementationStatus` | 实现评估 | 必填；当前为未见实现 |
+| `nextAction` | 后续动作 | 必填 |
+| `validationRecord` | 校验记录 | 必填；引用本轮校验动作 |
+
+### Relationships
+
+- 关联 `01_Project_Progress.md`
+- 关联 `03_Task_Checklist.md`
+- 关联 `15_SYS002_Requirement_Breakdown.md`
--- a/specs/004-rev007-revenue-statistics-design/plan.md
+++ b/specs/004-rev007-revenue-statistics-design/plan.md
@ -0,0 +1,98 @@
+# Implementation Plan: REV-007 营收统计查询设计
+
+**Branch**: `004-rev007-revenue-statistics-design` | **Date**: 2026-03-18 | **Spec**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/spec.md)
+**Input**: Feature specification from `/specs/004-rev007-revenue-statistics-design/spec.md`
+
+## Summary
+
+本 feature 面向 `REV-007` 统计分析模块的正式文档补齐，重点收口三类内容：1）在 [12_REV_Detailed.md](/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md) 中明确统计主题、查询维度、核心指标与排除项；2）在 [03_Interface_Design.md](/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md) 中补齐 `IF-REV-010` 的查询边界、输入输出与权限导出约束；3）在 [01_Database_Design.md](/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md) 中明确统计数据承接口径、视图/汇总边界与“未见实现”的保守表述，并同步治理台账。
+
+## 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/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/`
+**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-007` 统计分析相关章节、`IF-REV-010` 相关接口章节、数据库统计承接口径章节与治理台账
+**Project Type**: 文档治理仓库
+**Constraints**:
+- 不新增平行正式稿
+- 不臆造 backend 已实现的统计入口
+- Archive 仅作来源核对
+- 使用相对路径与现有正式编号体系
+- 不把预测分析、BI 专题或独立数仓实现写成本轮既成事实
+**Scale/Scope**: 跨详细设计、接口设计、数据库设计与治理台账的中等规模文档收口
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- [x] **主文档归属已确认**：本次改动将优先落在 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md` 及治理台账，而不是新增平行正式稿。
+- [x] **范围基线已确认**：`REV-007` 已存在于 `SYS-002` 营收业务模块中，当前仅补齐统计查询正式口径，不扩展到独立 BI/预测分析范围。
+- [x] **Archive 使用方式合规**：Archive 仅作为统计主题和历史口径的参考来源，不直接替代主文档结论。
+- [x] **一致性影响已列出**：受影响项包括统计主题名称、指标口径、`IF-REV-010` 边界、数据库统计承接口径、实现状态表述与治理台账。
+- [x] **校验与台账动作已规划**：已明确单文件校验与 `make check-links`，并计划同步更新 `01_Project_Progress.md` 与 `03_Task_Checklist.md`。
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/[###-feature]/
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output (/speckit.plan command)
+├── data-model.md        # Optional: document entities/traceability objects
+├── quickstart.md        # Optional: validation or review quickstart
+├── contracts/           # Optional: interface or section-level artifacts
+└── tasks.md             # Phase 2 output (/speckit.tasks command)
+```
+
+### Repository Touchpoints
+
+```text
+docs/design/
+├── 00_Management/
+├── 01_Overview/
+├── 02_Detailed_Design/
+├── 03_Technical_Design/
+└── 04_Appendix/Archive/
+
+README.md
+AGENTS.md
+.specify/templates/
+```
+
+**Structure Decision**: [Document the exact files to be updated and the reason each file is in scope]
+**Structure Decision**:
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md`：补齐 `REV-007` 的业务范围、统计主题、维度、指标和排除项。
+- `docs/design/03_Technical_Design/03_Interface_Design.md`：补齐 `IF-REV-010` 的正式接口定义、查询主题、输入输出与权限导出边界。
+- `docs/design/03_Technical_Design/01_Database_Design.md`：补齐统计承接口径、视图/汇总边界、历史与现状保守口径。
+- `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`：同步 `SYS002-REQ-012` 的实现评估和后续建议。
+- `docs/design/00_Management/01_Project_Progress.md`：记录本轮 `REV-007` 设计收口进展。
+- `docs/design/00_Management/03_Task_Checklist.md`：同步 tracked-task 闭环记录。
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| 无 | - | - |
--- a/specs/004-rev007-revenue-statistics-design/quickstart.md
+++ b/specs/004-rev007-revenue-statistics-design/quickstart.md
@ -0,0 +1,58 @@
+# Quickstart: REV-007 营收统计查询设计
+
+## 目标
+
+本 quickstart 用于指导评审者和文档维护者快速完成 `REV-007` 统计查询设计补齐的检查，不涉及 backend 实施。
+
+## 步骤 1：阅读规格与计划结论
+
+1. 阅读 `spec.md`，确认本轮范围只覆盖 `REV-007` 的正式设计收口，不扩展到预测分析或独立 BI 专题。
+2. 阅读 `research.md`，确认以下决策已固定：
+   - `REV-007` 保持使用 `IF-REV-010`
+   - 统计范围收敛为经营查询
+   - 统计口径按“主题 + 维度 + 指标”组织
+   - 数据承接口径以在线主数据聚合和视图/汇总口径为主
+
+## 步骤 2：执行文档改动时的目标落点
+
+1. 在 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 补齐：
+   - 统计主题清单
+   - 维度与指标口径
+   - 导出与权限边界
+   - 排除项与文档先行边界
+2. 在 `docs/design/03_Technical_Design/03_Interface_Design.md`：
+   - 补齐 `IF-REV-010` 的正式接口定义
+   - 明确查询条件、输出主题、权限和导出边界
+3. 在 `docs/design/03_Technical_Design/01_Database_Design.md`：
+   - 明确统计数据来源、视图/汇总口径和保守承接口径
+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-007` 的统计主题、维度和指标口径不再停留在摘要级表述
+- `IF-REV-010` 的输入输出、权限与导出边界已明确
+- 数据库主文档未把统计承接口径误写为已存在独立统计表族
+- 治理台账明确保持“设计收口推进中，代码入口未见明确实现”的真实结论
+- 正式文档与台账同步更新
+
+## 步骤 5：本轮实现摘要
+
+- 已完成 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md`、`15_SYS002_Requirement_Breakdown.md`、`01_Project_Progress.md`、`03_Task_Checklist.md` 的正式文档回写。
+- `REV-007` 已在正式文档中明确按“主题 + 维度 + 指标”组织统计查询，`IF-REV-010` 的输入输出、权限和导出边界已补齐。
+- 数据库主文档已明确统计承接口径以在线主数据聚合、视图或汇总口径为主，不臆造独立统计表或离线数仓能力。
+- 已执行并通过全部单文件校验与 `make check-links`。
--- a/specs/004-rev007-revenue-statistics-design/research.md
+++ b/specs/004-rev007-revenue-statistics-design/research.md
@ -0,0 +1,56 @@
+# Phase 0 Research: REV-007 营收统计查询设计
+
+## 决策 1：`REV-007` 保持 `IF-REV-010` 作为正式统计查询接口
+
+- **Decision**: `REV-007` 继续使用 `IF-REV-010` 作为正式统计查询接口编号，不新增新的 `IF-*` 编号。
+- **Rationale**:
+  - 当前正式接口总表已为 `REV-007` 预留 `IF-REV-010`，问题在于内容过薄，而不是编号错误。
+  - 继续沿用现有编号可以避免与 `REV-006` 那类编号冲突治理混在一起。
+  - 本轮重点是补齐统计主题、查询维度和输出口径，而不是重做接口编号体系。
+- **Alternatives considered**:
+  - 新增 `IF-REV-014`：否决，因为没有编号冲突，新增会制造不必要扰动。
+  - 保持“仅总表项，不补详细定义”：否决，因为不足以支撑后续实现与评审。
+
+## 决策 2：统计范围收敛为经营查询，不扩展到预测与 BI 专题
+
+- **Decision**: `REV-007` 正式设计仅覆盖经营统计查询，包括营收、收费、欠费、客户、渠道、抄表完成率和必要的业务概览类统计；预测分析、专题大屏、独立 BI/数仓能力不纳入本轮正式范围。
+- **Rationale**:
+  - 当前正式详细设计和需求拆解都只给出了经营查询级别的描述。
+  - backend 现状未见明确统计分析实现入口，过度扩展会直接变成新需求。
+  - 先收口“标准查询口径”更符合“设计先行、实现待立项”的保守策略。
+- **Alternatives considered**:
+  - 把趋势预测、经营驾驶舱、大屏分析一并纳入：否决，因为超出现有正式范围。
+  - 只保留一句“营收统计查询”：否决，因为无法指导后续实现或立项。
+
+## 决策 3：统计结果按“主题 + 维度 + 指标”三层口径组织
+
+- **Decision**: `REV-007` 的正式设计按“统计主题、查询维度、核心指标”三层组织，不直接写死复杂报表清单。
+- **Rationale**:
+  - 当前文档缺的是统计口径框架，而不是具体报表枚举。
+  - 三层结构便于在详细设计、接口设计和数据库设计之间保持一致表达。
+  - 后续若扩展某类专题报表，也能在既有三层口径下继续补充。
+- **Alternatives considered**:
+  - 直接罗列大量报表名称：否决，因为容易脱离现有实现依据。
+  - 只写主题不写维度/指标：否决，因为口径仍然过空。
+
+## 决策 4：数据库承接口径以在线主数据聚合和视图/汇总口径为主
+
+- **Decision**: `REV-007` 在数据库设计中只约束“基于现有在线业务表聚合的视图/汇总口径”，不确认独立统计表或离线数仓对象。
+- **Rationale**:
+  - 当前数据库主文档只有一般性“统计分析视图”片段，未见 `REV-007` 专项统计表族。
+  - backend 也未见明确统计模块，因此写成独立统计表会超出证据范围。
+  - 以聚合视图/统计结果集描述可以满足设计收口，同时保持保守。
+- **Alternatives considered**:
+  - 臆造 `stat_*` 或 `report_*` 表：否决，因为没有实现或正式主文档证据。
+  - 完全不写数据库承接口径：否决，因为接口与详设无法闭环。
+
+## 决策 5：治理台账明确保持“设计收口完成，代码入口未见实现”
+
+- **Decision**: `REV-007` 在治理台账中的当前实现判断保持“未见实现”，但增加“设计收口已完成”的状态说明。
+- **Rationale**:
+  - 现有 `15_SYS002_Requirement_Breakdown.md` 已明确该模块未见实现。
+  - 文档补齐不应被误读为 backend 已完成统计能力。
+  - 这种表述更适合后续立项与排期管理。
+- **Alternatives considered**:
+  - 直接改成“部分实现”：否决，因为暂无明确代码入口证据。
+  - 只写“未见实现”不提设计进展：否决，因为无法体现本轮交付价值。
--- a/specs/004-rev007-revenue-statistics-design/spec.md
+++ b/specs/004-rev007-revenue-statistics-design/spec.md
@ -0,0 +1,129 @@
+# 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 项文档校验或一致性检查。
--- a/specs/004-rev007-revenue-statistics-design/tasks.md
+++ b/specs/004-rev007-revenue-statistics-design/tasks.md
@ -0,0 +1,177 @@
+# Tasks: REV-007 营收统计查询设计
+
+**Input**: Design documents from `/specs/004-rev007-revenue-statistics-design/`
+**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/
+
+**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
+
+## Path Conventions
+
+- Main documents: `docs/design/01_Overview/`, `docs/design/02_Detailed_Design/`, `docs/design/03_Technical_Design/`
+- Governance documents: `docs/design/00_Management/`
+- Archive references: `docs/design/04_Appendix/Archive/`
+- Runtime guidance: `README.md`, `AGENTS.md`, `.specify/templates/`
+
+## Phase 1: Scope & Source Confirmation (Shared Foundation)
+
+**Purpose**: Confirm the source-of-truth set and impact boundary before editing.
+
+- [X] T001 Confirm target documents and exact `REV-007` touchpoints in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/spec.md`
+- [X] T002 Confirm governing source-of-truth and allowed reference sources in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/plan.md`
+- [X] T003 [P] Record final scope judgment for `REV-007` themes, exclusions, and implementation-status wording in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/research.md`
+- [X] T004 [P] Identify cross-document impacts for `IF-REV-010`、统计主题、指标口径、数据库承接口径和治理台账 in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/contracts/rev007-interface-contract.md`
+
+---
+
+## Phase 2: Foundational Alignment (Blocking Prerequisites)
+
+**Purpose**: Prepare the cross-document baseline that all user stories depend on.
+
+- [X] T005 Consolidate `REV-007` decisions, entities, and contract fields from `/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/research.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/data-model.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/contracts/rev007-interface-contract.md`
+- [X] T006 [P] Cross-check current sparse `REV-007` and `IF-REV-010` references in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`
+- [X] T007 [P] Cross-check current database statistics wording and existing “统计分析视图” placeholder in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md`
+- [X] T008 Confirm ledger update expectations for this feature in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md`
+
+---
+
+## Phase 3: User Story 1 - 收口统计业务范围 (Priority: P1) 🎯 MVP
+
+**Goal**: 让 `12_REV_Detailed.md` 中的 `REV-007` 章节具备完整的统计主题、查询维度、核心指标、导出边界和排除项说明。
+
+**Independent Test**: 单独评审 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` 的 `REV-007` 章节，应能明确统计主题、维度、指标与不在本轮范围的专题分析项。
+
+### Implementation for User Story 1
+
+- [X] T009 [US1] Update `REV-007` 功能说明、关键设计、核心数据和落地边界 in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- [X] T010 [P] [US1] Add `Statistics Theme`、`Statistics Dimension`、`Statistics Indicator` 对应的主题/维度/指标摘要 to `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- [X] T011 [P] [US1] Sync `REV-007` implementation assessment and Story notes in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- [X] T012 [US1] Run `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` and capture result
+- [X] T013 [US1] Run `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` and capture result
+
+**Checkpoint**: User Story 1 is reviewable and confirms the `REV-007` business scope without depending on interface/database redesign.
+
+---
+
+## Phase 4: User Story 2 - 统一接口与数据承接口径 (Priority: P2)
+
+**Goal**: 在接口和数据库主文档中为 `REV-007` 建立清晰的 `IF-REV-010` 查询边界、输入输出要求与统计数据承接口径。
+
+**Independent Test**: 单独评审 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md` 与 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md`，应能确认 `IF-REV-010` 的职责、统计主题、维度、指标与数据库保守承接口径。
+
+### Implementation for User Story 2
+
+- [X] T014 [US2] Add `IF-REV-010` formal interface definition, request/response shape, and permission/export boundary in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`
+- [X] T015 [P] [US2] Update statistics themes, dimension terminology, and data-source wording in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`
+- [X] T016 [US2] Update statistical aggregation boundary, view/summary wording, and implementation-status constraints in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md`
+- [X] T017 [P] [US2] Sync `REV-007` interface mapping and data-source terminology back into `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- [X] T018 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` and capture result
+- [X] T019 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` and capture result
+- [X] T020 [US2] Run `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` and capture result after interface/data sync
+
+**Checkpoint**: User Story 2 is reviewable and fully expresses `IF-REV-010` and the database-side aggregation boundary independently.
+
+---
+
+## Phase 5: User Story 3 - 同步治理与实现评估结论 (Priority: P3)
+
+**Goal**: 在治理台账中收口 `REV-007` 的设计进度、实现状态和后续建议，保持“设计补齐中、代码入口未见明确实现”的真实结论。
+
+**Independent Test**: 单独评审 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`、`/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md` 与 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md`，应能确认 `REV-007` 的治理记录已同步。
+
+### Implementation for User Story 3
+
+- [X] T021 [US3] Update `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` with `REV-007` design-closure result, implementation status, and follow-up recommendation
+- [X] T022 [US3] Update `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md` with the `REV-007` design closure milestone
+- [X] T023 [US3] Update `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md` with the `REV-007` tracked-task closure status
+- [X] T024 [US3] Run `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` and capture result after governance sync
+- [X] T025 [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 result
+
+**Checkpoint**: User Story 3 is reviewable and confirms governance closure independently.
+
+---
+
+## Final Phase: Cross-Cutting Closure
+
+**Purpose**: Ensure repository-wide consistency after all story slices are complete.
+
+- [X] T026 [P] Re-check source-of-truth alignment across `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- [X] T027 [P] Run `make check-links` after all document changes and capture result
+- [X] T028 Prepare final summary with modified files, validation results, remaining risks, and next-step suggestions in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/quickstart.md`
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Phase 1: Scope & Source Confirmation**: No dependencies; MUST finish before content edits
+- **Phase 2: Foundational Alignment**: Depends on Phase 1; MUST finish before user story work
+- **Phase 3: User Story 1**: Depends on Phase 2
+- **Phase 4: User Story 2**: Depends on Phase 2 and should follow User Story 1 because interface/data wording must align with the finalized statistics scope
+- **Phase 5: User Story 3**: Depends on Phase 2 and should follow User Story 2 because governance wording must use the finalized interface and data-source terminology
+- **Final Phase**: Depends on all selected user stories being complete
+
+### Within Each User Story
+
+- Update target documents before syncing supporting or governance documents
+- Complete content edits before validation
+- Complete validation before ledger updates are marked done
+- Complete ledger sync before final summary
+
+### User Story Completion Order
+
+`US1 -> US2 -> US3`
+
+### Parallel Opportunities
+
+- `T003` and `T004` can run in parallel after source confirmation
+- `T006` and `T007` can run in parallel during foundational alignment
+- In `US1`, `T010` and `T011` can run in parallel after `T009`
+- In `US2`, `T015` and `T017` can run in parallel after `T014` and `T016`
+- `T026` and `T027` can run in parallel during final closure
+
+## Parallel Execution Examples
+
+### User Story 1
+
+```text
+Run in parallel after T009:
+- T010 [P] [US1] Add theme/dimension/indicator summaries in 12_REV_Detailed.md
+- T011 [P] [US1] Sync implementation assessment in 15_SYS002_Requirement_Breakdown.md
+```
+
+### User Story 2
+
+```text
+Run in parallel after T014 and T016:
+- T015 [P] [US2] Update statistics terminology and data-source wording in 03_Interface_Design.md
+- T017 [P] [US2] Sync interface/data wording back into 12_REV_Detailed.md
+```
+
+## Implementation Strategy
+
+### MVP First
+
+先完成 `US1`，因为 `12_REV_Detailed.md` 中的统计主题、维度和指标边界是后续接口和数据库收口的前提。只要 `US1` 完成，就能先交付一版可评审的 `REV-007` 业务范围说明。
+
+### Incremental Delivery
+
+1. 完成 `US1`，锁定统计业务范围和排除项
+2. 完成 `US2`，锁定 `IF-REV-010` 与数据库承接口径
+3. 完成 `US3`，锁定治理台账和实现状态表述
+4. 最后统一执行全局一致性检查和链接校验
+
+### Notes
+
+- 每个 story 都可以独立评审，不要求一次性改完全部文档
+- 所有任务都必须回写既有正式文档，不能新建平行正式稿
+- Archive 只作为核对来源，不直接替代主文档
+- 验证和台账同步不是可选项