状態管理・ルーティング設計

状態管理戦略

サーバー状態 vs クライアント状態

状態の種類	管理方法	例
サーバー状態	TanStack Query	従業員データ、申告データ、マスタデータ
クライアント状態	React Context / useState	UIの開閉状態、一時的なフォーム入力
認証状態	React Context + BFF セッション	ログイン状態、ユーザーロール、テナントID。JWT はブラウザに渡さず BFF サーバーサイドで管理（→ BFFアーキテクチャ）

キャッシュ戦略

• Stale-While-Revalidate: 古いデータを表示しつつ、バックグラウンドで更新
• Optimistic Updates: 自動保存時に即座にUIを更新し、エラー時にロールバック
• キャッシュ無効化: コマンド実行後に関連クエリを即座に無効化（CQRSの即時整合性に対応）

---

ルーティング設計

型安全ルーティング

• TanStack Routerによる型安全なルーティング
• URLパラメータの型検証
• ルート間のデータプリフェッチ

URL構造

# 従業員ポータル
/employee/                                  # ダッシュボード
/employee/{taxYear}/declaration             # 申告フロー
/employee/{taxYear}/declaration/confirm     # 最終確認
/employee/settings                          # 個人設定

# 管理者ポータル
/admin/                                     # ダッシュボード
/admin/{taxYear}/declarations               # 申告一覧
/admin/{taxYear}/declarations/{id}          # 従業員詳細
/admin/{taxYear}/reports                    # 帳票出力
/admin/employees                            # 従業員マスタ
/admin/settings                             # 企業設定

# 代行事業者ポータル
/agency/                                    # 横断ダッシュボード
/agency/tasks                               # Global Task Queue
/agency/clients                             # 顧問先一覧
/agency/clients/{tenantId}/...              # 顧問先コンテキスト（管理者ポータル同等）

# システム管理
/system/                                    # システムダッシュボード
/system/tenants                             # テナント管理
/system/masters                             # マスタ管理
/system/jobs                                # ジョブ監視