OCR/openspec/changes/archive/2025-12-11-cleanup-dead-code/proposal.md

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 - 圖表識別                                 │
└─────────────────────────────────────────────────────────────┘