フェーズA：コード基盤の整備（Make→実装向けの骨格化）

目的：自動生成コードを“運用できる構成”に整える
主要タスク

• Next.js/React（またはVite）化・ディレクトリ整理（src/features/{portal-fields,...} など）。
• Tailwind / shadcn/ui 導入（Make由来のスタイルを段階的に置換）。
• 画面単位の状態フレームをそのままコンポーネント分割（List / Detail / Overlays）。
• UI要素に data-id を付与（テストとアクセシビリティ用）。
  成果物：整理済みフロントrepo、UIコンポーネント群
  DoD：ローカルでUIが静的データで表示／遷移できる

---

フェーズB：API契約の固定（OpenAPI を唯一の真実に）

目的：境界（スキーマ）を固定してドリフトを防止
主要タスク

• openapi.yaml を**タグ付け（vX.Y.Z）**して固定（GET/POST/PATCH/DELETE、エラー=Problem+JSON、ページング=cursor）。
• openapi-typescript 等で TS型/SDK自動生成、CIで差分検知。
  成果物：openapi.yaml（タグ付）、src/types/api.d.ts / src/api/sdk.ts
  DoD：npm run typegen で型が再生成され、型エラーが0

---

フェーズC：環境・接続設定（CORS/Proxy/Env）

目的：フロント→API の通信路を安定化
主要タスク

• .env.* に API_BASE_URL・AUTH_* を定義。
• 接続は (1) 直接CORS or **(2) 開発プロキシ（Next rewrites / Vite proxy）**を採用。
• FastAPI側でdevのみCORS緩和（origins=localhost:ポート）。
  成果物：.env.development、next.config.js/vite.config.ts、FastAPI CORS設定
  DoD：fetch(API_BASE_URL) が 200 で通る

---

フェーズD：読み取り統合（List/DetailのGET）

目的：まずはRead-onlyで安定接続
主要タスク

• React Query 導入（useQuery）・Skeleton・空状態・エラー表示。
• ページング（cursor）・ソート・検索のクエリパラメータ実装。
• i18n字段（label_i18n.ja_JP 等）の表示ロジック・フォールバック。
  成果物：usePortalFieldsList(), usePortalField(id) のhooks、画面実装
  DoD：一覧→詳細の往復が実データで安定、再読込/ネットワークエラーもUIが破綻しない

---

フェーズE：更新系統合（PATCH/POST/DELETE）

目的：フォーム編集・作成・削除の実装
主要タスク

• useMutation で 楽観更新と悲観ロールバックの方針決定。
• Problem+JSON をUIにマッピング（フィールドエラー／トースト）。
• 既存のOverlays（ConfirmDialog/Toast）に実処理を接続。
  成果物：useUpdateField, useCreateField, useDeleteField など
  DoD：編集→保存→一覧反映、削除→confirm→反映、二重送信防止完備

---

フェーズF：認証・権限制御

目的：安全な接続とUI制御
主要タスク

• 認証フロー（例：ログイン→アクセストークン→リフレッシュ）。
• APIクライアントのInterceptor（Authorization付与、401時の更新/サインアウト）。
• UIの権限ゲート（groups_xml_ids 等）でボタンの表示/非表示。
  成果物：authClient.ts、権限付きガード、セッション管理
  DoD：権限に応じて操作が不可視/無効化、トークン期限切れの再取得が動作

---

フェーズG：国際化・ラベル運用（i18n）

目的：*_i18n を中心に多言語表示を安定
主要タスク

• ja_JP/en_US 切替、欠損時フォールバック。
• UI固定文言は i18n 辞書、*DB由来のフィールド名/ヘルプは _i18n を使用。
  成果物：i18n設定、言語切替コンポーネント
  DoD：主要画面で言語切替が即時反映、未翻訳は自然にフォールバック

---

フェーズH：契約テスト & 例外系の自動化

目的：契約ドリフトと例外崩れを防止
主要タスク

• スキーマ準拠テスト（例：Dredd / Schemathesis / Zod でruntime検証）。
• 失敗系シナリオ（タイムアウト/500/422）をMSWで注入しUI確認（本番では不要、開発テスト用）。
  成果物：契約テスト、失敗系Playwright/E2E
  DoD：PR時に契約テストが必ず走る／代表的な失敗系のE2Eがgreen

---

フェーズI：アクセシビリティ & UX仕上げ

目的：実用レベルの使い心地に
主要タスク

• フォーカストラップ（Dialog）・Escクローズ・初期フォーカス・ラベル関連付け。
• ローディング/空/エラーの状態デザイン統一。
  成果物：A11yチェックリスト、修正コミット
  DoD：キーボード操作でCRUDが成立、主要コンポーネントのaxe監査がクリア

---

フェーズJ：CI/CD・プレビュー環境

目的：変更の安全リリース
主要タスク

• フロントはPRごとプレビュー（Vercel等）、API_BASE_URLをdev/stagingに切替。
• Lint/TypeCheck/Test/ContractTestをCIで強制。
  成果物：github/workflows/*、環境別.envとドキュメント
  DoD：PR作成→自動ビルド→プレビューURL発行→レビュー後マージ

---

フェーズK：ハンドオフ（オフショア統合作業の前提物）

目的：迷わず繋いで仕上げられる状態を作る
主要タスク

• 実装ガイド（API一覧、型、クエリ規則、エラーポリシー、オーバーレイ対応表）。
• サンプルcurl/HTTPie・Postman/Brunoコレクション・環境別.env.example。
• 画面ごとの DoD チェックリスト（List/Detail/編集/削除/失敗系）。
  成果物：/docs/integration-guide.md、APIコレクション、envサンプル
  DoD：ガイドに沿って新規メンバーが半日でローカル実行～CRUD確認まで到達