# 架構文件審查報告 (Architecture Review Report)

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-25 |
| 文件版本 | V1.0 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-25 | 全面審查 docs_v1.0 架構文件的一致性与完整性 | OpenCode | OpenCode |

---

## 1. 審查範圍

| 文件 | 狀態 | 評分 |
|------|------|------|
| `IMPLEMENTATION/FILE_IDENTITY_API_DESIGN.md` | 核心設計 | 7/10 |
| `ARCHITECTURE/RESOURCE_MANAGEMENT/UNIFIED_RESOURCE_REGISTRY.md` | 資源管理 | 8/10 |
| `PROCESSORS/_CORE/PROCESSOR_RESUME_STRATEGY.md` | 續傳機制 | 9/10 |
| `AI_AGENTS/CORE/AGENT_SPEC.md` | Agent 規範 | 8/10 |
| `STANDARDS/DOCS_STANDARD.md` | 文檔規範 | 9/10 |

---

## 2. 發現的問題與建議

### 2.1 高優先級 (High) — 架構矛盾

#### 🚨 H1: `faces` 表與 `file_identities` 表的關係不清

**問題**:
* `FILE_IDENTITY_API_DESIGN.md` 同時定義了 `faces` 表和 `file_identities` 表。
* `faces` 表有 `identity_id` (表示 Face 可直接歸屬 Identity)。
* `file_identities` 表也有身份關聯資訊。
* **兩者的職責重疊**，開發者會困惑該寫入哪張表。

**建議**:
* **方案 A**: 移除 `faces` 表，將 Face 視為 `pre_chunk` 的一種類型，Face 與 Identity 的關聯僅通過 `file_identities` 管理。
* **方案 B**: 保留 `faces` 表，但明確定義其為「Face 檢測原始數據表」，`file_identities` 僅作為「Face 與 Identity 的多對多關聯橋接表」。
* **推薦方案 A**：符合「Frame = Pre-chunk」的設計理念，減少冗餘。

#### 🚨 H2: 缺少 `pre_chunks` 表的 Schema 定義

**問題**:
* `FILE_IDENTITY_API_DESIGN.md` 中**未定義** `pre_chunks` 表結構。
* 但 `PROCESSOR_RESUME_STRATEGY.md` 明確指出 Processor 應產出 `pre_chunks`。
* 實作時將無參考標準。

**建議**:
* 在設計文件中補充 `pre_chunks` 表定義，至少包含：
    ```sql
    pre_chunks (
        pre_chunk_id   UUID PK,
        file_id        UUID FK → files,
        processor_type VARCHAR(20),  -- 'yolo', 'face', 'asr'...
        frame_index    BIGINT,       -- 幀索引 (或語句索引)
        timestamp      FLOAT,        -- 時間位置
        data           JSONB,        -- 處理器原始輸出
        created_at     TIMESTAMPTZ
    )
    ```

#### 🚨 H3: Candidate 與 Face 的關係未明確定義

**問題**:
* 設計說「Candidate 是未被確認歸屬 Identity 的 face」。
* 但資料庫中沒有 `candidates` 表。
* Candidate 是邏輯狀態還是物理表？

**建議**:
* **方案 A (推薦)**: Candidate 不需要獨立表。`faces.identity_id IS NULL` 即代表該 Face 是 Candidate。
* 在 API 設計中明確說明：`GET /people/candidates` = `SELECT * FROM faces WHERE identity_id IS NULL`。

---

### 2.2 中優先級 (Medium) — 設計缺失

#### ⚠️ M1: 缺少 Chunk 聚合規則的輸入輸出定義

**問題**:
* Rule 1/2/3 如何讀取 `pre_chunks` 並產出 `chunks`？
* 沒有明確的數據流說明。

**建議**:
* 補充 `CHUNKING` 目錄下的規則文件，定義每個 Rule 的：
  * **Input**: 從哪些 `pre_chunks` 讀取？
  * **Logic**: 聚合邏輯是什麼？
  * **Output**: 產出什麼樣的 `chunk`？

#### ⚠️ M2: Resource Registry 與現有 Job Worker 的整合

**問題**:
* `UNIFIED_RESOURCE_REGISTRY.md` 定義了統一的資源註冊機制。
* 但現有的 `src/worker/job_worker.rs` 是硬編碼調度 (`ProcessorType::all()`)。
* 如何過渡？

