PDF 發票證明聯處理器

一個專為多家寵物用品店設計的 PDF 發票處理自動化工具，能夠批量解密、分類歸檔並合併 PDF 發票證明聯。

作者：Bruce Yang & AI Copilot

🚀 主要功能

• 批量解壓縮：自動解壓縮 pdfs_inbox/ 目錄中的 ZIP 檔案
• 智能解密：使用各店家統一編號作為密碼自動解密 PDF 檔案
• 自動分類：按店家和月份將發票 PDF 分類歸檔至 archive/ 目錄
• PDF 合併：每月自動合併同一店家的所有發票為單一 PDF 檔案
• Excel 報表：產生詳細的發票處理摘要 Excel 報告
• 自動清理：處理完成後自動清空暫存目錄
• 智慧路徑：支援腳本和 EXE 兩種執行模式
• 防呆機制：完善的錯誤處理和配置檔案驗證

📦 安裝與設定

1. 複製專案

git clone [repository-url]
cd pdf_invoice_processor

2. 建立虛擬環境（建議）

# Windows
python -m venv venv
venv\Scripts\activate

# Linux/macOS
python -m venv venv
source venv/bin/activate

3. 安裝依賴套件

pip install -r requirements.txt

4. 配置檔案設定

複製範例配置檔案並填入實際資料：

# 複製範例檔案
cp config/passwords.yaml.example config/passwords.yaml

# 編輯配置檔案，填入各店家的統一編號

5. 目錄結構

pdf_invoice_processor/
├── main.py                      # 主程式（含智慧路徑處理）
├── README.md
├── requirements.txt             # 依賴套件清單
├── build_exe.spec               # PyInstaller 打包規格檔案
├── run.bat                      # Windows CMD 啟動腳本
├── run.ps1                      # PowerShell 啟動腳本
├── assets/
│   └── icon.ico                 # EXE 圖示檔案（build_exe.spec 已使用）
├── pdfs_inbox/                 # 待處理 ZIP 檔案放置處
├── temp/                        # 解壓縮暫存目錄（自動清理）
├── archive/                     # 按店家/月份分類的解密 PDF
├── output/                      # 合併後的 PDF 和 Excel 報告
├── reports/                     # 其他報告檔案
├── config/
│   ├── passwords.yaml           # 店家資訊和統一編號配置（需自行建立）
│   └── passwords.yaml.example   # 配置檔案範例
└── venv/                        # Python 虛擬環境（建議使用）

⚙️ 配置檔案

config/passwords.yaml

此檔案包含各店家的基本資訊和統一編號（用作 PDF 解密密碼）。首次使用時，請複製範例檔案並填入實際資料：

# 複製範例檔案
cp config/passwords.yaml.example config/passwords.yaml

配置格式：

stores:
  店家名稱:
    company: 公司正式名稱
    uniform_id: '統一編號8碼'

配置說明：

• 可在 config/passwords.yaml 中配置多個店家
• 每個店家需提供統一編號作為 PDF 解密密碼
• 統一編號必須為 8 碼數字
• 請參考 config/passwords.yaml.example 了解完整配置格式

配置檔案驗證：

• 自動檢查檔案格式和結構
• 驗證統一編號是否為8碼數字
• 支援多路徑配置檔案讀取（腳本/EXE模式）
• 格式錯誤的店家配置會被忽略並顯示警告

🔧 使用方法

1. 準備檔案

將包含發票 PDF 的 ZIP 檔案放入 pdfs_inbox/ 目錄

2. 執行主程式

方法一：使用啟動腳本（推薦）

# PowerShell
.\run.ps1

# 或 CMD
run.bat

方法二：手動執行

# 確保虛擬環境已激活
python main.py

3. 處理流程

程式將自動執行以下步驟：

1. 初始化：建立必要目錄結構
2. 解壓縮：解壓縮 pdfs_inbox/ 中的所有 ZIP 檔案至 temp/
3. 掃描識別：掃描並識別發票證明聯 PDF 檔案
4. 智能解密：使用各店家統一編號嘗試解密 PDF
5. 分類歸檔：將成功解密的 PDF 按店家和月份分類存放至 archive/
6. PDF 合併：按月份合併同一店家的所有 PDF 至 output/
7. 生成報表：生成包含處理摘要的 Excel 報告至 output/
8. 執行總結：顯示處理結果統計
9. 自動清理：清空 temp/ 暫存目錄

4. 程式特色

