# DMK 项目代码生成阶段执行 SOP (v6.1 全量契约对齐版)

## 一、 执行总纲
本 SOP 指导智能体将 `target_table_skills/` 逻辑转化为生产脚本。执行过程必须严格遵循“业务逻辑服从 Skill，技术结构服从应用层 DDL”的原则。

## 二、 强制参考文档矩阵 (Source of Truth)
| 文档名称 | 角色 | 查阅时机 |
| :--- | :--- | :--- |
| **`target_table_skills/*.md`** | **业务图纸** | 核心字段映射、计算原语、计算侧分工依据。 |
| **`POC-TSG...DDL(1).sql`** | **技术契约** | **终极标准**。建表结构、字段名、类型必须与之 100% 对齐。 |
| **`specs/openspec.md`** | **项目宪法** | 校验 UNION 策略、HLL 去重等全局硬约束。 |
| **`ods/基础信息语义统一.md`** | **标准词典** | 核实 ODS 原始字段名（特别是 4/5G 差异）。 |

## 三、 输出物标准规范 (Standard Deliverables)
每张表在 `src/<表名>/` 目录下必须产出：
1. **`DDL.sql`**: PG 建表语句（含 Schema 前缀）。必须与 `POC-TSG...sql` 结构完全一致。
2. **`compute.sql`**: 核心逻辑。严禁 `SELECT *`，统一缺省值 `-1`。
3. **`sync.sh` (标准 Linux Bash 范式)**:
   ```bash
   #!/bin/bash
   # 配置区
   SCHEMA="${SCHEMA:-dmk}"
   HDFS_ROOT="${HDFS_ROOT:-/user/hive/warehouse}"
   LOCAL_DIR="/tmp/dmk_sync"
   # 计算 (Hive -e) -> 提取 (hdfs getmerge) -> 加载 (psql copy)
   ```
4. **`README.md`**: 包含前置依赖、验收查询 SQL。

## 四、 质量门禁规范 (Quality Gates)

### 4.1 单表生成自检
- [ ] **契约校验**: 字段名、类型、主键必须与 `POC-TSG...sql` 100% 匹配。
- [ ] **COUNT 校验**: 必须包含 `SELECT COUNT(*)` 确认数据非空。
- [ ] **非空校验**: 核心主键与指标字段不可全为 NULL。
- [ ] **HLL 校验**: `indoor_flag = -1` 时确认使用 HLL 去重。

### 4.2 阶段间验收标准
| 阶段 | 验收标准 | 验证方法 |
| :--- | :--- | :--- |
| **L1: 空间基准与桥接层** | `td_grid` 空间覆盖完整 | 抽查 grid 边界与楼宇 AOI 关联 |
| **L2: 核心事实层** | 小区-网格关系正确 | 对比原始 ODS 采样点分布 |
| **L3: 多维聚合层** | 楼宇/区域覆盖率准确 | 与栅格明细层累加结果对比 |

## 五、 异常处理与回滚决策矩阵

| 失败场景 | 处理机制 | 重试/回滚策略 |
| :--- | :--- | :--- |
| DDL 创建失败 | 检查字段类型、长度、保留字 | 修正并对照应用层契约重试 |
| SQL 逻辑错误 | 报备并回滚该表数据 | 执行 `TRUNCATE TABLE ${SCHEMA}.${TABLE}` |
| 同步脚本失败 | 检查网络/HDFS路径 | 重跑 `sync.sh` |
| 依赖不就绪 | 立即停止，溯源前置任务 | 待前置表验收通过后再启动 |

**熔断信号**：连续 3 张表执行失败，或发现违反 `openspec.md` 硬约束，必须立即终止生成并报告。

## 六、 阶梯式执行序列 (Dependency Sequence)
1. **Level 1 (空间基准与桥接层)**: `td_grid` -> `td_building_grid_m` -> `tm_scene_grid_coverage_m`
2. **Level 2 (核心事实与明细层)**: `tm_grid_coverage_m` -> `td_building_cell_m` -> `tm_cell_grid_coverage_m` -> `tm_building_user_wifi_m`
3. **Level 3 (多维聚合与专题分析层)**: `tm_building_coverage_m` -> `tm_region_coverage_m` -> `tm_scene_coverage_m` -> `tm_cluster_area_m`

## 七、 禁止行为
- ❌ 严禁在没有读取应用层 DDL 的情况下自行定义表结构。
- ❌ 严禁混用 4/5G 的 ODS 原始采样指标字段。
- ❌ 严禁使用 Windows 风格的路径或命令。

---
**版本：v6.1 (全量契约对齐版)**
**日期：2026-05-03**