shanxi-resilience-sql-generator

name	shanxi-resilience-sql-generator
description	陕交控项目专用SQL生成工具 - 按照项目规范生成DDL/DML/SQL检查语句，支持数据仓库分层（DIM/DWD/DWS/ADS），自动添加中文注释和版本字段

陕交控项目SQL生成工具

专门用于陕交控多路段改扩建韧性提升项目的SQL生成工作。

前置必读

执行本 Skill 前，必须先阅读 docs/数据表说明.md，该文件是本项目所有数据库表的权威说明，包含：

• 表清单总览（分层、记录数、简介）
• 各表数据字典（字段名、类型、可空、描述）
• 唯一约束与主键定义
• 查询示例与索引设计
• 版本管理规则（version_yyyymm）
• source_flag 枚举值

编写 DML/检查 SQL 时，禁止凭记忆假设表结构或字段名，必须以 docs/数据表说明.md 中的数据字典为准。新建表时同步更新该文件。

核心功能

1. DDL 生成

自动生成建表语句：

• DIM 层维表
• DWD 层明细表
• DWS 层汇总表
• ADS 层应用结果表
• 版本配置表

2. DML 生成

生成数据加工SQL：

• 按模块（M0-M5）组织
• CTE 分步计算
• 参数化查询
• 数据质量检查

3. 检查SQL生成

生成数据验证SQL：

• 主键唯一性检查
• 必填字段非空检查
• 枚举值范围检查
• 业务逻辑验证

4. SQL 模板

提供标准SQL模板：

• 版本化数据查询
• 时间口径统计
• 空间查询（PostGIS）
• 溯源标记（source_flag）

SQL 头部注释模板

-- ============================================================
-- M{N}: {SQL 文件功能描述}
-- ============================================================
-- 作用: {这个 SQL 做什么}
-- 输入表: {依赖的表名列表}
-- 输出表: {写入的表名}
-- 粒度: {一行代表什么，例如 section_id × day}
-- 关键字段: {关键字段列表，例如 section_id, day, ...}
-- ============================================================

数据仓库分层规范

DIM 层（维表层）

CREATE TABLE IF NOT EXISTS dim_{name} (
    {id} varchar(20) NOT NULL,
    {attributes} ...,
    source_flag varchar(16) DEFAULT 'actual',
    created_at timestamp DEFAULT CURRENT_TIMESTAMP,
    updated_at timestamp DEFAULT CURRENT_TIMESTAMP,
    CONSTRAINT pk_dim_{name} PRIMARY KEY ({id})
);

DWD 层（明细事实层）

CREATE TABLE IF NOT EXISTS dwd_{name} (
    {id} varchar(20) NOT NULL,
    version_yyyyMM varchar(6) NOT NULL,
    {attributes} ...,
    source_flag varchar(16) DEFAULT 'actual',
    created_at timestamp DEFAULT CURRENT_TIMESTAMP,
    updated_at timestamp DEFAULT CURRENT_TIMESTAMP,
    CONSTRAINT pk_dwd_{name} PRIMARY KEY ({id}, version_yyyyMM)
);

DWS 层（汇总事实层）

CREATE TABLE IF NOT EXISTS dws_{name} (
    {dimension_keys} ...,
    {metrics} ...,
    source_flag varchar(16) DEFAULT 'computed',
    created_at timestamp DEFAULT CURRENT_TIMESTAMP,
    updated_at timestamp DEFAULT CURRENT_TIMESTAMP,
    CONSTRAINT pk_dws_{name} PRIMARY KEY ({dimension_keys})
);

ADS 层（应用结果层）

CREATE TABLE IF NOT EXISTS ads_{name} (
    {key} ...,
    {results} ...,
    scheme_id varchar(64) NOT NULL,
    source_flag varchar(16) DEFAULT 'computed',
    created_at timestamp DEFAULT CURRENT_TIMESTAMP,
    CONSTRAINT pk_ads_{name} PRIMARY KEY (scheme_id, {key})
);

关键字段命名规范

字段名	说明
section_number	同一单一路径上的收费单元归属同一编号
scheme_id	施工方案 ID
section_id	收费单元 ID
od_id	OD 对 ID
path_id	路径 ID
version_yyyyMM	版本年月（YYYYMM）
source_flag	数据来源标识

SourceFlag 枚举值

值	说明
actual	真实采集数据
filled	统计补全数据
rule	规则生成数据
api	外部接口数据
computed	计算派生数据

使用示例

生成 DDL

skill: shanxi-resilience-sql-generator
args: "ddl --layer dwd --name toll_station --pk 'id,version_yyyyMM'"

生成 DML

skill: shanxi-resilience-sql-generator
args: "dml --module m1 --input dwd_toll_station --output dws_section_capacity"

生成检查SQL

skill: shanxi-resilience-sql-generator
args: "check --table dwd_toll_station --pk 'id,version_yyyyMM'"

索引创建规范

常用索引

• 版本字段：idx_{table}_version
• 类型字段：idx_{table}_type
• 状态字段：idx_{table}_status
• 时间字段：idx_{table}_day
• 外键字段：idx_{table}_{fk_column}

索引示例

CREATE INDEX IF NOT EXISTS idx_dwd_toll_station_version ON dwd_toll_station(version_yyyyMM);
CREATE INDEX IF NOT EXISTS idx_dwd_toll_station_type ON dwd_toll_station(TYPE);
CREATE INDEX IF NOT EXISTS idx_dwd_toll_station_status ON dwd_toll_station(status);

数据质量检查SQL模板

主键唯一性检查

SELECT {pk_columns}, COUNT(*) AS cnt
FROM {table_name}
GROUP BY {pk_columns}
HAVING COUNT(*) > 1;

必填字段非空检查

SELECT
    COUNT(*) FILTER (WHERE {column1} IS NULL) AS null_{column1},
    COUNT(*) FILTER (WHERE {column2} IS NULL) AS null_{column2}
FROM {table_name};

枚举值范围检查

SELECT DISTINCT {column}
FROM {table_name}
WHERE {column} NOT IN ('{value1}', '{value2}', ...);