feat(debug参数控制): 更新文档以反映新的调试参数设计，支持全局和模块级调试控制

docs/ocr_tools/universal_doc_parser/debug参数控制.md

@@ -1,109 +1,308 @@
-## 当前问题诊断
+# Debug 参数控制设计文档 v2
 
-**共 5 处断裂点：**
+## 当前实现方案（v2 - 分模块控制）
 
-| # | 问题 | 位置 |
-|---|---|---|
-| 1 | `--debug` CLI 参数**从未传进** `pipeline.debug_mode` | main_v2.py：yaml 有 output 块时，`debug` 参数被完全丢弃 |
-| 2 | `_process_all_elements` 调用时**没有穿透** `debug_mode` | pipeline_manager_v2.py：element_processors 看不到 pipeline 层的 debug 状态 |
-| 3 | `element_processors` 构建子模块 `debug_options` 时**漏掉了 `enabled`** | 只注入了 `output_dir`/`prefix`，子模块即使拿到路径也不会输出 |
-| 4 | 新旧两套系统（`debug_mode` vs `debug_options.enabled`）**无统一激活入口** | base.py 做了兼容读取但没有统一写入 |
-| 5 | streaming 模式**完全不传播** `debug_mode` | `pipeline_manager_v2_streaming.py` |
+**设计理念**：提供全局和精细两种控制方式，命令行参数直接覆盖配置文件设置。
 
----
+### 控制层级
+
+```
+命令行参数（4个独立开关）
+    ↓ 调用
+_apply_debug_overrides() 函数
+    ↓ 直接修改
+pipeline.config['xxx']['debug_options']['enabled'] = True
+    ↓ 各模块读取
+layout_detector / table_classifier / wired_table 等使用各自的 debug_options
+```
 
-## 建议设计：单一开关 → 逐层传播
+---
 
-**核心原则**：命令行 `--debug` 是唯一的顶层开关，向下覆盖 yaml 配置。
+## 命令行参数设计
 
-### 第一层：main_v2.py — 写入 pipeline.debug_mode
+### 新增 4 个 debug 参数
 
 ```python
-# process_single_input 中，创建 pipeline 后立即覆盖 debug_mode
-pipeline = _create_pipeline(...)
+parser.add_argument("--debug", action="store_true",
+    help="开启全局debug模式（启用所有模块的调试输出）")
 
-# 命令行 --debug 优先级高于 yaml
-if debug:
-    pipeline.debug_mode = True
-    # 同步覆盖 output 配置
-    pipeline.config.setdefault('output', {})['debug_mode'] = True
+parser.add_argument("--debug-layout", action="store_true",
+    help="仅开启布局检测的debug输出")
+
+parser.add_argument("--debug-table", action="store_true",
+    help="仅开启表格识别的debug输出")
+
+parser.add_argument("--debug-ocr", action="store_true",
+    help="仅开启OCR识别的debug输出")
+```
+
+### 使用示例
+
+```bash
+# 1. 全局 debug（开发阶段完整调试）
+python main_v2.py -i test.pdf -c config.yaml --debug
+
+# 2. 定位布局问题（只看 layout 输出）
+python main_v2.py -i test.pdf -c config.yaml --debug-layout
+
+# 3. 定位表格问题（只看 table 输出）
+python main_v2.py -i test.pdf -c config.yaml --debug-table
+
+# 4. 组合使用（layout + table，不包括OCR）
+python main_v2.py -i test.pdf -c config.yaml --debug-layout --debug-table
+
+# 5. 正常运行（无 debug 输出）
+python main_v2.py -i test.pdf -c config.yaml
 ```
 
-### 第二层：pipeline_manager_v2.py — 向子模块传播
+---
+
+## 核心实现：`_apply_debug_overrides()` 函数
 
-在 `_process_all_elements` 调用处加入 debug 参数传递（pipeline → element_processors）：
+### 函数签名
 
 ```python
-processed_elements, discarded_elements = self._process_all_elements(
-    ...
-    debug_mode=self.debug_mode,   # ← 补充这一项
-    output_dir=output_dir,
-)
+def _apply_debug_overrides(
+    pipeline,
+    debug: bool,
+    debug_layout: bool,
+    debug_table: bool,
+    debug_ocr: bool,
+    output_config: dict
+):
 ```
 
