feat: 添加OCR结果对比模块的详细说明文档

comparator/README.md

@@ -0,0 +1,943 @@
+# 📊 OCR 结果对比模块 (Comparator)
+
+OCR 结果对比模块提供了强大的文档对比功能，支持表格、段落的细粒度差异检测，特别优化了财务报表、流水表格等复杂文档的对比。
+
+## 📁 模块结构
+
+```
+comparator/
+├── __init__.py                      # 模块初始化
+├── compare_ocr_results.py           # 命令行对比工具（入口）
+├── ocr_comparator.py                # 核心对比器
+├── table_comparator.py              # 表格对比器 ✨
+├── paragraph_comparator.py          # 段落对比器
+├── similarity_calculator.py         # 相似度计算器
+├── data_type_detector.py            # 数据类型检测器
+├── content_extractor.py             # 内容提取器
+├── text_processor.py                # 文本处理器
+├── report_generator.py              # 报告生成器
+└── README.md                        # 本文档
+```
+
+## ✨ 核心功能
+
+### 🎯 智能表格对比
+
+#### 1. 两种对比模式
+
+**标准模式 (`standard`)**
+- 适用于结构固定的表格
+- 逐行逐列精确对比
+- 不进行表头检测
+- 适合：静态报表、统计表
+
+**流水模式 (`flow_list`)** ✨
+- 适用于结构可变的表格
+- **智能表头检测**（关键词匹配）
+- **支持多层表头识别**（如资产负债表）
+- 列类型自动检测
+- 差异严重度智能分级
+- 适合：流水表、财务报表、交易记录
+
+
+#### 2. 列类型自动检测
+
+**支持的数据类型：**
+
+| 类型 | 标识 | 特征 | 示例 |
+|------|------|------|------|
+| 数字金额 | `numeric` | 包含数字、小数点、逗号 | `28,239,305.48` |
+| 日期时间 | `datetime` | 符合日期格式 | `2023-12-31` / `2023年12月31日` |
+| 文本型数字 | `text_number` | 纯数字但作为文本（如票据号） | `20231231001` |
+| 普通文本 | `text` | 其他文本内容 | `货币资金` |
+
+**检测算法：**
+
+```python
+def detect_column_type(column_values):
+    """检测列的数据类型"""
+    numeric_count = 0
+    datetime_count = 0
+    text_number_count = 0
+    
+    for value in column_values:
+        if is_numeric(value):
+            numeric_count += 1
+        elif is_datetime(value):
+            datetime_count += 1
+        elif is_text_number(value):
+            text_number_count += 1
+    
+    # 超过 60% 认定为该类型
+    total = len(column_values)
+    if numeric_count / total > 0.6:
+        return 'numeric'
+    elif datetime_count / total > 0.6:
+        return 'datetime'
+    elif text_number_count / total > 0.6:
+        return 'text_number'
+    else:
+        return 'text'
+```
+
+#### 4. 差异严重度分级 ✨
+
+**基础严重度（由单元格内容决定）：**
+
+| 差异类型 | 基础严重度 | 说明 |
+|---------|----------|------|
+| `table_amount` | **high** | 金额数字不一致 |
+| `table_datetime` | **medium** | 日期时间不一致 |
+| `table_text` | **low/medium** | 文本不一致（根据相似度） |
+| `table_header_position` | **high** | 表头位置不一致 |
+| `table_header_content` | **high** | 表头内容不一致 |
+| `table_row_missing` | **high** | 行数不一致 |
+| `table_column_missing` | **high** | 列数不一致 |
+
+**列类型冲突自动提升：** ✨
+
+```python
+# 如果列类型不一致，自动将严重度提升到 high
+if col_idx in mismatched_columns:
+    if base_severity != 'high':
+        final_severity = 'high'
+        description += " [列类型冲突]"
+```
+
+**示例：**
+
+```json
+{
+  "type": "table_text",
+  "severity": "high",  // 从 low 提升到 high
+  "column_type_mismatch": true,
+  "description": "文本不一致: 流动资产 vs 流动 资产 [列类型冲突]"
+}
+```
+
+#### 5. 表格匹配算法
+
+**智能匹配两个文件中的表格：**
+
+```python
+def find_matching_tables(tables1, tables2):
+    """查找匹配的表格对"""
+    matches = []
+    
+    for idx1, table1 in enumerate(tables1):
+        best_match_idx = -1
+        best_similarity = 0
+        
+        for idx2, table2 in enumerate(tables2):
+            # 计算综合相似度
+            similarity = calculate_table_similarity(table1, table2)
+            
+            if similarity > best_similarity and similarity > 0.5:
+                best_similarity = similarity
+                best_match_idx = idx2
+        
+        if best_match_idx >= 0:
+            matches.append((idx1, best_match_idx, best_similarity))
+    
+    return matches
+```
+
+**相似度计算（总分 100%）：**
+
+1. **行列数相似度 (30%)**
+   - 行数相似度 (15%)
+   - 列数相似度 (15%)
+   - ✨ **改进**：容忍 1-2 列差异（如合并列导致）
+
+2. **表头相似度 (50%)** - 最重要
+   - 精确匹配 (40%)：完全一致的表头数量
+   - 模糊匹配 (40%)：相似度 > 80% 的表头
+   - 语义匹配 (20%)：识别常见表头关键词
+
+3. **内容特征相似度 (20%)**
+   - 数据类型分布
+   - 数值范围
+   - 文本特征
+
+**示例输出：**
+
+```python
+# 匹配结果
+matches = [
+    (0, 0, 95.2),  # 文件1第0个表格 ↔ 文件2第0个表格，相似度 95.2%
+    (1, 1, 87.3),  # 文件1第1个表格 ↔ 文件2第1个表格，相似度 87.3%
+]
+```
+
+### 📝 段落对比
+
+**对比策略：**
+
+1. **段落匹配**
+   - 基于相似度的智能匹配
+   - 支持段落顺序调整
+   - 识别新增/删除的段落
+
+2. **差异检测**
+   - 文本内容差异
+   - 格式差异（如列表、引用）
+   - 图片内容差异（可选）
+
+3. **相似度算法**
+   - `ratio`：标准 Levenshtein 距离
+   - `partial_ratio`：部分匹配
+   - `token_sort_ratio`：排序后匹配
+   - `token_set_ratio`：集合匹配
+
+### 🔍 文本相似度计算
+
+**支持的相似度算法：**
+
+```python
+# 1. 标准相似度（ratio）
+similarity = fuzz.ratio("文本1", "文本2")
+# 输出: 85 (0-100)
+
+# 2. 部分匹配（partial_ratio）
+similarity = fuzz.partial_ratio("这是一段很长的文本", "很长的文本")
+# 输出: 100
+
+# 3. 排序后匹配（token_sort_ratio）
+similarity = fuzz.token_sort_ratio("apple banana", "banana apple")
+# 输出: 100
+
+# 4. 集合匹配（token_set_ratio）
+similarity = fuzz.token_set_ratio("the quick brown fox", "brown quick fox")
+# 输出: 100
+```
+
+## 🚀 快速开始
+
+### 1. 基本对比
+
+```bash
+# 对比两个 Markdown 文件
+python comparator/compare_ocr_results.py file1.md file2.md
+
+# 输出 JSON 格式
+python comparator/compare_ocr_results.py file1.md file2.md -f json
+
+# 输出 Markdown 格式
+python comparator/compare_ocr_results.py file1.md file2.md -f markdown
+
+# 同时输出两种格式
+python comparator/compare_ocr_results.py file1.md file2.md -f both
+```
+
+### 2. 流水表格对比 ✨
+
+```bash
+# 使用流水模式（智能表头检测 + 多层表头识别）
+python comparator/compare_ocr_results.py file1.md file2.md \
+    --table-mode flow_list \
+    -o output/comparison_result \
+    -f both
+
+# 资产负债表对比（自动识别多层表头）
+python comparator/compare_ocr_results.py balance_sheet1.md balance_sheet2.md \
+    --table-mode flow_list \
+    --similarity-algorithm ratio \
+    -o balance_sheet_comparison
+```
+
+### 3. 高级对比
+
+```bash
+# 使用 token_set_ratio 算法（集合匹配）
+python comparator/compare_ocr_results.py file1.md file2.md \
+    --similarity-algorithm token_set_ratio
+
+# 忽略图片内容对比
+python comparator/compare_ocr_results.py file1.md file2.md \
+    --ignore-images
+
+# 指定输出文件名
+python comparator/compare_ocr_results.py file1.md file2.md \
+    -o my_comparison_report
+
+# 详细调试信息
+python comparator/compare_ocr_results.py file1.md file2.md \
+    --table-mode flow_list \
+    -v
+```
+
+## 📖 命令行参数
+
+### 必需参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `file1` | string | 第一个文件路径（原OCR结果） |
+| `file2` | string | 第二个文件路径（验证结果） |
+
+### 可选参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `-o, --output` | `comparison_result` | 输出文件名（不含扩展名） |
+| `-f, --format` | `both` | 输出格式：`json` / `markdown` / `both` |
+| `--table-mode` | `standard` | 表格对比模式：`standard` / `flow_list` |
+| `--similarity-algorithm` | `ratio` | 相似度算法：`ratio` / `partial_ratio` / `token_sort_ratio` / `token_set_ratio` |
+| `--ignore-images` | `False` | 是否忽略图片内容对比 |
+| `-v, --verbose` | `False` | 显示详细调试信息 |
+
+## 📊 输出格式
+
+### JSON 格式
+
+```json
+{
+  "file1": "/path/to/file1.md",
+  "file2": "/path/to/file2.md",
+  "comparison_time": "2025-11-07 14:30:25",
+  "table_mode": "flow_list",
+  "similarity_algorithm": "ratio",
+  
+  "differences": [
+    {
+      "type": "table_amount",
+      "position": "第15行第5列",
+      "file1_value": "15.00",
+      "file2_value": "15,00",
+      "description": "金额不一致: 15.00 vs 15,00",
+      "severity": "high",
+      "column_name": "金额",
+      "column_type": "numeric",
+      "row_index": 15,
+      "col_index": 4
+    },
+    {
+      "type": "table_header_position",
+      "position": "表头位置",
+      "file1_value": "第1行",
+      "file2_value": "第2行",
+      "description": "表头位置不一致: 文件1在第1行，文件2在第2行",
+      "severity": "high"
+    },
+    {
+      "type": "table_text",
+      "position": "第20行第3列",
+      "file1_value": "流动资产",
+      "file2_value": "流动 资产",
+      "description": "文本不一致: 流动资产 vs 流动 资产 [列类型冲突]",
+      "severity": "high",
+      "column_type_mismatch": true
+    }
+  ],
+  
+  "statistics": {
+    "total_differences": 42,
+    "table_differences": 35,
+    "amount_differences": 8,
+    "datetime_differences": 3,
+    "text_differences": 24,
+    "paragraph_differences": 7,
+    "critical_severity": 2,
+    "high_severity": 11,
+    "medium_severity": 17,
+    "low_severity": 12
+  },
+  
+  "table_matches": [
+    {
+      "file1_table_index": 0,
+      "file2_table_index": 0,
+      "similarity": 95.2,
+      "header_position_file1": 1,
+      "header_position_file2": 1,
+      "row_count_file1": 10,
+      "row_count_file2": 10,
+      "column_count_file1": 6,
+      "column_count_file2": 6
+    }
+  ]
+}
+```
+
+### Markdown 格式
+
+```markdown
+# OCR结果对比报告
+
+## 📋 基本信息
+- **原OCR结果**: `/path/to/file1.md`
+- **验证结果**: `/path/to/file2.md`
+- **对比时间**: `2025-11-07 14:30:25`
+- **表格对比模式**: `flow_list`
+- **相似度算法**: `ratio`
+
+---
+
+## 📊 统计信息
+- **总差异数量**: 42
+- **表格差异**: 35
+  - 金额差异: 8 (严重度: high)
+  - 日期差异: 3 (严重度: medium)
+  - 文本差异: 24 (严重度: low/medium)
+  - 列类型冲突: 3 (严重度提升至: high)
+- **段落差异**: 7
+
+---
+
+## 📈 严重度分布
+- ❌ **严重差异 (Critical)**: 2
+- ⚠️ **高优先级 (High)**: 11
+- ℹ️ **中优先级 (Medium)**: 17
+- 💡 **低优先级 (Low)**: 12
+
+---
+
+## 🔍 表格匹配情况
+
+### 表格 #1 ↔ 表格 #1 (相似度: 95.2%)
+- **行数对比**: 10 vs 10, 相似度: 100.0%
+- **列数对比**: 6 vs 6, 相似度: 100.0%
+- **表头位置**: 文件1第1行, 文件2第1行
+- **表头相似度**: 92.5%
+  - 精确匹配: 83%
+  - 模糊匹配: 100%
+  - 语义匹配: 100%
+
+---
+
+## 📝 差异详情（按严重度分类）
+
+### ❌ 严重差异 (Critical)
+
+| 序号 | 位置 | 类型 | 原OCR结果 | 验证结果 | 描述 |
+|------|------|------|-----------|----------|------|
+| 1 | 表格列类型 | table_header_critical | 5列类型不一致 | 共10列 | 列类型差异过大 (50%) |
+
+---
+
+### ⚠️ 高优先级差异 (High)
+
+| 序号 | 位置 | 类型 | 原OCR结果 | 验证结果 | 描述 |
+|------|------|------|-----------|----------|------|
+| 1 | 第15行第5列 | table_amount | 15.00 | 15,00 | 金额不一致 |
+| 2 | 第20行第3列 | table_text | 流动资产 | 流动 资产 | 文本不一致 [列类型冲突] |
+| 3 | 表头位置 | table_header_position | 第1行 | 第2行 | 表头位置不一致 |
+
+---
+
+### ℹ️ 中优先级差异 (Medium)
+
+| 序号 | 位置 | 类型 | 原OCR结果 | 验证结果 | 描述 |
+|------|------|------|-----------|----------|------|
+| 1 | 第8行第2列 | table_datetime | 2023-12-31 | 2023年12月31日 | 日期格式不一致 |
+
+---
+
+### 💡 低优先级差异 (Low)
+
+| 序号 | 位置 | 类型 | 原OCR结果 | 验证结果 | 描述 |
+|------|------|------|-----------|----------|------|
+| 1 | 第3行第1列 | table_text | 现金及现金等价物 | 现金及 现金等价物 | 文本相似度: 92.3% |
+```
+
+## 🎯 使用场景示例
+
+### 场景 1：银行流水对比
+
+```bash
+# 命令
+python comparator/compare_ocr_results.py \
+    /data/银行流水/dotsocr/page_001.md \
+    /data/银行流水/paddleocr_vl/page_001.md \
+    --table-mode flow_list \
+    --similarity-algorithm ratio \
+    -o output/bank_flow_comparison \
+    -f both
+
+# 特点
+# ✅ 自动检测表头（日期、金额、余额等关键词）
+# ✅ 列类型检测（数字金额、日期、文本型数字）
+# ✅ 金额差异高优先级
+# ✅ 列类型冲突自动提升严重度
+```
+
+### 场景 2：资产负债表对比 ✨
+
+```bash
+# 命令
+python comparator/compare_ocr_results.py \
+    /data/年报/mineru/balance_sheet.md \
+    /data/年报/ppstructv3/balance_sheet.md \
+    --table-mode flow_list \
+    --similarity-algorithm ratio \
+    -o output/balance_sheet_comparison \
+    -v
+
+# 特点
+# ✅ 自动识别多层表头（总表头 + 分类标题）
+# ✅ 检测"流动资产:"等分类行
+# ✅ 智能评分（分类行 +0.1，数据行 +0.2）
+# ✅ 详细调试信息（-v 参数）
+
+# 调试输出示例
+📍 检测到表头在第 1 行 (得分: 0.87)
+   - 关键词: "资产"(0.25) + "余额"(0.50) + "负债"(0.25)
+   - 下一行: 分类行 (+0.1)
+   - 总得分: 1.0 + 0.1 = 1.1
+```
+
+### 场景 3：利润表对比
+
+```bash
+# 命令
+python comparator/compare_ocr_results.py \
+    /data/财报/paddleocr_vl/income_statement.md \
+    /data/财报/dots_ocr/income_statement.md \
+    --table-mode flow_list \
+    --similarity-algorithm token_set_ratio \
+    -o output/income_statement_comparison
+
+# 特点
+# ✅ 集合匹配算法（容忍词序差异）
+# ✅ 自动检测"收入"、"成本"等关键词
+# ✅ 数值列精确对比
+```
+
+### 场景 4：批量对比
+
+```bash
+# 批量对比脚本
+for file1 in /data/dotsocr/*.md; do
+    file2="/data/paddleocr_vl/$(basename $file1)"
+    if [ -f "$file2" ]; then
+        python comparator/compare_ocr_results.py \
+            "$file1" "$file2" \
+            --table-mode flow_list \
+            -o "output/$(basename $file1 .md)_comparison" \
+            -f json
+    fi
+done
+```
+
+## 🔧 编程接口
+
+### 直接调用 OCRResultComparator
+
+```python
+from comparator.ocr_comparator import OCRResultComparator
+
+# 初始化对比器
+comparator = OCRResultComparator(
+    table_mode='flow_list',
+    similarity_algorithm='ratio',
+    ignore_images=False
+)
+
+# 从文件加载内容
+with open('file1.md', 'r', encoding='utf-8') as f:
+    content1 = f.read()
+with open('file2.md', 'r', encoding='utf-8') as f:
+    content2 = f.read()
+
+# 执行对比
+result = comparator.compare(content1, content2)
+
+# 查看结果
+print(f"总差异数: {result['statistics']['total_differences']}")
+print(f"表格差异: {result['statistics']['table_differences']}")
+print(f"段落差异: {result['statistics']['paragraph_differences']}")
+
+# 获取高优先级差异
+high_diffs = [d for d in result['differences'] if d['severity'] == 'high']
+print(f"高优先级差异: {len(high_diffs)}")
+```
+
+### 表格对比器独立使用
+
+```python
+from comparator.table_comparator import TableComparator
+
+# 初始化表格对比器
+table_comparator = TableComparator(
+    mode='flow_list',
+    similarity_algorithm='ratio'
+)
+
+# 准备表格数据
+table1 = [
+    ['日期', '金额', '余额'],
+    ['2023-01-01', '1000.00', '5000.00'],
+    ['2023-01-02', '500.00', '5500.00']
+]
+
+table2 = [
+    ['日期', '金额', '余额'],
+    ['2023-01-01', '1,000.00', '5,000.00'],
+    ['2023-01-02', '500.00', '5500.00']
+]
+
+# 执行对比
+differences = table_comparator.compare_tables(table1, table2)
+
+# 分析差异
+for diff in differences:
+    print(f"{diff['position']}: {diff['description']} (严重度: {diff['severity']})")
+```
+
+### 相似度计算器独立使用
+
+```python
+from comparator.similarity_calculator import SimilarityCalculator
+
+# 初始化计算器
+calculator = SimilarityCalculator(algorithm='ratio')
+
+# 计算文本相似度
+similarity = calculator.calculate("流动资产", "流动 资产")
+print(f"相似度: {similarity}%")  # 输出: 92.31%
+
+# 切换算法
+calculator.set_algorithm('token_set_ratio')
+similarity = calculator.calculate("apple banana", "banana apple")
+print(f"相似度: {similarity}%")  # 输出: 100%
+```
+
+### 数据类型检测器独立使用
+
+```python
+from comparator.data_type_detector import DataTypeDetector
+
+# 初始化检测器
+detector = DataTypeDetector()
+
+# 检测单个值
+print(detector.detect_type("28,239,305.48"))  # 输出: numeric
+print(detector.detect_type("2023-12-31"))     # 输出: datetime
+print(detector.detect_type("20231231001"))    # 输出: text_number
+print(detector.detect_type("货币资金"))        # 输出: text
+
+# 检测列类型
+column_values = ["1000.00", "2000.50", "3000.75", "文本"]
+column_type = detector.detect_column_type(column_values)
+print(f"列类型: {column_type}")  # 输出: numeric (75% 是数字)
+```
+
+## 🐛 调试技巧
+
+### 1. 启用详细日志
+
+```bash
+# 使用 -v 参数
+python comparator/compare_ocr_results.py file1.md file2.md \
+    --table-mode flow_list \
+    -v
+```
+
+**输出示例：**
+
+```
+🔍 开始对比...
+📄 文件1: /path/to/file1.md
+📄 文件2: /path/to/file2.md
+⚙️ 表格模式: flow_list
+⚙️ 相似度算法: ratio
+
+📊 提取表格...
+   文件1: 发现 2 个表格
+   文件2: 发现 2 个表格
+
+🔗 匹配表格...
+   表格 #1 ↔ 表格 #1: 相似度 95.2%
+
+📍 检测表头位置...
+   文件1表格1: 检测到表头在第 1 行 (得分: 0.87)
+      关键词: "资产"(0.25) + "余额"(0.50) + "负债"(0.25)
+      下一行: 分类行 (+0.1)
+   文件2表格1: 检测到表头在第 1 行 (得分: 0.85)
+
+🔍 对比单元格...
+   第15行第5列: 金额差异 (15.00 vs 15,00) [严重度: high]
+   第20行第3列: 文本差异 (流动资产 vs 流动 资产) [列类型冲突] [严重度: high]
+
+✅ 对比完成
+   总差异: 42
+   表格差异: 35
+   段落差异: 7
+```
+
+### 2. 检查表格匹配
+
+```python
+# 查看表格匹配结果
+result = comparator.compare(content1, content2)
+for match in result['table_matches']:
+    print(f"表格 #{match['file1_table_index']} ↔ #{match['file2_table_index']}")
+    print(f"  相似度: {match['similarity']}%")
+    print(f"  行数: {match['row_count_file1']} vs {match['row_count_file2']}")
+    print(f"  列数: {match['column_count_file1']} vs {match['column_count_file2']}")
+```
+
+### 3. 分析列类型冲突
+
+```python
+# 过滤列类型冲突的差异
+type_conflicts = [
+    d for d in result['differences'] 
+    if d.get('column_type_mismatch', False)
+]
+
+for diff in type_conflicts:
+    print(f"位置: {diff['position']}")
+    print(f"文件1: {diff['file1_value']}")
+    print(f"文件2: {diff['file2_value']}")
+    print(f"基础严重度: {diff.get('base_severity', 'N/A')}")
+    print(f"最终严重度: {diff['severity']}")
+    print()
+```
+
+### 4. 检查表头检测结果
+
+```python
+# 手动检测表头
+from comparator.table_comparator import TableComparator
+
+comparator = TableComparator(mode='flow_list')
+header_row_idx = comparator._detect_table_header_row(table)
+
+print(f"检测到表头在第 {header_row_idx + 1} 行")
+
+# 查看评分详情
+for idx, row in enumerate(table):
+    score = comparator._score_header_row(row, table, idx)
+    print(f"第 {idx + 1} 行: 得分 {score:.2f}")
+```
+
+## 📚 常见问题
+
+### Q1: 表头检测不准确？
+
+**A:** 
+- 检查表格是否包含表头关键词（日期、金额、余额等）
+- 使用 `-v` 参数查看详细评分信息
+- 手动指定表头位置（在代码中设置 `header_row_idx`）
+
+### Q2: 列类型检测错误？
+
+**A:** 
+- 检查列的数据一致性（是否混合了不同类型）
+- 调整检测阈值（默认 60%，可在代码中修改）
+- 查看检测日志了解判断依据
+
+### Q3: 差异过多且都是 high 严重度？
+
+**A:** 
+- 检查是否存在列类型冲突（会自动提升严重度）
+- 使用不同的相似度算法（如 `token_set_ratio`）
+- 确认表格结构是否一致（行列数）
+
+### Q4: 多层表头识别失败？✨
+
+**A:** 
+- 确认表格结构符合预期：
+  - 第1行：总表头
+  - 第2行：分类标题（如"流动资产:"）
+  - 第3行起：数据行
+- 检查分类行格式：
+  - 第一个单元格包含关键词 + 冒号
+  - 其他单元格为空
+- 使用 `-v` 参数查看检测详情
+
+### Q5: 表格匹配失败？
+
+**A:** 
+- 检查表格相似度阈值（默认 50%）
+- 查看表头相似度（最重要的匹配因素）
+- 确认行列数差异是否过大
+
+### Q6: 金额格式差异导致误报？
+
+**A:** 
+- 使用数字标准化工具预处理：
+  ```python
+  from normalize_financial_numbers import normalize_financial_numbers
+  normalized = normalize_financial_numbers(text)
+  ```
+- 或在对比前手动统一格式
+
+### Q7: 相似度计算结果异常？
+
+**A:** 
+- 尝试不同的相似度算法
+- 检查文本是否包含特殊字符
+- 确认编码格式正确（UTF-8）
+
+## 🎓 最佳实践
+
+### 1. 选择合适的对比模式
+
+| 文档类型 | 推荐模式 | 理由 |
+|---------|---------|------|
+| 固定格式报表 | `standard` | 结构稳定，逐行对比更精确 |
+| 银行流水 | `flow_list` | 表头位置可能变化，需要智能检测 |
+| 资产负债表 | `flow_list` | 支持多层表头识别 ✨ |
+| 利润表 | `flow_list` | 自动检测"收入"、"成本"等关键词 |
+| 交易记录 | `flow_list` | 列类型多样，需要类型检测 |
+
+### 2. 选择合适的相似度算法
+
+| 算法 | 适用场景 | 特点 |
+|------|---------|------|
+| `ratio` | 精确对比 | 严格匹配，适合格式统一的文本 |
+| `partial_ratio` | 部分匹配 | 适合长短文本对比 |
+| `token_sort_ratio` | 词序差异 | 容忍词序不同 |
+| `token_set_ratio` | 集合匹配 | 容忍重复词、词序 |
+
+### 3. 处理常见差异类型
+
+**金额差异：**
+```bash
+# 预处理：标准化金额格式
+python normalize_financial_numbers.py input.json output.json
+
+# 对比
+python comparator/compare_ocr_results.py file1.md file2.md \
+    --table-mode flow_list
+```
+
+**日期格式差异：**
+```python
+# 在对比前统一日期格式
+def normalize_date(date_str):
+    # 2023-12-31 → 2023年12月31日
+    # 2023/12/31 → 2023年12月31日
+    pass
+```
+
+**列类型冲突：**
+```python
+# 检查冲突原因
+type_conflicts = [d for d in differences if d.get('column_type_mismatch')]
+for diff in type_conflicts:
+    print(f"{diff['position']}: {diff['file1_value']} vs {diff['file2_value']}")
+    # 分析是 OCR 错误还是格式差异
+```
+
+### 4. 批量对比策略
+
+```bash
+#!/bin/bash
+# batch_compare.sh
+
+# 配置
+SOURCE_DIR="/data/dotsocr"
+TARGET_DIR="/data/paddleocr_vl"
+OUTPUT_DIR="/output/comparisons"
+
+# 批量对比
+for file1 in "$SOURCE_DIR"/*.md; do
+    filename=$(basename "$file1")
+    file2="$TARGET_DIR/$filename"
+    
+    if [ -f "$file2" ]; then
+        echo "对比: $filename"
+        python comparator/compare_ocr_results.py \
+            "$file1" "$file2" \
+            --table-mode flow_list \
+            --similarity-algorithm ratio \
+            -o "$OUTPUT_DIR/${filename%.md}_comparison" \
+            -f both
+    else
+        echo "跳过: $filename (目标文件不存在)"
+    fi
+done
+
+echo "✅ 批量对比完成"
+```
+
+### 5. 结果分析流程
+
+```python
+import json
+
+# 加载对比结果
+with open('comparison_result.json', 'r') as f:
+    result = json.load(f)
+
+# 1. 统计分析
+stats = result['statistics']
+print(f"总差异: {stats['total_differences']}")
+print(f"表格差异: {stats['table_differences']}")
+
+# 2. 严重度分布
+print(f"Critical: {stats['critical_severity']}")
+print(f"High: {stats['high_severity']}")
+print(f"Medium: {stats['medium_severity']}")
+print(f"Low: {stats['low_severity']}")
+
+# 3. 差异类型分布
+type_counts = {}
+for diff in result['differences']:
+    type_counts[diff['type']] = type_counts.get(diff['type'], 0) + 1
+
+for diff_type, count in sorted(type_counts.items(), key=lambda x: x[1], reverse=True):
+    print(f"{diff_type}: {count}")
+
+# 4. 关注高优先级差异
+high_diffs = [d for d in result['differences'] if d['severity'] == 'high']
+for diff in high_diffs:
+    print(f"⚠️ {diff['position']}: {diff['description']}")
+```
+
+## 📝 开发指南
+
+### 扩展新的数据类型检测
+
+```python
+# 在 data_type_detector.py 中添加
+def is_currency(value):
+    """检测是否为货币格式"""
+    patterns = [
+        r'¥\s*[\d,]+\.?\d*',
+        r'\$\s*[\d,]+\.?\d*',
+        r'[\d,]+\.?\d*\s*元',
+    ]
+    return any(re.match(pattern, str(value)) for pattern in patterns)
+```
+
+### 自定义相似度算法
+
+```python
+# 在 similarity_calculator.py 中添加
+def custom_similarity(text1, text2):
+    """自定义相似度计算"""
+    # 实现自定义逻辑
+    pass
+
+# 注册算法
+SimilarityCalculator.register_algorithm('custom', custom_similarity)
+```
+
+### 扩展表格对比逻辑
+
+```python
+# 继承 TableComparator
+class CustomTableComparator(TableComparator):
+    def _detect_table_header_row(self, table):
+        """自定义表头检测逻辑"""
+        # 实现自定义检测
+        pass
+    
+    def _compare_cells(self, cell1, cell2, column_type):
+        """自定义单元格对比"""
+        # 实现自定义对比
+        pass
+```
+
+## 📄 许可证
+
+本模块采用 MIT 许可证。
+
+---
+
+**最后更新**: 2025年11月7日
+**维护者**: zhch158_admin