ent-seed-sql-generator

Ent 种子 SQL 生成器

从 Ent schema 和混合证据生成一份可执行的种子 SQL 文件，包含确定性 ID、有效的关系和贴近生产环境的真实数据。写入 SQL 前，先确认生成计划，以便及早发现方言、策略和范围不匹配的问题，避免白费功夫。

在与用户确认方言、策略、实体范围和大致行数（或根据证据确定这些信息）之前，**不要编写任何 SQL**。方言假设错误会使每一行都失效；策略选择错误则会导致返工。

触发条件 / 不适用场景

当任务是根据 Ent schema 上下文、文档、演示行为或提示词要求生成或修改种子 SQL 时，使用此技能。

不要将此技能用于 schema 迁移设计、运行时仓库/服务实现或查询性能调优。

参考资料加载计划

仅加载当前任务所需的资料：

• references/model-extraction.md：实体、字段和关系提取及依赖规划
• references/id-and-relation-rules.md：确定性 ID、外键完整性、多租户约束
• references/output-sql-pattern.md：最终 SQL 布局及特定策略的模式
• references/password-hashing.md：仅在填充凭据字段时使用

检查清单

按以下顺序逐项处理。为每项创建一个任务。

1. 收集输入 — 提示词、Ent schema 文件、现有种子数据、产品文档
2. 检测方言并消除歧义 — 如有不明确之处，一次只问一个问题
3. 展示生成计划 — 实体、策略、行数；获取批准
4. 构建 schema 映射 — 依赖顺序、外键图、枚举值
5. 生成 SQL 文件 — 遵循 output-sql-pattern.md
6. 执行质量检查 — 孤立外键、唯一性冲突、必填字段缺失

流程图

digraph ent_seed_sql_generator {
    "Collect inputs" [shape=box];
    "Any ambiguities?" [shape=diamond];
    "Ask clarifying question\n(one at a time)" [shape=box];
    "Present generation plan" [shape=box];
    "Plan approved?" [shape=diamond];
    "Build schema map\n& dependency order" [shape=box];
    "Generate SQL artifact" [shape=box];
    "Quality gates" [shape=box];
    "Deliver artifact" [shape=doublecircle];

    "Collect inputs" -> "Any ambiguities?";
    "Any ambiguities?" -> "Ask clarifying question\n(one at a time)" [label="yes"];
    "Ask clarifying question\n(one at a time)" -> "Any ambiguities?";
    "Any ambiguities?" -> "Present generation plan" [label="no"];
    "Present generation plan" -> "Plan approved?";
    "Plan approved?" -> "Present generation plan" [label="revise"];
    "Plan approved?" -> "Build schema map\n& dependency order" [label="yes"];
    "Build schema map\n& dependency order" -> "Generate SQL artifact";
    "Generate SQL artifact" -> "Quality gates";
    "Quality gates" -> "Deliver artifact";
}

阶段 1：收集输入并澄清

按以下顺序收集可用输入：

