cfe65158a3
- Enable PP-StructureV3's use_doc_orientation_classify feature - Detect rotation angle from doc_preprocessor_res.angle - Swap page dimensions (width <-> height) for 90°/270° rotations - Output PDF now correctly displays landscape-scanned content Also includes: - Archive completed openspec proposals - Add simplify-frontend-ocr-config proposal (pending) - Code cleanup and frontend simplification 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
176 lines
8.9 KiB
Markdown
176 lines
8.9 KiB
Markdown
# Change: Cleanup Dead Code and Improve Code Quality
|
||
|
||
## Why
|
||
|
||
深度代碼盤點發現專案中存在以下問題：
|
||
1. 已廢棄但未刪除的服務文件（507行）
|
||
2. 過時的配置項（已標記 deprecated 但未移除）
|
||
3. 重複的 bbox 處理邏輯散落在 4 個文件中
|
||
4. 未使用的 imports 和類型斷言問題
|
||
5. 多個 TODO 標記需要處理或移除
|
||
6. **Paddle/PP-Structure 相關的禁用功能和補丁代碼**
|
||
|
||
本提案旨在系統性清理這些垃圾代碼，提升代碼質量和可維護性。
|
||
|
||
## What Changes
|
||
|
||
### Phase 1: 刪除廢棄文件 (高優先級)
|
||
|
||
| 文件 | 行數 | 原因 |
|
||
|------|------|------|
|
||
| `backend/app/services/pdf_generator.py` | 507 | 已被 `pdf_generator_service.py` 完全替代，無任何引用 |
|
||
|
||
### Phase 2: 移除過時配置 (高優先級)
|
||
|
||
| 文件 | 配置項 | 原因 |
|
||
|------|--------|------|
|
||
| `backend/app/core/config.py` | `gap_filling_iou_threshold` | 已過時，應使用 IoA 閾值 |
|
||
| `backend/app/core/config.py` | `gap_filling_dedup_iou_threshold` | 已過時，應使用 `gap_filling_dedup_ioa_threshold` |
|
||
|
||
### Phase 3: 提取共用 bbox 工具函數 (中優先級)
|
||
|
||
創建 `backend/app/utils/bbox_utils.py`，統一以下位置的重複邏輯：
|
||
|
||
| 文件 | 函數 | 行號 |
|
||
|------|------|------|
|
||
| `gap_filling_service.py` | `normalized_bbox` property | L51 |
|
||
| `pdf_generator_service.py` | `_get_bbox_coords` | L1859 |
|
||
| `pp_structure_debug.py` | `_normalize_bbox` | L240 |
|
||
| `text_region_renderer.py` | `get_bbox_as_rect` | L162 |
|
||
|
||
### Phase 4: 前端代碼清理 (低優先級)
|
||
|
||
| 文件 | 問題 | 行號 |
|
||
|------|------|------|
|
||
| `ExportPage.tsx` | 未使用的 `CardDescription` import | L5 |
|
||
| `UploadPage.tsx` | `as any` 類型斷言 + TODO | L32-34 |
|
||
| `TaskHistoryPage.tsx` | `as any` 類型斷言 | L337 |
|
||
| `useTaskValidation.ts` | `as any` 類型斷言 | L61 |
|
||
|
||
### Phase 5: 清理禁用的表格補丁功能 (中優先級)
|
||
|
||
以下功能是針對 PP-Structure 輸出缺陷的「補丁行為」，已禁用且不應再使用：
|
||
|
||
| 服務文件 | 配置項 | 狀態 | 說明 | 建議 |
|
||
|----------|--------|------|------|------|
|
||
| `cell_validation_engine.py` | `cell_validation_enabled` | False | 過濾過度檢測的表格單元格 | **可刪除** - 應改進 PP-Structure 而非補丁 |
|
||
| `table_content_rebuilder.py` | `table_content_rebuilder_enabled` | False | 從 Raw OCR 重建表格 HTML | **可刪除** - 補丁行為 |
|
||
| - | `table_quality_check_enabled` | False | 單元格框質量檢查 | **移除配置** - 未完全實現 |
|
||
| - | `table_rendering_prefer_cellboxes` | False | 算法需改進 | **移除配置** - 算法有誤 |
|
||
|
||
### Phase 6: 評估 PP-Structure 模型使用 (需討論)
|
||
|
||
#### 當前使用的模型 (11個)
|
||
|
||
**必需模型 (3個) - 核心 OCR 功能**
|
||
| 模型 | 用途 | 狀態 |
|
||
|------|------|------|
|
||
| `PP-DocLayout_plus-L` | 佈局檢測 | **必需** |
|
||
| `PP-OCRv5_server_det` | 文本檢測 | **必需** |
|
||
| `PP-OCRv5_server_rec` | 文本識別 | **必需** |
|
||
|
||
**表格相關模型 (5個) - 可選但啟用**
|
||
| 模型 | 用途 | 狀態 | 記憶體 |
|
||
|------|------|------|--------|
|
||
| `SLANeXt_wired` | 有邊框表格結構識別 | 啟用 | ~350MB |
|
||
| `SLANeXt_wireless` | 無邊框表格結構識別 | **保守模式下禁用** | ~350MB |
|
||
| `PP-LCNet_x1_0_table_cls` | 表格分類 | 啟用 | ~50MB |
|
||
| `RT-DETR-L_wired_table_cell_det` | 有邊框單元格檢測 | 啟用 | 共享 |
|
||
| `RT-DETR-L_wireless_table_cell_det` | 無邊框單元格檢測 | **保守模式下禁用** | 共享 |
|
||
|
||
**增強功能模型 (2個) - 可選**
|
||
| 模型 | 用途 | 狀態 | 是否需要 |
|
||
|------|------|------|----------|
|
||
| `PP-FormulaNet_plus-L` | 公式轉 LaTeX | 啟用 | 視需求，可禁用節省 ~300MB |
|
||
| `PP-Chart2Table` | 圖表轉表格 | 啟用 | 視需求，可禁用節省 ~200MB |
|
||
|
||
**預處理模型 (3個)**
|
||
| 模型 | 用途 | 狀態 | 建議 |
|
||
|------|------|------|------|
|
||
| `PP-LCNet_x1_0_doc_ori` | 文檔方向檢測 | 啟用 | 保留 |
|
||
| `PP-LCNet_x1_0_textline_ori` | 文本行方向檢測 | 啟用 | 保留 |
|
||
| `UVDoc` | 文檔變形修正 | **禁用** | **可移除配置** - 會導致文檔失真 |
|
||
|
||
#### 禁用的 Gap Filling 功能
|
||
|
||
| 配置項 | 狀態 | 相關代碼 | 建議 |
|
||
|--------|------|----------|------|
|
||
| `gap_filling_enabled` | False | `gap_filling_service.py` | 保留代碼，作為可選增強 |
|
||
| `gap_filling_iou_threshold` | 過時 | config.py | **刪除** - 已被 IoA 閾值取代 |
|
||
| `gap_filling_dedup_iou_threshold` | 過時 | config.py | **刪除** - 已被 IoA 閾值取代 |
|
||
|
||
## Impact
|
||
|
||
- **Affected specs**: 無（純代碼清理，不改變系統行為）
|
||
- **Affected code**:
|
||
- Backend: 刪除 1-3 個文件，修改 config.py，創建 bbox_utils.py
|
||
- Frontend: 修改 4 個文件（類型改進）
|
||
- **記憶體影響**: 如移除無邊框表格模型，可節省 ~700MB GPU 記憶體
|
||
|
||
## Benefits
|
||
|
||
- 減少約 **600-1,500 行**冗餘代碼（視 Phase 5-6 範圍）
|
||
- 統一 bbox 處理邏輯，減少重複代碼 **80-100 行**
|
||
- 提升 TypeScript 類型安全性
|
||
- 移除過時配置和補丁代碼，減少維護負擔
|
||
- 精簡 PP-Structure 模型配置，提升可讀性
|
||
|
||
## Risk Assessment
|
||
|
||
- **風險等級**: 低-中
|
||
- **Phase 1-2**: 無風險（刪除未使用的代碼）
|
||
- **Phase 3**: 低風險（重構，需要測試）
|
||
- **Phase 4**: 低風險（類型改進）
|
||
- **Phase 5**: 低風險（刪除禁用的補丁代碼）
|
||
- **Phase 6**: 中風險（需評估模型是否還需要）
|
||
- **回滾策略**: Git revert
|
||
|
||
## Paddle/PP-Structure 使用情況摘要
|
||
|
||
### 直接使用 Paddle 的文件 (僅 3 個)
|
||
|
||
| 文件 | 行數 | 功能 |
|
||
|------|------|------|
|
||
| `ocr_service.py` | ~2,590 | OCR 引擎管理、GPU 配置、模型卸載 |
|
||
| `pp_structure_enhanced.py` | ~1,324 | PP-StructureV3 結果解析、元素提取 |
|
||
| `memory_manager.py` | ~2,269 | GPU 記憶體監控、多後端支持 |
|
||
|
||
### 表格解析模式 (table_parsing_mode)
|
||
|
||
| 模式 | 說明 | 適用場景 |
|
||
|------|------|----------|
|
||
| `full` | 激進，完整表格檢測 | 表格密集的文檔 |
|
||
| `conservative` | **當前使用**，禁用無邊框表格 | 混合文檔 |
|
||
| `classification_only` | 僅識別表格區域，無結構解析 | 數據表/電子表格 |
|
||
| `disabled` | 完全禁用表格識別 | 純文本文檔 |
|
||
|
||
### 補丁 vs 核心功能分類
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 核心功能 (必須保留) │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ • PaddleOCR 文本識別 │
|
||
│ • PP-DocLayout 佈局檢測 │
|
||
│ • SLANeXt 表格結構識別 │
|
||
│ • 記憶體管理和自動卸載 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 補丁功能 (建議移除) │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ • cell_validation_engine.py - 過度檢測過濾 │
|
||
│ • table_content_rebuilder.py - 表格內容重建 │
|
||
│ • table_quality_check - 未完全實現 │
|
||
│ • table_rendering_prefer_cellboxes - 算法有誤 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 可選增強 (保留代碼，按需啟用) │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ • gap_filling_service.py - OCR 補充遺漏區域 │
|
||
│ • PP-FormulaNet - 公式識別 │
|
||
│ • PP-Chart2Table - 圖表識別 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|