语义数据库设计
多平台 Agent Skill。本文件只放工作流与硬约束；细则按需打开下表文档，勿把本文件写长。
阅读路径（入门 → 深入）
- 本页：模式分流、默认约定、硬约束、自检
- 对照样例：E01 PostgreSQL → MySQL / GaussDB
- 细则按需：reference.md
- 评测：examples.md 回归 T01–T17
- 疑难：FAQ.md
| 文档 | 内容 |
|---|---|
| reference.md | 命名、类型映射、方言、SQL 注释、落盘、DESIGN 模板、关系/级联/索引、表格批量 |
| glossary/ | _common + 电商/OA/物联网/物流/财务/银行/AI 等行业词表 |
| examples.md | 端到端示例 + 多方言对照 + 表格批量 + 回归 T01–T17 + 验收清单 |
| examples/DESIGN.template.md | 完整 Mode A 设计说明可复制骨架 |
| FAQ.md | 常见问题、禁忌、验收验证路径（短答 + 深链） |
| 层 | 默认风格 | 示例 |
|---|---|---|
| glossary 推荐字段名 | snake_case | product_name、created_at、amount_excluding_tax |
| 库表 / 列 | snake_case | 通常与推荐名相同 |
命中词表后推荐名可直接作列名。用户输入 camelCase/PascalCase 英文时须转为 snake_case（除非用户禁止）。交付 DESIGN.md 必须含「语义 / 推荐名 / DB」对照。禁止在同一 DDL 文件内混用 camelCase 列名（用户明确要求除外）。
术语加载：先 glossary/_common，再加载已识别或用户声明的行业表（见 glossary/README.md）。
模式分流
| 用户信号 | 模式 | 产出 |
|---|---|---|
| 设计库表 / 语义→DDL / 建表 | A | 完整 schema.sql + DESIGN.md（默认落盘） |
| 评审 / 规范化已有 DDL | B | 规范化 DDL + 差异说明（不静默改业务含义） |
| Excel / CSV / 粘贴表格批量建表 | 表格→按实体聚合→A | 合并进同一完整 schema |
| 一并给出 ER | A + ER（或批量后再 ER） | 同上 + er.mmd |
| 「只要片段」 | A 覆盖 | 单表/局部 DDL（不强制更新整库权威文件） |
B 不重写业务含义（除非用户明确要求改结构）。
落盘 / 追加 / 方言：reference §完整 Schema 与文件生命周期 · §方言档案。
表格规则：reference §表格批量建表。
默认约定（未说明时采用）
| 项 | 默认 |
|---|---|
| 方言 | PostgreSQL（一等支持 MySQL、GaussDB=openGauss/base=postgresql） |
| 产出范围 | 仅用户点名的一种方言（未点名 → PostgreSQL） |
| 落盘 | database/schema.sql + database/DESIGN.md |
| ER | 用户要求时写 database/er.mmd |
| 追加 | 已有文件则合并新表；同名表禁止静默覆盖；禁止同一文件混写多方言 |
| 表名 / 列名 | snake_case（表名倾向复数或集合名，如 products） |
| 主键 | id（类型随方言：PG/Gauss BIGSERIAL；MySQL BIGINT AUTO_INCREMENT；可改 UUID） |
| 关联列 | <entity>_id |
| 外键关联模式 | logical（主外键不强制；无库级 FOREIGN KEY/REFERENCES）。用户点名强制 → enforced |
| SQL 注释 | 必须：表 + 每列方言原生 COMMENT；文件头 -- 元信息保留但不替代。reference §SQL 注释 |
| 审计列 | created_at / updated_at（可声明不要） |
| 软删 | 用户要求时加 deleted_at |
| 用户英文 | camelCase/PascalCase 必转 snake_case（已是 underscore 则保留），对照写入 DESIGN |
| 表格批量 | 按逻辑列映射；按实体聚合；row=<n> 追溯；单行失败默认继续并汇总 |
覆盖：「只要片段」「MySQL」「GaussDB」「UUID 主键」「不要审计列」「强制外键 / 逻辑外键」「写入其他路径」「遇错即停」等。
硬约束（评测失败点）
- 关键三件套：至少识别一个实体；主键策略（或接受默认）；关系意图（或明确无跨表关系）。缺失时：追问，或交草案并标「待确认假设」——禁止静默臆造复杂 ER。
- 术语：查 glossary（
_common→ 行业表）；推荐名为 snake_case；禁拼音作标识符；实体相关列用实体前缀（product_name，不用裸name除非确为通用）。 - 命名风格：库内 snake_case；表名默认复数/集合义；交付必须含语义↔推荐名/列名对照。reference §命名规则
- 方言：仅输出当前选定的一种方言；
gaussdb必须声明base=postgresql；禁止将「GaussDB MySQL 兼容」静默当成 PG 或 MySQL 交付。 - 生命周期：默认完整 DDL+DESIGN 落盘/追加；同名表禁止静默覆盖；同一权威文件禁止混方言；换方言须确认整文件重写或改路径；交付含文件路径与 dialect（Gauss 含 base）；完整 A 的 DESIGN 须符合固定章节模板（见 reference §设计说明模板）。
- 表格批量：每一数据行独立解析后按实体聚合；标注
row=<n>；缺必填且无法推断 → 记录失败、默认继续并汇总；禁止整表当一条未分行语义。 - 关系 / 外键模式 / 级联 / 索引：默认
fk_mode=logical（有关联列+索引，无库级 FK）；仅用户要求强制时用enforced；整次交付统一模式，禁止静默混用；自引用与可选关联按语义可空；默认不写ON DELETE/UPDATE CASCADE；禁止默认多态；关联列/唯一默认建索引，复合索引须有查询或联合唯一语义。reference §关系与索引 - SQL 注释：新建表与列必须有方言原生注释（PG/Gauss：
COMMENT ON；MySQL：建表内COMMENT）；禁止仅用--行注释冒充；索引默认不强制。reference §SQL 注释 - 边界：不实现 ORM 代码生成、不连库执行迁移、不做数据回填、不做内置 xlsx 解析。越界请求说明边界并拉回 DDL/设计说明。
输入
关键（缺则追问/标待确认）： 实体、主键策略（或默认）、关系意图（或单表）。
常用可选： 属性与约束、方言（postgresql / mysql / gaussdb）、外键模式（强制/不强制）、UUID、软删、不要审计列、只要片段、写入路径、要 ER、领域。
表格逻辑列： 模块（可选）、实体名称（必填）、属性/字段说明、类型、约束、关系。见 reference；模板 examples/entity-attribute-table-template.csv。
澄清约定（可靠性）
- 关键缺失：优先同一轮合并列出所需问题，或交草案并写入 DESIGN「待确认」。
- 用户已回答后：禁止用同一问题无新信息地反复追问。
- 非关键：采用默认约定，写入 DESIGN「假设」。
- 仍须遵守硬约束「关键三件套」——禁止为少追问而静默臆造复杂 ER。
失败 / 越界提示格式
冲突、越界或自检失败时，回复须含：
- 原因（一两句）
- 下一步（至少一条可执行选项，如：确认覆盖 / 改路径 / 补关系 / 改用
mysql）
禁止只说「失败」「不行」而无下一步。常见冲突见 FAQ。
流程
A → DDL + DESIGN
- 分流意图（A / B / ER / 表格批量 / 只要片段）；解析方言档案与目标路径。reference §方言档案
- 澄清关键缺失；非关键用默认并标注假设。表格：先映射列，按行解析，再按实体聚合。
- 术语 → 查 glossary（
_common→ 行业表）得 snake_case 推荐名 并采用。reference §命名 · glossary/README - 建模 → 表、列、PK、关联列、唯一/非空；解析
fk_mode（默认 logical）；关系（1:N / N:M→关联表）。reference §关系与索引 - 类型 → 语义→所选方言类型（Gauss：先 PG 再差异补丁）。reference §类型映射
- 注释 → 为每个新建表/列写方言原生 COMMENT。reference §SQL 注释
- 落盘 / 追加 → 写入或合并
database/schema.sql；更新DESIGN.md；同名表或方言冲突则询问。 - 可选 ER →
database/er.mmd。 - 交付（见下）。
表格批量 → 聚合 → A
- 识别表头 → 逻辑列；无法识别则请用户映射。
- 按行校验；失败行记录并（默认）继续。
- 按
entityName聚合属性/关系 → 多实体语义块。 - 进入 Mode A；合并进同一权威文件；DESIGN 含
row=追溯与失败汇总。
细节：reference §表格批量建表。
B → 评审 / 规范化
输入：用户粘贴的 DDL 或工作区已有 schema.sql。
产出：规范化 DDL（或差异说明）+ 变更列表。禁止静默删除用户已声明的业务列。评审时识别或询问方言，避免用错语法习惯纠正。
交付物（最小集）
A（默认）： 已写入目标文件的 DDL（含表/列 COMMENT）+ DESIGN.md（须含模板章节：元信息/dialect（gaussdb 含 base=postgresql）、fk_mode、实体一览、命名对照、关系、假设、待确认、非目标）。骨架：examples/DESIGN.template.md。
A + ER： 另含 er.mmd。
A（只要片段）： 局部 DDL（片段内表/列仍须注释）+ 短说明（可不更新权威整库文件；不强制完整模板，须标明片段）。
表格批量： 同一完整文件；DESIGN 另含批量表设计摘要；按实体/row=<n>；文末失败行汇总（若有）。
B： 规范化结果 + 与原文差异（可指出缺 COMMENT）。
自检（交付前）
- [ ] DDL 可执行于声明方言（语法层面）；关键三件套已定或已标待确认
- [ ] 表/列 snake_case；语义↔推荐名有对照；术语已经 glossary（推荐名为 underscore）
- [ ] 方言已声明；Gauss 含
base=postgresql；未混写多方言；未静默冒充 Gauss MySQL 兼容 - [ ] PK/关联列/唯一合理；
fk_mode已声明且与 DDL 一致（logical 无库级 FK；enforced 有）；未过度索引；审计列符合约定；无默认 CASCADE；未默认多态；未静默混用模式 - [ ] 每个新建表与列均有方言原生 COMMENT（非仅
--行注释）；注释与 DESIGN 对照不矛盾 - [ ] 默认已落盘或已追加；同名表未静默覆盖；交付含路径与 dialect
- [ ] 完整 A：DESIGN 含元信息（含
fk_mode）、实体一览、命名对照、关系、假设、待确认、非目标（见模板） - [ ] 若表格批量：未整表当一条语义；有
row=追溯；失败行已汇总（若有）；含批量表设计摘要 - [ ] 未越界承诺连库执行 / ORM 工程 / 生产迁移 / 内置 xlsx 解析
失败则修复或说明，禁止交付错误 DDL 却声称已定稿。
验收验证路径
| 层级 | 手段 |
|---|---|
| 交付前 | 上方自检清单（语法层面可执行于声明方言） |
| 人工评测 | examples.md 回归 T01–T17 + E01 多方言样例 |
| 不做 | 连库执行迁移、内置「已在库跑通」证明（有意边界） |
详见 FAQ · 如何验收。
评测入口：examples.md §回归用例集（T01–T17）。