-### 第三层：element_processors.py — 构建 debug_options 时加上 enabled
+### 覆盖逻辑
 
 ```python
-# 当前（缺失 enabled）
-debug_opts_override = {'output_dir': output_dir, 'prefix': basename}
+# 1. 确定需要启用哪些模块的 debug
+enable_layout_debug = debug or debug_layout
+enable_table_debug = debug or debug_table
+enable_ocr_debug = debug or debug_ocr
 
-# 修正后
-debug_opts_override = {
-    'enabled': debug_mode,        # ← 缺失的这一项
-    'output_dir': output_dir,
-    'prefix': basename,
-}
+# 2. 更新 pipeline 全局状态
+if debug or debug_layout or debug_table or debug_ocr:
+    pipeline.debug_mode = True
+    output_config['debug_mode'] = True
+
+# 3. 直接修改配置文件中的 debug_options.enabled
+if enable_layout_debug:
+    config['layout_detection']['debug_options']['enabled'] = True
+
+if enable_table_debug:
+    config['table_classification']['debug_options']['enabled'] = True
+    config['table_recognition_wired']['debug_options']['enabled'] = True
+
+if enable_ocr_debug:
+    config['ocr_recognition']['debug_options']['enabled'] = True
 ```
 
-### yaml 配置建议：`debug_options` 应只配置**保存内容**，不配 `enabled`
+### 优先级规则
 
-各子模块的 `debug_options` 只负责描述"调试时保存什么"，`enabled` 动态注入：
+| 条件 | 结果 |
+|------|------|
+| 命令行无任何 debug 参数 | 使用配置文件默认值（通常为 false） |
+| 命令行有 `--debug` | 所有模块 debug 启用 |
+| 命令行有 `--debug-layout` | 仅布局检测 debug 启用 |
+| 命令行有 `--debug-table` | 仅表格相关 debug 启用 |
+| 命令行有 `--debug-layout --debug-table` | 布局+表格 debug 启用，OCR 不启用 |
+
+---
+
+## YAML 配置文件规范
+
+### 推荐配置（enabled 默认 false）
+
+各模块的 `debug_options` 只描述"调试时保存什么内容"，`enabled` 字段默认为 `false`，由命令行参数动态控制：
 
 ```yaml
-# ✅ 推荐：只描述保存项，enabled 由运行时控制
+# ✅ 推荐：enabled: false，由命令行控制
+layout_detection:
+  debug_options:
+    enabled: false              # 默认关闭，--debug 或 --debug-layout 时启用
+    output_dir: null            # null = 跟随主输出目录
+    prefix: ""                  # 文件名前缀
+
+table_classification:
+  debug_options:
+    enabled: false              # 默认关闭，--debug 或 --debug-table 时启用
+    output_dir: null
+    save_table_lines: true      # 描述保存哪些内容
+    image_format: "png"
+    prefix: ""
+
 table_recognition_wired:
   debug_options:
-    output_dir: null        # null = 随输出目录
+    enabled: false              # 默认关闭，--debug 或 --debug-table 时启用
+    output_dir: null
     save_table_lines: true
+    save_connected_components: true
     save_grid_structure: true
     save_text_overlay: true
+    image_format: "png"
+    prefix: ""
+```
 
-# ❌ 不推荐：hardcode enabled: true，会绕过命令行开关
+### ❌ 不推荐的配置
+
+```yaml
+# ❌ enabled: true 会导致永远开启，无法被命令行关闭
 table_recognition_wired:
   debug_options:
-    enabled: true           # 这会永远开启，无法被命令行关闭
+    enabled: true               # 硬编码为 true，会绕过命令行控制
 ```
 
 ---
 
-## 推荐的完整控制层级
+## 代码修改清单
 
+### 1. main_v2.py（已完成）
+
+**新增参数：**
+```python
+parser.add_argument("--debug", ...)
+parser.add_argument("--debug-layout", ...)
+parser.add_argument("--debug-table", ...)
+parser.add_argument("--debug-ocr", ...)
+```
+
+**新增函数：**
+```python
+def _apply_debug_overrides(pipeline, debug, debug_layout, debug_table, debug_ocr, output_config):
+    # 实现配置覆盖逻辑
 ```
-命令行 --debug
-    ↓ 写入
-pipeline.debug_mode（覆盖 yaml output.debug_mode）
-    ↓ 注入（已有）
-layout_detector.debug_mode
-    ↓ 注入（待补）
-element_processors(debug_mode=...)
-    ↓ 构建（待补 enabled 字段）
-wired_table.recognize(debug_options={'enabled': debug_mode, ...})
-table_classifier.classify(debug_options={'enabled': debug_mode, ...})
+
+**更新调用：**
+```python
+def process_single_input(..., debug, debug_layout, debug_table, debug_ocr, ...):
+    pipeline = _create_pipeline(...)
+    _apply_debug_overrides(pipeline, debug, debug_layout, debug_table, debug_ocr, output_config)
 ```
 
-`--log_level` 与 debug 是**独立维度**，不需要联动，按现有设计保持即可。
+### 2. 配置文件（需要更新）
+
+所有场景配置文件中的 `debug_options.enabled` 改为 `false`：
+- `bank_statement_yusys_v4.yaml`
+- `bank_statement_yusys_v3.yaml`
+- `bank_statement_mineru_vl.yaml`
+- 等其他配置文件...
 
 ---
 
