docs: add Identity Best-Face API requirement document for frontend team

2026-06-01 21:58:54 +08:00
parent 874d688987
commit 3731a1230f
1 changed files with 277 additions and 0 deletions
--- a/IDENTITY_BEST_FACE_API.md
+++ b/IDENTITY_BEST_FACE_API.md
@@ -0,0 +1,277 @@
+# Identity Best-Face API
+
+**狀態：** 規劃中
+**提出日期：** 2026-06-01
+**提出者：** WordPress Portal 前端團隊
+
+---
+
+## 1. 背景
+
+WordPress Portal 的 People 頁面需要在 identity detail view 與 grid card 中顯示代表臉部縮圖。目前前端作法：
+
+1. `GET /identity/{uuid}/traces` → 取得所有 trace 列表（含 `avg_confidence`）
+2. 對每個 trace 載入第一幀 thumbnail → `GET /file/{uuid}/trace/{tid}/thumbnail`
+3. 從有 thumbnail 的 trace 中，選 `avg_confidence` 最高者作為代表圖
+
+### 現有問題
+
+- **品質不佳**：trace thumbnail 固定取第一幀，不一定是該 trace 內最清晰或正面的臉部畫面
+- **浪費頻寬**：前端需發送大量並行請求（最多 20 trace × thumbnail），多數 thumbnail 最終不會被使用
+- **無快取**：每次進入 detail view 都要重複載入所有 thumbnail
+- **不一致**：同樣 identity 在 grid card 與 detail view 可能顯示不同代表圖
+
+---
+
+## 2. 目標
+
+後端新增一個 endpoint，對指定 identity **跨所有 trace** 選出品質最佳（最清晰）的臉部畫面，並提供可直接使用的縮圖 URL，支援 disk cache。
+
+---
+
+## 3. API 規格
+
+### `GET /api/v1/identity/:identity_uuid/best-face`
+
+無 query parameter。
+
+#### 成功回應 `200`
+
+```json
+{
+  "success": true,
+  "identity_uuid": "a6fb22eebefaef17e62af874997c5944",
+  "name": "Audrey Hepburn",
+  "source": "fresh",
+  "best": {
+    "file_uuid": "a6fb22eebefaef17e62af874997c5944",
+    "trace_id": 42,
+    "frame_number": 3120,
+    "timestamp_secs": 124.8,
+    "bbox": {
+      "x": 240,
+      "y": 180,
+      "width": 120,
+      "height": 160
+    },
+    "confidence": 0.97,
+    "quality_score": 18624.0,
+    "blur_score": 2.1,
+    "thumbnail_url": "/api/v1/file/a6fb22eebefaef17e62af874997c5944/trace/42/thumbnail"
+  }
+}
+```
+
+#### 無可用臉部 `200`
+
+```json
+{
+  "success": true,
+  "identity_uuid": "a6fb22eebefaef17e62af874997c5944",
+  "name": "Audrey Hepburn",
+  "source": "fresh",
+  "best": null
+}
+```
+
+#### 欄位說明
+
+| 欄位 | 型態 | 說明 |
+|------|------|------|
+| `success` | boolean | 請求是否成功 |
+| `identity_uuid` | string | identity UUID（32字元無連字號） |
+| `name` | string | identity 名稱 |
+| `source` | string | `"fresh"`（即時計算）或 `"cache"`（來自 disk cache） |
+| `best` | object/null | 最佳臉部資訊，無可用臉部時為 `null` |
+| `best.file_uuid` | string | 該臉部所屬檔案 UUID |
+| `best.trace_id` | int | 該臉部所屬 trace ID |
+| `best.frame_number` | int | 代表臉的影格編號 |
+| `best.timestamp_secs` | float | 代表臉的時間戳（秒） |
+| `best.bbox` | object | 臉部 bounding box `{x, y, width, height}` |
+| `best.confidence` | float | 該臉部的 detection confidence |
+| `best.quality_score` | float | 品質分數 = `(width * height) * confidence` |
+| `best.blur_score` | float | 模糊度分數（ffmpeg blurdetect），越低越清晰 |
+| `best.thumbnail_url` | string | 縮圖 URL（相對路徑，可直接用於瀏覽器） |
+
+---
+
+## 4. 實作建議
+
+### 4.1 建議放置位置
+
+**選項 A（建議）：** `src/api/trace_agent_api.rs`
+
+- 原因：核心邏輯重用 `select_rep_face()`（目前為 `pub(crate)`，位於同一檔案），無需修改既有的 function visibility
+- 在 `trace_agent_routes()` 中新增路由
+
+**選項 B：** `src/api/identity_binding.rs`
+
+- 需將 `select_rep_face` 改為 `pub` 才能跨檔案呼叫
+- 路由語意上更接近 identity 操作
+
+### 4.2 演算法
+
+```
+1. DISK CACHE CHECK
+   路徑：{OUTPUT_DIR}/identities/{uuid}/best_face.json
+   讀取 identity.json 的 updated_at，與 cache 中記錄的版本比較
+   若 cache 未過期 → 直接回傳（source: "cache"）
+   若無 cache 或已過期 → 繼續計算
+
+2. QUERY IDENTITY
+   SELECT id, name FROM identities
+   WHERE REPLACE(uuid::text, '-', '') = $1
+
+3. QUERY TOP N TRACES
+   SELECT fd.file_uuid, fd.trace_id,
+          AVG(fd.confidence)::float8 AS avg_conf
+   FROM {schema}.face_detections fd
+   WHERE fd.identity_id = $1
+     AND fd.confidence > 0.7
+     AND (fd.metadata->>'qc_ok' IS NULL
+          OR (fd.metadata->>'qc_ok')::boolean = true)
+   GROUP BY fd.file_uuid, fd.trace_id
+   ORDER BY avg_conf DESC
+   LIMIT 5
+
+4. FOR EACH TRACE (並行)
+   select_rep_face(pool, file_uuid, trace_id, err_fn)
+   　→ 回傳該 trace 內 blur_score 最低（最清晰）的臉
+   失敗則 skip（log warning）
+
+5. SELECT BEST AMONG RESULTS
+   主排序：blur_score ASC（越低越清晰）
+   次排序：quality_score DESC（blur_score 差距 < 0.5 時）
+   全部失敗 → best = null
+
+6. WRITE DISK CACHE
+   路徑：{OUTPUT_DIR}/identities/{uuid}/best_face.json
+   內容：best 欄位 + 計算時間 + identity updated_at
+
+7. RESPONSE
+```
+
+### 4.3 效能參數
+
+| 參數 | 值 | 說明 |
+|------|----|------|
+| TOP N | 5 | 只對 confidence 最高的 5 個 trace 做 blurdetect |
+| confidence 門檻 | > 0.7 | 同既有的 `select_rep_face` 邏輯 |
+| QC 過濾 | qc_ok = true/null | 同既有邏輯 |
+| ffmpeg timeout | inherit from Command | 每個 trace 約 1-3s |
+| cache TTL | 直到下一次 bind/unbind/merge | 事件驅動失效 |
+
+### 4.4 快取策略
+
+**寫入時機：** `get_identity_best_face` 計算完成後
+
+**失效時機（刪除 `best_face.json`）：**
+
+| 觸發 operation | 所在檔案 | 備註 |
+|---------------|---------|------|
+| `bind_trace` (POST) | `identity_binding.rs` | 新增 face 關聯 |
+| `unbind` (POST) | `identity_binding.rs` | 移除 face 關聯 |
+| `mergeinto` (POST) | `identity_binding.rs` | source + target 雙雙清除 |
+| `profile-image` (POST) | `identity_api.rs` | 使用者上傳新大頭照 |
+
+**Cache 驗證機制：** 儲存計算時的 `identity.updated_at`，每次請求時比對：
+- 若 identity 的 `updated_at` 未變 → cache 有效
+- 若已變 → 重新計算
+
+### 4.5 建議的新增/修改檔案
+
+| 檔案 | 動作 | 說明 |
+|------|------|------|
+| `src/api/trace_agent_api.rs` | **新增** handler + struct + route | ~+130 行 |
+| `src/api/identity_binding.rs` | **修改** 3 處 + cache invalidation helper | ~+25 行 |
+| `src/api/identity_api.rs` | **修改** 1 處（profile-image POST） | ~+5 行 |
+
+### 4.6 需要的新 struct
+
+**`src/api/trace_agent_api.rs`**（或獨立檔案 `src/core/identity_best_face.rs`）：
+
+```rust
+#[derive(Debug, Serialize, Deserialize)]
+pub struct BestFaceResponse {
+    pub success: bool,
+    pub identity_uuid: String,
+    pub name: String,
+    pub source: String,
+    pub best: Option<BestFaceResult>,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct BestFaceResult {
+    pub file_uuid: String,
+    pub trace_id: i32,
+    pub frame_number: i64,
+    pub timestamp_secs: f64,
+    pub bbox: RepFaceBbox,
+    pub confidence: f64,
+    pub quality_score: f64,
+    pub blur_score: f64,
+    pub thumbnail_url: String,
+}
+```
+
+### 4.7 Cache Invalidation Helper Function
+
+```rust
+async fn invalidate_best_face_cache(output_dir: &str, uuid_clean: &str) {
+    let path = format!("{}/identities/{}/best_face.json", output_dir, uuid_clean);
+    let _ = tokio::fs::remove_file(path).await;
+}
+```
+
+---
+
+## 5. 前端整合參考（供後端團隊理解使用情境）
+
+WP snippet 72 (`ms-people.js`) 的 `loadPersonDetail` 中，優先使用新 endpoint：
+
+```js
+async function loadPersonDetail(person) {
+  if (person.thumb && person._hasProfileImage) return;
+
+  try {
+    const res = await apiFetch('/identity/' + person.id + '/best-face');
+    if (res?.success && res?.best) {
+      const b = res.best;
+      person.thumb = `${API_BASE}/file/${b.file_uuid}/trace/${b.trace_id}/thumbnail?api_key=${API_KEY}`;
+      person._hasProfileImage = true;
+      updateDetailAvatar(person);
+      return;
+    }
+  } catch (e) { /* fallback to legacy */ }
+
+  // 原邏輯：traces → thumbnails → confidence sort
+}
+```
+
+同樣可用於 grid card 的代表圖載入（`loadGridThumbnails`）：
+
+```js
+// 一次性載入所有 pending identity 的 best-face
+const results = await Promise.allSettled(
+  persons.map(p => apiFetch('/identity/' + p.id + '/best-face'))
+);
+```
+
+---
+
+## 6. 驗收標準
+
+1. `GET /api/v1/identity/{uuid}/best-face` → `200` + valid JSON
+2. 有 trace 的 identity → `best` 不為 null，且 `blur_score` 為該 identity 所有 trace 中最低
+3. 無 trace 的 identity → `best: null`
+4. 短時間內重複請求同一 identity → `source: "cache"`，回應時間 < 10ms
+5. 綁定新 trace 後再次請求 → `source: "fresh"`（cache 已正確失效）
+6. `thumbnail_url` 可直接用於 `<img>` 顯示
+
+---
+
+## 7. 風險與注意事項
+
+- **首次請求延遲**：對有大量 trace 的 identity（如主角），首次請求可能需 5-15 秒。建議前端顯示 loading state
+- **ffmpeg 資源**：同時多個請求可能導致高 CPU 使用。可考慮加入 per-identity lock 避免重複計算
+- **邊界案例**：trace 內的 faces 全部 confidence ≤ 0.7 或 qc_ok=false，則該 trace 被跳過，可能導致 `best: null`