1. 当前提示词要求
2. Ent schema 和迁移/DDL 文件（ent/schema/*.go、ent/migrate/）
3. 现有种子文件和演示代码行为
4. 产品文档和领域说明

然后检测 SQL 方言：

• 检查 ent/client.go 或配置中的驱动名称（mysql、postgres、sqlite）
• 查看迁移文件中的方言特有语法
• 检查 go.mod 中的方言导入（ent/dialect/mysql 等）

如果阅读现有输入后仍有以下任何内容不明确，请一次只问一个问题：

• 方言：「我无法从项目文件中确定数据库方言。你的目标是 MySQL、PostgreSQL 还是 SQLite？」
• 策略：「这个种子数据应采用一次性方式（仅用于全新部署）、幂等方式（INSERT OR IGNORE / ON CONFLICT DO NOTHING），还是 upsert（ON CONFLICT DO UPDATE）？」
• 范围：「应为所有实体填充种子数据，还是仅填充特定子集？如果是子集，请说明具体实体。」
• 行数：「每个实体需要多少行？（开发用种子数据通常为 3–10 行）」

不要询问可从现有文件中找到答案的问题。只询问确实会影响输出的问题。

阶段 2：生成计划

编写 SQL 前，先展示简洁的计划：

方言： MySQL 策略： 幂等 实体顺序（按依赖关系排列）：

1. organizations — 3 行，无依赖
2. users — 5 行，外键 → organizations
3. projects — 4 行，外键 → organizations + users

ID 范围： organizations 2000–2999，users 1000–1999，projects 3000–3999 假设： 密码字段将使用固定的 bcrypt 哈希作为测试凭据

这样可以吗？确认后我再开始编写。

根据任务复杂度调整计划。对于没有外键的单个实体，一行摘要即可。对于包含许多表的多租户系统，应列出完整的依赖顺序。

阶段 3：构建架构映射

计划获批后，阅读 references/model-extraction.md，并从 ent/schema/*.go 中提取：

• 字段：类型、Optional、Nillable、Unique、Default、Immutable、Sensitive
• 枚举：field.Enum 或 validate 规则中的所有有效值
• 边：edge.To、edge.From、Required、Unique、Ref — 推导外键归属
• 索引：唯一约束和复合索引

计算拓扑依赖顺序：没有外键引用的表优先，依赖表随后。联接表最后处理。

阶段 4：生成 SQL 工件

遵循 references/output-sql-pattern.md。应用 references/id-and-relation-rules.md 中的 ID 范围和外键完整性规则。

ID 分配：

• 整数主键：为每种实体类型使用互不重叠的范围
• 字符串主键：使用语义化 ID（usr_admin、org_acme）
• UUID：根据业务键确定性生成，绝不随机生成

数据一致性：

• 时间戳：created_at <= updated_at，并分布在合理的时间范围内
• 状态流转：符合实际生命周期（draft → active → archived）
• 所有权：每个 owner_id 都引用现有的用户行
• 文本内容：使用有意义的字符串，而非 Lorem Ipsum；采用真实的电子邮件格式

对于凭据字段，请阅读 references/password-hashing.md。

特定方言的模式：

类型	PostgreSQL	MySQL	SQLite
JSON	'{"k":"v"}'::jsonb	'{"k":"v"}'	'{"k":"v"}'
数组	ARRAY['a','b']	不支持原生类型	不支持原生类型
布尔值	TRUE/FALSE	1/0	1/0
时间戳	'2026-01-01 09:00:00'	'2026-01-01 09:00:00'	'2026-01-01 09:00:00'

需内联处理的特殊情况：

• 软删除：将活动记录的 deleted_at 设为 NULL
• 自引用（树结构）：先插入根记录，子记录引用有效的父级 ID
• 多租户：先填充租户表；所有依赖表都必须包含有效的租户外键
• 复合唯一约束：验证所有行中的列组合均唯一

阶段 5：质量检查

交付前，请验证：

• 没有孤立外键 — 每个被引用的 ID 都存在
• 没有违反唯一约束 — 包括复合唯一索引
• 没有占位符或 TODO 值
• 所有 ID 都是确定性的（没有随机或自动生成的值）
• 时间戳内部一致（created_at <= updated_at）
• 每个 INSERT 都包含所有必填字段（Ent 架构中的 Required()）
• 没有无效的枚举值
• JSON 列包含有效的 JSON 字符串

输出约定

恰好交付一个 SQL 工件（根据用户要求内联提供或以文件形式提供），包含：

1. 头部注释：输入来源、方言、策略、假设
2. 可选的清理块（仅适用于幂等或 upsert 策略）
3. 按依赖顺序分组的 INSERT 块，每组前有注释
4. 可选的验证 SELECT 查询（仅在用户要求时提供）

防护准则

• 绝不在缺乏依据时臆造表或列 — 将推断内容标注为注释
• 绝不使用随机 ID — 种子 ID 必须在多次运行中保持稳定
• 绝不打乱外键依赖顺序 — 父表优先于子表，联接表最后处理
• 绝不让行数膨胀 — 每个核心表通常 3–10 行就足够
• 绝不暴露生产凭据 — 仅使用测试值
• 绝不在一个文件中混用多种方言
• 绝不遗漏必填字段

相关技能

• 上游 — ent-schema-implementer 提供 ent/schema/*.go，这是主要输入；如果尚未编写 schema，则由 db-schema-designer 提供 prd/DDL.md。如果两者都不存在，请依据用户提供的 schema 证据开展工作，而不要臆造表。
• 下游 — 无；SQL 产物是终端产物。如果需要处理的是运行时服务代码，而非数据，请使用 sphere-feature-workflow。
• 边界 — 使用 db-schema-designer 进行 schema 和迁移设计；此技能仅负责确定性的种子数据和 fixture SQL。
• 配套技能 — 无。
• 如果本次会话未安装所引用的技能，请在交接消息中注明其名称，并继续处理当前产物；不要因此停滞。