# Project Risk & Issue Outlook

本文件整理當前專案的可預見問題、潛在問題與建議修復方向（依風險與可行性排序）。依據來源：`git log`（97 commits, 2025-11-12~11-26）、`docs/architecture-overview.md`、`openspec/changes/archive/2025-11-26-enhance-memory-management/tasks.md` 等。

## 可預見的問題項目
- **記憶體管理文件缺口**：`openspec/changes/archive/2025-11-26-enhance-memory-management/tasks.md` 的 8.2 文檔未完成，ModelManager/ServicePool/MemoryGuard 的調參與故障處置缺乏 runbook，部署或擴容時易踩坑。方向：補完架構說明、調參指南、故障排解與監控落地範例（Prometheus 指標與警戒值）。
- **PDF 生成回歸風險高**：版面保持與表格/圖片渲染在 `fa1abcd` 之後多次修正（例如 `d33f605`→`92e326b`、`108784a`→`3358d97`、`6e050eb`），顯示缺少自動回歸。方向：建立最小回歸集（多欄文本、含圖表/表格、列表/Span 混排）與 golden PDF/JSON 比對，覆蓋 Direct/OCR 雙軌。
- **最新 OCR 表格格式修復未經回歸**：`6e050eb` 修正 OCR 軌表格資料格式與裁剪，無對應測試。方向：為 OCR 軌加表格解析/PDF 出圖的整合測試，確保與前端下載/展示一致。
- **PP-Structure 參數調校可能影響資源**：`frontend` 支援前端可調 `pp_structure_params`（`2312b4c`），若缺乏 guard，可能放大 GPU/記憶體壓力。方向：在後端對超參做白名單與上限檢查，並納入 MemoryGuard 預估。
- **Chart 能力啟停策略缺少驗證**：`b048f2d` 禁用 → `7e12f16` 重新啟用；缺少覆蓋率與性能數據。方向：為 chart 模型啟用/關閉建立健康檢查與 A/B 測試數據收集。

## 潛在的問題項目
- **UnifiedDocument 結構漂移風險**：雙軌共用輸出，近期多次調整（列表、Span、多欄、LOGO 元素），缺少結構驗證或 schema 鎖定。可能導致前端/匯出器/PDF 生成不一致。方向：定義 JSON Schema 或 pydantic 驗證，建立 contract 測試。
- **服務池與記憶體守護的長時間行為未驗證**：雖有單元/整合測試，缺乏長時間 soak/stress（GPU 記憶碎片、模型 unload/reload、信號處理）。方向：加入 24h soak 測試與記憶體走勢告警，驗證 SIGTERM/SIGINT 清理。
- **LibreOffice 轉檔鏈低觀測性**：Office 直抽與轉 PDF (`ef335cf`) 依賴系統 LibreOffice，缺少失敗監控與重試策略。方向：為轉檔階段增加 metrics/告警，並提供 fallback/重試。
- **前端/後端 API 契約缺少檢查**：多次 V1→V2 遷移與新增參數（`pp_structure_params` 等），目前僅靠 E2E，缺少型別/契約檢查。方向：加入 OpenAPI 契約測試或生成型別校驗（ts-sdk 對齊 FastAPI schema）。
- **混合抽圖/圖片保存路徑邊界**：Direct/OCR 混合抽圖與 `_save_image` 實作曾多次修復，仍缺少對 None/缺檔路徑的防禦。方向：為缺檔/無圖的 PDF 生成加強斷言與 fallback。

## 建議修復與方向
1) **完成記憶體管理文檔與樣板設定**：在 `docs/` 新增 MemoryGuard/ServicePool 調參與故障排除指南，附 `.env` 範例與 Prometheus 規則，對應 tasks 8.2 清單。
2) **建立 PDF/UnifiedDocument 回歸套件**：收集代表性樣本（多欄、表格、列表、含圖/LOGO、OCR/Direct 雙軌），產生 golden JSON/PDF，加入 CI 比對，並為 `6e050eb` 相關表格路徑新增測試。
3) **加入 UnifiedDocument Schema 驗證**：定義 schema（pydantic/JSON Schema），在匯出/PDF 生成前驗證；同時讓前端型別由 OpenAPI 生成以防 drift。
4) **PP-Structure 參數防護與資源估算**：後端實作白名單/上限與 MemoryGuard 預估，避免前端自由調參造成 GPU OOM；增加拒絕/降級回饋。
5) **長時間穩定性與轉檔可觀測性**：增加 soak/stress pipeline，追蹤 GPU/CPU/記憶碎片；為 LibreOffice/轉檔階段加 metrics、重試與錯誤分類告警。