PR 粒度のざっくり例（NLQ-PR-xx）

ここでは、Figma からエクスポートされたフロントコードが既に apps/figma/* として存在している前提で、
オフショアチームにお願いしたい PR の粒度イメージを示します。

基本方針:

• まずは nlq-dev のフロント（NLQ コンソール）を完成させる。
• その後、同じパターンで Dev-Portal Top 等のシンプルな画面を「惰性で」増やしていく。
• インフラ系（K8s overlay / EKS / ALB）は、UI と並行または後追いで別 PR とする。

NLQ-PR-01 — Figma プロトタイプ取り込み & 整理

目的: Figma.make から出力された NLQ 画面のコードをリポジトリに正式に取り込み、「参照元」として固定する。

• Scope:
  • apps/figma/nlq-console/ のディレクトリを作成し、Figma 出力一式をそこに配置。
    • index.html, package.json, vite.config.ts, src/**/* など。
  • apps/figma/README.md を作成し、「ここはプロトタイプ置き場であり、本番ビルドとは別」と明記。
  • 既存のルート package.json / CI に影響が出ないことを確認。
• DoD:
  • apps/figma/nlq-console 以下がビルド可能（npm install && npm run dev が通る程度）。
  • README に「本番 UI 実装の参照用である」ことが明記されている。

NLQ-PR-02 — 本番用 NLQ UI アプリのスケルトン作成

目的: Figma プロトタイプを参考にしつつ、本番用の NLQ UI（nlq-dev フロント）を置く場所とスケルトンを用意する。

