Neo-ZQYY/.kiro/specs/dwd-business-panorama/requirements.md

需求文档：DWD 业务全景梳理

简介

从 DWD 层出发，系统梳理飞球 ETL 对台球厅所有业务数据的记录方式。不仅覆盖每个字段的含义，还要搞清楚字段间的关联性，最终产出覆盖业务全景、账务全景、财务全景三个维度的分析文档。

现有的 consume-money-caliber-deep-analysis.md 和 consumption-cases-analysis.md 已深入分析了结算/支付相关的 DWD 表，但仅从支付订单金额角度无法搞清楚整个球房的业务、财务、账务全貌。本 SPEC 旨在补全剩余的业务域（台桌、助教、会员、团购、商品、库存），并将所有域串联成三个全景视图。

⚠️ 核心准则：数据本源优先（强制）

启动本 SPEC 的根本原因：项目中现有的所有文档（包括 consume-money-caliber-deep-analysis.md、consumption-cases-analysis.md、BD 手册、ETL 代码注释等）都可能存在纰漏、过期、遗漏或与数据库现实不符的情况。因此本次梳理必须遵循以下强制准则：

信息可信度分层

层级	可信度	说明	使用方式
宏观/直观层	✅ 可参考	表的业务归属、业务域划分、主要关联方向、流程大框架等直观明显的信息	直接参考作为起点，无需逐一验证
字段级/数据关联层	⚠️ 必须验证	字段语义、金额计算规则、枚举值含义、跨表关联关系等细节	慎之又慎，必须通过测试库数据关联做推理验证，不可直接采信

强制准则

1. 数据库是唯一真相源（字段级）：字段级别的结论必须以测试库（test_etl_feiqiu）的实际表结构和数据为准。表结构信息必须通过查询 information_schema 或 pg_catalog 获取，禁止参考 db/ 目录下的 DDL .sql 文件。宏观层面的信息（表的职责、业务域归属、流程大框架）可参考现有文档作为起点
2. 先查后写，禁止臆断：描述任何字段语义、业务规则、金额关系之前，必须先通过 SQL 查询验证实际数据分布和值域。未经查询验证的结论禁止写入文档
3. 刨根问底，通过数据关联做推理：对每个金额字段、状态枚举、关联关系，不能停留在"看起来是什么"，必须通过交叉查询、边界案例、异常值分析确认其真实业务含义。从含义明确的字段出发，通过数据关联倒推不确定的字段
4. 现有文档作为假设而非事实：引用现有文档的字段级结论时，必须标注为"待验证假设"，并在验证后标注实际结果（一致/偏差/错误）
5. 偏差必须显式记录：当验证发现现有文档与数据库现实不一致时，必须在新文档中明确记录偏差内容、偏差原因（如果能推断）、以及修正后的正确描述
6. 无数据不下结论：如果测试库中某张表无数据或数据量不足以支撑结论，必须明确标注"数据不足，无法验证"，禁止基于推测填充内容
7. 不确定性必须显式警告：对于以下情况，必须在文档中以醒目的 ⚠️ 警告 标记：(a) 经过长时间推理和多次交叉验证仍无法对齐的数据关系；(b) 根据现有数据和依据无法确认的字段含义或业务规则。警告内容须说明：已尝试的验证方法、无法确认的具体原因、建议的后续验证方向

术语表

• DWD_层：Data Warehouse Detail 层，ETL 管道中的明细数据层，存储经过清洗和标准化的业务事实和维度数据
• 全景文档：按特定视角（业务/账务/财务）组织的、覆盖所有相关 DWD 表及其字段关联的分析文档
• 梳理器：执行本 SPEC 任务的分析人员或脚本，负责读取 DWD 表结构和数据并产出文档
• 测试库：PostgreSQL 数据库 test_etl_feiqiu，包含 DWD 层的实际数据，用于验证文档描述的准确性
• 业务域：DWD 表按业务功能的分组，包括：结算、台桌、助教、会员、团购、商品、库存
• 主表/扩展表：DWD 层的表设计模式，主表存核心字段，_ex 扩展表存补充字段，通过主键 1:1 关联
• 维度表：以 dim_ 前缀命名的 DWD 表，存储缓慢变化的主数据（SCD2 模式）
• 事实表：以 dwd_ 前缀命名的 DWD 表，存储业务事件流水（增量写入）
• 字段语义：字段在实际业务中的真实含义，可能与 DDL 注释不一致（如 point_amount 实际是线上收款而非积分）
• 对账公式：用于校验数据一致性的等式关系，如 F1（消费构成）、F2（收支平衡）

需求

需求 1：DWD 表结构与字段语义梳理（智能聚焦策略）

用户故事： 作为数据分析人员，我希望获得每张 DWD 表中有业务意义的字段的准确语义说明，以便理解数据如何记录业务事实。

梳理策略说明： apps/etl/connectors/feiqiu/docs/database/DWD/ 下已有各表的文档，宏观层面（表的职责、业务域归属、主要关联关系）可作为参考起点。但字段级别的语义必须通过数据关联倒推验证，不可直接采信。梳理时采用"智能聚焦"策略，而非逐字段全量罗列。

