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

# 实施计划：DWD 业务全景梳理

## 概述

将 DWD 业务全景梳理的设计方案转化为可执行的任务序列。任务按两阶段组织：基础层（文档1：表结构总览）→ 全景层（文档2~5），数据验证贯穿全程。属性测试使用 Python + hypothesis，放置在 `tests/` 目录。

## Tasks

- [x] 1. 阶段一：DWD 表结构与字段语义总览（文档1）
  - [x] 1.1 枚举 DWD 全部表并按业务域分组
    - 查询 `test_etl_feiqiu.dwd` 的 `information_schema.tables` 获取全部表名
    - 按 7 个业务域（结算、台桌、助教、会员、团购、商品、库存）分组
    - 查询每张表的行数和时间范围，确认数据状态
    - 创建 `docs/reports/dwd-table-structure-overview.md` 文件骨架（含模板元素：标题、元数据块、目录、正文、附录）
    - _Requirements: 1.1, 7.1, 7.2, 7.3_

  - [x] 1.2 结算域表梳理（dwd_settlement_head/ex, dwd_payment, dwd_refund/ex）
    - 对每张表执行单表智能聚焦分析：information_schema 获取列信息 → 字段分类筛选（空字段/ETL字段/透明字段/业务关键字段）→ 业务关键字段倒推验证
    - 金额字段执行深度验证：值域分布（MIN/MAX/AVG/中位数/NULL占比）+ 交叉验证
    - 枚举字段执行 DISTINCT + 频次分布
    - 对比现有 BD 手册标注偏差
    - 将结果写入文档1的结算域章节
    - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.8, 6.1, 6.6_

  - [x] 1.3 台桌域表梳理（dim_table/ex, dwd_table_fee_log/ex, dwd_table_fee_adjust/ex）
    - 同 1.2 的分析流程
    - 重点验证台费计价相关字段、台费调整的触发条件
    - 标注 dim_table 的 SCD2 字段
    - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.8, 6.1, 6.6_

  - [x] 1.4 助教域表梳理（dim_assistant/ex, dwd_assistant_service_log/ex）
    - 同 1.2 的分析流程
    - 重点验证助教服务类型枚举、`_ex.is_trash` 作废标记的业务含义
    - 标注 dim_assistant 的 SCD2 字段
    - 注意：`dwd_assistant_trash_event` 已于 2026-02-22 DROP，作废判断改用 `dwd_assistant_service_log_ex.is_trash`
    - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.8, 6.1, 6.6_

  - [x] 1.5 会员域表梳理（dim_member/ex, dim_member_card_account/ex, dwd_member_balance_change/ex, dwd_recharge_order/ex）
    - 同 1.2 的分析流程
    - 重点验证储值卡本金/赠送金额分账、余额变动类型枚举
    - 标注 dim_member 和 dim_member_card_account 的 SCD2 字段
    - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.8, 6.1, 6.6_

  - [x] 1.6 团购域表梳理（dim_groupbuy_package/ex, dwd_groupbuy_redemption/ex, dwd_platform_coupon_redemption/ex）
    - 同 1.2 的分析流程
    - 重点验证团购三层价格体系（sale_price / pl_coupon_sale_amount / coupon_amount）
    - 标注 dim_groupbuy_package 的 SCD2 字段
    - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.8, 6.1, 6.6_

  - [x] 1.7 商品域与库存域表梳理（dim_tenant_goods/ex, dim_store_goods/ex, dim_goods_category, dwd_store_goods_sale/ex, dwd_goods_stock_summary, dwd_goods_stock_movement）
    - 同 1.2 的分析流程
    - 重点验证商品分类树结构、租户商品与门店商品的关系
    - 标注维度表的 SCD2 字段（dim_goods_category 无扩展表）
    - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 6.1, 6.6_

  - [x] 1.8 完善文档1：跨表关联关系汇总与文档收尾
    - 汇总所有表的主键、外键关联、关联类型（1:1, 1:N）
    - 补充 Mermaid ER 图展示跨域关联
    - 补充附录：空字段汇总、验证 SQL 汇总
    - 添加文档间引用链接（相对路径格式）
    - 确认文档模板完整性（标题、元数据块、目录、正文、附录）
    - _Requirements: 1.5, 6.4, 7.3, 7.4, 7.5_

