# People 頁面設計文件

## 1. 分層架構

| 層級 | 負責 |
|---|---|
| **Rust (Backend)** | API 代理、檔案系統存取、API key 管理 |
| **Vue (Frontend)** | UI 渲染、狀態管理、使用者交互 |

---

## 2. Core API 端點（已實測驗證）

詳見 `CORE_API_REFERENCE.md`。以下摘要 People 頁面使用的端點：

| 功能 | Method | 端點 | Response Key | 備註 |
|---|---|---|---|---|
| 列出人物 | GET | `/api/v1/identities` | `identities` | 含 metadata.starred |
| 人物詳情 | GET | `/api/v1/identity/{uuid}` | 頂層 | 含 tmdb_profile 路徑 |
| 搜尋人物 | GET | `/api/v1/identities/search?q=` | `results` | 欄位不同於 list |
| 大頭照 | — | 本地檔案讀取 | — | 非 Core API |
| 人臉列表 | GET | `/api/v1/identity/{uuid}/faces` | `data` | **不是** `faces` |
| 追蹤列表 | GET | `/api/v1/identity/{uuid}/traces` | `traces` | |
| 改名 | PATCH | `/api/v1/identity/{uuid}` | 頂層 | Body: `{"name": "..."}` |
| 刪除 | DELETE | `/api/v1/identity/{uuid}` | — | 204/404 |
| 建立 | POST | `/api/v1/identity` | — | 需要 face_json_path |
| 合併 | POST | `/api/v1/identity/{uuid}/mergeinto` | — | Body: `{"into_uuid": "..."}` |
| 綁定 | POST | `/api/v1/identity/{uuid}/bind` | — | Body: `{"face_id": "string", "file_uuid": "..."}` |
| 解綁 | POST | `/api/v1/identity/{uuid}/unbind` | — | Body: 同上 |
| 候選人臉 | GET | `/api/v1/faces/candidates` | `candidates` | |
| 縮圖 | GET | `/api/v1/file/{uuid}/thumbnail` | Binary | |
| 影片 | GET | `/api/v1/file/{uuid}/video` | Binary | |

---

## 3. Rust Structs 定義

```rust
struct PersonInfo {
    identity_uuid: String,
    name: String,
    starred: bool,  // 從 metadata.starred 提取
}

struct FaceInfo {
    id: i64,
    file_uuid: String,
    frame_number: i64,
    timestamp_secs: f64,
    face_id: Option<String>,
    confidence: f64,
}

struct TraceInfo {
    trace_id: i64,
    file_uuid: String,
    frame_count: i64,
    first_sec: f64,
    last_sec: f64,
    avg_confidence: f64,
}

struct FaceCandidate {
    id: i64,
    face_id: Option<String>,
    file_uuid: String,
    frame_number: i64,
    confidence: f64,
}

struct SearchIdentityResult {
    identity_id: i64,
    name: String,
    source: String,
    tmdb_id: Option<i64>,
    file_uuid: Option<String>,
    start_time: f64,
    end_time: f64,
    text_content: Option<String>,
}
```

---

## 4. Rust Commands 清單

### 4.1 現有（需修改）
| Command | 修改內容 |
|---|---|
| `get_people` | PersonInfo 加 `starred: bool`，解析 metadata.starred |
| `get_faces` | 解析 `data` key 而非 `faces`，FaceInfo 加 timestamp_secs |
| `get_video_stream` | **重構**：寫入 temp file → 回傳 `file://` URL |

### 4.2 現有（不變）
| Command | 行為 |
|---|---|
| `get_traces` | `GET /identity/{uuid}/traces` |
| `get_identity_profile` | 讀本地 profile.jpg → base64 |
| `update_identity_name` | `PATCH /identity/{uuid}` |
| `delete_identity` | `DELETE /identity/{uuid}` |
| `get_thumbnail` | 抓縮圖 → base64 |

