| name | aibdd-form-ddl-spec |
| description | 從推理包翻譯為 SQL DDL（MySQL `.mysql.sql` / PostgreSQL `.pg.sql` / MSSQL `.mssql.sql`）。 負責各方言 DDL 語法規章 + 歸檔。dialect 由 `target_path` 副檔名 SSOT， 不做跨 boundary 決策；路徑 / 切檔策略 / dialect 選擇由 Planner 透過 DELEGATE 參數指定。
|
| user-invocable | false |
§1 角色
Formulation skill。綁定 DSL = SQL DDL，支援三種方言：
| 副檔名 | Dialect | 對應 parser |
|---|
*.mysql.sql | MySQL | MySQLSpecParser |
*.pg.sql | PostgreSQL | PostgresSpecParser |
*.mssql.sql | Microsoft SQL Server | MSSQLSpecParser |
被多個 Planner DELEGATE（如 aibdd-system-analysis 之 sub-boundary state schema）。Planner 在 DELEGATE payload 內提供具體 target_path（含副檔名），本 skill 由副檔名 SSOT dialect、不自決。
下游 dsl_cli 的 spec parser 會把 DDL 解析為 TablePart / RefPart，與 DBML 共用同一份 Part 形狀 — 因此 boundary 的 part_to_dsl.py plugin 不需要因 dialect 而調整。
§2 入口契約
接收推理包：
| 項目 | 內容 |
|---|
| M/D/C 變更集 | Entity / Attribute / Relationship / AggregateHint 的增刪改 |
| Axis 單位對應 | 推理包中每個單位的具體對應 |
| CiC 記號清單 | 便條紙（GAP / ASM / BDY / CON）+ 錨點 |
| 退出狀態 | Reason 步是否完整通過 |
target_path | Planner 指定之相對於 ${DATA_DIR} 的檔案路徑，必須以 .mysql.sql / .pg.sql / .mssql.sql 結尾（例：domain.mysql.sql、<boundary-id>/states/<state>.pg.sql；切檔策略由 Planner 決定）。不得含 <<NN-functional-module>> 借位子層 — ${DATA_DIR} 在 SSOT 已是 flat directory（見 aibdd-core::spec-package-paths.md），functional module 借位只允許出現在 ${TRUTH_BOUNDARY_PACKAGES_DIR} 子樹。 |
Dialect SSOT：dialect 完全由 target_path 副檔名決定；Planner 不另傳 dialect 欄位，本 skill 也不另寫入 dialect 識別字到檔案中。
缺項：推理包不完整、target_path 未指定、或副檔名非三者之一 → 回退呼叫 Planner 補齊。
§3 Formulate SOP
- 判定 dialect：讀
target_path 副檔名 → mysql / pg / mssql。
- 讀取 format reference：
references/format-reference.md（共通 SQL DDL 語法 + 三方言型別 / 自增 / 約束對照）
- 展開 DDL 結構：從推理包的 Entity / Relationship 展開為
CREATE TABLE / 表級 FOREIGN KEY / inline REFERENCES（僅 PG）
- 套用 patterns：讀
references/patterns/naming-rules.md
- 保留 CiC：推理包中的便條紙 inline 到 DDL 註解（
-- CiC(<KIND>): ... 或行尾 -- ...）
- 寫檔前 ASSERT：
target_path 不得含 <<NN-functional-module>> 借位子層；target_path 副檔名必為 .mysql.sql / .pg.sql / .mssql.sql；- 任一違反 → STOP 並回退 Planner 補正（白話文回報具體違反項）。
- 寫檔前 dialect 自查：以 §3 判定的 dialect 對照 §4 表，確認未使用其他方言獨有語法（如 PG 檔不應出現
AUTO_INCREMENT、MSSQL 檔不應出現 SERIAL）。違反 → 改寫為當前 dialect 的對等語法。
- 寫檔：依
target_path 寫出（落點＝${DATA_DIR} ⊕ target_path）。
- 機械驗證：呼叫
scripts/check_sql_syntax.py <寫出檔> 確認語法合法 + dialect 自洽。
§4 DSL 最佳實踐
命名規則
- Table：
snake_case 複數（lesson_progresses）
- Column：
snake_case（user_id）
- FK constraint：
FK_<from_table>_<to_table>（具名）或匿名（MySQL/MSSQL 允許）
- PK constraint：
PK_<table>（MSSQL/PG 偏好具名）；MySQL 可用 inline PRIMARY KEY
- Planner 傳入 prefix 時套用在 Table 名前
Dialect 自增主鍵（最常見差異）
| 方言 | 慣用寫法 |
|---|
| MySQL | id INT NOT NULL AUTO_INCREMENT, PRIMARY KEY (id) |
| PG | id SERIAL PRIMARY KEY 或 id INT GENERATED ALWAYS AS IDENTITY PRIMARY KEY |
| MSSQL | id INT IDENTITY(1,1) NOT NULL, CONSTRAINT PK_<table> PRIMARY KEY (id) |
Schema modularization
- 切檔策略由 Planner 決定（domain = 單檔；state = per-boundary / per-sub-boundary）
- 跨檔 FK 在 SQL DDL 中無語法支援；若 Planner 指定多檔，同一 referential 路徑下的 FK 雙端必須在同一檔，否則 STOP 並回退 Planner 補正
- 本 skill 只負責在指定 path 寫出合格 DDL
Aggregate Hint
- 用 SQL 行尾註解
-- aggregate_root 標記 aggregate root table
- AggregateHint 不改 Table 結構，只加註解
CiC 註解
- 行尾：
-- CiC(<CATEGORY>): ...（CATEGORY ∈ GAP / ASM / AMB / CON）
- 完整格式定義見
aibdd-form-activity::references/cic-format.md
§5 匯報
以白話文 1–3 句匯報（依 aibdd-core::planner-contract.md §REPORT 匯報；不輸出 JSON / YAML）：
Form DDL Spec 完成。產出 N 個 <dialect> DDL 檔案。{若有便條紙則加「尚有 N 張便條紙待釐清」；無則省略}
§6 參考
- references/format-reference.md：共通 SQL DDL 語法 + 三方言型別 / 自增 / 約束對照
- references/patterns/naming-rules.md：Table / Column / Constraint 命名 + Strategy Guard
- scripts/check_sql_syntax.py：語法 / FK / dialect 一致性機械驗證
