家計簿アプリ (kakeibo-app)

三井住友カード(Vpass)の利用通知メール(Gmail経由)を自動取得し、カテゴリ分け・グラフ表示・月次集計を行う個人用家計簿Webアプリ。

• 取り込み: GitHub Actions (cron) が1時間毎にGmailからVpass通知メールを取得し、解析・分類してSupabaseに保存
• 表示: Next.js製フロントエンドがSupabaseから読み取り専用で取得し、グラフ・一覧を表示（Vercelでホスティング）
• 無料運用: GitHub Actions + Supabase + Vercelの無料枠のみで完結

初回セットアップの手順は docs/SETUP.md を参照してください。

アーキテクチャ

Gmail ([email protected]) → GitHub Actions (cron) → Supabase (Postgres) → Next.js (Vercel)

• 書き込みができるのはGitHub Actionsの取り込みジョブのみ（Supabase service role key使用）
• フロントエンドはSupabaseのanonキー(読み取り専用、Row Level Securityで制御)を使う
• transactions.gmail_message_id の一意制約により、取り込みジョブは何度再実行しても安全（冪等）

ローカル開発

npm install
cp .env.example .env.local   # Supabaseの値を入力
npm run dev

.env.local には最低限 NEXT_PUBLIC_SUPABASE_URL と NEXT_PUBLIC_SUPABASE_ANON_KEY が必要です（docs/SETUP.md 参照）。

取り込みジョブをローカルで手動テストする

GMAIL_CLIENT_ID=xxx \
GMAIL_CLIENT_SECRET=yyy \
GMAIL_REFRESH_TOKEN=zzz \
SUPABASE_URL=https://xxxx.supabase.co \
SUPABASE_SERVICE_ROLE_KEY=xxxx \
npm run ingest

実行するとGmailから直近2日分のVpass通知メールを検索し、新規分だけをSupabaseに登録します。既存のメールはgmail_message_idで重複排除されるため、何度実行しても安全です。

過去分のメールをまとめて取り込む(バックフィル)

Gmail検索の対象期間（直近2日分）より前の古いVpass通知メールをまとめて取り込みたい場合:

1. Gmail上で対象のメールを複数選択し、「転送」→「添付ファイルとして転送」で自分宛てに送る（1通に複数の.emlをまとめられる）
2. GitHub Actions Secretsに SELF_FORWARD_SENDER を追加し、転送元のメールアドレスを設定する
3. 次回の取り込みジョブ実行時（または手動実行）に、添付された.emlも自動的に解析・登録される

添付メール1件ごとに元のメールのMessage-IDで重複判定するため、同じ転送メールを何度処理しても二重登録されません。

新しいカード会社を追加する方法

1. ingest/parsers/types.ts の EmailParser インターフェースを実装した新しいファイルを ingest/parsers/ に追加する（例: rakuten.ts）。参考: ingest/parsers/smbc-vpass.ts
2. ingest/parsers/index.ts の parsers 配列に追加したパーサーを1行足す
3. supabase/schema.sql の cards テーブルに新しいカードの行を追加する（任意）

これだけで、Gmail検索クエリ（buildSearchQuery）・解析・分類の全パイプラインが自動的に新しいカードにも対応します。

ディレクトリ構成

• app/ — Next.js App Router のページ（ダッシュボード・取引一覧）
• components/ — チャート・UIコンポーネント
• ingest/ — Gmail取り込みスクリプト（GitHub Actionsから実行）
• lib/ — Supabaseクライアント・型定義・データ取得関数
• scripts/mint-gmail-refresh-token.ts — 初回のみローカルで実行するGmail認可スクリプト
• supabase/schema.sql — SupabaseのSQL Editorに貼り付けるスキーマ定義

今後の拡張（未実装・スキーマは準備済み）

• 予算管理機能: budgets テーブルと monthly_category_totals ビューを使った予算対比UI
• 他カード会社（楽天・JCBなど）のパーサー追加