- [x] 2. 检查点 - 文档1 完成确认
  - 确认文档1（`docs/reports/dwd-table-structure-overview.md`）已覆盖全部 42 张表（含新发现的 dim_staff/dim_staff_ex）
  - 确认每张表的业务关键字段均已通过测试库数据验证
  - 确认偏差记录完整（point_amount 等偏差已标注）
  - 第9章门店维度有占位符待后续补充，不阻塞全景文档

- [x] 3. 阶段二A：业务全景文档（文档2）
  - [x] 3.1 创建文档2骨架并梳理消费产生链路
    - 创建 `docs/reports/dwd-business-panorama.md`，使用全景文档通用模板
    - 描述从开台到结算的完整业务流程，标注每个环节涉及的 DWD 表和关键字段
    - 以 Mermaid 流程图展示从开台到结算的完整数据流向
    - 基于文档1的字段语义，引用而非重复描述
    - _Requirements: 2.1, 2.7, 6.4, 7.3_

  - [x] 3.2 梳理各消费类目的产生机制
    - 台费（含多台桌合并）：计价规则、台桌类型与单价关系、计时方式
    - 台费折扣（dwd_table_fee_adjust）：触发条件和计算方式
    - 商品消费：商品销售流水的记录方式
    - 助教服务（陪打/超休）：服务类型和计费方式
    - 灯控电费：记录方式
    - 每个环节提供至少一个测试库真实数据样例
    - _Requirements: 2.2, 2.3, 2.6_

  - [x] 3.3 梳理优惠与团购机制
    - 平台团购券（美团/抖音）核销流程
    - 会员折扣计算方式
    - 台费调整（adjust_amount）的业务场景
    - 团购券三层价格体系（sale_price / pl_coupon_sale_amount / coupon_amount），标注每层价格对应的 DWD 表和字段
    - 每个环节提供测试库数据样例
    - _Requirements: 2.4, 2.5, 2.6_

  - [x] 3.4 文档2收尾：附录与引用
    - 补充附录（验证 SQL、数据样例）
    - 添加文档间引用链接
    - 确认文档模板完整性
    - _Requirements: 7.3, 7.4, 7.5_

- [x] 4. 阶段二B：账务全景文档（文档3）
  - [x] 4.1 创建文档3骨架并梳理支付渠道
    - 创建 `docs/reports/dwd-accounting-panorama.md`，使用全景文档通用模板
    - 描述所有支付渠道及其在 DWD 层的记录方式（线上收款、现金、储值卡余额、平台团购券）
    - 描述 dwd_payment 与 dwd_settlement_head 的关联方式
    - 描述 payment_method 枚举值与实际支付渠道的对应关系
    - 描述支付方式推断逻辑（因 settlement_head_ex.payment_method 全部为 0 不可用）
    - _Requirements: 3.1, 3.2, 3.6, 6.4, 7.3_

  - [x] 4.2 梳理会员储值卡体系与退款流程
    - 充值流程（dwd_recharge_order）
    - 余额变动记录（dwd_member_balance_change）
    - 本金/赠送金额分账逻辑
    - 退款流程：结算退款、充值退款、转账退款的触发场景和 DWD 记录方式
    - _Requirements: 3.3, 3.4_

  - [x] 4.3 梳理对账公式与 consume_money 口径
    - 列出所有已验证的对账公式（F1~F6、R1~R3、RF1~RF2、B1~B4）
    - 对每个公式在 test_etl_feiqiu 全量数据上执行验证，标注成立率和例外情况
    - 描述 consume_money 字段的三种历史口径（A/B/C）及时间线，标注当前生效口径
    - _Requirements: 3.5, 3.7, 6.2_

  - [x] 4.4 文档3收尾：附录与引用
    - 补充附录（验证 SQL、对账公式验证结果）
    - 添加文档间引用链接
    - 确认文档模板完整性
    - _Requirements: 7.3, 7.4, 7.5_

- [x] 5. 检查点 - 文档2和文档3完成确认
  - 确认文档2覆盖全部消费类目和优惠机制（台费/商品/助教/灯控/团购券/会员折扣）
  - 确认文档3覆盖全部支付渠道和对账公式（F1/F2/B1-B3/consume_money三种口径）
  - 确认所有关键结论标注了验证状态
  - 确认文档3覆盖全部支付渠道和对账公式
  - 确认所有关键结论标注了验证状态
  - Ensure all tests pass, ask the user if questions arise.