**建議**:
* 定義過渡路徑：
    1. **Phase 1**: Worker 仍使用硬編碼，但 Processor 啟動時額外註冊到 Registry（僅用於監控）。
    2. **Phase 2**: Worker 改為從 Registry 動態發現資源。

#### ⚠️ M3: 檔案類型限制與欄位設計

**問題**:
* `files` 表定義了 `file_type` (video, pdf...) 但現階段僅處理 Video。
* `pre_chunks` 和 `chunks` 表若設計時未考慮擴充性，未來加 PDF 時需大改。

**建議**:
* 在 `pre_chunks` 表加入 `coordinate_type` 欄位：
  * Video: 使用 `frame_index` (幀號)
  * Text: 使用 `page_number` + `paragraph_index`
* 確保 Schema 可容納未來的檔案類型。

---

### 2.3 低優先級 (Low) — 文檔一致性

#### ℹ️ L1: 術語不一致

| 文件 | 使用的術語 | 建議統一為 |
|------|-----------|-----------|
| `FILE_IDENTITY_API_DESIGN.md` | `file_id` | `file_id` |
| `PROCESSOR_RESUME_STRATEGY.md` | `file_uuid` | `file_id` |
| 現有程式碼 | `uuid` | `file_id` |

**建議**: 全文統一使用 `file_id` 或 `file_uuid`，避免混用。

#### ℹ️ L2: API Response 格式微調

`FILE_IDENTITY_API_DESIGN.md` 定義了 `candidates` 為回應中的 key，但規範說 List 應使用 `data`。

**建議**: 統一使用 `data` 作為 List 回應的 key，或明確列出例外情況。

#### ℹ️ L3: 缺少錯誤碼定義

API 設計中定義了 `{"ok": false, "error": "..."}` 但未列出標準錯誤碼。

**建議**: 新增 `ERROR_CODES.md`，定義如 `E001_FILE_NOT_FOUND` 等標準錯誤。

---

## 3. 架構完整性檢查清單

| 項目 | 狀態 | 說明 |
|------|------|------|
| File 管理 | ✅ | Schema 完整 |
| Identity 管理 | ✅ | Schema 完整 |
| Face/Candidate 管理 | ⚠️ | 缺少明確的 Candidates 查詢邏輯定義 |
| Pre-chunk 定義 | ❌ | **缺少 Schema** (高優先級) |
| Chunk 聚合規則 | ⚠️ | 有目錄但缺少詳細規則文件 |
| Processor 續傳 | ✅ | 設計完整 |
| Resource Registry | ✅ | 設計完整 |
| AI Agent 規範 | ✅ | 設計完整 |
| API 錯誤處理 | ⚠️ | 缺少標準錯誤碼 |
| 遷移策略 | ❌ | **缺少從舊系統到新系統的遷移指南** |

---

## 4. 建議的行動計畫

### Phase 0: 文檔修正 (立即)
* [ ] 在 `FILE_IDENTITY_API_DESIGN.md` 中補充 `pre_chunks` 表 Schema (解決 H2)
* [ ] 明確定義 `faces` vs `file_identities` 的職責分工 (解決 H1)
* [ ] 統一術語 (`file_id` vs `file_uuid`) (解決 L1)

### Phase 1: 補充缺失文檔
* [ ] 撰寫 `CHUNKING/RULES/RULE_SPEC.md` (解決 M1)
* [ ] 撰寫 `MIGRATION_GUIDE.md` (從舊系統過渡)
* [ ] 撰寫 `API_ERROR_CODES.md` (解決 L3)

### Phase 2: 架構對齊
* [ ] 確認 Resource Registry 與現有 Job Worker 的整合路徑 (解決 M2)

---

## 5. 總結

目前的架構設計在**核心概念** (File + Identity + Pre-chunk + Chunk) 上是正確的，方向明確。
主要缺失在於：
1. **`pre_chunks` 表未定義** (最關鍵，影響實作)
2. **Face/Candidate 的關係需要更清晰的表述**
3. **缺少舊系統遷移策略**

建議在進入 Implementation Phase 前，先完成 Phase 0 的文檔修正。

---

## 版本資訊

* 版本: V1.0
* 審查日期: 2026-04-25
* 審查者: OpenCode