• Scope:
  • apps/nlq-console/ など、本番用 NLQ UI 用のディレクトリを新設。
  • Vite + React + TypeScript の最小構成を作成（Figma プロトタイプの package.json を参考にするが、ルートとは分離）。
  • 主要ページ構成だけ定義（例:）
    • / : NLQ コンソール（質問入力 + 結果表示のシェル）
    • 必要であれば /settings など（ただし中身はまだダミーでよい）。
  • Figma 由来の UI コンポーネントのうち、共通レイアウトや components/ui/* を複製または npm package 化して取り込む。
• DoD:
  • apps/nlq-console で npm install && npm run dev が成功し、ブラウザで基本レイアウトが表示される（ダミーデータでOK）。
  • apps/figma/nlq-console はあくまで参照用、本番は apps/nlq-console で開発するという方針が README に記載されている。

NLQ-PR-03 — /nlq/plan + /nlq/execute のフロー実装（フロント）

目的: NLQ コンソール画面に、/nlq/plan → /nlq/execute までの基本フローを実装する。

• Scope:
  • docs/nlq-api-contract.md に基づき、以下の API クライアントを実装：
    • POST /nlq/plan → PlanRequest, PlanResponse
    • POST /nlq/execute → ExecuteRequest, ExecuteResponse
  • フロントの動き：
    • ユーザが質問を入力し、Plan ボタンを押すと、候補 SQL のリスト（SqlCandidate）が表示される。
    • 候補を選択 → Execute ボタンで /nlq/execute を呼び出し、結果テーブル（columns + rows）を表示。
    • エラー時はシンプルなトースト or アラート表示（Figma コンポーネントを流用）。
  • 状態管理（React Query 等）の最小導入：
    • useQuery / useMutation などで API 呼び出しとローディング状態管理を行う。
• DoD:
  • dev 環境で、質問 → Plan → Execute まで、実際の API を叩いて UI が動作する。
  • PlanRequest / ExecuteRequest のパラメータ（特に session_id, mode, candidate_id）が仕様どおり渡されている。

NLQ-PR-04 — History / Analysis 画面の実装 & 結合

目的: /nlq/history, /nlq/analysis, /nlq/analysis/{analysis_id}/upsert を UI に組み込み、分析レポート閲覧〜保存までを一通り体験できるようにする。

• Scope:
  • API クライアント追加：
    • GET /nlq/history → HistoryResponse
    • POST /nlq/analysis → AnalysisRequest, AnalysisResponse
    • POST /nlq/analysis/{analysis_id}/upsert → DiffUpsertRequest, DiffUpsertResponse
  • 画面側：
    • History パネル：
      • 過去の HistoryItem をリスト表示（type=plan/execute/analysis ごとにアイコン or ラベル）。
      • クリックすると、対象の session や analysis を再表示できる。
    • Analysis パネル：
      • /nlq/execute の結果から「分析する」ボタンを押して /nlq/analysis を呼び出し、Markdown レポートを表示。
      • 必要に応じてタイトル・タグを編集し、/nlq/analysis/{analysis_id}/upsert で保存。
  • Figma コンポーネントの再利用：
    • Card / Tabs / Table などを使い、デザインに寄せつつ実装。
• DoD:
  • dev 環境で、以下のストーリーが UI 上で完結する：
    • 質問 → Plan → Execute → 分析生成 → 分析保存（DiffUpsert）→ History に履歴が現れる。
  • API 契約 (docs/nlq-api-contract.md) とレスポンスのハンドリングが一致している。

NLQ-PR-05 — UX 調整 & コンポーネント共通化（nlq-dev 完成度アップ）

目的: nlq-dev のフロントを「人に見せられるレベル」まで整え、同じパターンで他画面も作りやすい状態にする。

• Scope:
  • Figma デザインに合わせた細かい UX 調整：
    • ローディング状態（スピナー／スケルトン）
    • エラー表示（トースト、インラインエラーメッセージ）
    • 空状態（No history, No analysis など）の文言・イラスト（あれば）
  • UI コンポーネントの共通化：
    • NLQ 固有コンポーネント（例: QuestionInput, SqlCandidateList, ResultTable, AnalysisPane など）を apps/nlq-console/src/components に整理。
    • Figma 由来の汎用 UI コンポーネントは components/ui/* として再利用しやすくしておく。
  • フロント側の簡単な Story/Docs:
    • apps/nlq-console/README.md に、開発用の起動方法と簡単な画面説明を書く。
• DoD:
  • nlq-dev 画面が「ひととおり業務に耐えうる見た目」になっている。
  • コンポーネント構成が整理され、他画面からも真似しやすい構造になっている。

NLQ-PR-06 — 他画面（Dev-Portal Top など）向け UI パターンのテンプレート化

目的: nlq-dev の UI 実装パターンをテンプレート化し、Dev-Portal Top など他画面を「惰性で」増やせるようにする。

• Scope:
  • Figma プロトタイプ（例: apps/figma/dev-portal-top/）を参考に、
    • apps/dev-portal-top/ のような本番用ディレクトリを作成。
    • レイアウト・UI コンポーネントは nlq-dev のものを最大限再利用。
  • Dev-Portal Top 向けの最小機能：
    • モデル一覧の表示（API or 仮データ）
    • 各モデルから NLQ 画面（nlq-dev）へのリンク（クエリパラメータに model を渡すなど）。
  • nlq-dev で作ったコンポーネント・パターン（カード一覧、検索フォーム等）を流用することで、
    「同じノリで他画面も作れる」ことを証明する位置づけ。
• DoD:
  • Dev-Portal Top 用の UI アプリが起動し、最低限の画面遷移（Dev-Portal Top → nlq-console）が動作する。
  • オフショアチーム内で、「この PR を真似すれば別画面も作れる」という理解が共有されている。

NLQ-PR-07 以降 — インフラ系 PR（K8s / EKS / ALB）

UI 系の PR とは別に、インフラ系は以下のような PR 番号で切ることを想定しています。

• NLQ-PR-07 — K8s dev overlay 初期実装（nlq-api / chroma / neo4j）
  • k8s/overlays/dev の kustomization.yaml 作成、ConfigMap/Secret パッチ追加。
• NLQ-PR-08 — K8s prod overlay 初期実装
  • k8s/overlays/prod 用の kustomize 設定と example Secret/ConfigMap を追加。
• NLQ-PR-09 — AWS EKS / ALB / ACM 配線（スケルトン）
  • EKS 上での Service / Ingress / ALB / 証明書の設計と docs 追加。

番号はあくまで例なので、実際の運用に合わせて前後しても構いません。
ただし、

• NLQ-PR-01〜06: 主に フロント（特に nlq-dev）中心
• NLQ-PR-07 以降: 主に インフラ / デプロイまわり