ctc_poc2026/code_generation_sop.md

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 范式):

   #!/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