---
inclusion: fileMatch
fileMatchPattern: "**/tasks/**,**/loaders/**,**/scd/**,**/dws/**,**/dwd/**,**/quality/**,**/business-rules/**,**/schemas/**,**/routers/**,**/financial*,**/settlement*,**/consume*,**/accounting*,**/salary*,**/assistant*,**/member*,**/index*,**/winback*,**/newconv*,**/relation_index*,**/spending*,**/stock*,**/finance_*,**/income_*,**/discount_*,**/order_contribution*,**/cfg_*,**/orchestration/**,**/config/**"
name: dwd-doc-authority
description: DWD-DOC 标杆文档强制规则。涉及 ETL 任务/财务/结算/消费/助教/会员/指数/统计/配置相关文件时自动加载。
---

# DWD-DOC 标杆文档（权威数据源，强制优先参考）

`docs/reports/DWD-DOC/` 是本项目的业务模型与财务数据权威标杆文档。
所有涉及金额口径、支付渠道、消费链路、账务公式、字段语义的开发工作，必须以此目录为第一参考源。

## 文档清单

| 文件 | 内容 | 关键规则 |
|------|------|----------|
| `README.md` | 总览 + GAP 闭环状态 | 文档索引入口 |
| `01-business-panorama.md` | 消费链路 + 优惠机制 + 消费场景 | settle_type 枚举、助教费用拆分、团购券三层价格 |
| `02-accounting-panorama.md` | 支付渠道 + 对账公式 + consume_money 口径 | 支付渠道恒等式、F2 三期公式 |
| `03-financial-panorama.md` | 收入构成 + 储值卡资金流 + 对账矩阵 | 平台结算互斥关系 |
| `04-dimension-panorama.md` | 维度表与主数据全景 | SCD2 维度取值规则 |
| `05-f2-balance-audit.md` | F2 收支平衡公式专项 | 三期公式 + 139 笔失败根因 |
| `06-calibration-checklist.md` | 校准清单 + 验证 SQL | 全部验证公式集中 |
| `consume/consume-money-caliber.md` | consume_money 口径变化时间线 | 三种口径(A/B/C)定义与切换时间点 |

## 强制规则（所有 session 生效）

1. **consume_money 禁止直接用于计算**：存在三种历史口径(A/B/C)混合，DWS 层及下游统一使用 `items_sum = table_charge_money + goods_money + assistant_pd_money + assistant_cx_money + electricity_money`
2. **助教费用必须拆分**：使用 `assistant_pd_money`（陪打）和 `assistant_cx_money`（超休），禁止使用笼统的 `service_fee` / `ASSISTANT_BASE` / `ASSISTANT_BONUS`（`service_fee` 仅在平台结算表中表示"平台服务费"，语义不同）
3. **支付渠道恒等式**：`balance_amount = recharge_card_amount + gift_card_amount`（100% 成立），三者不可重复计算
4. **settle_type 过滤**：正向交易取 `IN (1, 3)`，本表无 `is_delete` 字段
5. **电费未启用**：`electricity_money` 全为 0，`gross_amount` 不含电费是正确的
6. **折扣互斥**：`discount_manual`（大客户优惠）与 `discount_other` 互斥，两者之和 = `adjust_amount`
7. **现金流互斥**：`cash_inflow_total` 中 `platform_settlement_amount` 和 `groupbuy_pay_amount` 互斥
8. **废单判断**：使用 `dwd_assistant_service_log_ex.is_trash`，`dwd_assistant_trash_event` 已废弃（2026-02-22 DROP）
9. **储值卡字段命名**：DWS 层使用 `balance_pay`（总额）、`recharge_card_pay`（现金充值卡）、`gift_card_pay`（赠送卡）；`recharge_card_consume`（财务日报）
10. **会员字段断档（DQ-6）**：`settlement_head.member_phone/member_name` 自 2025-12 起全为 NULL。需要会员信息时通过 `member_id` LEFT JOIN `dwd.dim_member`（取 `scd2_is_current=1`）
11. **会员卡字段断档（DQ-7）**：`settlement_head.member_card_type_name` 自 2025-07-21 起全为 NULL。需要会员卡类型时通过 `member_id` LEFT JOIN `dwd.dim_member_card_account`（取 `scd2_is_current=1`）。通用规则：结算单上所有会员相关冗余字段均不可靠，一律通过 ID 关联维度表获取

## 与其他文档的优先级

当 BD 手册、ETL 任务文档、业务规则文档、SPEC 文档、DDL 注释与 DWD-DOC 冲突时，以 DWD-DOC 为准。

> 标杆文档基于 2026-03-06 对 test_etl_feiqiu 数据库的实际数据验证，公式和比例关系具有权威性。