- [x] 6. 阶段二C：财务全景文档（文档4）
  - [x] 6.1 创建文档4骨架并梳理收入构成
    - 创建 `docs/reports/dwd-financial-panorama.md`，使用全景文档通用模板
    - 按收入来源分类描述门店收入构成：台费收入、商品收入、助教服务收入、充值收入
    - 描述每种收入来源对应的 DWD 表、关键金额字段、从 DWD 到 DWS 的聚合路径
    - _Requirements: 4.1, 4.2, 6.4, 7.3_

  - [x] 6.2 梳理团购收入确认与储值卡资金流向
    - 团购券场景收入确认逻辑：门店实际收入 = pl_coupon_sale_amount，差额为门店补贴
    - 储值卡充值资金流向：充值收款 → 余额入账（本金+赠送）→ 消费扣款 → 退款
    - 标注每个环节的 DWD 表和金额字段
    - _Requirements: 4.3, 4.4_

  - [x] 6.3 构建对账矩阵与数据质量评估
    - 按支付渠道构建对账矩阵：每种支付渠道涉及的 DWD 表和字段、跨表校验公式
    - 标注已知数据质量问题和对账例外（助教券支付缺口、商品消费未覆盖等）
    - 给出影响范围的量化评估
    - _Requirements: 4.5, 4.6_

  - [x] 6.4 文档4收尾：附录与引用
    - 补充附录（验证 SQL、对账矩阵详细数据）
    - 添加文档间引用链接（引用文档2的消费构成、文档3的支付渠道）
    - 确认文档模板完整性
    - _Requirements: 7.3, 7.4, 7.5_

- [x] 7. 阶段二D：维度表与主数据全景（文档5）
  - [x] 7.1 创建文档5骨架并梳理门店与台桌维度
    - 创建 `docs/reports/dwd-dimension-panorama.md`，使用全景文档通用模板
    - 梳理 dim_site/ex：门店维度结构、SCD2 字段、与事实表的关联
    - 梳理 dim_table/ex：台桌维度结构、台桌类型枚举、与台费流水的关联
    - _Requirements: 5.1, 5.2, 6.4, 7.3_

  - [x] 7.2 梳理会员体系与助教维度
    - 会员档案（dim_member/ex）：会员等级/标签记录方式
    - 储值卡账户（dim_member_card_account/ex）：账户类型、余额字段
    - 助教维度（dim_assistant/ex）：助教类型、服务能力
    - 描述维度表与事实表的关联方式，标注关联字段和基数
    - _Requirements: 5.2, 5.3_

  - [x] 7.3 梳理商品体系与团购维度
    - 商品分类树（dim_goods_category）：分类层级结构
    - 租户商品（dim_tenant_goods/ex）与门店商品（dim_store_goods/ex）的关系
    - 库存相关表（dwd_goods_stock_summary, dwd_goods_stock_movement）的结构
    - 团购套餐维度（dim_groupbuy_package/ex）：套餐与券种关系、价格体系
    - _Requirements: 5.4, 5.5_

  - [x] 7.4 文档5收尾：Mermaid ER 图与附录
    - 补充 Mermaid ER 图展示全部维度表与事实表的关联关系
    - 补充附录（验证 SQL、SCD2 字段汇总）
    - 添加文档间引用链接
    - 确认文档模板完整性
    - _Requirements: 5.1, 5.2, 7.3, 7.4, 7.5_

- [x] 8. 检查点 - 全部5份文档完成确认
  - 确认 5 份文档均已创建在 `docs/reports/` 目录下
  - 确认文档间引用链接格式正确（相对路径）且目标文件存在
  - 确认每份文档包含完整模板元素（标题、元数据块、目录、正文、附录）
  - Ensure all tests pass, ask the user if questions arise.

