momentry_studio/docs/proposals/face-group-naming-issue.md

Face Group 命名持久化問題 - 技術分析報告

日期: 2026-07-19
提出團隊: Momentry Studio
狀態: 待 Core Team 討論

---

一、問題現象

1.1 用戶操作流程

1. 選擇影片檔案
2. 建立 face group 並命名（如 "test group"）
3. 將 trace 移入該 group
4. 成功顯示新 group，可播放影片
5. 跳轉到其他頁面
6. 返回 Face 頁面
7. "test group" 消失

1.2 影響範圍

功能	影響
新建 face group	❌ 無法持久化
重新命名 face group	❌ 無法持久化
移動 trace 到 group	❌ 無法持久化
系統自動生成的 group	✅ 正常

---

二、技術分析

2.1 數據流追蹤

Frontend                          Core API                    TKG
   │                                 │                          │
   │ updateTraceProfileGroup(        │                          │
   │   fileUuid, traceIds,           │                          │
   │   { name: "test group" }        │                          │
   │ )                               │                          │
   ├─────────────────────────────────►│                          │
   │                                 │ PUT /trace-profile/group │
   │                                 │ { name: "test group" }   │
   │                                 ├─────────────────────────►│
   │                                 │                          │
   │                                 │              存入 face_trace.label
   │                                 │                          │
   │ loadClusterResults()            │                          │
   ├─────────────────────────────────►│                          │
   │                                 │ GET /file/{uuid}/        │
   │                                 │     face-groups          │
   │                                 ├─────────────────────────►│
   │                                 │                          │
   │                                 │              從 TKG 讀取 label
   │                                 │◄─────────────────────────┤
   │                                 │                          │
   │ ◄───────────────────────────────┤ { face_groups: [...] }   │
   │                                 │                          │

2.2 Bug 定位

文件位置: /Users/accusys/momentry_studio/src/api/index.ts
行號: 379

問題代碼:

case 'update_trace_profile_group': {
  return { 
    url: '/api/v1/trace-profile/group', 
    method: 'PUT', 
    body: { 
      file_uuid: a.fileUuid, 
      trace_ids: a.traceIds, 
      name: a.group_name || a.label,  // ← BUG: 忽略 a.name
      key_frame: a.keyFrame, 
      key_face: a.keyFace 
    } 
  }
}

Frontend 調用分析:

行號	文件	調用方式	參數
430	PeopleView.vue	updateTraceProfileGroup(..., { name })	name ✅
864	PeopleView.vue	updateTraceProfileGroup(..., { label: name })	label ⚠️
928	PeopleView.vue	updateTraceProfileGroup(..., { name: ... })	name ✅
971	PeopleView.vue	updateTraceProfileGroup(..., { name })	name ✅

結果:

• API Builder 期望 group_name 或 label
• Frontend 大部分傳入 name
• 導致 Core API 收到 name: undefined

---

三、命名不一致問題

3.1 各層級欄位對照

層級	欄位名稱	說明
TKG face_trace node	label	根本存儲位置
Core API /trace-profile (GET)	name	返回給前端
Core API /trace-profile/group (PUT)	name	接受前端參數
Frontend 大部分調用	name	✅ 正確
Frontend line 864	label	⚠️ 不一致
API Builder 期望	group_name || label	❌ 不匹配

3.2 Core API 文檔定義

PUT /api/v1/trace-profile/group

參數	類型	必填	說明
file_uuid	string	Yes	File UUID
trace_ids	integer[]	Yes	Trace IDs
name	string	Yes	新群組名稱

Core API 明確接受 name 參數。

---

四、架構設計問題

4.1 TKG Label 類型混淆

現狀: TKG label 欄位可能代表不同意圖：

來源	值範例	說明
用戶命名	"Peter", "Cary Grant"	用戶主動指定
系統生成	"Trace_1", "Face Trace 9"	自動生成
其他	可能還有其他類型	待確認

問題: 無法區分 label 的來源/類型

4.2 建議方案

選項 A：增加 label_type 欄位

// TKG face_trace node
{
  "node_type": "face_trace",
  "label": "Peter",
  "label_type": "face_name",  // 新增欄位
  "properties": {
    "trace_id": 9,
    "face_count": 142,
    ...
  }
}

label_type 可能值:

值	說明
face_name	用戶定義的名稱
system	系統自動生成
tmdb	來自 TMDB 識別

選項 B：使用 labels 陣列（支援多標籤）

{
  "node_type": "face_trace",
  "labels": [
    { "value": "Peter", "type": "face_name", "source": "user" },
    { "value": "Trace_9", "type": "system", "source": "auto" }
  ],
  ...
}

選項 C：維持現狀

• TKG 保持 label 單一欄位
• Core API 翻譯：label ↔ name
• Frontend 統一使用 name

---

五、修復方案

5.1 方案 A：前端統一使用 name（最小改動）

修改點:

文件	行號	原代碼	新代碼
src/api/index.ts	379	name: a.group_name || a.label	name: a.name
src/views/PeopleView.vue	864	{ label: name }	{ name }

優點:

• 改動少
• 符合 Core API 文檔
• 立即解決問題

缺點:

• 未處理 TKG label 類型問題
• 未來可能有類似問題

預計工作量: 0.5 小時

5.2 方案 B：TKG 增加 label_type（完整方案）

需要修改:

1. TKG Schema

   • 增加 label_type 欄位

2. Core API

   • /trace-profile/group 增加 label_type 參數（默認 face_name）
   • 更新 TKG node 時設定 label_type

3. Frontend

   • 傳遞 { name: "...", label_type: "face_name" }

優點:

• 完整解決命名類型問題
• 支援未來擴展

缺點:

• 需要改動 TKG 和 Core API
• 工作量較大

預計工作量: 2-4 小時（跨團隊）

---

六、討論議題

6.1 短期決策

1. 是否先執行方案 A，讓功能正常運作？
2. 方案 A 的風險評估？

6.2 長期設計

1. TKG 是否需要 label_type 欄位？
2. 如果需要，label_type 應該有哪些值？
3. Core API 是否需要同時支援 name 和 label_type 參數？

6.3 命名規範

建議建立正式對照表:

層級	欄位	類型	說明
TKG	label	string	根本存儲
TKG	label_type	string	類型標識（新增？）
Core API	name	string	API 參數/返回
Frontend	name	string	統一使用

---

七、附錄

A. 相關代碼位置

文件	說明
/Users/accusys/momentry_studio/src/api/index.ts:379	API Builder
/Users/accusys/momentry_studio/src/store.ts:252	updateTraceProfileGroup
/Users/accusys/momentry_studio/src/views/PeopleView.vue:430,864,928,971	調用點
/Users/accusys/momentry_core/docs_v1.0/doc_wasm/modules/18_profile.md	Core API 文檔

B. Core API 端點

端點	方法	說明
/api/v1/trace-profile	GET	獲取單一 trace profile
/api/v1/trace-profile	PUT	更新單一 trace profile
/api/v1/trace-profile/group	PUT	批量更新 trace profile
/api/v1/file/{uuid}/face-groups	GET	獲取 face groups

---

以上問題請 Core Team 確認後，再決定修復方向。