admin/momentry_core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add UUID naming rule to AGENTS.md + DOCS_STANDARD.md — never bare uuid, always file_uuid/identity_uuid

Browse Source
This commit is contained in:
Accusys
2026-05-14 17:40:18 +08:00
parent 8608d38548
commit 1319eecc71
2 changed files with 37 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
AGENTS.md
View File

@@ -673,6 +673,20 @@ docs_v1.0/M4_workspace/YYYY-MM-DD_<topic>_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 |

18
docs_v1.0/STANDARDS/DOCS_STANDARD.md
View File

@@ -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 |
---