---
inclusion: always
---

# 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`（财务日报）

## 使用场景

- 编写或修改 ETL 任务代码（DWD/DWS 层）
- 编写或修改后端 API 涉及金额计算的逻辑
- 编写或修改小程序/管理后台涉及财务数据展示的页面
- 编写 SQL 查询涉及结算、支付、消费金额
- 编写或审阅 BD 手册、SPEC 文档中的字段口径描述
- 前置调研（`pre-change-research.md`）中涉及财务/账务模块时

## 与其他文档的优先级

当以下文档与 DWD-DOC 标杆文档冲突时，以 DWD-DOC 为准：
- BD 手册（`apps/etl/connectors/feiqiu/docs/database/`）
- ETL 任务文档（`apps/etl/connectors/feiqiu/docs/etl_tasks/`）
- 业务规则文档（`apps/etl/connectors/feiqiu/docs/business-rules/`）
- SPEC 文档（`docs/prd/specs/`）
- DDL 注释（`docs/database/ddl/`）

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