### 4.3 新增
| Command | Core API | Body/Params | 回傳 |
|---|---|---|---|
| `search_identities` | `GET /identities/search?q=...` | `query: String, limit: usize` | `Vec<SearchIdentityResult>` |
| `merge_identities` | `POST /identity/{uuid}/mergeinto` | `uuid: String, into_uuid: String` | `()` |
| `bind_face` | `POST /identity/{uuid}/bind` | `uuid, face_id: String, file_uuid: String` | `()` |
| `unbind_face` | `POST /identity/{uuid}/unbind` | `uuid, face_id: String, file_uuid: String` | `()` |
| `get_face_candidates` | `GET /faces/candidates` | `page: usize, per_page: usize` | `Vec<FaceCandidate>` |

**注意：create_identity 需要 face_json_path，不在 People 頁面直接使用。**

---

## 5. Vue 前端元件樹

```
PeopleView.vue
├── Toolbar
│   ├── h1 "People"
│   ├── 搜尋框 → debounce 300ms → invoke('search_identities')
│   └── 建立按鈕（暫留，create 需要 face_json_path）
│
├── PeopleGrid
│   └── PersonCard × N (v-for filteredPeople)
│       ├── 大頭照 → invoke('get_identity_profile') cache
│       ├── 名稱
│       ├── ⭐ 星號 (starred)
│       └── @click → selectPerson()
│
├── DetailModal
│   ├── Header: 大頭照 + 可編輯名稱 + UUID
│   ├── FacesTab (橫向捲軸)
│   │   └── face × N → confidence %
│   ├── TracesTab (縱向列表)
│   │   └── trace × N → 時間 + 信心% → @click → VideoPlayer
│   └── ActionsTab
│       ├── Delete → confirm + invoke('delete_identity')
│       ├── Merge → 搜尋目標 + invoke('merge_identities')
│       ├── Bind Face → 從 Candidates 選取 → invoke('bind_face')
│       └── Unbind Face → invoke('unbind_face')
│
├── CandidatesModal
│   └── FaceCandidate × N → @click → bind_face()
│
└── VideoPlayer (共用元件)
    └── <video :src="videoSrc"> (file:// URL from temp file)
```

---

## 6. CSS 設計系統

### 色彩
| 用途 | 色碼 |
|---|---|
| Primary | `#2563eb` |
| Secondary | `#64748b` |
| Success | `#22c55e` |
| Warning | `#f59e0b` |
| Error | `#ef4444` |
| Card BG | `#ffffff` |
| Text Primary | `#1e293b` |
| Text Secondary | `#64748b` |

### 元件樣式
| 元件 | 樣式 |
|---|---|
| Grid | `repeat(auto-fill, minmax(100px, 1fr))` gap 16px |
| Card | bg #fff, border 1px #e5e7eb, radius 12px, padding 16px, hover border #4f46e5 |
| Avatar | 56px 圓形, bg #eef2ff, color #4f46e5 |
| Modal | fixed inset:0, bg rgba(0,0,0,.6), centered, max-w 700px, max-h 80vh |
| VideoPlayer | fixed inset:0, bg rgba(0,0,0,.85), video max-w 80vw max-h 60vh, radius 16px |

---

## 7. 資料流

```
事件                    Vue 呼叫                          Rust Command
─────────────────      ──────────────                      ────────────
頁面載入               invoke('get_people')                get_people()
點擊人物               invoke('get_faces')                 get_faces()
                      invoke('get_traces')                 get_traces()
                      invoke('get_identity_profile')       get_identity_profile()
搜尋輸入(debounce)     invoke('search_identities')         search_identities()
編輯名稱               invoke('update_identity_name')      update_identity_name()
刪除人物               invoke('delete_identity')           delete_identity()
合併人物               invoke('merge_identities')          merge_identities()
綁定人臉               invoke('bind_face')                 bind_face()
解綁人臉               invoke('unbind_face')               unbind_face()
載入候選人臉           invoke('get_face_candidates')       get_face_candidates()
播放影片               invoke('get_video_stream')          get_video_stream() → temp file
```

---

## 8. 實作順序

1. **Phase 1**: 修改 `PersonInfo` + `FaceInfo` struct + 重構 `get_video_stream` (temp file)
2. **Phase 2**: 新增 `search_identities` + `get_face_candidates`
3. **Phase 3**: 新增 `merge_identities` + `bind_face` + `unbind_face`
4. **Phase 4**: Vue PeopleView 完整 UI（grid + modal + tabs + actions + 搜尋 + 合併 + 綁定）
5. **Phase 5**: 更新 AGENTS.md + 提交