BIPPI-imp-trm-accstmt - 银行对账单转换技能

将银行对账单文件（MT940格式、国内银行Excel格式或PDF格式）转换为目标系统的标准银行账户流水导入模板。

支持的银行格式

国际格式

• MT940 (SWIFT标准银行对账单)

国内银行Excel格式（测试通过）

国内银行PDF格式（测试通过）

使用方法

基本转换

单文件转换：

请将 平安银行.pdf 银行对账单转换为 BIPV5 系统的导入模板

批量合并转换（将目录下所有对账单合并为单个文件）：

将当前目录下所有银行对账单（MT940、Excel和PDF格式）合并转换为一个BIPV5导入模板

完整参数指定

将以下银行对账单转换为 BIPV5 系统导入模板：
- 输入文件：/path/to/平安银行.pdf
- 输出文件：/path/to/output/BIPV5_平安银行.xlsx
- 目标系统：BIPV5
- 账户组织编码：ORG001
- 银行名称：平安银行

输出位置说明

输出文件名格式：

• 单文件：{原文件名}_BIPV5.xlsx
• 合并文件：merged_BIPV5.xlsx

工作流程

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  输入文件       │───▶│  格式解析器     │───▶│  数据映射器     │───▶│  输出生成器     │
│  (MT940/Excel/  │    │  (Parser)       │    │  (Mapper)       │    │  (Excel)        │
│   PDF)          │    │                 │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘    └─────────────────┘
                              │                      │                      │
                              ▼                      ▼                      ▼
                       parsers/              mappings/               输出文件
                       mt940_parser.py       mt940_to_bipv5.json     BIPV5_银行流水.xlsx
                       excel_parser.py
                       pdf_parser.py

核心特性

1. 多格式解析支持：通过插件化的解析器系统支持扩展（MT940/Excel/PDF）
2. 多系统输出支持：通过插件化的映射器系统支持扩展：
   • BIPV5：银行流水处理 Excel 模板
   • EAS_YXH（金蝶云星瀚）：离线明细导入 .xlsx 模板
   • FINGARD（保融ATS）：离线信息 .xls 模板
   • NSTC（九恒星司库）：批量导入银行明细格式 .xls 模板
   • YYNCC（用友NCC）：数据页签 .xls 模板
3. 智能字段匹配：使用余弦相似度算法匹配可能存在细微差异的列名
4. 可配置映射：通过JSON配置文件管理字段映射关系
5. 批量合并：支持将多个银行对账单合并为单个文件
6. PDF支持：基于PyMuPDF的X/Y位置信息按列重组表格，兼容多种列头折行格式

BIPV5目标字段

解析器系统

MT940解析器

MT940格式关键字段映射：

Excel解析器特性

1. 智能表头识别：自动查找包含"交易日期"或"交易时间"的行作为表头
2. 账号自动提取：从表头区域提取本方账号、户名、币种信息
3. 币种清理：自动清理账号中的币种标识
4. 字段智能匹配：使用余弦相似度匹配各种列名格式

PDF解析器特性

1. 双模式支持：

   • 文本型PDF（默认）：使用 PyMuPDF 的 page.get_text() 直接提取文字
   • 图片型PDF（可选）：通过可插拔 OCR 接口（默认 Tesseract）识别

2. 位置信息驱动：使用 PyMuPDF 的 X/Y 坐标信息按列重组表格，不依赖固定列数

3. 列头归一化：智能处理多种列头折行格式：

   • 中文两行折行（如 交易时 + 间 → 交易时间）
   • 中英文对照（如 贷方发 + 生额(收 + 入) → 贷方发生额(收入)）
   • 含括号元（如 发生金额（元） → 发生金额）

4. 可插拔OCR接口：

   from scripts.parsers.pdf_parser import PDFParser, TesseractOCR
   
   parser = PDFParser()
   parser.set_ocr_backend(TesseractOCR())  # 注入 Tesseract OCR
   data = parser.parse('image_based.pdf')
   

5. 多页PDF自动合并：跨页交易表自动识别（按 Y 坐标分组、按 X 坐标排序列）

添加新解析器

1. 在 scripts/parsers/ 目录创建新的解析器文件
2. 继承 BaseParser 类
3. 实现 parse() 和 detect_format() 方法
4. 在 scripts/core/parser_factory.py 中注册

输出文件格式

BIPV5 Excel模板结构

模板文件: assets/template/YYBIPV5_banktransaction.xlsx
Sheet: 银行流水处理
├── Row 1-3: 模板说明
├── Row 4: 英文字段名 (id, accentity_code, bankaccount_account, ...)
├── Row 5: 空行
├── Row 6: 中文字段名 (*银行账号, *本方交易流水号, ...)
├── Row 7-9: 空行
└── Row 10+: 数据行

