PDF Batch Field Extractor

Overview

Batch-extract specified content from multiple PDF files and consolidate
the results into a formatted Excel spreadsheet. Each row corresponds to
one PDF file, identified by its filename. Built-in support for Chinese
customs declarations (报关底单) and bills of lading (提单), with
extensible custom-field extraction via user-supplied regex.

When to Use

• User provides a folder or ZIP of PDFs and wants specific fields
  extracted into Excel (e.g., "帮我提取这些PDF里的件数和毛重").
• User has customs/logistics documents (报关单, 提单, 发票, etc.) and
  needs structured data extraction.
• User wants to batch-process PDFs and match results by filename.

Quick Start

Run the extraction script directly. The script accepts a directory or
ZIP file as input and produces an .xlsx file as output.

# Basic usage: extract 件数, 毛重, 净重 from a folder
python scripts/extract_pdf_fields.py -i ./pdfs/ -o result.xlsx -f 件数,毛重,净重

# From a ZIP file
python scripts/extract_pdf_fields.py -i ./archive.zip -o result.xlsx -f 件数,毛重

# With custom field (user-supplied regex)
python scripts/extract_pdf_fields.py -i ./pdfs/ -o result.xlsx \
  -f 件数,毛重,提单号 --custom "提单号:B/L NO\.?\s*(\S+)"

Dependencies: pdfplumber, openpyxl — install with:

pip install pdfplumber openpyxl

Built-in Fields

Extraction Strategy by PDF Type

The script auto-detects PDF type from text content and applies the
appropriate extraction order:

1. 报关底单 (Customs Declaration): Use the structured "header + data
   line" strategy first — find the line containing both 件数 and
   毛重(千克), then read pure-number tokens from the next data line.
   First integer = 件数, first decimal = 毛重, second decimal = 净重.

2. 提单 (Bill of Lading): Use regex patterns for English-format
   fields (CTNS, KGS, CBM).

3. Unknown type: Try BOL regex first, then customs declaration strategy.

Custom Fields

For fields not in the built-in list, use --custom "field_name:regex":
- The first capture group (…) in the regex is extracted as the value.
- Multiple --custom flags can be combined.
- Regex uses Python re syntax with IGNORECASE | MULTILINE flags.

Examples:

# Extract bill of lading number
--custom "提单号:B/L NO\.?\s*(\S+)"

# Extract container number
--custom "集装箱号:([A-Z]{4}\d{7})"

# Extract customs declaration number
--custom "海关编号:海关编号[：:]\s*(\d+)"

Script Parameters

Excel Output Format

• Columns: 序号 | 文件名 | 文件类型 | 编号 | [extracted fields] | 备注
• Color coding: Green = all fields found; Yellow = error/partial.
• Freeze panes: Header row is frozen for easy scrolling.
• Auto-width: Column widths adapt to content (max 55 chars).

Handling Edge Cases

• Scanned PDFs (image-only): The script reports "无法提取文本" in
  the 备注 column. These require OCR — use an OCR tool (e.g., Tesseract,
  PaddleOCR) to convert to text first, then re-run.
• Mixed document types in one folder: The script handles this
  automatically — each PDF is processed with the appropriate strategy
  based on its detected type.
• Missing fields: If a field cannot be found, the cell shows "未找到"
  and the row is highlighted yellow.
• Encoding: Filenames with Chinese characters are handled correctly
  on Windows, macOS, and Linux.

Workflow for Common Requests

1. User provides PDFs (folder or ZIP) and specifies fields to extract.
2. Determine if the requested fields are built-in or need custom regex.
3. Run the script with appropriate parameters.
4. Present the Excel file to the user via present_files.

For detailed field extraction patterns and PDF format documentation,
see references/field_patterns.md.