- [x] 9. 属性测试与示例测试
  - [x] 9.1 创建属性测试文件骨架与公共工具
    - 创建 `tests/test_dwd_panorama_properties.py`
    - 实现公共工具函数：读取文档内容、解析 markdown 结构、提取表名、提取链接
    - 配置 hypothesis settings（min_examples=100）
    - 使用 `load_dotenv` 加载根 `.env`，通过 `TEST_DB_DSN` 连接测试库
    - _Requirements: 6.1_

  - [x] 9.2 编写 Property 1: DWD 表覆盖完整性
    - **Property 1: DWD 表覆盖完整性**
    - 查询 information_schema.tables 获取 DWD schema 全部表名
    - 解析 5 份文档提取提及的表名
    - 验证覆盖率 = 100%
    - **Validates: Requirements 1.1, 5.1**

  - [x] 9.3 编写 Property 2: 主键标注准确性
    - **Property 2: 主键标注准确性**
    - 对随机采样的表，查询 information_schema.table_constraints + key_column_usage 获取实际主键
    - 解析文档1中该表的主键标注
    - 验证一致性
    - **Validates: Requirements 1.5**

  - [x] 9.4 编写 Property 3: 业务环节数据佐证
    - **Property 3: 业务环节数据佐证**
    - 解析业务全景文档（文档2）的每个业务环节段落
    - 验证每个段落包含至少一个代码块或数据表格
    - **Validates: Requirements 2.6**

  - [x] 9.5 编写 Property 4: 对账公式验证一致性
    - **Property 4: 对账公式验证一致性**
    - 提取账务全景文档（文档3）中的对账公式和标注的成立率
    - 重新执行验证 SQL，比对成立率
    - **Validates: Requirements 3.5, 6.2**

  - [x] 9.6 编写 Property 5: 文档元数据完整性
    - **Property 5: 文档元数据完整性**
    - 对每份全景文档，检查开头是否包含：数据来源（test_etl_feiqiu）、验证日期、数据时间范围
    - **Validates: Requirements 6.4**

  - [x] 9.7 编写 Property 6: 文档输出路径正确性
    - **Property 6: 文档输出路径正确性**
    - 验证所有产出文件位于 `docs/reports/` 目录下
    - **Validates: Requirements 7.1**

  - [x] 9.8 编写 Property 7: 文档模板一致性
    - **Property 7: 文档模板一致性**
    - 对每份文档，检查是否包含标题、元数据块、目录、正文、附录
    - **Validates: Requirements 7.3**

  - [x] 9.9 编写 Property 8: 内部链接格式
    - **Property 8: 内部链接格式**
    - 正则提取所有 markdown 内部链接
    - 验证使用相对路径格式（以 `./` 或 `../` 开头）且目标文件存在
    - **Validates: Requirements 7.5**

  - [x] 9.10 编写示例测试
    - 创建 `tests/test_dwd_panorama_examples.py`
    - SCD2 字段标注检查：dim_member 文档中包含 scd2_start_time 等字段
    - 消费类目覆盖检查：业务全景文档包含"台费"、"商品消费"、"助教服务"、"灯控电费"
    - 团购三层价格检查：文档包含 sale_price、pl_coupon_sale_amount、coupon_amount
    - Mermaid 流程图检查：业务全景文档包含 mermaid 代码块
    - consume_money 三种口径检查：文档包含口径 A、B、C
    - 对账矩阵检查：财务全景文档包含矩阵格式表格
    - 5 份文档产出检查：docs/reports/ 下存在 5 个指定文件名
    - 每份文档 Mermaid 图表检查
    - 无数据表标注检查（边界条件）
    - _Requirements: 1.6, 1.7, 2.2, 2.5, 2.7, 3.5, 3.7, 4.5, 7.2, 7.4_

- [x] 10. 最终检查点 - 全部完成确认
  - 运行全部属性测试：`cd C:\NeoZQYY && pytest tests/test_dwd_panorama_properties.py -v`
  - 运行全部示例测试：`cd C:\NeoZQYY && pytest tests/test_dwd_panorama_examples.py -v`
  - 确认 5 份文档内容完整、验证状态标注齐全
  - Ensure all tests pass, ask the user if questions arise.

## Notes

- 标记 `*` 的任务为可选，可跳过以加速 MVP
- 每个任务引用了具体的需求编号，确保可追溯
- 检查点任务确保增量验证
- 属性测试验证文档的结构正确性，示例测试验证具体内容覆盖
- 所有数据库查询必须使用测试库 `test_etl_feiqiu`，通过 `TEST_DB_DSN` 连接
- 文档1是其他4份文档的基础，必须先完成阶段一再进入阶段二