52 lines
3.9 KiB
Markdown
52 lines
3.9 KiB
Markdown
---
|
||
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/](../sql-agent-demo/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](../sql-agent-demo/queries/penalty_daily_report.sql)、[penalty_weekly.sql](../sql-agent-demo/queries/penalty_weekly.sql)、[penalty_monthly_report.sql](../sql-agent-demo/queries/penalty_monthly_report.sql)）核心指标：去重扣款师傅数（`COUNT(DISTINCT master_id)`）、去重罚单数（`COUNT(DISTINCT penalty_sheet_id)`）、已实际支付的师傅数（`extra_status = 'paid'` 时再去重）。
|
||
- 师傅扣款月报（[penalty_master_deduction_monthly_report.sql](../sql-agent-demo/queries/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](../sql-agent-demo/skills/sql-requirement-review/SKILL.md) 等 Skill 协议，是通用的取数口径澄清方法论，不局限于本项目：
|
||
|
||
- 需求信息分三类：`CONFIRMED`（用户明确给出或已批准口径）、`DERIVED`（可直接推导且不改变指标含义）、`UNKNOWN`（缺失后会导致不同结果，必须确认）。
|
||
- 迭代需求要先区分 `NEW`/`EXISTING`/`UNCLEAR` 范围；存在历史模块时优先要历史 SQL 或已部署任务，历史实现只能作证据，不能自动升级为正确口径。
|
||
- 只问真正影响结果的问题，并合并相关问题一起问；能靠 DDL/表元数据自己查到的信息不要求用户回答。
|
||
- 检查聚合和重复计算风险：明确一行代表什么、什么去重、是否有一对多关联、是否混淆累计值与期间值。
|
||
|
||
## 相关
|
||
|
||
- 数仓表选型和分区规则见 [warehouse.md](warehouse.md)。
|
||
- SQL 写法规范见 [sql-rules.md](sql-rules.md)。
|