docs: file_uuid generation rules for M4

docs_v1.0/STANDARDS/USER_DOCS_STANDARD.md

@@ -0,0 +1,372 @@
+---
+document_type: "standard_doc"
+service: "MOMENTRY_CORE"
+title: "使用者文件創建規範"
+date: "2026-05-17"
+version: "V1.0"
+status: "active"
+owner: "M5"
+created_by: "OpenCode"
+tags:
+  - "docs-standard"
+  - "user-docs"
+  - "api-reference"
+  - "demo-guide"
+  - "troubleshooting"
+ai_query_hints:
+  - "查詢 USER_DOCS_STANDARD.md 的內容"
+  - "如何撰寫使用者文件"
+  - "端點文檔模板格式"
+  - "curl 範例規範"
+  - "使用者文件檢查清單"
+related_documents:
+  - "STANDARDS/DOCS_STANDARD.md"
+  - "GUIDES/API_ENDPOINTS.md"
+  - "GUIDES/Demo_EndToEnd.md"
+  - "REFERENCE/API_ERROR_CODES.md"
+---
+
+# 使用者文件創建規範
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-17 |
+| 文件版本 | V1.0 |
+| 狀態 | Active |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-05-17 | 定義使用者文檔的建立標準與模板 | OpenCode | DeepSeek V4 Flash |
+
+---
+
+## 定位
+
+本文檔是 `DOCS_STANDARD.md` 的**補充**，專門規範**使用者導向文件**（User-facing documentation）的內容標準。
+
+`DOCS_STANDARD.md` 已定義的規則（YAML Frontmatter、檔案命名、格式標準、版本歷史）不在此重複，本規範僅聚焦於使用者文檔特有的要求。
+
+---
+
+## 1. 文件分類
+
+| document_type | 中文說明 | 適用場景 | 存放目錄 |
+|---------------|----------|----------|----------|
+| `user_manual` | 使用手冊 | 系統操作、完整功能說明 | `GUIDES/` |
+| `quick_start` | 快速入門 | 最小啟動流程、幾分鐘即可完成 | `GUIDES/` |
+| `demo_guide` | 示範指南 | 端對端功能示範、step-by-step | `GUIDES/` |
+| `api_reference` | API 參考 | 端點列表、請求/回應格式 | `GUIDES/` |
+| `troubleshooting` | 疑難排解 | 常見問題與解決方案 | `GUIDES/` |
+| `glossary` | 術語表 | 專有名詞定義 | `GUIDES/` |
+| `tech_eval` | 技術評估 | 模型選型、方案比較 | `DESIGN/` |
+| `design` | 設計文件 | 功能設計、架構設計 | `DESIGN/` |
+| `reference_doc` | 參考文件 | 資料模型、規格權威來源 | `REFERENCE/` |
+| `operations` | 運維文件 | 基礎設施、發佈、監控 | `OPERATIONS/` |
+| `integration` | 整合文件 | 外部服務、n8n 工作流 | `INTEGRATIONS/` |
+| `standard_doc` | 規範文件 | 標準、規則、流程 | `STANDARDS/` |
+
+---
+
+## 2. 對象標記（Audience Labeling）
+
+每份使用者文件開頭的頂部資訊表後，必須標註目標讀者與預備知識：
+
+```markdown
+| 項目 | 內容 |
+|------|------|
+| 建立者 | ... |
+| 建立時間 | ... |
+| 文件版本 | ... |
+| 目標讀者 | system_admin / developer / end_user |
+| 預備知識 | none / 需了解 Pipeline / 需有 API Key / 需熟悉 REST API |
+```
+
+| 讀者類型 | 說明 | 適用文件 |
+|----------|------|----------|
+| `system_admin` | 系統管理員，負責安裝、配置、維護 | install guide, operations, troubleshooting |
+| `developer` | 開發者/整合者，透過 API 存取系統 | api_reference, demo_guide |
+| `end_user` | 終端使用者，透過 Portal 操作 | user_manual, quick_start |
+
+---
+
+## 3. 端點文檔模板
+
+每個 API 端點必須使用以下三段式模板：
+
+### `METHOD /path/to/endpoint`
+
+**Auth**: Required / Optional / Public
+**Scope**: file-level / identity-level / system-level
+
+#### Request Parameters
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `param_name` | string | Yes | - | Parameter description |
+
+#### Example
+
+```bash
+curl -s -X POST "$API/path" \
+  -H "X-API-Key: $KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"param": "value"}'
+```
+
+#### Response (200)
+
+```json
+{
+  "success": true,
+  "data": {}
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | boolean | Always true on 200 |
+| `data` | object | Result payload |
+
+#### Error Responses
+
+| Code | HTTP | When |
+|------|------|------|
+| `E001` | 404 | Resource not found |
+| `E003` | 400 | Invalid parameters |
+
+> 錯誤碼對照表請參考 `REFERENCE/API_ERROR_CODES.md`
+
+---
+
+## 4. curl 範例規範
+
+### 4.1 變數使用
+
+```bash
+# 每份文件開頭設定
+API="http://localhost:3003"
+KEY="your-api-key-here"
+```
+
+### 4.2 基本範例
+
+```bash
+curl -sf "$API/health" | jq '{
+  status, version
+}'
+```
+
+### 4.3 POST 範例
+
+```bash
+curl -s -X POST "$API/api/v1/resource/tmdb/check" \
+  -H "X-API-Key: $KEY" \
+  | jq '.status'
+```
+
+### 4.4 規則
+
+| 規則 | 說明 |
+|------|------|
+| 使用 `$API` 和 `$KEY` | 讀者可直接複製貼上，只需改變數值 |
+| 包含預期輸出 | `curl` 指令後必須有 ````json` 預期輸出 |
+| 使用 `jq` 過濾 | 只顯示關鍵欄位，避免輸出過長 |
+| 認證 header 固定顯示 | `-H "X-API-Key: $KEY"` 每次都寫出來 |
+
+---
+
+## 5. Response 展示規範
+
+### 5.1 成功回應
+
+```json
+{
+  "success": true,
+  "total": 42,
+  "results": [
+    { "file_uuid": "abc...", "name": "Test" }
+  ]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | boolean | Always true on 200 |
+| `total` | integer | Total count |
+| `results` | array | Result array |
+
+### 5.2 錯誤回應
+
+```json
+{
+  "success": false,
+  "error": "Resource not found"
+}
+```
+
+> 錯誤碼請對照 `REFERENCE/API_ERROR_CODES.md`
+
+---
+
+## 6. 黃金範例：端點文檔
+
+### `POST /api/v1/resource/tmdb/check`
+
+**Auth**: Required
+**Scope**: system-level
+**Description**: Ping TMDb API to verify reachability and measure latency.
+
+#### Request
+
+This endpoint requires no body.
+
+#### Example
+
+```bash
+curl -s -X POST "$API/api/v1/resource/tmdb/check" \
+  -H "X-API-Key: $KEY" | jq '.status'
+```
+
+#### Response
+
+```json
+{
+  "api_key_configured": true,
+  "enabled": false,
+  "api_reachable": true,
+  "api_latency_ms": 120,
+  "api_error": null,
+  "last_check_at": "2026-05-17T12:00:00Z"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `api_key_configured` | boolean | TMDB_API_KEY env var is set |
+| `api_reachable` | boolean | TMDb API responded successfully |
+| `api_latency_ms` | integer | Response time in milliseconds |
+
+#### Error Responses
+
+| HTTP | When |
+|------|------|
+| `401` | Missing or invalid API key |
+
+---
+
+### `POST /api/v1/file/:file_uuid/tmdb-probe`
+
+**Auth**: Required
+**Scope**: file-level
+**Description**: Read local TMDb cache and create/update identities. Requires `tmdb-prefetch` to have been run first.
+
+#### Request
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `file_uuid` | string | Yes (path param) | File UUID of a registered video |
+
+#### Example
+
+```bash
+curl -s -X POST "$API/api/v1/file/abc/tmdb-probe" \
+  -H "X-API-Key: $KEY" | jq '{success, identities_created, movie_title}'
+```
+
+#### Response (200 — identities created)
+
+```json
+{
+  "success": true,
+  "identities_created": 15,
+  "movie_title": "Charade",
+  "cast_count": 20
+}
+```
+
+#### Response (200 — no cache found)
+
+```json
+{
+  "success": false,
+  "message": "No TMDb cache found. Run tmdb-prefetch first."
+}
+```
+
+---
+
+### `GET /api/v1/resource/tmdb`
+
+**Auth**: Required
+**Scope**: system-level
+**Description**: View TMDb resource status including configuration, identity counts, and available cache files.
+
+#### Example
+
+```bash
+curl -s "$API/api/v1/resource/tmdb" \
+  -H "X-API-Key: $KEY" | jq '{identities_seeded, cache_files, operations: [.operations[].path]}'
+```
+
+#### Response
+
+```json
+{
+  "success": true,
+  "status": {
+    "api_key_configured": true,
+    "enabled": false,
+    "api_reachable": null
+  },
+  "identities_seeded": 15,
+  "identities_with_embedding": 12,
+  "cache_files": 2,
+  "operations": [
+    {"method": "GET", "path": "/api/v1/resource/tmdb", "description": "TMDb resource status"}
+  ]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `identities_seeded` | integer | Identities with `source='tmdb'` |
+| `identities_with_embedding` | integer | Those with `face_embedding` not null |
+| `cache_files` | integer | `*.tmdb.json` files in output dir |
+
+---
+
+## 7. 文件階層圖
+
+```mermaid
+USER_MANUAL.md                ← 所有使用者入口
+  ├── API_QUICK_REFERENCE.md  ← 快速查端點
+  │   └── API_ENDPOINTS.md    ← 每端點詳細 curl + response
+  │       └── API_ERROR_CODES.md ← 錯誤碼對照
+  ├── Demo_EndToEnd.md        ← step-by-step 完整 pipeline demo
+  ├── TMDb_User_Guide.md      ← TMDb enrichment 專屬
+  └── PORTAL_API_DEMO_GUIDE.md ← Portal 操作示範
+```
+
+---
+
+## 8. 檢查清單
+
+### 必需（P0）
+
+- [ ] `document_type` 正確設定（見 §1）
+- [ ] 頂部資訊表含目標讀者與預備知識（§2）
+- [ ] 有 curl 範例使用 `$API` `$KEY` 變數（§4）
+- [ ] curl 範例後有預期輸出（§4.4）
+- [ ] API 端點使用三段式模板（§3）
+
+### 建議（P1）
+
+- [ ] 使用 `jq` 過濾輸出，只顯示關鍵欄位
+- [ ] 響應欄位有欄位說明表（§5）
+- [ ] 錯誤回應對照 `API_ERROR_CODES.md`
+- [ ] 文件結尾有相關文件交叉連結