OCR/openspec/changes/archive/2025-12-12-optimize-task-files-and-visualization/tasks.md

Tasks: 優化任務檔案生成與視覺化下載

1. 後端設定優化

• 1.1 修改 config.py debug 預設值
  • pp_structure_debug_enabled: True → False
  • pp_structure_debug_visualization: True → False

2. 後端 Visualization 下載 API

• 2.1 在 tasks.py 新增 visualization 下載端點

  • GET /api/v2/tasks/{task_id}/download/visualization
  • 檢查 visualization 資料夾是否存在
  • 打包資料夾內所有 PNG 為 ZIP
  • 返回 StreamingResponse (application/zip)

• 2.2 在 TaskDetail response 中加入 has_visualization 欄位

  • 檢查 task result directory 下是否有 visualization 資料夾
  • 回傳 boolean 值

3. 前端 Visualization 下載功能

• 3.1 在 types/apiV2.ts 更新 TaskDetail type

  • 新增 has_visualization?: boolean

• 3.2 在 apiV2.ts 新增下載方法

  • downloadVisualization(taskId: string): Promise<void>

• 3.3 在 TaskDetailPage.tsx 新增下載按鈕

  • 只有 has_visualization = true 時顯示
  • 點擊後下載 ZIP 檔案

4. 停止生成 Markdown 檔案

• 4.1 修改 ocr_service.py 的 save_results() 方法

  • 移除 Markdown 檔案生成
  • 返回值中 markdown_path 始終為 None

• 4.2 修改 unified_document_exporter.py

  • export_all(): 移除 Markdown 導出
  • export_formats(): 移除 Markdown 支援

• 4.3 前端 TaskHistoryPage.tsx 移除 JSON/MD 下載按鈕

  • 改為版面 PDF 和流式 PDF 兩個下載按鈕

5. 確保 raw_ocr_regions.json 正常生成

• 5.1 將 raw_ocr_regions.json 生成從 debug 區塊分離

  • 獨立於 pp_structure_debug_enabled 設定
  • 此檔案為 PDF 生成和翻譯服務所必需

• 5.2 在 pp_structure_debug.py 新增 save_debug_results() 方法

  • 只保存純 debug 檔案（_pp_structure_raw.json, _debug_summary.json）
  • 不再重複保存 _raw_ocr_regions.json

6. Bug 修復

• 6.1 修復 Processing 頁面不切換到新任務的問題
  • 在 useTaskValidation.ts 中加入 taskId 變化時重置 isNotFound 的邏輯

7. 測試與驗證

• 7.1 驗證 TypeScript 編譯通過
• 7.2 驗證 *_raw_ocr_regions.json 仍正常生成
• 7.3 驗證 visualization 資料夾仍正常生成
• 7.4 測試 visualization 下載功能
• 7.5 驗證 PDF 內容正常顯示
• 7.6 驗證新任務上傳後 Processing 頁面正確切換