Neo-ZQYY/.kiro/steering/dwd-doc-authority.md

inclusion

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 数据库的实际数据验证，公式和比例关系具有权威性。