Claude CodeでStripeの返金とチャージバックを実装する — 状態の記録と証拠の準備

## 返金・不審請求
- 台帳 `payment_cases` の主キーは返金行・不審請求IDにし、同じ行は上書きで更新する
- イベントの中身は信じず、処理時点のAPIで取り直した値を台帳に書く
- 権限の変更は `src/billing/access.ts` の関数だけが行う。webhookの処理から直接触らない
- 不審請求の `evidence_details.due_by` を必ず台帳に残す
- 証拠のAPI呼び出しは `submit: false` のみ。`submit: true` はコードに書かない
- 検証は `npm test -- test/disputes`。落ちたまま完了と言わない

src/billing/ に返金と不審請求の処理を実装して。
CLAUDE.mdの規約に従うこと。
charge.refunded と charge.dispute.created / closed を受ける
ハンドラを書き、同じイベントを2回流しても台帳が変わらないテストを
test/disputes/ に先に書いて、落ちることを確認してから実装して。

// src/billing/cases.ts
db.exec(`CREATE TABLE IF NOT EXISTS payment_cases (
  case_id TEXT PRIMARY KEY,          -- "refund:ch_xxx" または dp_xxx(不審請求)
  kind TEXT NOT NULL CHECK (kind IN ('refund','dispute')),
  charge_id TEXT NOT NULL,
  payment_intent_id TEXT,
  amount INTEGER NOT NULL,           -- 通貨の最小単位
  currency TEXT NOT NULL,
  status TEXT NOT NULL,
  due_by INTEGER,                    -- 不審請求の回答期限(UNIX秒)
  updated_at TEXT NOT NULL
)`);
 
const upsert = db.prepare(`
  INSERT INTO payment_cases
    (case_id, kind, charge_id, payment_intent_id, amount, currency, status, due_by, updated_at)
  VALUES (@case_id, @kind, @charge_id, @payment_intent_id, @amount, @currency, @status, @due_by, @now)
  ON CONFLICT(case_id) DO UPDATE SET
    amount = excluded.amount, status = excluded.status,
    due_by = excluded.due_by, updated_at = excluded.updated_at`);
 
export async function onChargeRefunded(stripe: Stripe, event: Stripe.Event) {
  const fromEvent = event.data.object as Stripe.Charge;
  // 順序の入れ替わりに備え、処理時点のChargeを取り直す
  const charge = await stripe.charges.retrieve(fromEvent.id);
  const full = charge.amount_refunded >= charge.amount;
 
  upsert.run({
    case_id: `refund:${charge.id}`, kind: "refund", charge_id: charge.id,
    payment_intent_id: (charge.payment_intent as string | null) ?? null,
    amount: charge.amount_refunded, currency: charge.currency,
    status: full ? "refunded_full" : "refunded_partial",
    due_by: null, now: new Date().toISOString(),
  });
 
  if (full) await revokeAccessForCharge(stripe, charge);
}

// src/billing/access.ts
export async function revokeAccessForCharge(stripe: Stripe, charge: Stripe.Charge) {
  const subId = await findSubscriptionId(stripe, charge.payment_intent as string | null);
  if (!subId) return; // 請求書と結びつかない支払い。サブスクの権限は触らない
  setEntitlement(subId, "revoked");
}
 
export async function holdAccessForCharge(stripe: Stripe, paymentIntentId: string | null) {
  const subId = await findSubscriptionId(stripe, paymentIntentId);
  if (subId) setEntitlement(subId, "on_hold");
}

function recordDispute(dispute: Stripe.Dispute, pi: string | null) {
  upsert.run({
    case_id: dispute.id, kind: "dispute", charge_id: dispute.charge as string,
    payment_intent_id: pi, amount: dispute.amount, currency: dispute.currency,
    status: dispute.status, due_by: dispute.evidence_details?.due_by ?? null,
    now: new Date().toISOString(),
  });
}
 
export async function onDisputeCreated(stripe: Stripe, event: Stripe.Event) {
  const dispute = event.data.object as Stripe.Dispute;
  const pi = (dispute.payment_intent as string | null)
    ?? ((await stripe.charges.retrieve(dispute.charge as string)).payment_intent as string | null);
 
  recordDispute(dispute, pi);
  await holdAccessForCharge(stripe, pi);
  await notifyOwner(`不審請求 ${dispute.id}: 期限 ${dispute.evidence_details?.due_by}`);
}

export async function onDisputeClosed(stripe: Stripe, event: Stripe.Event) {
  const dispute = event.data.object as Stripe.Dispute; // status は won または lost
  const pi = dispute.payment_intent as string | null;
  recordDispute(dispute, pi);
 
  const subId = await findSubscriptionId(stripe, pi);
  if (subId) setEntitlement(subId, dispute.status === "won" ? "active" : "revoked");
}

// scripts/dispute-evidence.ts  使い方: tsx scripts/dispute-evidence.ts dp_xxx [--stage]
const dispute = await stripe.disputes.retrieve(id);
const row = db.prepare(
  `SELECT u.name, u.email, u.signup_ip, o.service_started_at
     FROM orders o JOIN users u ON u.id = o.user_id
    WHERE o.charge_id = ?`
).get(dispute.charge as string);
 
const evidence = {
  customer_name: row?.name,
  customer_email_address: row?.email,
  customer_purchase_ip: row?.signup_ip,
  service_date: row?.service_started_at?.slice(0, 10),
  access_activity_log: buildAccessLog(dispute.charge as string), // 利用ログの要約
};
 
console.table(Object.entries(evidence).map(([k, v]) => [k, v ? "あり" : "空"]));
if (process.argv.includes("--stage")) {
  await stripe.disputes.update(id, { evidence: clean(evidence), submit: false });
  console.log("下書きを保存しました。提出はダッシュボードで行います。");
}

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/dispute-guard.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/dispute-guard.sh
COMMAND=$(jq -r '.tool_input.command')
 
if echo "$COMMAND" | grep -q 'dispute-evidence' && echo "$COMMAND" | grep -q 'sk_live'; then
  jq -n '{hookSpecificOutput: {hookEventName: "PreToolUse",
    permissionDecision: "deny",
    permissionDecisionReason: "本番キーでの証拠スクリプトの実行は人が行います"}}'
else
  exit 0
fi