# Debug 参数控制设计文档 v2

## 当前实现方案（v2 - 分模块控制）

**设计理念**：提供全局和精细两种控制方式，命令行参数直接覆盖配置文件设置。

### 控制层级

```
命令行参数（4个独立开关）
    ↓ 调用
_apply_debug_overrides() 函数
    ↓ 直接修改
pipeline.config['xxx']['debug_options']['enabled'] = True
    ↓ 各模块读取
layout_detector / table_classifier / wired_table 等使用各自的 debug_options
```

---

## 命令行参数设计

### 新增 4 个 debug 参数

```python
parser.add_argument("--debug", action="store_true",
    help="开启全局debug模式（启用所有模块的调试输出）")

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
```

---

## 核心实现：`_apply_debug_overrides()` 函数

### 函数签名

```python
def _apply_debug_overrides(
    pipeline,
    debug: bool,
    debug_layout: bool,
    debug_table: bool,
    debug_ocr: bool,
    output_config: dict
):
```

### 覆盖逻辑

```python
# 1. 确定需要启用哪些模块的 debug
enable_layout_debug = debug or debug_layout
enable_table_debug = debug or debug_table
enable_ocr_debug = debug or debug_ocr

# 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
```

### 优先级规则

| 条件 | 结果 |
|------|------|
| 命令行无任何 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: 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:
    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: ""
```

### ❌ 不推荐的配置

```yaml
# ❌ enabled: true 会导致永远开启，无法被命令行关闭
table_recognition_wired:
  debug_options:
    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):
    # 实现配置覆盖逻辑
```

**更新调用：**
```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)
```

### 2. 配置文件（需要更新）

所有场景配置文件中的 `debug_options.enabled` 改为 `false`：
- `bank_statement_yusys_v4.yaml`
- `bank_statement_yusys_v3.yaml`
- `bank_statement_mineru_vl.yaml`
- 等其他配置文件...

---

## 优势对比

### 新方案优势（v2）

✅ **灵活性高**
- 全局开关：`--debug` 一键全开
- 精细控制：`--debug-layout` 定位特定问题
- 组合使用：可以同时启用多个特定模块

✅ **实现简洁**
- 无需逐层传递参数（避免穿透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` 精准排查