docs: add file status sync API delivery document for Studio team

2026-07-19 22:00:34 +08:00
parent 2ed56b7973
commit 244af51edf
1 changed files with 180 additions and 0 deletions
@@ -0,0 +1,180 @@
+# File Status Sync API - 交付文件
+
+**日期**: 2026-07-19
+**作者**: Core API Team
+**狀態**: 已完成
+
+---
+
+## 一、問題描述
+
+### 1.1 現象
+
+- 部分檔案在 `/face` 列表看不到
+- 需要到 `/library` 等待幾秒後才會出現
+- 原因：檔案實際已完成處理，但 DB `status` 仍為 `processing`
+
+### 1.2 根本原因
+
+| 問題 | 說明 |
+|------|------|
+| Worker 未運行 | `update_video_status(Completed)` 未執行 |
+| 狀態不一致 | Processor 檔案存在，但 DB status 未更新 |
+
+---
+
+## 二、解決方案
+
+### 2.1 新增端點
+
+```
+POST /api/v1/file/:file_uuid/sync-status
+```
+
+### 2.2 功能說明
+
+1. 檢查 5 個必要 processor 檔案：
+   - `face.json`
+   - `asrx.json`
+   - `ocr.json`
+   - `pose.json`
+   - `appearance.json`
+
+2. 如果全部存在 → 更新 `status = 'completed'`
+3. 否則 → 保持 `status = 'processing'`
+
+### 2.3 Response 範例
+
+```json
+{
+  "success": true,
+  "file_uuid": "9f6a9cd55a5809f977f5a6589b9045c5",
+  "status": "completed",
+  "processors_complete": 5,
+  "processors_total": 5
+}
+```
+
+---
+
+## 三、Studio 整合建議
+
+### 3.1 API Builder
+
+**檔案**: `/Users/accusys/momentry_studio/src/api/index.ts`
+
+```typescript
+case 'sync_file_status': {
+  return { 
+    url: `/api/v1/file/${a.fileUuid}/sync-status`, 
+    method: 'POST' 
+  }
+}
+```
+
+### 3.2 Store Function
+
+**檔案**: `/Users/accusys/momentry_studio/src/store.ts`
+
+```typescript
+export async function syncFileStatus(fileUuid: string): Promise<any> {
+  const result = await apiCall('sync_file_status', { fileUuid })
+  
+  // 更新 filesCache
+  const f = filesCache.value.find((x: any) => x.file_uuid === fileUuid)
+  if (f && result.status) {
+    f.status = result.status
+  }
+  
+  return result
+}
+```
+
+### 3.3 使用時機
+
+#### 選項 A：進入 /face 時批次同步
+
+```typescript
+// PeopleView.vue - onMounted
+async function loadFiles() {
+  await ensureFiles()
+  
+  // 批次同步狀態
+  for (const f of filesCache.value) {
+    if (f.status === 'processing') {
+      await syncFileStatus(f.file_uuid)
+    }
+  }
+}
+```
+
+#### 選項 B：單一檔案選擇時同步
+
+```typescript
+// 選擇檔案前先確認狀態
+async function selectFile(fileUuid: string) {
+  const result = await syncFileStatus(fileUuid)
+  if (result.status !== 'completed') {
+    // 顯示提示：檔案尚未處理完成
+    return
+  }
+  selectedFileUuid.value = fileUuid
+}
+```
+
+---
+
+## 四、測試驗證
+
+### 4.1 測試指令
+
+```bash
+# 同步單一檔案
+curl -X POST "http://localhost:3002/api/v1/file/{file_uuid}/sync-status" \
+  -H "X-API-Key: $KEY"
+
+# 驗證狀態
+curl -s "http://localhost:3002/api/v1/file/{file_uuid}" \
+  -H "X-API-Key: $KEY" | jq '.status'
+```
+
+### 4.2 已驗證案例
+
+| 檔案 | 處理前 | 處理後 |
+|------|--------|--------|
+| Accusys-WD_FilmRiot_test.mp4 | `processing` | `completed` |
+| Charade_YouTube_24fps.mp4 | `processing` | `processing`（正確，未完成）|
+
+---
+
+## 五、相關檔案路徑
+
+### Core API
+
+| 檔案 | 完整路徑 |
+|------|----------|
+| Endpoint 實現 | `/Users/accusys/momentry_core/src/api/files.rs` |
+| API 文檔 | `/Users/accusys/momentry_core/docs_v1.0/doc_wasm/modules/18_profile.md` |
+
+### Studio (需修改)
+
+| 檔案 | 完整路徑 |
+|------|----------|
+| API Builder | `/Users/accusys/momentry_studio/src/api/index.ts` |
+| Store | `/Users/accusys/momentry_studio/src/store.ts` |
+| PeopleView | `/Users/accusys/momentry_studio/src/views/PeopleView.vue` |
+
+---
+
+## 六、注意事項
+
+1. **效能考量**：若檔案數量多，建議使用選項 B（單一檔案同步）
+2. **快取更新**：`syncFileStatus` 會同時更新 `filesCache`
+3. **權限**：需要有效的 API Key
+
+---
+
+**Core API Team**: 如有問題，請透過 `M4_workspace/` 文檔回覆。
+
+*Document Version: 1.0*
+*Last Updated: 2026-07-19*