diff --git a/AGENTS.md b/AGENTS.md index 4d5724e..d17be0c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -673,6 +673,20 @@ docs_v1.0/M4_workspace/YYYY-MM-DD__test_report.md (測試報告) 詳細規範見 `docs_v1.0/M4_workspace/M4_NOTIFICATION_PROTOCOL.md`。 +## UUID Naming Rule + +**Never use bare `uuid` in API route paths, query params, JSON keys, or code variable names. Always qualify:** + +| Context | Must use | Never | +|---------|----------|-------| +| Video/file resource | `file_uuid` | `uuid` | +| Identity resource | `identity_uuid` | `uuid` | +| Query parameter | `file_uuid=`, `identity_uuid=` | `uuid=` | +| Route path | `:file_uuid`, `:identity_uuid` | `:uuid` | +| JSON key | `"file_uuid"`, `"identity_uuid"` | `"uuid"` | + +This applies to docs, code, API responses, and curl examples. Exceptions: internal database primary key names (e.g. `identities.uuid` column). + ## Document Compliance Checklist Before creating any `REFERENCE/*.md` file, verify all items below. @@ -689,6 +703,13 @@ Before creating any `REFERENCE/*.md` file, verify all items below. | 6 | English content | Entire file in English | | 7 | REFERENCE/ path | File must reside under `docs_v1.0/REFERENCE/` | +### P0b — UUID Naming + +| # | Check | Rule | +|---|-------|------| +| 8 | `file_uuid` not bare `uuid` | All file references use `file_uuid` (see UUID Naming Rule above) | +| 9 | `identity_uuid` not bare `uuid` | All identity references use `identity_uuid` | + ### P1 — Suggested (3 items) | # | Check | Note | diff --git a/docs_v1.0/STANDARDS/DOCS_STANDARD.md b/docs_v1.0/STANDARDS/DOCS_STANDARD.md index ebfd2f0..4ee471f 100644 --- a/docs_v1.0/STANDARDS/DOCS_STANDARD.md +++ b/docs_v1.0/STANDARDS/DOCS_STANDARD.md @@ -3,7 +3,7 @@ document_type: "standard_doc" service: "MOMENTRY_CORE" title: "文件創建規範" date: "2026-04-27" -version: "V2.0" +version: "V2.1" status: "active" owner: "Warren" created_by: "OpenCode" @@ -35,11 +35,25 @@ related_documents: --- +## UUID 命名規範 + +API 路徑、查詢參數、JSON key、程式碼變數中**禁止使用裸 `uuid`**: + +| 情境 | 必須使用 | 禁止使用 | +|------|----------|----------| +| 影片/檔案資源 | `file_uuid` | `uuid` | +| 身份資源 | `identity_uuid` | `uuid` | +| 查詢參數 | `file_uuid=`, `identity_uuid=` | `uuid=` | +| 路由路徑 | `:file_uuid`, `:identity_uuid` | `:uuid` | +| JSON key | `"file_uuid"`, `"identity_uuid"` | `"uuid"` | + +例外:資料庫內部 primary key(如 `identities.uuid` 欄位)可保留原名。 + ## 版本歷史 | 版本 | 日期 | 目的 | 操作人 | 工具/模型 | |------|------|------|--------|-----------| -| V1.0 | 2026-03-18 | 創建文件規範 | Warren | OpenCode / MiniMax M2.5 | +| V2.1 | 2026-05-14 | 新增 UUID 命名規範 | M5 | OpenCode | | V2.0 | 2026-04-27 | 添加 AI Agent 友好完整規範(10.6-10.12) | OpenCode | GLM-5 | ---