# 3002 vs 3003 API 比較報告

> **日期**: 2026-04-14 | **目的**: 分析正式版與開發版 API 差異

---

## 1. 版本差異

| 項目 | 3002 (正式版) | 3003 (開發版) |
|------|:---:|:---:|
| **Build 日期** | 2026-04-13 00:29:25 | 2026-04-14 23:01:47 |
| **程式碼狀態** | ❌ 舊版，缺少新 API | ✅ 最新版，包含所有新功能 |
| **需要重新編譯** | ✅ 是 | ❌ 否 |

---

## 2. API 端點可用性比較

### 2.1 完全相同的端點（JSON 結構一致）

| 端點 | 3002 | 3003 | JSON 結構 |
|------|:---:|:---:|:---:|
| `GET /health` | ✅ 200 | ✅ 200 | ✅ 一致 |
| `GET /api/v1/person/:id` | ✅ 200 | ✅ 200 | ✅ 一致 |
| `GET /api/v1/chunks/:id/persons` | ✅ 200 | ✅ 200 | ✅ 一致 |
| `GET /api/v1/face/list` | ✅ 200 | ✅ 200 | ✅ 一致 |
| `GET /api/v1/face/:id` | ✅ 200 | ✅ 200 | ✅ 一致 |
| `POST /api/v1/face/search` | ✅ 200 | ✅ 200 | ✅ 一致 |

### 2.2 3002 缺少的端點

| 端點 | 3002 | 3003 | 新增日期 |
|------|:---:|:---:|:---:|
| `GET /api/v1/person/list` | ❌ 404 | ✅ 200 | 2026-04-14 |
| `POST /api/v1/person/auto-identify` | ❌ 405 | ✅ 200 | 2026-04-14 |
| `POST /api/v1/person/suggest` | ❌ 405 | ✅ 200 | 2026-04-14 |
| `POST /api/v1/person/merge` | ❌ 405 | ✅ 200/400 | 2026-04-14 |
| `POST /api/v1/person/merge/undo` | ❌ 404 | ✅ 200 | 2026-04-14 |
| `GET /api/v1/person/merge/history` | ❌ 404 | ✅ 200 | 2026-04-14 |
| `GET /api/v1/person/:id/similar` | ❌ 404 | ✅ 200 | 2026-04-14 |
| `PATCH /api/v1/person/:id/confirm` | ❌ 404 | ✅ 200 | 2026-04-14 |
| `POST /api/v1/person/:id/unbind-speaker` | ❌ 404 | ✅ 200 | 2026-04-14 |
| `POST /api/v1/person/:id/reassign-speaker` | ❌ 404 | ✅ 200 | 2026-04-14 |
| `POST /api/v1/person/:id/remove-appearance` | ❌ 404 | ✅ 200 | 2026-04-14 |
| `POST /api/v1/person/:id/reassign-appearance` | ❌ 404 | ✅ 200 | 2026-04-14 |
| `POST /api/v1/person/:id/split` | ❌ 404 | ✅ 200 | 2026-04-14 |
| `POST /api/v1/search/universal` | ❌ 404 | ✅ 200 | 2026-04-14 |
| `POST /api/v1/search/frames` | ❌ 404 | ✅ 200 | 2026-04-14 |
| `GET /api/v1/search/persons` | ❌ 404 | ✅ 200 | 2026-04-14 |
| `GET /api/v1/person/:id/thumbnail` | ❌ 404 | ✅ 200 | 2026-04-14 |

---

## 3. JSON 回應結構比較

### 3.1 GET /api/v1/person/:id (兩者一致)

```json
{
  "success": "bool",
  "person_id": "str",
  "name": "str",
  "face_identity_id": "null",
  "speaker_id": "str|null",
  "confidence": "float",
  "appearance_count": "int",
  "total_appearance_duration": "float",
  "first_appearance_time": "float",
  "last_appearance_time": "float",
  "is_confirmed": "bool",
  "created_at": "str",
  "updated_at": "str"
}
```

### 3.2 3003 獨有的 JSON 結構

#### POST /api/v1/person/auto-identify
```json
{
  "success": "bool",
  "message": "str",
  "total_persons": "int",
  "matched_speakers": "int",
  "persons": [{
    "person_id": "str",
    "name": "str|null",
    "speaker_id": "str|null",
    "appearance_count": "int",
    "total_appearance_duration": "float",
    "first_appearance_time": "float|null",
    "last_appearance_time": "float|null",
    "is_confirmed": "bool",
    "speaker_confidence": "float|null"
  }]
}
```

#### POST /api/v1/person/suggest
```json
{
  "success": "bool",
  "naming_suggestions": [{
    "person_id": "str",
    "current_name": "str|null",
    "suggested_name": "str",
    "confidence": "float",
    "sources": [{"type": "str", "detail": "str", "weight": "float"}],
    "action": "str (auto_apply|needs_review)"
  }],
  "merge_suggestions": [{
    "person_id": "str",
    "merge_with": ["str"],
    "confidence": "float",
    "reasons": ["str"],
    "action": "str"
  }],
  "total_naming": "int",
  "total_merge": "int"
}
```

#### POST /api/v1/search/universal
```json
{
  "query": "str",
  "results": [{
    "type": "str (chunk|frame|person)",
    // chunk 類型
    "chunk_id": "str",
    "chunk_type": "str",
    "start_time": "float",
    "end_time": "float",
    "score": "float",
    "text": "str|null",
    "speaker_id": "str|null",
    "metadata": "object"
    // 或 frame 類型
    // 或 person 類型
  }],
  "total": "int",
  "took_ms": "int"
}
```

---

## 4. 資料來源隔離

| 層級 | 3002 | 3003 |
|------|------|------|
| PostgreSQL Schema | `public` | `dev` |
| MongoDB Database | `momentry` | `momentry_dev` |
| Redis Prefix | `momentry:` | `momentry_dev:` |
| Qdrant Collection | `momentry_rule1` | `momentry_dev_rule1` |
| Output Dir | `/Users/accusys/momentry/output` | `/Users/accusys/momentry/output_dev` |

---

## 5. 部署建議

### 3002 需要更新

3002 運行的是 **2026-04-13** 的舊版程式碼，缺少 **17 個新 API 端點**。

**更新步驟**:
```bash
# 1. 確認程式碼已是最新
git status

# 2. 重新編譯
cargo build --release

# 3. 停止舊版
kill $(lsof -ti:3002)

# 4. 啟動新版
nohup cargo run --release --bin momentry -- server > /tmp/momentry_prod.log 2>&1 &

# 5. 驗證
curl http://localhost:3002/test-schema
# 應回傳: SCHEMA=public

curl http://localhost:3002/api/v1/person/list?limit=1
# 應回傳: {"success":true,"persons":[...], "total":N}
```

---

## 6. 總結

| 類別 | 狀態 |
|------|------|
| **程式碼版本** | 3002 落後 1 天 (2026-04-13 vs 2026-04-14) |
| **API 端點** | 3002 缺少 17 個新端點 |
| **JSON 結構** | 相同端點的 JSON 結構完全一致 |
| **資料隔離** | ✅ 完全獨立 (public vs dev) |
| **需要行動** | ✅ 3002 需要重新編譯部署 |
