機能3：クレカ CSV 照合

1. 概要・目的

法人クレジットカードの CSV 明細を 証憑管理簿（14列スプレッドシート）に 自動登録し、既存の受領証憑（レシート・領収書）と突合できる状態を作る機能。

前提：証憑管理簿の位置づけ

• スプシ ID：1F6PTXD3ckob3EeglnS7gyjSG6RM0CS-PKRaoBwzXK-E　タブ名：証憑管理簿
• 14列（A〜N）構造、sheet_writer_v4.py で書き込む（connect8_ai 認証）
• Freee への書き込みは今回スコープ外。スプシが叩き台、確定は人間が Freee UI で実施

2. スコープ

3. 全体フロー

3-1. CSV 取込フロー

3-2. PDF 明細保管フロー（設計のみ・実装は承認後）

3-3. システム全体図

【投入】
  CEO → INBOX_creditcard/ (Drive)
         ├─ CSV ファイル  → うーぱん CSV パイプライン
         └─ PDF 明細     → Codex リネーム → Drive 保管フォルダ

【CSV パイプライン】
  INBOX_creditcard/
    ↓ カード判定
  カード別アダプタ（amex_adapter.py / smbc_adapter.py[stub] / ...）
    ↓ 共通内部スキーマ
  dedup チェック（日付+金額+外貨 vs 既存クレカ明細行）
    ↓
  sheet_writer_v4.append_row() → 証憑管理簿タブ
    ↓ G列=クレカ明細
  [次フェーズ] reconciler → I列（突合記号）埋め

【証憑管理簿（最終状態のイメージ）】
  row 100: 2026-05-01 | 474 | 76,960 VND | GRAB | 会社支払 | 電子証憑 | 電子その他 | [レシートURL] | ◯ | ...
  row 200: 2026-05-01 | 474 | 76,960 VND | GRAB | 会社支払 | 電子証憑 | クレカ明細  | [明細URL]    | ◯ | ...
                                                                                              ↑ I列で突合

4. マッピング表（確定版）

4-1. AMEX CSV 列定義

4-2. 証憑管理簿 14列へのマッピング

5. dedup（重複カット）仕様

5-1. 照合キー

証憑管理簿の既存行のうち G列 = "クレカ明細" の行に対して以下の3軸で照合する。

5-2. 判定結果

6. 照合（reconciliation）方針

Phase 1（今回）: 明細 side 登録

• クレカ CSV の各行を G列=「クレカ明細」として証憑管理簿に追加
• I列（突合記号）は空欄のまま
• 既存レシート行（G=電子その他 等）とは独立して共存

Phase 2（次フェーズ）: 突合エンジン

以下のキーで「クレカ明細行」と「レシート行」を照合し、I列に突合記号を書き込む。

GRAB 分割計上の特殊ルール

7. カード別 CSV アダプタ設計

7-1. 共通内部スキーマ（CardTransaction）

@dataclass
class CardTransaction:
    use_date:      date        # 発生日（ご利用日）
    amount_jpy:    int         # 日本円請求額（1円単位）
    store_name:    str         # 店舗名（原文）
    foreign_str:   str | None  # 外貨表示文字列 例: "76,960 VND"
    card_label:    str         # カード識別名 例: "AMEX"
    source_file:   str         # 元CSVファイル名
    card_last4:    str | None  # カード下4桁（マスク済）
    fx_rate:       float | None  # 換算レート（参考値）

7-2. アダプタ一覧

7-3. カード自動判定ロジック

7-4. アダプタ共通インターフェース

class BaseCardAdapter(ABC):
    CARD_LABEL: str  # "AMEX" / "SMBC" / etc.

    @classmethod
    def can_handle(cls, headers: list[str]) -> bool:
        """CSVヘッダ行から対応可否を返す"""
        ...

    def parse(
        self,
        filepath: str,
        fiscal_year: int = 2026,  # 年度（MM/DD → YYYY-MM-DD 変換用）
    ) -> list[CardTransaction]:
        """CSV をパースして CardTransaction リストを返す"""
        ...

8. INBOX 提案（CEO 承認待ち）

8-1. 提案フォルダ

8-2. フォルダ内の流れ（承認後）

8-3. SUICA ポーラーとの比較

9. AMEX プロトタイプ

9-1. テストタブ

プロトタイプの書き込み先：証憑管理簿スプシ内に一時タブ _proto_creditcard を作成。 主シート「証憑管理簿」本体には書かない。

9-2. フィクスチャデータ（AMEX GRAB 18件）

今会話で確認した実データ（2026年5月 ベトナム GRAB 利用）を fixture として使用。

9-3. 整形後の出力（dry-run）

以下が証憑管理簿 14列フォーマットに変換した結果。

合計 18 件。JPY 合計: 6,348 円。VND 合計: 1,030,720 VND

9-4. プロトタイプスクリプト

実装ファイル：2_Areas/A10_corporate_finance/phase_b_reimbursement/creditcard/amex_adapter.py

実行方法（CEO 承認後、テストタブへの書き込み時）：

# dry-run モード（スプシへの書き込みなし・整形結果のみ出力）
python amex_adapter.py --csv 20260609_amex_grab_charges.csv --dry-run

# テストタブ書き込みモード（_proto_creditcard タブに書く・主タブは触らない）
python amex_adapter.py --csv 20260609_amex_grab_charges.csv --test-tab

10. CEO 判断ポイント

11. 変更履歴