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

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

Summary

優化 OCR/Direct Track 任務處理過程中的檔案生成策略，移除不必要的檔案，並提供視覺化圖片下載功能。

檔案變更總覽

OCR Track 檔案變更

檔案	目前狀態	變更後	影響
*_result.json	生成	保留	核心資料，API/前端依賴
*_output.md	生成	停止生成	移除前端下載按鈕
*_layout.pdf / *_reflow.pdf	生成	保留	主要輸出格式
*_raw_ocr_regions.json	生成	保留	翻譯服務依賴
*_scan_page_N.png	生成	保留	OCR 處理和 PDF 生成需要
visualization/*.png	生成	保留	新增下載功能
standalone_img_*.png	生成	保留	result.json 引用，PDF 生成需要
img_in_table_*.png	生成	保留	result.json 引用，PDF 生成需要
pp3_*.png	生成	保留	result.json 引用，PDF 生成需要
*_pp_structure_raw.json	生成	停止生成	純 Debug，預設關閉
*_debug_summary.json	生成	停止生成	純 Debug，預設關閉
*_pp_structure_viz.png	生成	停止生成	純 Debug，預設關閉

Direct Track 檔案變更

檔案	目前狀態	變更後	影響
*_result.json	生成	保留	核心資料，API/前端依賴
*_output.md	生成	停止生成	移除前端下載按鈕
*_layout.pdf / *_reflow.pdf	生成	保留	主要輸出格式
f66673cc_p*_img*.png	生成	保留	result.json 引用，PDF 生成需要
f66673cc_p*_chart*.png	生成	保留	result.json 引用，PDF 生成需要

變更摘要

Track	停止生成的檔案	預估節省空間
OCR Track	*_output.md, *_pp_structure_raw.json, *_debug_summary.json, *_pp_structure_viz.png	~300-1500 KB/頁
Direct Track	*_output.md	~1-3 KB/檔案

後端變更

1. config.py - 修改預設值

# 修改前
pp_structure_debug_enabled: bool = Field(default=True)
pp_structure_debug_visualization: bool = Field(default=True)

# 修改後
pp_structure_debug_enabled: bool = Field(default=False)
pp_structure_debug_visualization: bool = Field(default=False)

影響：OCR Track 不再生成 debug 檔案（*_pp_structure_raw.json, *_debug_summary.json, *_pp_structure_viz.png）

2. unified_document_exporter.py - 停止生成 Markdown

修改 export_all() 方法，不再生成 *_output.md 檔案。

影響：兩個 Track 都不再生成 Markdown 檔案

3. ocr_service.py - 更新 save_results()

修改 save_results() 方法，不再生成 Markdown 檔案，返回值調整。

4. tasks.py (router) - 移除 Markdown 下載端點

移除或標記棄用 GET /api/v2/tasks/{task_id}/download/markdown 端點。

5. tasks.py (router) - 新增 visualization 下載端點

@router.get("/{task_id}/visualization-download")
async def download_visualization_zip(task_id: str, ...):
    """
    Download visualization images as ZIP file.
    Only available for OCR Track tasks with visualization folder.
    """
    # 檢查 visualization 資料夾是否存在
    # 打包資料夾內所有 PNG 為 ZIP
    # 返回 StreamingResponse (application/zip)

6. Task model/schema - 更新欄位

• 移除 result_markdown_path 欄位使用（保留欄位但不再寫入）
• 新增 has_visualization: bool 到 TaskDetail response

前端變更

1. TaskHistoryPage.tsx - 移除 Markdown 下載按鈕

// 移除此段
{task.result_markdown_path && (
  <Button onClick={() => handleDownload(task.task_id, 'markdown')}>
    MD
  </Button>
)}

2. ResultsPage.tsx - 移除 Markdown 下載按鈕

// 移除此段
<Button onClick={handleDownloadMarkdown}>
  Markdown
</Button>

3. apiV2.ts - 移除/新增 API 方法

// 移除
async downloadMarkdown(taskId: string): Promise<void>

// 新增
async downloadVisualization(taskId: string): Promise<Blob>

4. types/apiV2.ts - 更新 TaskDetail type

export interface TaskDetail {
  // ... 現有欄位
  has_visualization?: boolean  // 新增
}

5. TaskDetailPage.tsx - 新增 visualization 下載按鈕

// OCR Track 且有 visualization 時顯示
{task.has_visualization && (
  <Button onClick={handleDownloadVisualization}>
    <ImageIcon className="w-4 h-4 mr-2" />
    下載辨識結果圖片
  </Button>
)}

依賴關係確認

必須保留的檔案及原因

檔案	依賴來源	用途
*_result.json	API、前端、翻譯服務	核心結構化資料
*_raw_ocr_regions.json	translation_service.py	OCR Track 翻譯時讀取
*_scan_page_N.png	pdf_generator_service.py	Reflow PDF 生成
visualization/*.png	使用者下載	OCR 辨識結果視覺化
所有提取的圖片	*_result.json 中的 saved_path	PDF 生成時嵌入圖片

可移除的檔案及原因

檔案	原因
*_output.md	前端移除下載按鈕後無使用場景
*_pp_structure_raw.json	純 Debug 用途，生產環境不需要
*_debug_summary.json	純 Debug 用途，生產環境不需要
*_pp_structure_viz.png	純 Debug 用途，生產環境不需要

設定說明

後端設定 (.env.local)

# Debug 檔案生成（預設關閉）
PP_STRUCTURE_DEBUG_ENABLED=false
PP_STRUCTURE_DEBUG_VISUALIZATION=false

# 如需開啟 debug 檔案生成
PP_STRUCTURE_DEBUG_ENABLED=true
PP_STRUCTURE_DEBUG_VISUALIZATION=true

前端設定

無需額外設定，移除下載按鈕後自動生效。

向後相容性

1. API 端點 - GET /download/markdown 可保留但返回 404 或棄用訊息
2. 資料庫欄位 - result_markdown_path 欄位保留，但新任務不再寫入
3. 舊任務 - 已存在的 Markdown 檔案不受影響，仍可下載

Implementation Plan

1. 後端：修改 config.py 預設值（關閉 debug）
2. 後端：修改 unified_document_exporter.py 停止生成 Markdown
3. 後端：修改 ocr_service.py save_results() 不生成 Markdown
4. 後端：新增 visualization 下載端點
5. 後端：更新 TaskDetail response 加入 has_visualization
6. 前端：移除 TaskHistoryPage Markdown 下載按鈕
7. 前端：移除 ResultsPage Markdown 下載按鈕
8. 前端：移除 apiV2.ts downloadMarkdown 方法
9. 前端：新增 visualization 下載功能
10. 測試並驗證