-## 需要修改的文件清单
+## 优势对比
+
+### 新方案优势（v2）
+
+✅ **灵活性高**
+- 全局开关：`--debug` 一键全开
+- 精细控制：`--debug-layout` 定位特定问题
+- 组合使用：可以同时启用多个特定模块
 
-| 文件 | 改动 |
-|---|---|
-| main_v2.py | `--debug` 写入 `pipeline.debug_mode` |
-| pipeline_manager_v2.py | `_process_all_elements` 传入 `debug_mode` |
-| core/element_processors.py | 接收并向子模块传递 `debug_mode`，构建 `debug_options` 时加 `enabled` |
-| pipeline_manager_v2_streaming.py | 同步补充 debug_mode 传播（与 v2 保持一致） |
-| yaml 配置文件 | 各模块 `debug_options.enabled` 改为 `false`（运行时由命令行控制） |
+✅ **实现简洁**
+- 无需逐层传递参数（避免穿透5层架构）
+- 直接修改配置字典（一次性生效）
+- 各模块独立读取（解耦合）
+
+✅ **易于扩展**
+- 新增模块只需在 `_apply_debug_overrides()` 添加一个 if 分支
+- 不需要修改处理流水线的参数传递链路
+
+✅ **用户体验好**
+- 减少不必要的 debug 输出（针对性调试）
+- 加快调试速度（只看关心的模块）
+
+### 旧方案问题（v1）
+
+❌ 需要逐层穿透传递 `debug_mode` 参数：
+```
+main_v2.py → pipeline → _process_all_elements → element_processors → 各子模块
+```
+
+❌ 参数传递链路长，容易在某一层断裂
+
+❌ 只有全局开关，无法精细控制
+
+---
+
+## Debug 输出内容
+
+### 布局检测 debug（--debug-layout）
+
+输出文件：
+- `{basename}_page_{n}_layout.png` - 布局检测框可视化
+
+### 表格识别 debug（--debug-table）
+
+**表格分类**：
+- `{basename}_page_{n}_table_{i}_classification.png` - 有线/无线分类结果
+
+**有线表格识别**：
+- `{basename}_page_{n}_table_{i}_lines.png` - UNet 表格线检测
+- `{basename}_page_{n}_table_{i}_cells.png` - 单元格连通域
+- `{basename}_page_{n}_table_{i}_grid.png` - 逻辑网格结构
+- `{basename}_page_{n}_table_{i}_text_overlay.png` - 文本填充结果
+
+### OCR 识别 debug（--debug-ocr）
+
+输出文件：
+- `{basename}_page_{n}_ocr.png` - OCR 检测框和识别结果
+
+---
+
+## 与日志系统的关系
+
+**Debug 输出** 和 **日志级别** 是两个独立维度：
+
+| 参数 | 控制内容 | 输出位置 |
+|------|---------|---------|
+| `--debug` 系列 | 可视化图片输出 | 文件系统（output_dir） |
+| `--log_level` | 日志消息详细程度 | 控制台 / 日志文件 |
+
+**可以组合使用：**
+```bash
+# 开启详细日志 + 表格 debug 图片
+python main_v2.py -i test.pdf -c config.yaml --log_level DEBUG --debug-table
+```
 
 ---
-## 结语
+
+## 未来扩展建议
+
+### 1. 支持环境变量控制
+
+```bash
+export DEBUG_LAYOUT=1
+export DEBUG_TABLE=1
+python main_v2.py -i test.pdf -c config.yaml
+```
+
+### 2. 支持配置文件全局 debug 开关
+
+```yaml
+global:
+  debug_mode: false         # 全局默认值
+  debug_modules: []         # 或指定 ["layout", "table"]
+```
+
+### 3. 支持 debug 输出到独立目录
+
+```bash
+python main_v2.py -i test.pdf -c config.yaml --debug --debug-dir ./debug_output/
+```
+
+---
+
+## 总结
+
+**当前实现（v2）的核心特点：**
+
+1. ✅ **命令行优先**：`--debug` 参数是唯一的顶层开关
+2. ✅ **直接覆盖**：通过 `_apply_debug_overrides()` 直接修改配置字典
+3. ✅ **精细控制**：支持全局和分模块两种模式
+4. ✅ **配置解耦**：YAML 只描述"保存什么"，不控制"是否启用"
+5. ✅ **易于维护**：无需修改处理流水线的参数传递链路
+
+**最佳实践：**
+- 开发阶段：使用 `--debug` 全局调试
+- 生产环境：不加任何 debug 参数
+- 问题定位：使用 `--debug-layout` / `--debug-table` 精准排查