• 智慧路徑處理：自動區分資源檔案路徑和工作目錄路徑
• 防呆機制：完善的錯誤處理和配置檔案驗證
• 自動清理：處理完成後自動清空暫存檔案
• 模組化設計：清晰的程式結構和功能分離
• 雙模式支援：同時支援腳本執行和 EXE 封裝

📋 輸出說明

Archive 目錄結構

archive/
└── [店家名稱]/
    └── [年-月]/
        ├── 發票證明聯_MF12345678_20240101.pdf
        └── 發票證明聯_MF23456789_20240102.pdf

Output 目錄內容

• [店家]_[年-月]_invoice.pdf：該店家當月所有發票的合併檔案
• invoice_summary_[時間戳記].xlsx：詳細的處理摘要報告

📄 檔案命名規則

發票 PDF 檔案需遵循以下命名格式：

• 發票證明聯_[發票號碼]_[YYYYMMDD].pdf
• 發票號碼格式：2碼字母 + 8碼數字（如：MF12345678）

⚠️ 注意事項

1. 密碼配置：確保 config/passwords.yaml 中的統一編號正確無誤
2. 檔案格式：僅處理以「發票證明聯」開頭的 PDF 檔案
3. 自動清理：temp/ 目錄會在處理完成後自動清空
4. 編碼支援：完全支援繁體中文檔名和內容
5. 錯誤處理：程式具備完善的錯誤處理機制，執行失敗時會顯示詳細錯誤信息
6. 虛擬環境：建議使用虛擬環境隔離專案依賴，避免套件衝突
7. Windows 編碼：如遇 emoji 顯示問題，使用 run.ps1 會自動處理編碼設定

🛠️ 技術架構

核心功能模組

• PDF 處理：PyPDF2 3.0.1（解密、合併、讀寫）
• Excel 操作：pandas 2.3.3 + openpyxl 3.1.5（報表生成）
• YAML 配置：PyYAML 6.0.3（配置檔案解析）
• 檔案操作：shutil（目錄清理）
• 日期處理：python-dateutil（日期解析）

依賴套件清單

所有依賴套件已記錄在 requirements.txt 中，包含：

• PyPDF2>=3.0.0
• pandas>=2.0.0
• PyYAML>=6.0
• openpyxl>=3.1.0

程式結構

• 路徑工具：智慧路徑處理和資源管理
• 配置載入：防呆機制和多重路徑支援
• 檔案處理：解壓縮、解密、分類、合併
• 報表生成：Excel 摘要和執行統計
• 自動清理：暫存檔案管理和錯誤處理

📦 EXE 封裝

打包為執行檔

專案支援使用 PyInstaller 打包為獨立的 EXE 執行檔，無需安裝 Python 環境即可執行。

打包步驟：

1. 安裝 PyInstaller

   pip install pyinstaller

2. 執行打包命令

   pyinstaller build_exe.spec

3. 打包完成後

   • EXE 檔案位於 dist/PDF發票處理器.exe
   • 將 config/passwords.yaml 放在 EXE 同目錄的 config 資料夾中
   • 首次執行時，程式會自動建立必要的目錄結構

打包說明：

• 使用 build_exe.spec 規格檔案進行打包
• 自動包含必要的依賴套件和隱藏導入
• 包含範例配置檔案 passwords.yaml.example
• 打包後的 EXE 支援智慧路徑處理，可正確讀取配置檔案

注意事項：

• 打包前請確保 config/passwords.yaml 已正確配置
• EXE 檔案較大（約 100-200MB），因為包含了所有依賴套件
• 首次執行可能需要較長時間載入
• 打包後的 EXE 需要將 config/passwords.yaml 放在 EXE 同目錄的 config 資料夾中
• 建議將整個專案資料夾（包含 config/, pdfs_inbox/, archive/, output/ 等）一起搬移，而不是只搬單一 EXE 檔案

📊 系統需求

執行環境

• Python 3.7+
• Windows/macOS/Linux
• 所需套件詳見 requirements.txt

打包需求（可選）

• PyInstaller 6.0+（用於打包為 EXE）
• 安裝方式：pip install pyinstaller

---

💡 提示：

• 使用 run.ps1 或 run.bat 可快速啟動程式，無需手動激活虛擬環境
• 啟動腳本會自動檢查虛擬環境是否存在，並處理編碼問題
• 所有依賴套件版本詳見 requirements.txt
• 打包為 EXE 後，可在沒有 Python 環境的電腦上執行