Raqqa

共通資料：figma.make最小タッチ × AWS既存API連携（ローカル＋本番）

—

by

rakkaUser
in

1. 方針（要約）

  • **figma.make は“見た目の箱”**として採用。DOM/クラスは変更せず、必要なときだけ props を追加してデータ/イベントを受ける。
  • フロントは 常に /api/* を叩く。
    • ローカル: Vite の dev proxy が /api をローカルのAPI先（PF/モック）へ中継
    • 本番: CloudFront が /api/* を API オリジンへルーティング（同一オリジン化で CORS不要）
  • Router 主導の SPA として統合。各画面は 「Route要素＝コンテナ → figma箱」 の2段。本ドキュメントで扱うのは共通部分のみ（各画面の実データ接続/更新は別資料）。

2. 採用スタック（最小・堅牢）

層採用ねらい
開発/ビルドVitedev proxy で CORS回避・高速起動。figma 出力のTSXをそのまま動かす。
UIReact 18 + TypeScriptfigma.make と親和。props契約を型で固定。
ルーティングReact Router (SPA)画面＝ルート単位。SSR要件がなければ軽量。
取得/キャッシュTanStack Query取得・再取得・更新連動の標準化。
国際化i18n基盤（詳細は §5）固定文言＝辞書、DBラベル＝*_i18n。フォールバック規則を共通化。
モック/失敗系MSW / Prism（任意）バックエンド未稼働でも進められる（後述の“任意”運用）。
API契約OpenAPI（唯一の真実）型生成で契約順守を強制。

3. 環境構成（ローカル／本番 のみ）

3.1 ローカル（開発）

  • ブラウザ → Vite（SPA） → dev proxy → ローカルAPI先
    • API先は「PFで実API」「Prismモック（OpenAPIから自動）」「任意の手元API」のいずれか
  • 推奨設定
    • .env.development：VITE_API_BASE_URL=/api（相対に固定）
    • Vite dev proxy：/api をローカルAPI先へ中継（rewrite方針は全体で統一）
  • メリット：CORS不要・宛先を差し替えるだけで運用切替できる

3.2 本番（AWS・デモ）

  • CloudFront をフロントのエッジとして使用（推奨）
    • オリジン1：S3（SPAの静的配信）
    • オリジン2：API（APIGW/ALB/EKS/ECS/FastAPI 等、既存を尊重）
    • ビヘイビア:
      • /api/* → APIオリジン（必要なら prefix rewrite）
      • その他 → S3オリジン（SPAの index.html にフォールバック）
  • フロント設定
    • .env.production：基本は不要（VITE_API_BASE_URL=/api のまま）
  • メリット：同一オリジン扱いで CORS 設計が不要／フロントはどの環境でも同じビルドで動く

※ 本番をクロスオリジン運用にする場合は、API側で CORS 設定が必要（Origin/Methods/Headers/Credentials）。

4. 直線型プロセス（フェーズ分割せず“自然に”進める）

  1. figma 採り込み（最小タッチ）
    • figma.make 出力を SPA に“そのまま”配置して起動。モックのままで見た目が再現されることを確認。
    • 禁止：DOM/クラス変更・箱の内部で fetch/認証/i18n/権限実装。必要なら props を追加して受け口を作る。
  2. Router統合（共通AppShell 配下）
    • 画面＝Route要素（コンテナ）→ figma箱。AppShell に Toast/Confirm/Loader を1実装だけ置く。
  3. /api 接続の足場
    • ローカル：Vite dev proxy を /api → (PF/モック) に向ける。/api/openapi.json = 200 を確認。
    • 本番：CloudFront で /api/* を API へルーティング。/api/openapi.json = 200 を確認。
    • フロントのベースURLは両環境とも /api 固定（切替のための改修が不要）。
  4. i18n基盤を有効化（§5）
    • 固定文言と DBラベルを分離。フォールバック規則を共通化。
    • 言語切替 UI（AppShell）を追加して即時反映を確認。
    • figma箱は解決済みの文字列を props でもらうだけ（箱にi18nロジックを入れない）。

※ 各画面の D（READ接続）/E（更新） は別の個別資料で行います（コンテナで取得→アダプタでprops化→箱へ注入／更新は useMutation 方針・二重送信防止・Problem+JSON マッピング等）。

5. 日本語/英語の切替（i18n）— 詳細

5.1 方針

  • 固定文言（ボタン名・見出し・空/エラー文言など）… i18n辞書で管理
  • DB由来ラベル（モデル名・フィールド名など）… APIの *_i18n を最優先
  • フォールバック規則（共通・固定）
    • 例：label_i18n.ja_JP → label → model
    • 英語側も同様：label_i18n.en_US → label → model
  • figma箱には i18nロジックを入れない：解決済みの文字列を props で渡す

5.2 言語の決定順序（推奨）

  1. ?lang=ja-JP|en-US（URLクエリがあれば最優先）
  2. localStorage.lang（ユーザが最後に選んだもの）
  3. navigator.language（ja or en を ja-JP/en-US に正規化）
  4. VITE_I18N_DEFAULT_LOCALE（既定、例：ja-JP）

AppShell の言語スイッチャで変更時：URL/localStorage/i18nコンテキストを更新し、即時反映。

5.3 APIとの連携（どちらでも可・両対応可能）

  • A：多言語一括返却型（推奨）
    • API が label_i18n: { ja_JP, en_US } を返す場合、アダプタで選択して文字列を決める。
    • 言語切替時は 再フェッチ不要（UI側で再解決するだけ）。
  • B：言語別返却型（Accept-Language など）
    • Interceptor で Accept-Language: ja-JP|en-US を付与、APIが該当言語の値を返す。
    • 切替時は再フェッチ（または lang クエリ付与）。
  • どちらの方式でも、アダプタで最終フォールバック（label→model）を担保。

5.4 受け入れ基準（i18n）

  • スイッチ操作で 固定文言が即時反映
  • DBラベルは A方式なら即時／B方式なら再フェッチ後に反映
  • 欠落時は フォールバック で自然な文言（“不明”など極力回避）

6. 任意：ローカルで「形だけのバックエンド」が欲しい場合

  • Prism（OpenAPI → 自動モック）：OpenAPIから即席HTTPサーバ。/api のまま差し替え可能。
  • MSW（ブラウザ内モック）：失敗系（422/409/500/Timeout）を注入して UI 復帰を検証。
  • いずれも 本番には一切影響なし。必要に応じて使い分け。

7. 受入チェック（この共通資料の範囲）

ローカル

  • SPA が起動し figma 箱が描画（箱は props 追加のみの差分）
  • http://localhost:<port>/api/openapi.json が 200（CORS 警告なし）
  • 言語スイッチで固定文言が即時反映（DBラベルは方式に応じた挙動）

本番（AWS）

  • CloudFront：/api/* が API オリジンへ、その他は S3（SPA）へ
  • https://<domain>/api/openapi.json が 200
  • 言語スイッチが機能（A方式=即時／B方式=再フェッチ後）

8. 提出物（検収に必要な証跡）

  • 画面スクリーンショット（トップ、代表セクション、言語スイッチの前後）
  • Network：/api/openapi.json の 200（ローカル/本番）
  • diff --stat：figma 箱の差分が props 追加のみであること
  • CloudFront の /api ルーティング要約（1〜2行）

Comments

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です