145 lines
15 KiB
Markdown
145 lines
15 KiB
Markdown
# 需求文档：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 列出所有已验证的对账公式（F1~F6、R1~R3、RF1~RF2、B1~B4），标注每个公式的适用范围、成立率、以及已知的例外情况
|
||
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 使用相对路径链接到源文档，并标注引用的具体章节
|