---
name: sql-context-builder
description: 当逻辑计划已经完成，需要固定 SQL 生成和 SQL review 共同依赖的 alias、字段来源、join key、指标、维度、过滤、时间窗口、事实表/维表上下文时使用。消费 logic_plan 和 validation_result，不写 SQL，不调用 MCP。
---

# SQL Context Builder（SQL 上下文构建）

## 目标

把 SQL 生成时可能被临时猜测的内容提前固定下来。下游只能使用本 skill 输出的 alias、字段、join、指标、过滤、时间窗口和输出列。

## 输入

```yaml
logic_plan:
  status: PLANNED
validation_result:
  status: VALIDATED
  field_mapping: {}
  joins: []
```

## 工作顺序

1. 给每张表分配唯一、稳定、短小的 alias。
2. 标记事实表、维表、码表和目标表。
3. 把每个业务字段解析成 `alias.column`。
4. 固定 join 谓词、join 类型和基数假设。
5. 固定指标表达式、维度字段、时间字段、分区字段和过滤字段。
6. 固定时间窗口 SQL 片段，尤其是 T-1 完整日边界。
7. 固定输出列顺序和别名。
8. 检查 logic plan 中引用的字段都能在 context 中找到。
9. 对派生字段记录来源步骤和依赖字段。

## 时间窗口上下文

当存在时间过滤时，必须输出 `time_windows`。对“近 N 天按 T-1 完整日”：

```yaml
time_windows:
  - name: t_minus_1_complete_days
    event_field: fl.login_time
    lower_bound_sql: date_sub(current_date(), N)
    upper_bound_sql: current_date()
    predicate_sql: fl.login_time >= date_sub(current_date(), N) AND fl.login_time < current_date()
    boundary: left_closed_right_open
```

下游 SQL 必须复用 `predicate_sql`，不得临时改成 `BETWEEN`。

## 转化指标上下文

转化率必须固定分母、分子和顺序约束：

```yaml
metrics:
  - name: conversion_rate
    numerator: converted_user_cnt
    denominator: new_user_cnt
    order_constraint: pay_time >= register_time
    null_policy: denominator_zero_returns_0
    exists_after_anchor_event: true
```

## 输出格式

```yaml
sql_context:
  status: CONTEXT_READY | NEED_USER_CONFIRMATION
  aliases:
    - alias: fl
      table: user_login
      role: fact | dimension | lookup | target
      source_file: "元数据来源"
  fields:
    - id: fl.user_id
      alias: fl
      table: user_login
      column: user_id
      type: bigint
      role: [join_key, metric]
      nullable: false
      source_file: "元数据来源"
  joins:
    - left: fl.user_id
      right: ur.user_id
      type: left
      cardinality: "N:1"
      source_step: S3
  time_windows: []
  metrics: []
  dimensions: []
  filters: []
  outputs: []
  write_intent:
    mode: query_only | insert_into | insert_overwrite
    target_table: "可为空"
    overwrite_confirmed: false
  unresolved: []
```

## 用户可见摘要

除了 YAML，必须输出：

```markdown
## SQL 上下文
### 表别名
| Alias | 表名 | 角色 |
|---|---|---|

### 字段来源
| 字段 | 来源 | 用途 |
|---|---|---|

### Join 关系
| 左字段 | 右字段 | 类型 | 基数风险 |
|---|---|---|---|

### 指标公式
| 指标 | 分子 | 分母 | 空值策略 |
|---|---|---|---|

### 时间窗口
| 字段 | 下界 | 上界 | 边界 |
|---|---|---|---|
```

## 规则

- alias 一旦生成，下游不能重新命名。
- context 中不存在的字段，下游视为不存在。
- join key 只能来自元数据校验和逻辑计划。
- 指标表达式必须能追溯到 logic plan 的 aggregate 步骤。
- 输出列必须来自 `fields`、`metrics` 或明确派生字段。
- 如果 SQL 生成需要新字段，回到 metadata-validator 或 logic-planner。

## 停止条件

只在 alias、字段、join、指标、时间字段、过滤字段、输出列和写入意图都完整时输出 `CONTEXT_READY`。