验收标准

1. THE 梳理器 SHALL 覆盖 DWD 层全部 7 个业务域（结算、台桌、助教、会员、团购、商品、库存）的所有主表和扩展表，以现有 DWD 文档为宏观参考起点
2. THE 梳理器 SHALL 对每张表先执行字段分类筛选：(a) 查询全表空字段（全部为 NULL 的列），标记为"空字段-跳过"；(b) 识别含义明确的基础字段（如 id、site_id、created_at），简要标注即可；(c) 聚焦于业务关键字段（金额、状态、类型、关联 ID），进行深度验证
3. WHEN 梳理业务关键字段时，THE 梳理器 SHALL 采用"倒推法"：先从含义明确的字段出发，通过数据关联（JOIN、聚合对比、值域交叉）推断不确定字段的真实含义
4. WHEN 发现字段的实际业务含义与现有 DWD 文档或 DDL 注释不一致时，THE 梳理器 SHALL 明确标注偏差内容并给出基于测试库数据验证的修正说明
5. THE 梳理器 SHALL 标注每张表的主键、外键关联、以及与其他 DWD 表的关联方式（关联字段和关联类型如 1:1、1:N）
6. THE 梳理器 SHALL 标注每张维度表的 SCD2 生效/失效字段和当前记录标识字段
7. IF 测试库中某张表无数据或数据量不足以验证字段语义，THEN THE 梳理器 SHALL 在文档中标注该表的数据状态并说明无法验证的字段
8. THE 梳理器 SHALL 主动忽略以下字段类别，不在文档中详细展开：(a) 全表 NULL 的空字段（仅在附录中列出字段名）；(b) ETL 管理字段（如 _etl_loaded_at、_etl_batch_id），仅简要说明用途；(c) 含义完全透明且无歧义的字段（如 id、created_at、updated_at），仅在表结构概览中列出

需求 2：业务全景文档——消费是怎么产生的

用户故事： 作为门店经营者，我希望搞清楚台球厅的消费是怎么来的、价格怎么报的、优惠怎么产生的，以便理解整个消费链路。

验收标准

1. THE 全景文档 SHALL 描述从顾客开台到结算的完整业务流程，标注每个环节涉及的 DWD 表和关键字段
2. THE 全景文档 SHALL 覆盖以下消费类目的产生机制：台费（含多台桌合并）、商品消费、助教服务（陪打/超休）、灯控电费
3. THE 全景文档 SHALL 描述台费的计价规则，包括：台桌类型与单价的关系、计时方式、台费折扣（dwd_table_fee_adjust）的触发条件和计算方式
4. THE 全景文档 SHALL 描述优惠的产生机制，包括：平台团购券（美团/抖音）的核销流程、会员折扣的计算方式、台费调整（adjust_amount）的业务场景
5. THE 全景文档 SHALL 描述团购券的三层价格体系（顾客支付给平台的 sale_price、平台结算给门店的 pl_coupon_sale_amount、门店实际抵扣的 coupon_amount），并标注每层价格对应的 DWD 表和字段
6. WHEN 描述某个业务环节时，THE 全景文档 SHALL 提供至少一个来自测试库的真实数据样例作为佐证
7. THE 全景文档 SHALL 以 Mermaid 流程图展示从开台到结算的完整数据流向

需求 3：账务全景文档——客户怎么结算的

用户故事： 作为门店财务人员，我希望搞清楚客户的每一笔消费是通过什么方式结算的、支付流水怎么记录的，以便进行对账和核销。

验收标准

1. THE 全景文档 SHALL 描述所有支付渠道及其在 DWD 层的记录方式，包括：线上收款（微信/支付宝）、现金、储值卡余额（含礼品卡/充值卡）、平台团购券
2. THE 全景文档 SHALL 描述 dwd_payment 表与 dwd_settlement_head 的关联方式，以及 payment_method 枚举值与实际支付渠道的对应关系
3. THE 全景文档 SHALL 描述会员储值卡体系，包括：充值流程（dwd_recharge_order）、余额变动记录（dwd_member_balance_change）、本金/赠送金额的分账逻辑
4. THE 全景文档 SHALL 描述退款流程，包括：结算退款、充值退款、转账退款的触发场景和在 DWD 层的记录方式
5. THE 全景文档 SHALL 列出所有已验证的对账公式（F1F6、R1R3、RF1RF2、B1B4），标注每个公式的适用范围、成立率、以及已知的例外情况
6. WHEN 描述支付方式推断逻辑时，THE 全景文档 SHALL 提供完整的推断规则（因 settlement_head_ex.payment_method 全部为 0 不可用）
7. THE 全景文档 SHALL 描述 consume_money 字段的三种历史口径（A/B/C）及其时间线，标注当前生效的口径

需求 4：财务全景文档——收入确认与对账

用户故事： 作为门店管理者，我希望搞清楚门店的收入如何确认、各渠道的资金如何对账，以便进行财务分析和经营决策。

验收标准

