キャッシュ戦略・OpenAPI 仕様管理

キャッシュ戦略

TanStack Query との協調

BFF は Cache-Control レスポンスヘッダーを通じて、フロントエンドの TanStack Query キャッシュ戦略と協調する。

データ分類別キャッシュ方針

データ分類	例	Cache-Control	ETag	TanStack Query staleTime
不変データ	Finalized TaxCalculationResult、確定済み源泉徴収票	public, max-age=86400, immutable	あり	Infinity
年度パラメータ	TaxYearMaster、DeductionTypeMaster	public, max-age=3600	あり	1時間
マスタデータ	通貨コード、元号テーブル	public, max-age=86400	あり	24時間
ユーザーデータ（確定）	Approved/Submitted Declaration	private, max-age=60	あり	1分
ユーザーデータ（編集中）	Draft Declaration	private, no-cache	あり	0（常に再検証）

ETag によるキャッシュ検証

• BFF は DeclarationSnapshot の UpdatedAt + Version から ETag を生成
• フロントエンドの TanStack Query が If-None-Match ヘッダーを送信
• BFF は ETag が一致すれば 304 Not Modified を返却（ViewModel 変換をスキップ）

# リクエスト
GET /api/v1/2025/declarations/abc
If-None-Match: "v3-2026-01-15T10:30:00Z"

# レスポンス（変更なし）
304 Not Modified
ETag: "v3-2026-01-15T10:30:00Z"

---

OpenAPI 仕様管理

二層スキーマ戦略

スキーマ	消費者	内容	型生成
BFF OpenAPI 仕様	React SPA	ポータル別 ViewModel のスキーマ	openapi-typescript → TypeScript 型 → Zod スキーマ
Backend OpenAPI 仕様	外部連携システム	汎用 API スキーマ	外部向けドキュメントとして公開

フロントエンド型生成フロー

• BFF OpenAPI 仕様はスキーマ駆動開発の単一の情報源（Single Source of Truth）
• operationId を全エンドポイントに付与し、TanStack Query のクエリキー生成に使用
• フロントエンドでの手動 API 型定義は禁止

→ 満たす要件: OP-002 相互運用性