目录结构

BIPPI-imp-trm-accstmt/
├── SKILL.md                    # 技能说明文件
├── scripts/
│   ├── main.py                 # 主入口
│   ├── core/
│   │   ├── data_structures.py  # 数据结构定义
│   │   ├── parser_factory.py   # 解析器工厂
│   │   ├── mapper_factory.py   # 映射器工厂
│   │   ├── cosine_similarity.py # 余弦相似度工具
│   │   ├── currency_map.py     # 币种代码映射
│   │   └── template_manager.py # 模板文件管理器（本地查找+自动下载）
│   ├── parsers/
│   │   ├── base_parser.py      # 解析器基类
│   │   ├── mt940_parser.py     # MT940解析器
│   │   ├── excel_parser.py     # 国内银行Excel解析器
│   │   └── pdf_parser.py       # 国内银行PDF解析器（文本+可插拔OCR）
│   ├── mappers/
│   │   ├── base_mapper.py      # 映射器基类
│   │   ├── _xls_template_helpers.py # xls模板写入辅助
│   │   ├── bipv5_mapper.py     # BIPV5映射器
│   │   ├── eas_yxh_mapper.py   # 金蝶云星瀚映射器
│   │   ├── fingard_mapper.py   # 保融ATS映射器
│   │   ├── nstc_mapper.py      # 九恒星司库映射器
│   │   └── yyncc_mapper.py     # 用友NCC映射器
│   └── mappings/
│       └── mt940_to_bipv5.json # MT940到BIPV5映射配置
├── assets/
│   └── template/               # 5 个目标系统的导入模板
│       ├── YYBIPV5_banktransaction.xlsx
│       ├── eas_yxh_banktransaction.xlsx
│       ├── fingard_banktransaction.xls
│       ├── nstc_banktransaction.xls
│       └── yyncc_banktransaction.xls
├── references/
│   ├── currency.md             # 币种代码参考
│   └── User Guide - Exporting Data in SWIFT MT940 Format[1].pdf
└── evals/
    └── evals.json              # 测试用例

常用命令

# 单文件转换（输出到输入文件同目录）
python scripts/main.py input.xlsx
python scripts/main.py input.pdf

# 单文件转换（指定输出路径）
python scripts/main.py input.xlsx -o output/BIPV5_output.xlsx
python scripts/main.py input.pdf -o output/BIPV5_output.xlsx

# 批量转换（每个文件单独输出到输入目录）
python scripts/main.py --batch -i ./input_dir

# 批量合并（输出到输入目录）
python scripts/main.py --merge -i ./input_dir

# 批量合并（指定输出文件）
python scripts/main.py --merge -i ./input_dir -o ./output/merged.xlsx

依赖要求

• Python 3.8+
• openpyxl
• pandas
• scikit-learn (用于余弦相似度匹配)
• pymupdf (PyMuPDF，用于PDF文本提取)
• pillow (PIL，用于OCR图片处理)

安装依赖：

pip install openpyxl pandas scikit-learn pymupdf pillow

如需OCR支持图片型PDF（可选）：

pip install pytesseract
# 还需要安装系统级 Tesseract：Windows 从 https://github.com/UB-Mannheim/tesseract/wiki 下载并安装
# 安装中文语言包（chi_sim），然后在 PDFParser 中注入：
#   parser.set_ocr_backend(TesseractOCR())

PDF处理已知限制

1. 浦发银行对账单（英文+中文混合版式）：当前通用启发式无法准确解析，列头散布在多 Y 位置。建议先用 Adobe/PDF转Excel工具预处理。
2. 强加密PDF：受密码保护的PDF需先解密。
3. 扫描型PDF：默认未启用OCR，需安装Tesseract并注入OCR后端。
4. 跨页表格：当前已支持基础的多页合并，但极端情况下表头只出现在第一页。

错误处理

扩展指南

添加新的银行对账单格式

1. 创建新的解析器类继承 BaseParser
2. 实现 parse() 和 detect_format() 方法
3. 创建对应的映射配置文件
4. 在 parser_factory.py 中注册

添加新的目标系统

1. 创建新的映射器类继承 BaseMapper
2. 实现到新系统的字段映射
3. 在 mapper_factory.py 中注册
4. 创建对应的目标模板文件

接入新的OCR后端

1. 实现 OCRBackend 接口的 image_to_text 方法
2. 通过 PDFParser.set_ocr_backend(your_backend) 注入
3. 适用于：百度OCR、阿里云OCR、腾讯云OCR、PaddleOCR等