56 lines
4.2 KiB
Markdown
56 lines
4.2 KiB
Markdown
---
|
||
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`（财务日报）
|
||
10. **会员字段断档（DQ-6）**：`settlement_head.member_phone/member_name` 自 2025-12 起全为 NULL（上游不再下发）。需要会员手机号/昵称时，必须通过 `member_id` LEFT JOIN `dwd.dim_member`（字段 `mobile`/`nickname`，取 `scd2_is_current=1`），禁止直接使用 `member_phone`
|
||
11. **会员卡字段断档（DQ-7）**：`settlement_head.member_card_type_name` 自 2025-07-21 起全为 NULL，`member_card_account_id` 全为 0。需要会员卡类型时，必须通过 `member_id` LEFT JOIN `dwd.dim_member_card_account`（关联 `tenant_member_id = member_id`，取 `scd2_is_current=1`），禁止直接使用 `member_card_type_name`。通用规则：结算单上所有会员相关冗余字段均不可靠，一律通过 ID 关联维度表获取
|
||
|
||
## 使用场景
|
||
|
||
- 编写或修改 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 数据库的实际数据验证，公式和比例关系具有权威性。
|