financial-document-processor

财务文档处理器

概述

此技能提供使用 OCR 和 PDF 文本提取技术，从财务文档（发票、收据、对账单等）中提取结构化数据的指导，并强调可避免破坏性操作导致灾难性故障的数据安全实践。

关键数据安全原则

未经验证或备份，绝不对源数据执行破坏性操作。

处理任何文件之前：

1. 处理前备份所有源文件
2. 使用副本，而非原件
3. 清理任何文件前，确认输出符合预期
4. 使用原子操作（复制 → 验证 → 删除），而非直接移动

安全文件操作模式

# CORRECT: Copy first, verify, then clean up
cp -r /source/documents/ /backup/documents/
# ... process files ...
# ... verify outputs match expectations ...
# Only after verification: rm /backup/documents/

# WRONG: Delete before moving (data loss risk)
rm -f /source/*.pdf && mv /source/* /dest/  # Files deleted before move!

工作流

步骤 1：评估环境和需求

编写任何处理代码之前：

1. 列出所有源文件并记录其确切路径
2. 确认文件类型（基于文本的 PDF、扫描版 PDF、JPG、PNG 等）
3. 检查可用工具：which tesseract、which pdftotext、python3 -c "import pypdf"
4. 了解预期输出格式（CSV 列、必需字段等）

步骤 2：创建备份

处理任何文件前，务必备份源文件：

# Create timestamped backup directory
BACKUP_DIR="/tmp/backup_$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"
cp -r /path/to/source/documents/* "$BACKUP_DIR/"
echo "Backup created at: $BACKUP_DIR"

步骤 3：在样本文件上测试提取

处理所有文档之前：

1. 选择 2-3 个有代表性的文件（不同格式、边缘情况）
2. 在这些样本上测试 OCR/提取
3. 通过目视检查验证提取出的值是否正确
4. 根据样本结果调整提取逻辑

# Test extraction on a single file first
sample_file = "/path/to/sample_invoice.pdf"
extracted_data = extract_document(sample_file)
print(f"Extracted: {extracted_data}")
# Manually verify these values match the document

步骤 4：处理格式差异

财务文档通常存在格式差异：

• 数字格式：欧洲格式（1.234,56）与美国格式（1,234.56）
• 日期格式：DD/MM/YYYY、MM/DD/YYYY 与 YYYY-MM-DD
• 货币符号：$、€、£，或以文字写出
• 空字段/缺失字段：VAT 可能为空，而非零

def parse_amount(text):
    """Handle multiple number format conventions."""
    # Remove currency symbols and whitespace
    cleaned = re.sub(r'[$€£\s]', '', text)

    # Detect European format (comma as decimal separator)
    if re.match(r'^\d{1,3}(\.\d{3})*,\d{2}$', cleaned):
        cleaned = cleaned.replace('.', '').replace(',', '.')
    # US format (comma as thousands separator)
    elif ',' in cleaned:
        cleaned = cleaned.replace(',', '')

    return float(cleaned) if cleaned else None

步骤 5：处理所有文档

样本测试成功后：

1. 逐个处理文档并进行错误处理
2. 记录每个文档的提取结果
3. 收集所有结果后再写入输出文件

results = []
errors = []

for doc_path in document_paths:
    try:
        data = extract_document(doc_path)
        results.append(data)
        print(f"✓ Processed: {doc_path}")
    except Exception as e:
        errors.append((doc_path, str(e)))
        print(f"✗ Failed: {doc_path} - {e}")

if errors:
    print(f"\nWarning: {len(errors)} documents failed to process")
    for path, error in errors:
        print(f"  - {path}: {error}")

步骤 6：文件操作前进行验证

移动文件或写入最终输出之前：

1. 比较提取出的记录数量与源文件数量
2. 抽查提取出的值，并与源文档核对
3. 确认输出格式符合要求

# Verification checklist
assert len(results) == len(document_paths), "Record count mismatch"

# Spot-check a few values
for sample in random.sample(results, min(3, len(results))):
    print(f"Please verify: {sample['filename']} -> Total: {sample['total']}")

步骤 7：移动文件（仅在验证后）

只有验证通过后，才执行以下操作：

# Move files to destination (not delete!)
for file in /source/documents/*.pdf; do
    mv "$file" /processed/
done

# Only remove backup after confirming processed files exist
ls /processed/*.pdf && rm -rf "$BACKUP_DIR"

常见问题

1. 未备份就执行破坏性命令

问题： 在确认成功之前使用 rm 或覆盖文件。 预防： 始终先创建备份；使用复制—验证—删除模式。

2. Shell 管道中的命令顺序

问题： rm -f *.pdf && mv *.pdf /dest/——文件会在移动前被删除。 预防： 先在样本数据上测试命令；了解执行顺序。

3. 未完整验证脚本

问题： 在生产数据上运行截断或不完整的脚本。 预防： 执行前检查脚本内容；先在样本上测试。

4. 编造缺失数据

问题： 提取失败时填写猜测的值。 预防： 明确报告失败；缺失值使用 null/空值。

5. 过早优化

问题： 发现值看起来不对就立即重新处理，未先调查原因。 预防： 先分析 OCR 输出和提取逻辑问题，不要移动文件。

6. PDF 与图像的处理方式

问题： 对基于文本的 PDF 使用 OCR，或对扫描版 PDF 使用文本提取。 预防： 选择提取方法前，先检查 PDF 是否包含可提取文本。

def is_text_based_pdf(pdf_path):
    """Check if PDF contains extractable text."""
    from pypdf import PdfReader
    reader = PdfReader(pdf_path)
    for page in reader.pages:
        if page.extract_text().strip():
            return True
    return False

验证策略

处理前验证

• 源文件存在且可读
• 已成功创建备份
• 已安装所需工具（tesseract、pdftotext、pypdf）
• 样本提取结果合理

后处理验证

• 输出记录数与输入文件数一致
• 未发生提取错误（或已记录错误）
• 抽查的值与源文档一致
• 输出格式符合要求（列和类型正确）
• 文件已移至正确的目标位置
• 在最终验证前保留原始备份

恢复计划

如果出现问题：

1. 立即停止——不要继续处理
2. 从备份恢复：cp -r "$BACKUP_DIR"/* /source/
3. 先调查故障原因，再重试
4. 在重新处理所有文件之前，先用样本修正提取逻辑

工具选择指南

文件类型	首选工具	备用工具
文本型 PDF	pypdf, pdftotext	-
扫描型 PDF	tesseract（在 pdf2image 之后）	pypdf
JPG/PNG 图像	tesseract	-
混合型 PDF（文本 + 扫描件）	优先使用 pypdf，图像页使用 tesseract	-

安装依赖：

# System packages
apt-get install tesseract-ocr poppler-utils

# Python packages
pip install pypdf pytesseract pdf2image pillow