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 - 修改預設值

```python
# 修改前
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 下載端點

```python
@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 下載按鈕

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

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

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

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

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

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

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

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

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

```tsx
// 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)

```bash
# 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. 測試並驗證