root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

微信小程序页面迁移校验之前 P5任务处理之前

Browse Source
This commit is contained in:
Neo
2026-03-09 01:19:21 +08:00
parent 263bf96035
commit 6e20987d2f
1112 changed files with 153824 additions and 219694 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.kiro/specs/dwd-business-panorama/.config.kiro Normal file
View File

@@ -0,0 +1 @@
{"specId": "7e1dc63d-3dbd-4462-a43c-9ecaa9b1dd07", "workflowType": "requirements-first", "specType": "feature"}

440
.kiro/specs/dwd-business-panorama/design.md Normal file
View File

@@ -0,0 +1,440 @@
# 设计文档：DWD 业务全景梳理
## 概述
本设计文档描述如何系统梳理飞球 ETL 的 DWD 层全部业务数据，产出 5 份全景分析文档。这是一个纯文档梳理任务，不涉及代码改动，核心挑战在于：如何在"数据本源优先"的强制准则下，高效、准确地完成 7 个业务域、约 30 张表（含扩展表）的字段语义验证和跨表关联分析。
### 设计目标
1. 定义可重复执行的梳理方法论，确保每张表的分析过程一致
2. 设计每份文档的结构模板，确保产出物格式统一
3. 规划数据验证的技术方案，确保结论可追溯
4. 设计文档间的引用和关联机制，避免信息重复
### 范围
- 输入：`test_etl_feiqiu` 数据库 DWD schema 的全部表和数据
- 参考：现有 BD 手册（`apps/etl/connectors/feiqiu/docs/database/DWD/`）、已有分析报告（`docs/reports/`）
- 产出：5 份全景文档，输出到 `docs/reports/`
### DWD 表全景
根据现有 BD 手册，DWD 层包含以下表：
| 类型 | 表数量 | 表名 |
|------|--------|------|
| 维度表（主表） | 9 | `dim_site`, `dim_table`, `dim_assistant`, `dim_member`, `dim_member_card_account`, `dim_tenant_goods`, `dim_store_goods`, `dim_goods_category`, `dim_groupbuy_package` |
| 维度表（扩展表） | 8 | 上述除 `dim_goods_category` 外均有 `_ex` 扩展表 |
| 事实表（主表） | 13 | `dwd_settlement_head`, `dwd_payment`, `dwd_table_fee_log`, `dwd_table_fee_adjust`, `dwd_assistant_service_log`, `dwd_member_balance_change`, `dwd_recharge_order`, `dwd_refund`, `dwd_groupbuy_redemption`, `dwd_platform_coupon_redemption`, `dwd_store_goods_sale`, `dwd_goods_stock_summary`, `dwd_goods_stock_movement` |
| 事实表（扩展表） | 11 | 除 `dwd_payment`, `dwd_goods_stock_summary`, `dwd_goods_stock_movement` 外均有 `_ex` 扩展表 |
共计约 43 张表。
## 架构
### 整体梳理流程
梳理工作分为两个阶段：基础层（表结构与字段语义）和全景层（跨表关联分析）。基础层产出为全景层的输入。
```mermaid
flowchart TD
subgraph Phase1["阶段一：基础层梳理"]
A[枚举 DWD 全部表] --> B[按业务域分组]
B --> C[逐表执行智能聚焦分析]
C --> D[字段分类筛选]
D --> E[业务关键字段倒推验证]
E --> F[产出：DWD 表结构与字段语义总览]
end
subgraph Phase2["阶段二：全景层梳理"]
F --> G[业务全景：消费产生机制]
F --> H[账务全景：结算与支付]
F --> I[财务全景：收入与对账]
F --> J[维度表与主数据全景]
end
subgraph Validation["贯穿：数据验证"]
K[information_schema 查表结构]
L[SQL 查询验证值域分布]
M[交叉查询验证关联关系]
N[对账公式全量验证]
end
C -.-> K
E -.-> L
E -.-> M
H -.-> N
```
### 信息流向
```mermaid
flowchart LR
subgraph 输入源
DB[(test_etl_feiqiu<br/>DWD schema)]
BD[现有 BD 手册<br/>宏观参考]
RPT[已有分析报告<br/>待验证假设]
end
subgraph 梳理过程
DB -->|information_schema| META[表结构元数据]
DB -->|SQL 查询| DATA[实际数据验证]
BD -->|宏观层可参考| REF[参考起点]
RPT -->|字段级需验证| HYP[待验证假设]
end
subgraph 产出
META --> DOC1[文档1: 表结构总览]
DATA --> DOC1
REF --> DOC1
HYP --> DOC1
DOC1 --> DOC2[文档2: 业务全景]
DOC1 --> DOC3[文档3: 账务全景]
DOC1 --> DOC4[文档4: 财务全景]
DOC1 --> DOC5[文档5: 维度表全景]
end
```
## 组件与接口
### 组件一：单表智能聚焦分析器
对每张 DWD 表执行标准化的分析流程，产出该表的字段语义报告。
#### 分析流程（每张表）
```
步骤 1: 表结构获取
→ 查询 information_schema.columns 获取列名、类型、nullable
→ 禁止参考 db/ 目录下的 DDL .sql 文件
步骤 2: 字段分类筛选
→ 查询全表空字段（SELECT column WHERE ALL NULL），标记为"空字段-跳过"
→ 识别 ETL 管理字段（_etl_loaded_at, _etl_batch_id 等），简要标注
→ 识别含义透明字段（id, site_id, created_at 等），仅列出
→ 剩余为"业务关键字段"，进入深度验证
步骤 3: 业务关键字段倒推验证
→ 从含义明确的字段出发（如 id, site_id, total_amount）
→ 通过 JOIN / 聚合对比 / 值域交叉推断不确定字段
→ 金额字段：MIN/MAX/AVG/中位数/NULL占比 + 交叉验证
→ 枚举字段：DISTINCT 值 + 频次分布
→ 关联 ID：JOIN 验证关联完整性
步骤 4: 偏差检测
→ 对比现有 BD 手册的字段描述
→ 标注一致/偏差/错误
```
#### 输出格式（每张表）
```markdown
### {table_name}
**业务职责**：一句话描述
**数据状态**：{行数} 行，时间范围 {min_date} ~ {max_date}
**主键**：{pk_fields}
**关联表**：{related_tables with join fields}
#### 业务关键字段
| 字段名 | 类型 | 验证状态 | 语义说明 | 值域/分布 |
|--------|------|----------|----------|-----------|
| ... | ... | ✅/⚠️/❌ | ... | ... |
#### 空字段（附录）
{列出全 NULL 的字段名}
#### 偏差记录
{与现有文档不一致的地方}
```
### 组件二：全景文档生成器
基于单表分析结果，按业务视角组织跨表关联分析。
#### 全景文档通用模板
```markdown
# {全景文档标题}
> 数据来源：test_etl_feiqiu (DWD schema)
> 验证日期：{date}
> 数据时间范围：{min_date} ~ {max_date}
## 目录
{自动生成}
## 正文
{按业务逻辑组织的分析内容}
{每个关键结论标注验证状态：✅ 已验证 / ⚠️ 部分验证 / ❌ 未验证}
## 附录
### 验证 SQL
{关键验证查询}
### 数据样例
{来自测试库的真实数据}
```
### 组件三：数据验证引擎
贯穿整个梳理过程的验证机制。
#### 验证类型
| 验证类型 | 方法 | 适用场景 |
|----------|------|----------|
| 值域验证 | MIN/MAX/AVG/MEDIAN/NULL% | 金额字段、数值字段 |
| 枚举验证 | DISTINCT + COUNT | 状态字段、类型字段 |
| 关联验证 | LEFT JOIN + NULL 检查 | 外键关联完整性 |
| 等式验证 | SUM 对比 | 对账公式（F1~F6 等） |
| 交叉验证 | 多表 JOIN + 聚合对比 | 跨表金额一致性 |
| 边界验证 | WHERE = 0 / < 0 / IS NULL | 异常值业务含义 |
#### 验证结果标注规范
- ✅ 已验证：附验证 SQL 摘要或结果统计
- ⚠️ 部分验证：附已知例外数量和分类
- ❌ 未验证：附原因（数据不足/无法关联/逻辑不明）
- ⚠️ 警告：经多次交叉验证仍无法对齐的数据关系
## 数据模型
### DWD 表按业务域分组
本次梳理将 DWD 层全部表按 7 个业务域组织，每个域内的表构成一个分析单元。
```mermaid
erDiagram
%% 结算域
dwd_settlement_head ||--o{ dwd_payment : "order_settle_id"
dwd_settlement_head ||--o{ dwd_table_fee_log : "order_settle_id"
dwd_settlement_head ||--o{ dwd_store_goods_sale : "order_settle_id"
dwd_settlement_head ||--o{ dwd_assistant_service_log : "order_settle_id"
dwd_settlement_head ||--o{ dwd_platform_coupon_redemption : "order_settle_id"
dwd_settlement_head ||--o{ dwd_refund : "order_settle_id"
%% 台桌域
dim_table ||--o{ dwd_table_fee_log : "table_id"
dwd_table_fee_log ||--o{ dwd_table_fee_adjust : "table_fee_log_id"
%% 助教域（作废判断已内聚到 dwd_assistant_service_log_ex.is_trash）
dim_assistant ||--o{ dwd_assistant_service_log : "assistant_id"
%% 会员域
dim_member ||--o{ dim_member_card_account : "member_id"
dim_member ||--o{ dwd_member_balance_change : "member_id"
dim_member_card_account ||--o{ dwd_recharge_order : "tenant_member_card_id"
%% 团购域
dim_groupbuy_package ||--o{ dwd_groupbuy_redemption : "groupbuy_package_id"
%% 商品域
dim_goods_category ||--o{ dim_tenant_goods : "category_id"
dim_tenant_goods ||--o{ dim_store_goods : "tenant_goods_id"
dim_store_goods ||--o{ dwd_store_goods_sale : "site_goods_id"
dim_store_goods ||--o{ dwd_goods_stock_summary : "site_goods_id"
dim_store_goods ||--o{ dwd_goods_stock_movement : "site_goods_id"
%% 门店维度
dim_site ||--o{ dwd_settlement_head : "site_id"
```
### 业务域与表映射
| 业务域 | 事实表 | 维度表 | 核心关联 |
|--------|--------|--------|----------|
| 结算 | `dwd_settlement_head`(+ex), `dwd_payment`, `dwd_refund`(+ex) | — | 结算单是所有消费的汇总入口 |
| 台桌 | `dwd_table_fee_log`(+ex), `dwd_table_fee_adjust`(+ex) | `dim_table`(+ex) | 台费计费流水 → 台费调整 |
| 助教 | `dwd_assistant_service_log`(+ex) | `dim_assistant`(+ex) | 助教服务流水（作废通过 `_ex.is_trash` 判断） |
| 会员 | `dwd_member_balance_change`(+ex), `dwd_recharge_order`(+ex) | `dim_member`(+ex), `dim_member_card_account`(+ex) | 充值 → 余额变动 |
| 团购 | `dwd_groupbuy_redemption`(+ex), `dwd_platform_coupon_redemption`(+ex) | `dim_groupbuy_package`(+ex) | 团购核销 → 平台券核销 |
| 商品 | `dwd_store_goods_sale`(+ex) | `dim_tenant_goods`(+ex), `dim_store_goods`(+ex), `dim_goods_category` | 商品销售流水 |
| 库存 | `dwd_goods_stock_summary`, `dwd_goods_stock_movement` | （复用商品域维度表） | 库存汇总 + 变动流水 |
### 5 份文档的数据依赖关系
```mermaid
flowchart TD
DOC1["文档1: DWD 表结构与字段语义总览<br/>覆盖全部 43 张表"]
DOC1 --> DOC2["文档2: 业务全景<br/>消费产生机制"]
DOC1 --> DOC3["文档3: 账务全景<br/>结算与支付流水"]
DOC1 --> DOC4["文档4: 财务全景<br/>收入确认与对账"]
DOC1 --> DOC5["文档5: 维度表与主数据全景<br/>全部维度表"]
DOC2 -->|消费构成| DOC3
DOC2 -->|消费金额| DOC4
DOC3 -->|支付渠道| DOC4
DOC5 -->|维度关联| DOC2
DOC5 -->|维度关联| DOC3
```
### 文档产出路径与文件名
| 序号 | 文档 | 文件名 | 路径 |
|------|------|--------|------|
| 1 | DWD 表结构与字段语义总览 | `dwd-table-structure-overview.md` | `docs/reports/` |
| 2 | 业务全景：消费产生机制 | `dwd-business-panorama.md` | `docs/reports/` |
| 3 | 账务全景：结算与支付流水 | `dwd-accounting-panorama.md` | `docs/reports/` |
| 4 | 财务全景：收入确认与对账 | `dwd-financial-panorama.md` | `docs/reports/` |
| 5 | 维度表与主数据全景 | `dwd-dimension-panorama.md` | `docs/reports/` |
### 文档间引用规范
- 文档间使用相对路径引用：`[表结构总览](./dwd-table-structure-overview.md#table_name)`
- 引用已有分析报告：`[消费金额口径分析](./consume-money-caliber-deep-analysis.md#章节名)`
- 引用 BD 手册：`[BD 手册](../../apps/etl/connectors/feiqiu/docs/database/DWD/main/BD_manual_xxx.md)`
- 引用结论时标注验证状态和来源文档
## 正确性属性
*属性（Property）是一种在系统所有合法执行中都应成立的特征或行为——本质上是对系统应做什么的形式化陈述。属性是人类可读规格与机器可验证正确性保证之间的桥梁。*
### Property 1: DWD 表覆盖完整性
*对于* DWD schema（`test_etl_feiqiu.dwd`）中 `information_schema.tables` 返回的任意表，产出的文档集合中必须包含对该表的描述段落（表名出现在某份文档的标题或表格中）。
**Validates: Requirements 1.1, 5.1**
### Property 2: 主键标注准确性
*对于* DWD schema 中的任意表，文档中记录的主键字段集合必须与 `information_schema.table_constraints` + `key_column_usage` 查询返回的实际主键约束一致。
**Validates: Requirements 1.5**
### Property 3: 业务环节数据佐证
*对于* 业务全景文档（文档2）中描述的任意业务环节段落，该段落必须包含至少一个来自测试库的数据样例（以代码块或表格形式呈现的查询结果）。
**Validates: Requirements 2.6**
### Property 4: 对账公式验证一致性
*对于* 账务全景文档（文档3）中列出的任意对账公式，文档中标注的成立率和例外数量必须与在 `test_etl_feiqiu` 全量数据上执行该公式验证 SQL 的实际结果一致。
**Validates: Requirements 3.5, 6.2**
### Property 5: 文档元数据完整性
*对于* 产出的任意全景文档，文档开头必须包含：(a) 数据来源标注（`test_etl_feiqiu`）、(b) 验证日期、(c) 数据时间范围（最早和最晚记录的时间）。
**Validates: Requirements 6.4**
### Property 6: 文档输出路径正确性
*对于* 本次梳理产出的任意文档文件，其路径必须位于 `docs/reports/` 目录下。
**Validates: Requirements 7.1**
### Property 7: 文档模板一致性
*对于* 产出的任意全景文档，其结构必须包含以下模板元素：标题、数据来源与验证日期块、目录、正文、附录（含验证 SQL 或数据样例）。
**Validates: Requirements 7.3**
### Property 8: 内部链接格式
*对于* 产出文档中的任意内部链接（指向本项目其他 markdown 文件的链接），链接必须使用相对路径格式（以 `./` 或 `../` 开头），且目标文件实际存在。
**Validates: Requirements 7.5**
## 错误处理
本任务是纯文档梳理，不涉及运行时代码。"错误"主要指梳理过程中遇到的数据异常和验证失败。
### 数据异常处理策略
| 异常场景 | 处理方式 | 文档标注 |
|----------|----------|----------|
| 表无数据（0 行） | 跳过字段语义验证，仅记录表结构 | `❌ 未验证：表无数据` |
| 数据量不足（<10 行） | 执行有限验证，标注样本量不足 | `⚠️ 部分验证：仅 N 行数据` |
| 字段全 NULL | 标记为空字段，不展开分析 | 附录中列出字段名 |
| 对账公式不成立 | 分析例外案例，量化影响范围 | `⚠️ 成立率 X%，例外 N 笔` |
| 交叉验证矛盾 | 记录矛盾细节，标注为不确定 | `⚠️ 警告：无法对齐` |
| 现有文档与数据不一致 | 以数据为准，记录偏差 | `偏差记录` 段落 |
### 不确定性升级机制
当遇到以下情况时，必须在文档中以 `⚠️ 警告` 醒目标记：
1. 经过 ≥3 次不同角度的交叉验证仍无法确认的字段含义
2. 对账公式成立率 < 95% 且无法归因的例外
3. 金额字段的计算关系无法通过任何已知公式解释
4. 枚举值在现有文档中未记录且无法通过数据推断含义
警告内容须包含：已尝试的验证方法、无法确认的具体原因、建议的后续验证方向。
## 测试策略
### 测试方法说明
本任务的产出物是 markdown 文档而非代码，因此传统的单元测试和属性测试需要适配为"文档正确性验证"。
### 属性测试（Property-Based Testing）
使用 Python + `hypothesis` 库，针对设计文档中定义的正确性属性编写验证脚本。
**测试库**：`hypothesis`（项目已有，见 `tests/` 目录）
**最低迭代次数**：100 次（对于涉及随机采样的属性）
**测试位置**：`tests/` 目录（Monorepo 级属性测试）
#### 属性测试实现方案
| Property | 测试方法 | 实现思路 |
|----------|----------|----------|
| P1: 表覆盖完整性 | 查询 information_schema → 解析文档 → 比对 | 从数据库获取全部 DWD 表名，解析 5 份文档提取提及的表名，验证覆盖率 = 100% |
| P2: 主键标注准确性 | 查询 PK 约束 → 解析文档 → 比对 | 对于随机采样的 N 张表，比对文档中的主键与数据库实际主键 |
| P3: 业务环节数据佐证 | 解析文档段落 → 检查数据样例 | 解析业务全景文档的每个业务环节段落，验证包含代码块或数据表格 |
| P4: 对账公式验证一致性 | 提取公式 → 执行 SQL → 比对成立率 | 对于文档中的每个对账公式，重新执行验证 SQL，比对成立率 |
| P5: 文档元数据完整性 | 解析文档头部 → 检查必要字段 | 对于每份文档，检查开头是否包含数据来源、验证日期、时间范围 |
| P6: 文档路径正确性 | 列出产出文件 → 检查路径 | 验证所有产出文件位于 `docs/reports/` |
| P7: 文档模板一致性 | 解析文档结构 → 检查模板元素 | 对于每份文档，检查是否包含标题、元数据块、目录、正文、附录 |
| P8: 内部链接格式 | 正则提取链接 → 检查格式和目标 | 提取所有 markdown 链接，验证使用相对路径且目标文件存在 |
#### 属性测试标签格式
每个属性测试必须包含注释标签：
```python
# Feature: dwd-business-panorama, Property 1: DWD 表覆盖完整性
# Feature: dwd-business-panorama, Property 2: 主键标注准确性
# ...
```
### 单元测试（示例测试）
针对 prework 中标记为 `yes - example` 的验收标准：
| 验收标准 | 测试内容 |
|----------|----------|
| 1.6 SCD2 字段标注 | 检查 `dim_member` 文档中是否标注了 `scd2_start_time`, `scd2_end_time`, `scd2_is_current`, `scd2_version` |
| 2.2 消费类目覆盖 | 检查业务全景文档中是否包含"台费"、"商品消费"、"助教服务"、"灯控电费"四个关键词 |
| 2.5 团购三层价格 | 检查文档中是否提及 `sale_price`、`pl_coupon_sale_amount`、`coupon_amount` |
| 2.7 Mermaid 流程图 | 检查业务全景文档中是否包含 ` ```mermaid` 代码块 |
| 3.7 consume_money 三种口径 | 检查文档中是否包含口径 A、B、C 的描述 |
| 4.5 对账矩阵 | 检查财务全景文档中是否包含矩阵格式的表格 |
| 7.2 5 份文档产出 | 检查 `docs/reports/` 下是否存在 5 个指定文件名 |
| 7.4 Mermaid 图表 | 检查每份文档中是否包含至少一个 Mermaid 代码块 |
### 边界条件测试
| 验收标准 | 边界场景 |
|----------|----------|
| 1.7 表无数据 | 验证无数据表在文档中有"数据不足"标注 |
### 测试执行
```bash
# 属性测试（Monorepo 级）
cd C:\NeoZQYY && pytest tests/test_dwd_panorama_properties.py -v
# 单元测试
cd C:\NeoZQYY && pytest tests/test_dwd_panorama_examples.py -v
```

144
.kiro/specs/dwd-business-panorama/requirements.md Normal file
View File

@@ -0,0 +1,144 @@
# 需求文档：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 使用相对路径链接到源文档，并标注引用的具体章节

277
.kiro/specs/dwd-business-panorama/tasks.md Normal file
View File

@@ -0,0 +1,277 @@
# 实施计划：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份文档的基础，必须先完成阶段一再进入阶段二