239 lines
6.2 KiB
Markdown
239 lines
6.2 KiB
Markdown
# Machine Code Parser 分析报告
|
||
|
||
## 文件概况
|
||
|
||
- **文件**: `src/ocr/machine_code_parser.py`
|
||
- **总行数**: 919 行
|
||
- **代码行**: 607 行 (66%)
|
||
- **方法数**: 14 个
|
||
- **正则表达式使用**: 47 次
|
||
|
||
## 代码结构
|
||
|
||
### 类结构
|
||
|
||
```
|
||
MachineCodeResult (数据类)
|
||
├── to_dict()
|
||
└── get_region_bbox()
|
||
|
||
MachineCodeParser (主解析器)
|
||
├── __init__()
|
||
├── parse() - 主入口
|
||
├── _find_tokens_with_values()
|
||
├── _find_machine_code_line_tokens()
|
||
├── _parse_standard_payment_line_with_tokens()
|
||
├── _parse_standard_payment_line() - 142行 ⚠️
|
||
├── _extract_ocr() - 50行
|
||
├── _extract_bankgiro() - 58行
|
||
├── _extract_plusgiro() - 30行
|
||
├── _extract_amount() - 68行
|
||
├── _calculate_confidence()
|
||
└── cross_validate()
|
||
```
|
||
|
||
## 发现的问题
|
||
|
||
### 1. ⚠️ `_parse_standard_payment_line` 方法过长 (142行)
|
||
|
||
**位置**: 442-582 行
|
||
|
||
**问题**:
|
||
- 包含嵌套函数 `normalize_account_spaces` 和 `format_account`
|
||
- 多个正则匹配分支
|
||
- 逻辑复杂，难以测试和维护
|
||
|
||
**建议**:
|
||
可以拆分为独立方法:
|
||
- `_normalize_account_spaces(line)`
|
||
- `_format_account(account_digits, context)`
|
||
- `_match_primary_pattern(line)`
|
||
- `_match_fallback_patterns(line)`
|
||
|
||
### 2. 🔁 4个 `_extract_*` 方法有重复模式
|
||
|
||
所有 extract 方法都遵循相同模式：
|
||
|
||
```python
|
||
def _extract_XXX(self, tokens):
|
||
candidates = []
|
||
|
||
for token in tokens:
|
||
text = token.text.strip()
|
||
matches = self.XXX_PATTERN.findall(text)
|
||
for match in matches:
|
||
# 验证逻辑
|
||
# 上下文检测
|
||
candidates.append((normalized, context_score, token))
|
||
|
||
if not candidates:
|
||
return None
|
||
|
||
candidates.sort(key=lambda x: (x[1], 1), reverse=True)
|
||
return candidates[0][0]
|
||
```
|
||
|
||
**重复的逻辑**:
|
||
- Token 迭代
|
||
- 模式匹配
|
||
- 候选收集
|
||
- 上下文评分
|
||
- 排序和选择最佳匹配
|
||
|
||
**建议**:
|
||
可以提取基础提取器类或通用方法来减少重复。
|
||
|
||
### 3. ✅ 上下文检测重复
|
||
|
||
上下文检测代码在多个地方重复：
|
||
|
||
```python
|
||
# _extract_bankgiro 中
|
||
context_text = ' '.join(t.text.lower() for t in tokens)
|
||
is_bankgiro_context = (
|
||
'bankgiro' in context_text or
|
||
'bg:' in context_text or
|
||
'bg ' in context_text
|
||
)
|
||
|
||
# _extract_plusgiro 中
|
||
context_text = ' '.join(t.text.lower() for t in tokens)
|
||
is_plusgiro_context = (
|
||
'plusgiro' in context_text or
|
||
'postgiro' in context_text or
|
||
'pg:' in context_text or
|
||
'pg ' in context_text
|
||
)
|
||
|
||
# _parse_standard_payment_line 中
|
||
context = (context_line or raw_line).lower()
|
||
is_plusgiro_context = (
|
||
('plusgiro' in context or 'postgiro' in context or 'plusgirokonto' in context)
|
||
and 'bankgiro' not in context
|
||
)
|
||
```
|
||
|
||
**建议**:
|
||
提取为独立方法:
|
||
- `_detect_account_context(tokens) -> dict[str, bool]`
|
||
|
||
## 重构建议
|
||
|
||
### 方案 A: 轻度重构（推荐）✅
|
||
|
||
**目标**: 提取重复的上下文检测逻辑，不改变主要结构
|
||
|
||
**步骤**:
|
||
1. 提取 `_detect_account_context(tokens)` 方法
|
||
2. 提取 `_normalize_account_spaces(line)` 为独立方法
|
||
3. 提取 `_format_account(digits, context)` 为独立方法
|
||
|
||
**影响**:
|
||
- 减少 ~50-80 行重复代码
|
||
- 提高可测试性
|
||
- 低风险，易于验证
|
||
|
||
**预期结果**: 919 行 → ~850 行 (↓7%)
|
||
|
||
### 方案 B: 中度重构
|
||
|
||
**目标**: 创建通用的字段提取框架
|
||
|
||
**步骤**:
|
||
1. 创建 `_generic_extract(pattern, normalizer, context_checker)`
|
||
2. 重构所有 `_extract_*` 方法使用通用框架
|
||
3. 拆分 `_parse_standard_payment_line` 为多个小方法
|
||
|
||
**影响**:
|
||
- 减少 ~150-200 行代码
|
||
- 显著提高可维护性
|
||
- 中等风险，需要全面测试
|
||
|
||
**预期结果**: 919 行 → ~720 行 (↓22%)
|
||
|
||
### 方案 C: 深度重构（不推荐）
|
||
|
||
**目标**: 完全重新设计为策略模式
|
||
|
||
**风险**:
|
||
- 高风险，可能引入 bugs
|
||
- 需要大量测试
|
||
- 可能破坏现有集成
|
||
|
||
## 推荐方案
|
||
|
||
### ✅ 采用方案 A（轻度重构）
|
||
|
||
**理由**:
|
||
1. **代码已经工作良好**: 没有明显的 bug 或性能问题
|
||
2. **低风险**: 只提取重复逻辑，不改变核心算法
|
||
3. **性价比高**: 小改动带来明显的代码质量提升
|
||
4. **易于验证**: 现有测试应该能覆盖
|
||
|
||
### 重构步骤
|
||
|
||
```python
|
||
# 1. 提取上下文检测
|
||
def _detect_account_context(self, tokens: list[TextToken]) -> dict[str, bool]:
|
||
"""检测上下文中的账户类型关键词"""
|
||
context_text = ' '.join(t.text.lower() for t in tokens)
|
||
|
||
return {
|
||
'bankgiro': any(kw in context_text for kw in ['bankgiro', 'bg:', 'bg ']),
|
||
'plusgiro': any(kw in context_text for kw in ['plusgiro', 'postgiro', 'plusgirokonto', 'pg:', 'pg ']),
|
||
}
|
||
|
||
# 2. 提取空格标准化
|
||
def _normalize_account_spaces(self, line: str) -> str:
|
||
"""移除账户号码中的空格"""
|
||
# (现有 line 460-481 的代码)
|
||
|
||
# 3. 提取账户格式化
|
||
def _format_account(
|
||
self,
|
||
account_digits: str,
|
||
is_plusgiro_context: bool
|
||
) -> tuple[str, str]:
|
||
"""格式化账户并确定类型"""
|
||
# (现有 line 485-523 的代码)
|
||
```
|
||
|
||
## 对比：field_extractor vs machine_code_parser
|
||
|
||
| 特征 | field_extractor | machine_code_parser |
|
||
|------|-----------------|---------------------|
|
||
| 用途 | 值提取 | 机器码解析 |
|
||
| 重复代码 | ~400行normalize方法 | ~80行上下文检测 |
|
||
| 重构价值 | ❌ 不同用途，不应统一 | ✅ 可提取共享逻辑 |
|
||
| 风险 | 高（会破坏功能） | 低（只是代码组织） |
|
||
|
||
## 决策
|
||
|
||
### ✅ 建议重构 machine_code_parser.py
|
||
|
||
**与 field_extractor 的不同**:
|
||
- field_extractor: 重复的方法有**不同的用途**（提取 vs 变体生成）
|
||
- machine_code_parser: 重复的代码有**相同的用途**（都是上下文检测）
|
||
|
||
**预期收益**:
|
||
- 减少 ~70 行重复代码
|
||
- 提高可测试性（可以单独测试上下文检测）
|
||
- 更清晰的代码组织
|
||
- **低风险**，易于验证
|
||
|
||
## 下一步
|
||
|
||
1. ✅ 备份原文件
|
||
2. ✅ 提取 `_detect_account_context` 方法
|
||
3. ✅ 提取 `_normalize_account_spaces` 方法
|
||
4. ✅ 提取 `_format_account` 方法
|
||
5. ✅ 更新所有调用点
|
||
6. ✅ 运行测试验证
|
||
7. ✅ 检查代码覆盖率
|
||
|
||
---
|
||
|
||
**状态**: 📋 分析完成，建议轻度重构
|
||
**风险评估**: 🟢 低风险
|
||
**预期收益**: 919行 → ~850行 (↓7%)
|