mailquill

把散落在 Gmail 裡的銀行／信用卡帳單，安靜地收攏成一本私密、離線的財務帳。

Mailquill 讀取你 Gmail 中的台灣銀行／信用卡財務信件（電子帳單、消費通知、收據），解密 PDF、用純規則解析成結構化交易、做兩層分類，寫入 CSV（唯一真實來源），再產生一份自包含的離線 HTML 儀表板，讓你核對消費紀錄／金流／類別統計。

🔒 全本地處理：純 rule-based，零 LLM、零雲端；Gmail 僅唯讀存取。你的帳單、金額、卡號從不離開這台電腦。

---

✨ 特色

• 收件匣直接變帳本 — 依你在 Gmail 已分類的 Label 抓信，自動辨識銀行、解析明細。
• 解密加密 PDF — 用你本地的密碼清單（passwords.txt）自動嘗試解鎖電子帳單。
• 純規則、可稽核 — 每家銀行一支 parser，正則對版型；不猜、不呼叫任何模型，結果可複現。
• 兩層分類、隨你調 — 關鍵字 → (第一層, 第二層)，大小寫／全半形不敏感；改完一鍵重分類。
• 離線互動儀表板 — 單一 HTML 檔，零外部資源；可依銀行／分類／月份篩選，支援深色主題、正負金額紅綠標示、未分類整理面板。
• 永不靜默丟資料 — 無對應 parser、PDF 解不開、金額解析失敗，都會列成清單讓你逐步補齊。

---

📸 畫面預覽

總覽：淨消費／筆數／月均 + 月度趨勢；一鍵切換深色主題，分類／品類支援階層勾選（虛線＝部分選取）。

分類拆解：第一層占比圓餅 + 第二層品類 Top，長條／圓餅可切換。

負向表列：品類「排除」模式（紅色刪除線）＋跨銀行篩選。

---

🚀 快速開始

python3 -m venv .venv
.venv/bin/python -m pip install -e .          # 安裝
.venv/bin/python -m pip install -e ".[dev]"   # 含測試相依(選用)

# 1) 設定 Google OAuth、config.yaml、passwords.txt（見 docs/SETUP.md）
# 2) 從既有 Gmail Label 產生抓取規則草稿，檢查後即可
mailquill bootstrap

# 3) 抓信 → 解密 → 解析 → 分類 → 寫入 CSV / 重建 DB
mailquill run

# 4) 產生離線 HTML 儀表板
mailquill report        # → report.html，用瀏覽器打開

完整的 Google Cloud OAuth 申請、設定檔與密碼清單步驟，請見 設定指南 · docs/SETUP.md。 mailquill 與 python -m mailquill.cli 等價。

---

🔁 一次抓信，之後只重建／重報表（不用一直重抓）

Mailquill 的核心是 CSV 是唯一真實來源（single source of truth），SQLite 與 HTML 報表都只是它的衍生產物、隨時可丟可重建。這讓大多數日常操作完全不需要再連 Gmail：

                       ┌──────────── 只有這一步碰 Gmail ────────────┐
  Gmail ──(唯讀抓信)──▶ run ──▶ 解密PDF ──▶ 各家 parser ──▶ 正規化 ──▶ 分類
                                                                   │
                                                                   ▼
                                                    transactions.csv  ◀── 唯一真實來源(去重)
                                                          │
                        rebuild(改了 categories.yaml)  ◀──┤
                                                          ▼
                                                    mailquill.db(可重建的查詢層)