162 lines
7.5 KiB
Markdown
162 lines
7.5 KiB
Markdown
---
|
|
name: logic-planner
|
|
description: 当需要把一份已校验的数据需求(候选表/字段/join 关联已确认)拆解为 SQL 生成器可机械执行的步骤计划时使用。触发词包括"拆解逻辑"、"执行计划"、"logic plan"、"SQL 编排"、"怎么算"、"指标拆解"、"join 顺序"。消费 metadata-validator 的 Validation Result,产出固定步骤分类法(Source / Filter / Join / Transform / Aggregate / Output)的 Logic Plan。**不写 SQL**。
|
|
---
|
|
|
|
# Logic Planner(逻辑规划器)
|
|
|
|
## 概述(Overview)
|
|
|
|
将一份已校验的数据需求分解为固定分类法下的确定性步骤流水线。Logic Plan 是 `sql-context-builder` 拼装 SQL Context **唯一**的输入 — 下游不允许再做任何业务推理。
|
|
|
|
核心原则:**只拆分,不翻译。** 本 skill 绝不写 SQL 语法,只在业务/逻辑层面描述每一步要发生什么。SQL 翻译是另一回事。
|
|
|
|
## 何时使用(When to Use)
|
|
|
|
**使用场景:**
|
|
|
|
- `metadata-validator` 返回状态 `VALIDATED`,需要设计查询如何执行
|
|
- 用户询问"这个应该怎么算"、"逻辑是啥"、"一步步怎么走"等数据需求问题
|
|
- 写 SQL 之前需要先消除粒度、指标公式、去重、窗口、排名的歧义
|
|
|
|
**不要使用场景:**
|
|
|
|
- `metadata-validator` 返回 `NEED_USER_CONFIRMATION` — 先回去解决未决问题
|
|
- 用户已经提供了书面执行计划,只是要 SQL — 直接进入 `sql-context-builder`
|
|
|
|
## 输入(Inputs)
|
|
|
|
1. 来自 `metadata-validator` 的 **Validation Result**(状态为 `VALIDATED`)
|
|
2. 原始业务需求(通常嵌在 `requirements-analysis` 的输出中)
|
|
3. `field_mapping`(必备) — 每个业务字段在规划开始前必须先映射到物理 `(table, column, type)`
|
|
|
|
## 步骤分类法(Step Taxonomy)
|
|
|
|
每个 Logic Plan 都是一组步骤。每个步骤有且仅有一个 `kind`,且只能从下表选取。对重复操作(如多次 join、多次 filter)复用同一种 kind。
|
|
|
|
| Kind | 用途 | 必填字段 |
|
|
|---|---|---|
|
|
| `source` | 从表或子查询读取 | `alias`, `table`, `columns[]` |
|
|
| `filter` | 在指定 alias 上应用谓词 | `alias`, `predicates[]` |
|
|
| `join` | 在 key 上合并两个 alias | `left`, `right`, `keys[]`, `type` (inner/left/right/full/semi/anti) |
|
|
| `transform` | 派生新列(case-when、算术、类型转换) | `alias`, `expressions[]` |
|
|
| `aggregate` | 分组聚合 | `alias`, `group_by[]`, `metrics[]` (每个含 `expr`, `alias`, `agg`) |
|
|
| `dedupe` | DISTINCT 或基于 row_number 的去重 | `alias`, `keys[]`, `strategy` |
|
|
| `window` | 排名 / 累计 / lag-lead | `alias`, `partition_by[]`, `order_by[]`, `window_fn` |
|
|
| `output` | 最终投影和排序 | `columns[]`, `order_by[]`, `limit?` |
|
|
|
|
不要发明新 kind。如果某个变换无法归入上述分类,作为 `pending_question` 暴露并停止。
|
|
|
|
## 工作流(Workflow)
|
|
|
|
```dot
|
|
digraph logic_planner {
|
|
"读取 Validation Result + field_mapping" [shape=box];
|
|
"区分事实表 / 维度表,选定主源表" [shape=box];
|
|
"列出过滤条件(时间区间、状态、业务谓词)" [shape=box];
|
|
"规划 join(alias A ON key = alias B.key)" [shape=box];
|
|
"规划 transform(派生列、类型转换)" [shape=box];
|
|
"如需去重 / 窗口,一并规划" [shape=box];
|
|
"规划 aggregate(粒度 + 指标)" [shape=box];
|
|
"规划 output 投影 + 排序" [shape=box];
|
|
"还有歧义?" [shape=diamond];
|
|
"输出 Logic Plan" [shape=box];
|
|
"输出 Logic Plan + pending_questions" [shape=box];
|
|
|
|
"读取 Validation Result + field_mapping" -> "区分事实表 / 维度表,选定主源表";
|
|
"区分事实表 / 维度表,选定主源表" -> "列出过滤条件(时间区间、状态、业务谓词)";
|
|
"列出过滤条件(时间区间、状态、业务谓词)" -> "规划 join(alias A ON key = alias B.key)";
|
|
"规划 join(alias A ON key = alias B.key)" -> "规划 transform(派生列、类型转换)";
|
|
"规划 transform(派生列、类型转换)" -> "如需去重 / 窗口,一并规划";
|
|
"如需去重 / 窗口,一并规划" -> "规划 aggregate(粒度 + group_by)";
|
|
"规划 aggregate(粒度 + group_by)" -> "规划 output 投影 + 排序";
|
|
"规划 output 投影 + 排序" -> "还有歧义?";
|
|
"还有歧义?" -> "输出 Logic Plan" [label="no"];
|
|
"还有歧义?" -> "输出 Logic Plan + pending_questions" [label="yes"];
|
|
}
|
|
```
|
|
|
|
## 必须给出的推理(Required Reasoning,不可跳过)
|
|
|
|
在输出 plan 之前,你必须显式陈述并记录:
|
|
|
|
1. **粒度(Grain)** — 输出一行代表什么?(例如:一个客户、一个客户×月、一笔订单)
|
|
2. **指标公式(Metric formula)** — 对每个指标写出精确表达式:分子与分母都要定义
|
|
3. **时间粒度(Time grain)** — 确认时间字段与粒度(天 / 月 / 小时),用闭/开区间说明窗口
|
|
4. **Join 基数(Join cardinality)** — 对每个 join,预测 1:1 / 1:N / N:N。如果是 N:N,必须标记并询问用户是否在 join 前去重
|
|
5. **去重位置(Dedup position)** — 如果事实表存在行重复(例如一个客户多个地址),在 join 之前决定哪一侧、在哪个 key 上先去重
|
|
6. **空值策略(Null strategy)** — 对可空 join key 或度量,决定用 `INNER` 还是 `LEFT + COALESCE`
|
|
|
|
以上任意一项不清楚时,加入 `pending_question` 并停止。绝不臆测。
|
|
|
|
## 输出契约(Output Contract)
|
|
|
|
```yaml
|
|
logic_plan:
|
|
grain: "<一句话描述输出一行代表什么>"
|
|
fact_table: <table_name>
|
|
dimension_tables:
|
|
- <table_name>
|
|
steps:
|
|
- kind: source
|
|
alias: o
|
|
table: loan_order
|
|
columns: [customer_id, loan_amount, apply_time, status]
|
|
- kind: filter
|
|
alias: o
|
|
predicates:
|
|
- "o.apply_time >= '<window_start>'"
|
|
- "o.apply_time < '<window_end>'"
|
|
- "o.status = 'SUCCESS'"
|
|
- kind: join
|
|
left: { alias: o }
|
|
right: { alias: c, table: customer_info }
|
|
keys: ["o.customer_id = c.customer_id"]
|
|
type: left
|
|
cardinality_assumption: 1:N # 已知时填;否则写 "unknown"
|
|
- kind: transform
|
|
alias: o
|
|
expressions:
|
|
- expr: "CASE WHEN o.loan_amount >= 100000 THEN 'large' ELSE 'small' END"
|
|
alias: loan_bucket
|
|
- kind: aggregate
|
|
alias: o
|
|
group_by: ["c.city"]
|
|
metrics:
|
|
- expr: "SUM(o.loan_amount)"
|
|
alias: total_loan
|
|
agg: sum
|
|
- expr: "COUNT(DISTINCT o.customer_id)"
|
|
alias: customer_cnt
|
|
agg: count_distinct
|
|
- kind: output
|
|
columns: ["c.city AS city", "total_loan", "customer_cnt"]
|
|
order_by: ["total_loan DESC"]
|
|
limit: 100
|
|
pending_questions:
|
|
- "<尚未解决的歧义,会阻塞 SQL 生成>"
|
|
status: <PLANNED | NEED_USER_CONFIRMATION>
|
|
```
|
|
|
|
## 禁止行为(Forbidden Behaviors)
|
|
|
|
| 自我说服 | 现实 |
|
|
|---|---|
|
|
| "我直接写 SELECT 列表,用户能读懂 SQL" | Logic Plan 用业务术语,SQL 是下游的事。 |
|
|
| "聚合太显然,公式就省了" | 显式给出分子/分母才能避免静默的指标漂移。 |
|
|
| "1:N 还是 N:N 对 SELECT 来说无所谓" | 它决定了是否要去重以及是否有膨胀风险,影响很大。 |
|
|
| "时间粒度是用户的问题" | 必须由规划器选定一个粒度,选错了数字就全错。 |
|
|
| "HAVING 我到 SQL 那一步再加" | 所有过滤(含聚合后)都必须在 Logic Plan 中列出。 |
|
|
|
|
## 完成判定(Completion Criteria)
|
|
|
|
要输出状态 `PLANNED`,必须满足:
|
|
|
|
- 粒度用一句话描述,不是一段话
|
|
- 每个 `field_mapping` 条目都被恰好一个 step 引用
|
|
- 每个 join 都有 cardinality 假设
|
|
- 每个指标都有显式 `agg` 和 `alias`
|
|
- `pending_questions` 为空
|
|
|
|
否则:状态为 `NEED_USER_CONFIRMATION` 并停止。**不得**进入 `sql-context-builder`。
|