FastAPI Migration Prompts & Documentation

このディレクトリには、NexusCore の Flask → FastAPI 移行に関するプロンプトテンプレートと完了レポートが含まれています。

重要: API 構成の変更

外部公開 API は FastAPI ベースの /api/v1/** が正式版です（単一の正）。

Flask REST API（/api/v1/* 配下のエンドポイント）は CR-FASTAPI-010 で完全削除されました。 すべての REST API は FastAPI 側に統一されました。

詳細は FastAPI移行ステータス.md を参照してください。

• FastAPI: 公開 API 層（/api/v1/*）- 正式版（単一の正）
• Flask: Web UI 層（/projects/*, /dashboard/* など）- 当面存続（REST API は提供していません）

責務分離: WebApp HTML UI と FastAPI API

• WebApp HTML UI (Flask): サーバー内部 UI（人間向け HTML 画面）
  • HTML レンダリングとフォーム受け付けを担当
  • データ取得は FastAPI 経由ではなく、直接データベースアクセスまたは services 層を使用
  • FastAPI API migration の対象外（責務分離のため）
  • 詳細は WebApp_UI_API_マッピング.md を参照してください
• FastAPI API: 公開 API（外部/機械向け JSON API）
  • SDK / CLI / 外部統合向けのエンドポイント（/api/v1/*）
  • 統一された認証、エラーハンドリング、OpenAPI スキーマを提供

プロンプト一覧

CR-FASTAPI-000: API Inventory

• ファイル: [CR-FASTAPI-000プロンプト.md](/NexusCore/api/CR-FASTAPI-000%E3%83%97%E3%83%AD%E3%83%B3%E3%83%97%E3%83%88.html)
• 目的: 既存の Flask ベース API を全て棚卸しし、public / internal / 廃止候補を分類
• 出力: docs/api/APIインベントリ.md
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-000完了報告.md](/NexusCore/api/CR-FASTAPI-000%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-FASTAPI-001: FastAPI Skeleton

• ファイル: [CR-FASTAPI-001プロンプト.md](/NexusCore/api/CR-FASTAPI-001%E3%83%97%E3%83%AD%E3%83%B3%E3%83%97%E3%83%88.html)
• 目的: FastAPI アプリケーションの最小スケルトンと /api/v1/health エンドポイントを作成
• 出力: FastAPI アプリ本体、ルータ、スキーマ、テスト
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-001完了報告.md](/NexusCore/api/CR-FASTAPI-001%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)
• 追加改善レポート: [CR-FASTAPI-001機能強化報告.md](/NexusCore/api/CR-FASTAPI-001%E6%A9%9F%E8%83%BD%E5%BC%B7%E5%8C%96%E5%A0%B1%E5%91%8A.html)

CR-FASTAPI-002: Execute & Status Endpoints

• ファイル: プロンプトは CR-FASTAPI-002 として実行
• 目的: /api/v1/execute と /api/v1/status/{task_id} エンドポイントの FastAPI 版実装
• 出力: Execute スキーマ、ルータ、認証依存、テスト
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-002完了報告.md](/NexusCore/api/CR-FASTAPI-002%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-FASTAPI-003: GitHub Self-Healing Webhook API

• ファイル: プロンプトは CR-FASTAPI-003 として実行
• 目的: /api/v1/github/webhook エンドポイントの FastAPI 版実装（GitHub Self-Healing Webhook）
• 出力: GitHub Webhook スキーマ、ルータ、署名検証、テスト
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-003完了報告.md](/NexusCore/api/CR-FASTAPI-003%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-FASTAPI-004: 認証 DI 統一

• ファイル: プロンプトは CR-FASTAPI-004 として実行
• 目的: FastAPI の標準 DI（Depends）形式に統一された認証レイヤーの実装
• 出力: 認証依存モジュール、すべての Public API への認証 DI 適用、テスト
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-004完了報告.md](/NexusCore/api/CR-FASTAPI-004%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-FASTAPI-005: Pydantic モデルの分離と API 型安全化

• ファイル: プロンプトは CR-FASTAPI-005 として実行
• 目的: 既存 Flask/混在コードから移行してくる API 仕様を FastAPI で完全型安全化
• 出力: Projects/Runs/Plans スキーマ、ルータ、テスト
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-005完了報告.md](/NexusCore/api/CR-FASTAPI-005%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-FASTAPI-006: Error Handling Unification（エラー標準化）

• ファイル: プロンプトは CR-FASTAPI-006 として実行
• 目的: FastAPI 全 API で返すエラーを 1つの標準構造に統一
• 出力: エラービルダー関数、すべてのルータのエラーハンドリング統一、OpenAPI スキーマにエラーレスポンス追加、テスト
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-006完了報告.md](/NexusCore/api/CR-FASTAPI-006%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-FASTAPI-007: Flask REST API の棚卸し・非推奨化・削除計画の策定

• ファイル: プロンプトは CR-FASTAPI-007 として実行
• 目的: Flask REST API の棚卸し、非推奨化、削除計画の策定
• 出力: 移行状況ドキュメント、Flask REST API の非推奨化、削除計画
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-007完了報告.md](/NexusCore/api/CR-FASTAPI-007%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)
• 移行状況: FastAPI移行ステータス.md

CR-FASTAPI-008: Flask 内部 REST API の削除

• ファイル: プロンプトは CR-FASTAPI-008 として実行
• 目的: Flask 内部 REST API (/api/v1/execute, /api/v1/status) の物理削除
• 出力: Flask エンドポイント削除、テスト整理、ドキュメント更新
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-008完了報告.md](/NexusCore/api/CR-FASTAPI-008%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-FASTAPI-009: Project Run & Badge エンドポイントの移行

• ファイル: プロンプトは CR-FASTAPI-009 として実行
• 目的: Flask ベースの Project Run と Badge エンドポイントを FastAPI に移行
  • /api/v1/projects/<id>/run (POST)
  • /api/v1/projects/<id>/runs/latest (GET)
  • /api/v1/projects/<id>/badge/success_rate (GET)
  • /api/v1/projects/<id>/badge/last_run (GET)
• 出力: FastAPI ルータ、Pydantic スキーマ、テスト
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-009完了報告.md](/NexusCore/api/CR-FASTAPI-009%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-FASTAPI-010: WebApp 側 Flask API の完全削除

• ファイル: プロンプトは CR-FASTAPI-010 として実行
• 目的: WebApp 側の Flask REST API (api_external.py, api_badges.py) を完全削除
• 出力: Flask Blueprint 削除、テスト整理、ドキュメント更新
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-010完了報告.md](/NexusCore/api/CR-FASTAPI-010%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-FASTAPI-010A: Badges パス統一 & Health エラーインポート Hotfix

• ファイル: プロンプトは CR-FASTAPI-010A として実行
• 目的: Badges エンドポイントのパスを /api/v1/projects/... に統一、Health の ErrorResponse インポート確認
• 出力: パス統一、ドキュメント更新
• ステータス: ✅ 完了
• 完了レポート: CR-FASTAPI-010A_完了報告.md

CR-NEXUS-011: WebApp HTML UI の API 移行整合 & クリーンアップ

• ファイル: プロンプトは CR-NEXUS-011 として実行
• 目的: WebApp HTML UI の URL 正規化、docstring 整備、責務分離の明文化
• 出力: docstring 追加、ドキュメント作成、URL 統一確認
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-011完了報告.md](/NexusCore/api/CR-NEXUS-011%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)
• 関連ドキュメント: WebApp_UI_API_マッピング.md

CR-NEXUS-032: API Endpoint Path Normalization

• ファイル: プロンプトは CR-NEXUS-032 として実行
• 目的: RunView API のエンドポイントパスを正規化し、canonical /api/v1/runs を確立する
• 出力: パス正規化、テスト更新、TypeScript SDK 更新
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-032完了報告.md](/NexusCore/api/CR-NEXUS-032%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-NEXUS-035: DetachedInstanceError 解消

• ファイル: プロンプトは CR-NEXUS-035 として実行
• 目的: tests/api/test_external_api_smoke.py で発生している DetachedInstanceError（setup error）を解消する
• 出力: test fixture の安定化、ERROR（setup error）0 件
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-035完了報告.md](/NexusCore/api/CR-NEXUS-035%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-NEXUS-036: Error Code Catalog 空問題の解消

• ファイル: プロンプトは CR-NEXUS-036 として実行
• 目的: Error Code Catalog が空と判定される問題を解消し、tests/api/test_error_code_catalog.py の失敗を解消する
• 出力: Catalog パーサーの修正、テスト PASS
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-036完了報告.md](/NexusCore/api/CR-NEXUS-036%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-NEXUS-037: External API smoke の仕様整合

• ファイル: プロンプトは CR-NEXUS-037 として実行
• 目的: tests/api/test_external_api_smoke.py の失敗を解消し、external_api_smoke テストが安定して PASS する状態にする
• 出力: モック不整合の解消、テスト PASS
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-037完了報告.md](/NexusCore/api/CR-NEXUS-037%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-NEXUS-038: FastAPI auth misconfigured: 202 vs 500

• ファイル: プロンプトは CR-NEXUS-038 として実行
• 目的: 認証設定（API Key）不備を、確実に 500 として返すことを FastAPI の public API 契約として固定する
• 出力: 認証 dependency の修正、テスト PASS
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-038完了報告.md](/NexusCore/api/CR-NEXUS-038%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-NEXUS-039: PR コメント生成の責務境界の明文化

• ファイル: プロンプトは CR-NEXUS-039 として実行
• 目的: PR コメント生成の責務境界を固定し、format_pr_comment() と build_pr_comment() の関係を明文化する
• 出力: DB/Flask 依存の排除、二重出力防止ガード、テスト追加
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-039完了報告.md](/NexusCore/api/CR-NEXUS-039%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-NEXUS-040: FastAPI Projects 契約化

• ファイル: プロンプトは CR-NEXUS-040 として実行
• 目的: /api/v1/projects 配下のエンドポイントの Response Model を Pydantic で明示し、契約テストで固定する
• 出力: 契約テスト追加、契約ドキュメント追加
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-040完了報告.md](/NexusCore/api/CR-NEXUS-040%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)
• 関連ドキュメント: プロジェクトAPI契約.md

CR-NEXUS-041: Completion Report ガバナンス強化（Option A）

• ファイル: プロンプトは CR-NEXUS-041 として実行
• 目的: Completion Report 運用ルールの Single Source of Truth 化と、README と実ファイルの不整合をテストで検出可能にする
• 出力: ルール単一ソース化、存在チェックテスト追加、既存不整合是正
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-041完了報告.md](/NexusCore/api/CR-NEXUS-041%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-NEXUS-043: README 解析ロジックのテストヘルパー共通化

• ファイル: プロンプトは CR-NEXUS-043 として実行
• 目的: README.md から「✅ 完了 CR-ID」を抽出するロジックをテスト専用ヘルパーとして単一化し、重複を排除する
• 出力: テスト専用ヘルパーモジュール追加、重複コード削除
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-043完了報告.md](/NexusCore/api/CR-NEXUS-043%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-NEXUS-044: Completion Report 内容品質ゲート（中身の妥当性検証）

• ファイル: プロンプトは CR-NEXUS-044 として実行
• 目的: Completion Report の品質を「見出しがある」レベルから「中身が最低限成立している」レベルまで引き上げる
• 出力: 内容品質ゲートテスト追加
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-044完了報告.md](/NexusCore/api/CR-NEXUS-044%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-NEXUS-045: README CR ステータス品質ゲート（状態機械・整合性検証）

• ファイル: プロンプトは CR-NEXUS-045 として実行
• 目的: docs/api/README.md の CR エントリに対して、ステータスの正当性を機械的に検証する
• 出力: ステータス品質ゲートテスト追加、ヘルパー関数拡張
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-045完了報告.md](/NexusCore/api/CR-NEXUS-045%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-NEXUS-046: README CR エントリ品質ゲート（項目欠落・フォーマットぶれ検証）

• ファイル: プロンプトは CR-NEXUS-046 として実行
• 目的: docs/api/README.md の CR エントリの”項目欠落”と”フォーマットぶれ”を機械的に検出する
• 出力: エントリ品質ゲートテスト追加、ヘルパー関数拡張
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-046完了報告.md](/NexusCore/api/CR-NEXUS-046%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-NEXUS-047: Completion Report 解析ロジックのテストヘルパー共通化

• ファイル: プロンプトは CR-NEXUS-047 として実行
• 目的: Completion Report のセクション抽出・空判定・証跡検出ロジックをテスト専用ヘルパーに切り出し、今後の品質ゲート拡張に備える
• 出力: Completion Report 解析専用ヘルパー追加、既存テストのリファクタ
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-047完了報告.md](/NexusCore/api/CR-NEXUS-047%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-NEXUS-048: README/Completion Report テンプレ自動生成（scaffold）

• ファイル: プロンプトは CR-NEXUS-048 として実行
• 目的: README と Completion Report の作成を人手で行うと、フィールド漏れ・ステータス不整合・必須見出し・内容不足・ルールに合わせた雛形の書き方が毎回ブレる問題が発生する。CR を開始する時点で、README の CR エントリ雛形と Completion Report 雛形（必須見出し＋内容品質ゲートに通る最低限の骨格）を自動生成する scaffold を追加する
• 出力: tools/scaffold_cr.py, tests/api/test_scaffold_cr.py, docs/api/CR-NEXUS-048_完了報告.md
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-048完了報告.md](/NexusCore/api/CR-NEXUS-048%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-NEXUS-049: CR ガバナンス定義（README / Completion Report / 品質ゲート / scaffold）の Single Source of Truth（SSoT）化

• ファイル: プロンプトは CR-NEXUS-049 として実行
• 目的: CR ガバナンスに関する定義（Completion Report 必須セクション、README CR エントリ必須項目、CR ステータスと状態ルール、雛形テンプレート）が分散している状態を解消し、定義を 1 箇所に集約し、scaffold / 品質ゲート / helpers はその定義を参照するように修正する
• 出力: src/nexuscore/governance/cr_spec.py, tests/api/test_cr_spec_single_source_of_truth.py, docs/api/CR-NEXUS-049_完了報告.md
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-049完了報告.md](/NexusCore/api/CR-NEXUS-049%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-NEXUS-050: SSoT(cr_spec) 変更検知の強制ゲート（CI FAIL → 更新ツールで解除）

• ファイル: プロンプトは CR-NEXUS-050 として実行
• 目的: src/nexuscore/governance/cr_spec.py（SSoT）が変更されたら必ず pytest を FAIL させる。開発者が影響確認した上で、専用更新ツールを実行した場合のみ PASS する状態にする。「気づかないまま SSoT を変更して運用が壊れる事故」を防止する
• 出力: docs/governance/CR_SPEC_FINGERPRINT.txt, tools/update_cr_spec_fingerprint.py, tests/governance/test_cr_spec_change_guard.py, docs/api/CR-NEXUS-050_完了報告.md
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-050完了報告.md](/NexusCore/api/CR-NEXUS-050%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-NEXUS-051: CI Safe 依存 Lock 化

• ファイル: プロンプトは CR-NEXUS-051 として実行
• 目的: CI Safe テストの依存関係を lock 化し、再現性を最大化する。requirements-ci-safe.lock を導入し、pip-tools を使用してハッシュ付き lock ファイルを生成。
• 出力: requirements-ci-safe.lock, .github/workflows/ci.yml（Safe job 修正）, docs/CI_SAFE_LOCK.md, docs/CI_TEST_STRATEGY.md（更新）, docs/api/CR-NEXUS-051_完了報告.md
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-051完了報告.md](/NexusCore/api/CR-NEXUS-051%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-NEXUS-052: CI Safe Lock Guard (txt/lock mismatch detection + update tool)

• ファイル: プロンプトは CR-NEXUS-052 として実行
• 目的: requirements-ci-safe.txt と requirements-ci-safe.lock の不整合を CI 上で機械的に検知し、更新手順を単一コマンドに固定する仕組みを導入する。
• 出力: tests/governance/test_ci_safe_lock_guard.py, tools/update_ci_safe_lock.py, docs/CI_SAFE_LOCK.md（更新）, docs/api/CR-NEXUS-052_完了報告.md
• ステータス: ✅ 完了
• 完了レポート: [CR-NEXUS-052完了報告.md](/NexusCore/api/CR-NEXUS-052%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-FASTAPI-012: SDK 自動生成導線の構築

• ファイル: プロンプトは CR-FASTAPI-012 として実行
• 目的: OpenAPI 仕様書を元に Python / TypeScript 向け SDK を自動生成できる導線を追加
• 出力: SDK 生成スクリプト、Makefile コマンド、ドキュメント更新
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-012完了報告.md](/NexusCore/api/CR-FASTAPI-012%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)
• 関連 Spec: CR-FASTAPI-012 Spec

CR-FASTAPI-012A: SDK Generator Tooling Hardening

• ファイル: プロンプトは CR-FASTAPI-012A として実行
• 目的: SDK 生成ツールの固定化と安全性テストの追加
• 出力: ツール・バージョン情報の明示、軽量テスト追加、ドキュメント更新
• ステータス: ✅ 完了
• 完了レポート: CR-FASTAPI-012A_完了報告.md
• 関連 Spec: CR-FASTAPI-012A Spec

CR-FASTAPI-013: SDK / FastAPI E2E テスト基盤構築

• ファイル: プロンプトは CR-FASTAPI-013 として実行
• 目的: FastAPI アプリと SDK の連携を実際に検証する E2E テスト基盤の構築
• 出力: uvicorn 起動ヘルパー、E2E テスト、Makefile コマンド、ドキュメント更新
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-013完了報告.md](/NexusCore/api/CR-FASTAPI-013%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)
• 関連 Spec: CR-FASTAPI-013 Spec

CR-FASTAPI-013A: SDK E2E Tests – Real SDK Integration

• ファイル: プロンプトは CR-FASTAPI-013A として実行
• 目的: 実際に生成された Python SDK を使用した E2E テストの実装
• 出力: SDK クライアントヘルパー、実際の SDK API に合わせた E2E テスト、ドキュメント更新
• ステータス: ✅ 完了
• 完了レポート: CR-FASTAPI-013A_完了報告.md
• 関連 Spec: CR-FASTAPI-013A Spec

CR-FASTAPI-014: Auth Error Normalization（認証エラーの正規化）

• ファイル: プロンプトは CR-FASTAPI-014 として実行
• 目的: 認証エラーを 500 ではなく 401 に正規化
• 出力: get_current_user() のエラー正規化、テスト更新
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-014完了報告.md](/NexusCore/api/CR-FASTAPI-014%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)
• 関連 Spec: CR-FASTAPI-014 Spec

CR-FASTAPI-015: Error Code Catalog 作成（エラーコード一覧の単一ソース化）

• ファイル: プロンプトは CR-FASTAPI-015 として実行
• 目的: エラーコードの単一のソース（Single Source of Truth）を作成
• 出力: エラーコードカタログ.md、カタログと OpenAPI の整合性チェックテスト
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-015完了報告.md](/NexusCore/api/CR-FASTAPI-015%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)
• 関連 Spec: CR-FASTAPI-015 Spec

CR-FASTAPI-016: Orchestrator の UI（Gradio）依存分離

• ファイル: プロンプトは CR-FASTAPI-016 として実行
• 目的: FastAPI の API テスト実行時に Gradio / UI 層が import されないようにする
• 出力: RequirementAgent の Gradio import を lazy import に変更
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-016完了報告.md](/NexusCore/api/CR-FASTAPI-016%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)
• 関連 Spec: CR-FASTAPI-016 Spec

CR-FASTAPI-017: E2E テスト用 SQLite DB セットアップ

• ファイル: プロンプトは CR-FASTAPI-017 として実行
• 目的: E2E テスト用の SQLite DB を作成し、FastAPI アプリでテスト時に使用するようオーバーライド
• 出力: E2E 用 DB セットアップ fixture、test_projects_list_e2e
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-017完了報告.md](/NexusCore/api/CR-FASTAPI-017%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

CR-FASTAPI-018: Python SDK 商品化（v0.1.0）

• ファイル: プロンプトは CR-FASTAPI-018 として実行
• 目的: Python SDK を v0.1.0 として「外部に配布可能な製品レベル」に引き上げる
• 出力: pyproject.toml、README.md、LICENSE、examples、tests、ビルド・公開手順
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-018完了報告.md](/NexusCore/api/CR-FASTAPI-018%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)
• 関連 Spec: CR-FASTAPI-018 Spec

CR-FASTAPI-019: TypeScript SDK の整備 & E2E

• ファイル: プロンプトは CR-FASTAPI-019 として実行
• 目的: TypeScript SDK を Python SDK と同等レベル（v0.1.0 商品化＋E2E 確立）まで引き上げる
• 出力: package.json、README.md、LICENSE、examples、tests、ビルド・公開手順
• ステータス: ✅ 完了
• 完了レポート: [CR-FASTAPI-019完了報告.md](/NexusCore/api/CR-FASTAPI-019%E5%AE%8C%E4%BA%86%E5%A0%B1%E5%91%8A.html)

SDK 自動生成

NexusCore の FastAPI API から OpenAPI 仕様書を取得し、Python / TypeScript 向け SDK を自動生成できます。

前提条件

SDK 生成には以下のツールが必要です：

• 推奨: @openapitools/openapi-generator-cli（npm パッケージ）
  • インストール方法: npx --yes openapi-generator-cli（最新版を自動取得）
  • または: npm install -g @openapitools/openapi-generator-cli
• 代替: Java 版 openapi-generator（バージョン 7.x 系推奨）
  • Java がインストールされている必要があります

重要: SDK コードは手書きせず、必ず tools/generate_sdk.py を使用して OpenAPI 仕様書から自動生成してください。OpenAPI 仕様書が SDK の単一のソース（Single Source of Truth）です。

SDK 生成方法

すべての SDK を生成

make sdk
# または
python tools/generate_sdk.py --all

Python SDK のみ生成

make sdk-python
# または
python tools/generate_sdk.py --python

TypeScript SDK のみ生成

make sdk-ts
# または
python tools/generate_sdk.py --typescript

生成物の場所

• Python SDK: sdk/python/
• TypeScript SDK: sdk/typescript/

生成物の活用例

Python

from nexuscore_sdk import NexusCoreClient

client = NexusCoreClient(base_url="http://localhost:8000")
response = client.health()

TypeScript

商品レベルの SDK を使用（推奨）:

import { NexusCoreClient } from '@nexuscore/sdk';

const client = new NexusCoreClient({
  baseUrl: 'http://localhost:8000',
  apiKey: 'nexus_xxx...' // 必須
});

// プロジェクト一覧を取得
const projects = await client.listProjects();

// エラーハンドリング
try {
  await client.listProjects();
} catch (error) {
  if (error instanceof NexusCoreApiError) {
    console.log(`Error: ${error.code} (${error.status})`);
  }
}

詳細は TypeScript SDK README を参照してください。 const response = await client.health();

### 注意事項

- SDK 生成時は FastAPI アプリが起動している必要があります（`http://localhost:8000/api/openapi.json` から OpenAPI 仕様書を取得）
- または `--openapi-file` オプションで OpenAPI JSON ファイルを直接指定できます
- 生成された SDK は `.gitignore` で除外されています（再生成可能なため）

## E2E テスト

生成された SDK と FastAPI アプリの連携を実際に検証する E2E テストを実行できます。

### 前提条件

- SDK が事前に生成されていること（`make sdk-python` を実行）
- FastAPI アプリが正常に起動できること
- 必要な環境変数（API Key など）が設定されていること

### E2E テストの実行

**重要**: E2E テストを実行するには、事前に SDK を生成する必要があります。

```bash
# 1. SDK を生成（事前に実行）
make sdk-python

# 2. E2E テストを実行
make test-e2e

# または直接実行
pytest tests/e2e/test_sdk_e2e.py -v

注意: SDK が生成されていない場合、E2E テストは自動的にスキップされます。 これは「テスト環境の問題」であり、SDK / API 実装のバグではありません。

E2E テストの内容

E2E テストでは以下のケースを検証します：

1. Health エンドポイント (test_health_e2e):
   • Python SDK 経由で /api/v1/health を呼び出し
   • HTTP ステータス 200、status == “ok”、version が非空文字列、timestamp が ISO8601 形式を検証
2. Projects API (test_projects_list_e2e):
   • Python SDK 経由で /api/v1/projects の一覧取得を行う
   • 呼び出しが例外なく完了、戻り値が list / iterable、各要素に id, name など Project スキーマに準拠したフィールドが存在することを検証
3. Execute API (test_execute_e2e):
   • Python SDK 経由で /api/v1/execute を呼び出す
   • 正しい API Key を付けた場合の正常系（task_id, status_url など）を検証
   • API Key を付けない／不正なキーの場合の Unauthorized エラーを検証

E2E テストの仕組み

• FastAPI アプリを uvicorn でバックグラウンド起動（tests/e2e/helpers/server.py）
• 生成された Python SDK を使用して API を呼び出し（tests/e2e/helpers/sdk_client.py）
• テスト終了時にサーバーを自動停止
• SDK が存在しない場合は適切にスキップ

詳細は tests/e2e/test_sdk_e2e.py を参照してください。

使用方法

1. 各プロンプトファイルを開く
2. コードブロック内のテキストをコピー
3. Cursor のチャットに貼り付けて実行

FastAPI アプリケーションの起動方法

ローカル開発環境（WSL Ubuntu）

# 仮想環境を有効化
source myenv_linux/bin/activate
# または venv を使用している場合
# source venv/bin/activate

# PYTHONPATH を設定して FastAPI アプリを起動
export PYTHONPATH=/home/yn441611/NexusCore/src:$PYTHONPATH
uvicorn nexuscore.api.fastapi_app:app --reload --host 127.0.0.1 --port 8000

重要: PYTHONPATH を設定しないと ModuleNotFoundError: No module named 'nexuscore' エラーが発生します。

アクセス先

• FastAPI アプリ: http://127.0.0.1:8000
• API ドキュメント: http://127.0.0.1:8000/api/docs
• OpenAPI スキーマ: http://127.0.0.1:8000/api/openapi.json
• Health エンドポイント: http://127.0.0.1:8000/api/v1/health

ポート設計

• Flask アプリ: ポート 5000（既存の Web UI）
• FastAPI アプリ: ポート 8000（新規 API）
• 両方を同時に起動可能（別ポートのため）

実装パターンと .cursorrules の対応

CR-FASTAPI-001 で確立された実装パターンは、.cursorrules のルールに完全に準拠しています：

ディレクトリ構造

• FastAPI ルート: src/nexuscore/api/routes/ 配下に作成
  • 例: src/nexuscore/api/routes/health.py
• レスポンススキーマ: src/nexuscore/api/schemas/ 配下に Pydantic BaseModel で定義
  • 例: src/nexuscore/api/schemas/health.py
• 認証依存関係: src/nexuscore/api/dependencies/ 配下に配置
  • 例: src/nexuscore/api/dependencies/auth.py

API パス規則

• Public API: /api/v1/* プレフィックスを使用
  • 例: /api/v1/health, /api/v1/execute
• Internal API: /internal/* または /system/* を使用（将来実装）

レスポンスモデル

• すべてのエンドポイントで Pydantic BaseModel を使用
• response_model パラメータで明示的に指定
• OpenAPI スキーマに自動反映

テスト

• FastAPI TestClient を使用
• tests/api/ 配下に配置
• PYTHONPATH 設定が必要: export PYTHONPATH=/home/yn441611/NexusCore/src:$PYTHONPATH

エラー標準化（CR-FASTAPI-006）

CR-FASTAPI-006 により、FastAPI 全 API で返すエラーが統一された構造に統一されました。

Error Code Catalog（エラーコードカタログ）

エラーコードの単一のソース（Single Source of Truth）: エラーコードカタログ.md

すべてのエラーコードは エラーコードカタログ.md に定義されています。新しいエラーコードを追加する場合は、必ず エラーコードカタログ.md にも追記してください。

エラーレスポンス形式

すべてのエラーは以下の形式で返されます：

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Project with id 123 not found"
  }
}

エラーコード一覧

HTTP Status	Code	説明
400	INVALID_REQUEST	パラメータ不正
401	UNAUTHORIZED	API Key 不正
403	FORBIDDEN	権限なし
404	NOT_FOUND	リソース未検出
409	CONFLICT	既存・重複エラー
422	VALIDATION_ERROR	バリデーション不正
500	INTERNAL_ERROR	サーバー内部エラー

使用方法

エラーハンドリングは src/nexuscore/api/utils/errors.py の make_error() 関数を使用します：

from nexuscore.api.utils.errors import make_not_found_error

raise make_not_found_error("Project", str(project_id))

認証 DI 統一（CR-FASTAPI-004）

すべての Public API は FastAPI の標準 DI（Depends）形式で認証を行います。

認証方式

API Key 認証

• Header: X-API-Key
• 値: 環境変数 NEXUSCORE_API_KEY または secrets.json の NEXUSCORE_API_KEY

使用方法

from fastapi import Depends
from nexuscore.api.dependencies.auth import get_current_user, AuthenticatedUser

@router.post("/api/v1/example")
async def example_endpoint(
    current_user: AuthenticatedUser = Depends(get_current_user),
):
    # 認証済みユーザー情報を使用
    user_id = current_user.user_id
    roles = current_user.roles
    ...

API Key の設定

環境変数から設定:

export NEXUSCORE_API_KEY=your-api-key-here

secrets.json から設定:

{
  "NEXUSCORE_API_KEY": "your-api-key-here"
}

API Key 運用フロー（CR-FASTAPI-021, CR-FASTAPI-022, CR-FASTAPI-023）

運用フロー図:

┌─────────────────────────────────────────────────────────────┐
│ 1. 初回 API Key 発行（ローカル / CI）                       │
│    └─> bootstrap_apikey CLI (CR-FASTAPI-021)               │
│        └─> NEXUSCORE_BOOTSTRAP_API_KEY を生成              │
└─────────────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. 2本目以降の API Key 発行                                 │
│    └─> POST /api/v1/api-keys (CR-FASTAPI-020)              │
│        └─> 既存の API Key で認証して新しい Key を発行      │
└─────────────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. TypeScript E2E テスト（ローカル / CI）                   │
│    └─> getE2EApiKey() helper (CR-FASTAPI-022)             │
│        ├─> NEXUSCORE_API_KEY があればそれを使用           │
│        └─> なければ NEXUSCORE_BOOTSTRAP_API_KEY から      │
│            /api/v1/api-keys を叩いて自動発行                │
└─────────────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. CI での自動化（CR-FASTAPI-023）                         │
│    └─> .github/workflows/ts-e2e.yml                       │
│        ├─> bootstrap-apikey job: bootstrap key を生成      │
│        └─> ts-e2e job: NEXUSCORE_BOOTSTRAP_API_KEY を     │
│            受け取り、E2E テストを実行                       │
└─────────────────────────────────────────────────────────────┘

初回 API Key 発行 CLI（CR-FASTAPI-021）:

ブートストラップ CLI を使用して初回 API Key を発行できます。ユーザーが存在しない場合は自動的に作成されます。

# プロジェクトルートに移動（重要）
cd /home/yn441611/NexusCore

# 仮想環境を有効化
source activate

# PYTHONPATH を設定（重要）
export PYTHONPATH=src

# ユーザーが存在しない場合は自動作成
python -m nexuscore.cli.bootstrap_apikey \
  --user-login dev \
  --user-name "Dev User" \
  --key-name "Local Dev Key"

# 出力例:
# [INFO] Created user: dev (id=1)
# [INFO] Created API key: "Local Dev Key" (id=3)
# export NEXUSCORE_API_KEY="nexus_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

出力をコピーして環境変数に設定:

export NEXUSCORE_API_KEY="nexus_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

注意: python -m nexuscore.cli.bootstrap_apikey を実行する際は、必ずプロジェクトルートから実行し、PYTHONPATH=src を設定してください。

詳細は CR-FASTAPI-021 完了レポート を参照してください。

CI での API Key 自動生成（CR-FASTAPI-023）:

GitHub Actions では、.github/workflows/ts-e2e.yml が自動的に bootstrap API Key を生成し、後続の TS E2E テストジョブに渡します。

CI フロー:

1. bootstrap-apikey ジョブが bootstrap_apikey CLI を実行して bootstrap key を生成
2. 生成された key を job output として後続ジョブに渡す（::add-mask:: でログに表示されないようにマスク）
3. ts-e2e ジョブが NEXUSCORE_BOOTSTRAP_API_KEY 環境変数を受け取り、FastAPI サーバーを起動
4. E2E テスト内の helper (getE2EApiKey()) が自動的にテスト用 API Key を発行してテストを実行

ローカルで CI フローを再現:

# CI と同じ方法で bootstrap key を生成
make ci-bootstrap-apikey

詳細は CR-FASTAPI-023 完了レポート を参照してください。

認証が必要なエンドポイント

• /api/v1/execute - 必須認証
• /api/v1/status/{task_id} - 必須認証
• /api/v1/api-keys - 必須認証（API Key 発行・一覧取得・削除）
• /api/v1/projects - 必須認証
• /api/v1/runs - 必須認証

認証不要なエンドポイント

• /api/v1/health - 認証不要（公開エンドポイント）

例外

• /api/v1/github/webhook - GitHub Webhook の署名認証（X-Hub-Signature-256）のみ使用。API Key 認証は不要。

認証エラー時のステータスコードポリシー

認証エラーは必ず適切なステータスコードを返します。認証フェイルは決して 500 Internal Server Error を返しません。

ケース	ステータスコード	エラーコード	説明
API Key ヘッダーが欠如	422	VALIDATION_ERROR	FastAPI のバリデーションエラー（必須ヘッダー欠如）
API Key が無効	401	UNAUTHORIZED	API Key が無効または DB に存在しない
API Key は見つかるが User が見つからない	401	UNAUTHORIZED	認証フェイル（User が削除された場合など）
DB アクセスエラー（接続エラーなど）	500	INTERNAL_ERROR	サーバー側の問題（認証フェイルではない）
サーバー設定エラー（API Key が設定されていない）	500	INTERNAL_ERROR	サーバー設定の問題（認証フェイルではない）

重要な原則:

• 認証フェイル（API Key 不正・欠如・DB に存在しない）は必ず 401 Unauthorized を返す
• DB アクセスエラーなど、サーバー側の致命的な障害は 500 にするが、認証フェイルと明確に区別できるようにエラーメッセージを設定
• 認証エラーは決して 500 を返さない

認証エラー（旧セクション）

• 401 Unauthorized: API Key が無効または欠如
• 500 Internal Server Error: サーバー設定エラー（API Key が設定されていない）

注意事項

• すべてのプロンプトは #project: NexusCore タグで始まります
• 既存の Flask アプリには影響を与えないよう注意してください
• 変更は unified diff 形式で提示されます
• Flask と FastAPI は別ポートで同時起動可能です
• すべての Public API は Depends(get_current_user) を通す必要があります（GitHub Webhook は例外）