3.9 KiB
3.9 KiB
title, source_status
| title | source_status |
|---|---|
| 业务口径与真实案例 | 混合——枚举为 user_confirmed；catalog 指标定义来自 sql-agent-demo 演示数据，非生产正式口径 |
业务口径与真实案例
1. 罚单业务（penalty_sheet，已用户确认，2026-07-22）
business_type 枚举：
| 值 | 含义 |
|---|---|
not_timely_sign_in |
超时签到 |
master_refused_service |
拒绝服务 |
not_timely_reserve |
超时预约 |
来源表：wanshifu_dw.dwd_iop_penalty_sheet_base_handle_v。
已验证的取数模式（见 queries/）：
- 判定"最新一条罚单处理记录"：按
penalty_sheet_id, object_id分组，ROW_NUMBER() OVER (PARTITION BY penalty_sheet_id, object_id ORDER BY update_time DESC, callback_time DESC, penalty_handle_id DESC)取row_num = 1。 - 有效罚单过滤：
NVL(is_delete, 0) = 0、object_type = 'master'、master_source_type = 'tob'、strategy_type = 'punish'、strategy = 'cash'，且extra_status IN ('wait_pay', 'paid')。 - 日报/周报/月报（penalty_daily_report.sql、penalty_weekly.sql、penalty_monthly_report.sql）核心指标：去重扣款师傅数（
COUNT(DISTINCT master_id)）、去重罚单数（COUNT(DISTINCT penalty_sheet_id)）、已实际支付的师傅数（extra_status = 'paid'时再去重）。 - 师傅扣款月报（penalty_master_deduction_monthly_report.sql）在此基础上按师傅维度展开扣款明细。
这一组 SQL 是"分区+口径+去重"写法的可复用范本：判定最新状态用窗口函数去重、有效性过滤在 CTE 里显式列出、汇总指标全部基于去重后的 _valid CTE 计算，避免同一罚单多条状态记录重复计数。
2. 指标定义示例（来自演示数据 data/catalog.json，非正式生产口径，仅作口径记录格式参考）
| 指标 | 别名 | 定义 | 表达式 | 来源表 | 过滤条件 |
|---|---|---|---|---|---|
| 销售额 | GMV、成交金额 | 已支付且非测试订单的商品成交金额，不扣除后续退款 | SUM(pay_amount) |
fact_orders |
pay_status='PAID'、is_test=0 |
| 订单量 | 支付订单数 | 已支付且非测试订单去重数 | COUNT(DISTINCT order_id) |
fact_orders |
同上 |
| 新客销售额 | — | 存在歧义：候选定义为"用户首次支付发生在统计期内"或"用户首次下单发生在统计期内" | 需先选定新客定义 | — | — |
"新客销售额"是一个真实会卡住 Agent/分析师的典型歧义案例：两种候选定义会得到不同结果，必须先向业务方确认口径，不能自行假设。遇到类似"首次 X"型指标，先检查是否也存在这种候选定义分叉。
3. Agent 工作流对业务口径的处理原则
来自 sql-requirement-review 等 Skill 协议，是通用的取数口径澄清方法论，不局限于本项目：
- 需求信息分三类：
CONFIRMED（用户明确给出或已批准口径）、DERIVED（可直接推导且不改变指标含义）、UNKNOWN（缺失后会导致不同结果，必须确认）。 - 迭代需求要先区分
NEW/EXISTING/UNCLEAR范围；存在历史模块时优先要历史 SQL 或已部署任务，历史实现只能作证据，不能自动升级为正确口径。 - 只问真正影响结果的问题，并合并相关问题一起问；能靠 DDL/表元数据自己查到的信息不要求用户回答。
- 检查聚合和重复计算风险：明确一行代表什么、什么去重、是否有一对多关联、是否混淆累计值与期间值。
相关
- 数仓表选型和分区规则见 warehouse.md。
- SQL 写法规范见 sql-rules.md。