0) 前提・観測の準備（環境が正しいか）
- nlq-dev が起動している
- dev-portal が到達可能（http mode の場合）
- decikg が到達可能（http mode の場合）
- metabase が到達可能
- chroma（nlq 側の差分保存先）が到達可能
- trace / request_id / run_id で一連を追える状態（ログ相関）
成果物：
「この環境では E2E を回せる」ことの確認（疎通・設定値・ログ相関キー）
1) ルーティング分岐の確認（質問→DeciKG or Dev-Portal）
- 同じ “質問入力” で、route が期待通りに選ばれること
- SQL_ONLY / CYPHER_ONLY / HYBRID（あなたの設計上の分岐）
- stub/dummy の挙動（本番は http、ローカルは dummy でも可）を確認
- 失敗時でも API 契約上のレスポンス形が崩れないこと（UIが止まらない）
成果物：
「質問 → route 決定」が正しい証跡（route / stub_used / reason / timings）
2) Dev-Portal 連携の確認（質問の受け渡し→SQL生成→SQL結果受領）
Dev-Portal ルートの場合に限って確認する工程。
- nlq-dev → dev-portal に **質問（question）**が渡っている
- dev-portal が生成した SQL を nlq-dev が受領できる
- 実行結果（rows/columns/row_count 等）が nlq-dev に戻る
- dry_run と本実行の差異（本番前提に合わせる）
成果物：
「入力 question → 生成SQL → 実行結果」が揃った証跡（SQL/結果/diagnostics）
3) Metabase グラフ作成（結果データ→可視化オブジェクト生成）
- nlq-dev が受領した tabular result を元に
- 既存カード更新 or 新規カード作成
- 表示タイプ（time_series / ranking / scalar 等）が想定通り
- Metabase 側でカード/ダッシュボードが参照可能
- 同じ質問で “同じカードに更新” か “新カード作成” かの方針通り
成果物：
Metabase 上の成果物（card_id / url / dataset hash など）と、nlq-dev 側の対応づけ
4) コメント作成（生成コメント→保存）
- nlq-dev が結果からコメント（narration/insight）を生成できる
- コメントが API レスポンスに含まれ、UI表示を阻害しない
- コメント生成の入力（sql_result/graph_result/shape）と出力が追える
成果物：
コメント本文＋生成根拠の最小トレース（run_id / providers / timings）
5) コメント差分を ChromaDB に保存（diff → upsert）
- “前回コメント” と “今回コメント” の差分を作り
- ChromaDB に idempotent に upsert できる
- 保存形式（doc_id/natural_key/lang/meta）と検索キーが安定している
- 失敗時も UI/レスポンスは維持（warnings/errors に寄せる）
成果物：
Chroma upsert の証跡（upserted/failed、doc_id、meta、source_hash）
6) 再問い合わせで反映確認（同じ質問→差分が効いている）
- 同じ質問を再度投げたときに
- コメントが更新されている（diff反映）
- もしくは「差分なし」で NOP になっている（期待通り）
- Chroma 参照の有無（top_k=0 のときは効かない等）を含め、設計通りの結果になる
成果物：
「1回目→保存→2回目」での差分反映結果（before/after、retrieval diag）
7) 失敗系の工程（本番で揉めないための最低限）
- dev-portal 停止/タイムアウト時：nlq-dev は stub/エラー整形で落ちない
- metabase 失敗時：カード更新失敗が切り分け可能
- chroma 失敗時：コメント表示はできるが保存だけ失敗、など段階的劣化
成果物：
失敗時の reason_code / errors / 復旧手順の骨子に使えるログ
コメントを残す