1. THE 全景文档 SHALL 描述门店收入的构成，按收入来源分类：台费收入、商品收入、助教服务收入、充值收入
2. THE 全景文档 SHALL 描述每种收入来源对应的 DWD 表、关键金额字段、以及从 DWD 到 DWS 的聚合路径
3. THE 全景文档 SHALL 描述平台团购券场景下的收入确认逻辑：门店实际收入 = pl_coupon_sale_amount（平台结算额），而非 coupon_amount（券面值抵扣额），差额为门店补贴
4. THE 全景文档 SHALL 描述储值卡充值场景的资金流向：充值收款 → 余额入账（本金+赠送）→ 消费扣款 → 退款（如有），标注每个环节的 DWD 表和金额字段
5. THE 全景文档 SHALL 提供按支付渠道的对账矩阵，列出每种支付渠道在 DWD 层涉及的表和字段，以及跨表校验的公式
6. THE 全景文档 SHALL 标注已知的数据质量问题和对账例外（如助教券的支付缺口、商品消费未覆盖等），并给出影响范围的量化评估

需求 5：维度表与主数据全景

用户故事： 作为数据开发人员，我希望搞清楚 DWD 层所有维度表的结构和业务含义，以便在 DWS 聚合时正确关联维度。

验收标准

1. THE 全景文档 SHALL 覆盖所有 DWD 维度表（dim_site、dim_table、dim_assistant、dim_member、dim_member_card_account、dim_tenant_goods、dim_store_goods、dim_goods_category、dim_groupbuy_package），包括主表和扩展表
2. THE 全景文档 SHALL 描述每张维度表与事实表的关联方式，标注关联字段和关联基数
3. THE 全景文档 SHALL 描述会员体系的数据结构，包括：会员档案（dim_member）、储值卡账户（dim_member_card_account）、会员等级/标签的记录方式
4. THE 全景文档 SHALL 描述商品体系的数据结构，包括：商品分类树（dim_goods_category）、租户商品（dim_tenant_goods）与门店商品（dim_store_goods）的关系、库存相关表（dwd_goods_stock_summary、dwd_goods_stock_movement）的结构
5. THE 全景文档 SHALL 描述团购套餐维度（dim_groupbuy_package）的结构，包括：套餐与券种的关系、价格体系（面值/售价/门店结算价）

需求 6：数据验证与文档可信度保障

用户故事： 作为数据分析人员，我希望文档中的每个结论都经过测试库数据验证，以避免使用过期或错误的信息。

验收标准

1. WHEN 梳理任何 DWD 表的字段语义时，THE 梳理器 SHALL 通过查询测试库（test_etl_feiqiu）验证字段的实际值分布，确认语义描述的准确性。禁止仅凭 DDL 注释或现有文档描述字段含义
2. WHEN 文档引用对账公式时，THE 梳理器 SHALL 提供该公式在测试库全量数据上的验证结果（成立率、例外数量和分类）
3. IF 验证过程中发现现有文档（consume-money-caliber-deep-analysis.md、consumption-cases-analysis.md、BD 手册、ETL 代码注释等）的结论与测试库数据不一致，THEN THE 梳理器 SHALL 在新文档中明确标注修正内容，包括：原文档的描述、实际数据的表现、偏差原因分析
4. THE 梳理器 SHALL 在每份全景文档的开头标注数据验证日期和测试库数据的时间范围
5. THE 全景文档 SHALL 对每个关键结论标注验证状态：✅ 已验证（附验证 SQL 或结果摘要）、⚠️ 部分验证（附已知例外）、❌ 未验证（附原因）
6. THE 梳理器 SHALL 对每个金额字段执行以下深度验证流程：(a) 查询值域分布（MIN/MAX/AVG/中位数/NULL 占比）；(b) 与关联字段交叉验证（如 total_amount 是否等于各子项之和）；(c) 检查边界案例（零值、负值、极端值）的业务含义
7. WHEN 引用现有文档的任何结论时，THE 梳理器 SHALL 将其标注为"待验证假设"，并在验证后更新为实际结果（一致 ✅ / 偏差 ⚠️ / 错误 ❌），附偏差说明

需求 7：文档产出与组织

用户故事： 作为项目成员，我希望全景文档按统一格式组织并落在正确的路径下，以便团队查阅和后续维护。

验收标准

1. THE 梳理器 SHALL 将所有全景文档输出到 docs/reports/ 目录下
2. THE 梳理器 SHALL 产出以下文档（文件名待确认）：
   • DWD 表结构与字段语义总览
   • 业务全景：消费产生机制
   • 账务全景：结算与支付流水
   • 财务全景：收入确认与对账
   • 维度表与主数据全景
3. THE 全景文档 SHALL 使用统一的文档模板，包含：标题、数据来源与验证日期、目录、正文、附录（验证 SQL、数据样例）
4. THE 全景文档 SHALL 在适当位置使用 Mermaid 图表（ER 图、流程图、时序图）辅助说明数据关系和业务流程
5. WHEN 全景文档引用其他文档的结论时，THE 梳理器 SHALL 使用相对路径链接到源文档，并标注引用的具体章节