feat: optimize task file generation and add visualization download

Backend changes: - Disable PP-Structure debug file generation by default - Separate raw_ocr_regions.json generation from debug flag (critical file) - Add visualization folder download endpoint as ZIP - Add has_visualization field to TaskDetailResponse - Stop generating Markdown files - Save translated PDFs to task folder with caching Frontend changes: - Replace JSON/MD download buttons with PDF buttons in TaskHistoryPage - Add visualization download button in TaskDetailPage - Fix Processing page task switching issue (reset isNotFound) Archives two OpenSpec proposals: - optimize-task-files-and-visualization - simplify-frontend-add-billing 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-12 19:11:50 +08:00
parent 65abd51d60
commit efa7e4175c
14 changed files with 534 additions and 97 deletions
--- a/openspec/changes/archive/2025-12-12-optimize-task-files-and-visualization/proposal.md
+++ b/openspec/changes/archive/2025-12-12-optimize-task-files-and-visualization/proposal.md
@@ -0,0 +1,201 @@
+# 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. 測試並驗證
--- a/openspec/changes/archive/2025-12-12-optimize-task-files-and-visualization/tasks.md
+++ b/openspec/changes/archive/2025-12-12-optimize-task-files-and-visualization/tasks.md
@@ -0,0 +1,68 @@
+# Tasks: 優化任務檔案生成與視覺化下載
+
+## 1. 後端設定優化
+
+- [x] 1.1 修改 `config.py` debug 預設值
+  - `pp_structure_debug_enabled`: `True` → `False`
+  - `pp_structure_debug_visualization`: `True` → `False`
+
+## 2. 後端 Visualization 下載 API
+
+- [x] 2.1 在 `tasks.py` 新增 visualization 下載端點
+  - `GET /api/v2/tasks/{task_id}/download/visualization`
+  - 檢查 visualization 資料夾是否存在
+  - 打包資料夾內所有 PNG 為 ZIP
+  - 返回 StreamingResponse (application/zip)
+
+- [x] 2.2 在 TaskDetail response 中加入 `has_visualization` 欄位
+  - 檢查 task result directory 下是否有 visualization 資料夾
+  - 回傳 boolean 值
+
+## 3. 前端 Visualization 下載功能
+
+- [x] 3.1 在 `types/apiV2.ts` 更新 TaskDetail type
+  - 新增 `has_visualization?: boolean`
+
+- [x] 3.2 在 `apiV2.ts` 新增下載方法
+  - `downloadVisualization(taskId: string): Promise<void>`
+
+- [x] 3.3 在 `TaskDetailPage.tsx` 新增下載按鈕
+  - 只有 `has_visualization = true` 時顯示
+  - 點擊後下載 ZIP 檔案
+
+## 4. 停止生成 Markdown 檔案
+
+- [x] 4.1 修改 `ocr_service.py` 的 `save_results()` 方法
+  - 移除 Markdown 檔案生成
+  - 返回值中 `markdown_path` 始終為 `None`
+
+- [x] 4.2 修改 `unified_document_exporter.py`
+  - `export_all()`: 移除 Markdown 導出
+  - `export_formats()`: 移除 Markdown 支援
+
+- [x] 4.3 前端 TaskHistoryPage.tsx 移除 JSON/MD 下載按鈕
+  - 改為版面 PDF 和流式 PDF 兩個下載按鈕
+
+## 5. 確保 raw_ocr_regions.json 正常生成
+
+- [x] 5.1 將 `raw_ocr_regions.json` 生成從 debug 區塊分離
+  - 獨立於 `pp_structure_debug_enabled` 設定
+  - 此檔案為 PDF 生成和翻譯服務所必需
+
+- [x] 5.2 在 `pp_structure_debug.py` 新增 `save_debug_results()` 方法
+  - 只保存純 debug 檔案（`_pp_structure_raw.json`, `_debug_summary.json`）
+  - 不再重複保存 `_raw_ocr_regions.json`
+
+## 6. Bug 修復
+
+- [x] 6.1 修復 Processing 頁面不切換到新任務的問題
+  - 在 `useTaskValidation.ts` 中加入 taskId 變化時重置 `isNotFound` 的邏輯
+
+## 7. 測試與驗證
+
+- [x] 7.1 驗證 TypeScript 編譯通過
+- [ ] 7.2 驗證 `*_raw_ocr_regions.json` 仍正常生成
+- [ ] 7.3 驗證 visualization 資料夾仍正常生成
+- [ ] 7.4 測試 visualization 下載功能
+- [ ] 7.5 驗證 PDF 內容正常顯示
+- [ ] 7.6 驗證新任務上傳後 Processing 頁面正確切換