自動保存・ファイルアップロード

自動保存のエンドポイント設計

BFF 側フロー

モードレス自動保存は、SPA のビュー遷移（TanStack Router の beforeLoad）をトリガーとして BFF に PATCH リクエストを送信する:

PATCH エンドポイント

PATCH /api/v1/{taxYear}/declarations/{id}
Content-Type: application/json
Idempotency-Key: {UUID v7}

{
  "spouseIncome": 580000,
  "dependents": [...]
}

レスポンス:

{
  "viewState": {
    "status": "draft",
    "updatedAt": "2026-01-15T10:30:00Z",
    "version": 4
  },
  "calculationPreview": {
    "yeaAnnualTax": 45500,
    "overUnderPayment": -155200,
    "diff": { "...CalculationDiff (Layer 1)" }
  }
}

• 仮計算結果は Draft 中の参考値であり、TaxCalculationResult としての確定はライフサイクル遷移（Draft → Submitted）時に行う
• calculationPreview.diff はフロントエンドで直前の計算結果との差分を表示するために使用

Idempotency-Key の BFF 側ハンドリング

• BFF は Idempotency-Key + エンドポイント + テナント ID でリクエストを一意に識別
• 同一キーの再送信: 初回レスポンスをキャッシュから返却（ステータスコード・ボディ・ヘッダーを含む）
• キー未指定の PATCH: 楽観的排他制御（ETag / If-Match）で保護されるため許容
• キーの有効期間: 24時間

---

ファイルアップロード・ウイルススキャン

マルチパートアップロードフロー

ダウンロード

• 署名付き URL（Cloud Storage Signed URL）を BFF が生成してフロントエンドに返却
• URL の有効期間: 15分
• ダウンロード時の認可チェックは BFF で実行（署名付き URL 生成前に権限を検証）

対象ファイル種別

種別	最大サイズ	拡張子
源泉徴収票 (PDF)	10MB	.pdf
保険料控除証明書 (XML)	5MB	.xml
送金関係書類	10MB	.pdf, .jpg, .png

→ 満たす要件: SR-006 マルウェア対策