NexusCore SaaS基盤 MVP - 実装完了レポート

実装日時

2025-11-28

概要

NexusCore SaaS基盤のMVP（最小実装）を実装しました。 既存の Orchestrator v8.1 / NPE / BaseAgent / LLMRouter アーキテクチャを壊さずに、 Web UI と API を提供するための Flask アプリケーションを追加しました。

実装ステップ

1. SaaS基盤ディレクトリ構造の作成

作成ファイル:

  • src/nexuscore/webapp/__init__.py - Flaskアプリファクトリ
  • src/nexuscore/webapp/models.py - データベースモデル
  • src/nexuscore/webapp/auth.py - GitHub OAuth認証
  • src/nexuscore/webapp/views_projects.py - プロジェクト管理ビュー
  • src/nexuscore/webapp/views_logs.py - ログビューアビュー
  • src/nexuscore/webapp/views_dashboard.py - ダッシュボードビュー
  • src/nexuscore/webapp/db_logger.py - DBログフック

2. データベースモデルの実装

実装モデル:

  • User - GitHub OAuth で認証されたユーザー
  • Project - 対象リポジトリ（プロジェクト）
  • Run - 1回のオーケストレーション実行
  • PatchRecord - パッチ適用記録
  • ExecutionLog - 実行ログ（NPE / Orchestrator / Agent からの構造化ログ）
  • ApiKey - APIキー（読み取り専用）

3. FlaskアプリファクトリとDB初期化

実装内容:

  • create_app() 関数でFlaskアプリケーションを初期化
  • AppConfig から FLASK_SECRET_KEY と DATABASE_URI を読み込み
  • Flask-SQLAlchemy と Flask-Migrate を統合
  • Blueprint を登録

4. GitHub OAuth認証の実装

実装内容:

  • authlib.integrations.flask_client を使用した GitHub OAuth
  • /auth/login/github - GitHub へリダイレクト
  • /auth/github/callback - GitHub からのコールバック処理
  • ユーザー情報の upsert（存在すれば更新、なければ新規作成）
  • セッションに user_id を保存

5. プロジェクト管理APIの実装

実装内容:

  • /projects/ - プロジェクト一覧
  • /projects/<project_id> - プロジェクト詳細＋直近のRun一覧
  • /projects/new - 新規プロジェクト作成
  • /projects/<project_id>/run - プロジェクト実行トリガー

6. ログビューアAPIの実装

実装内容:

  • /logs/projects/<project_id> - プロジェクト単位のログ一覧
  • /logs/runs/<run_id> - 特定のRunのログ一覧
  • ソース（NPE / Orchestrator / Agent）でフィルタ可能
  • レベル（INFO / WARNING / ERROR）でフィルタ可能
  • ページング表示

7. NPE/OrchestratorへのDBログフック追加

実装内容:

  • src/nexuscore/npe/logger.py の log_transaction を拡張
  • Flaskアプリコンテキストが存在する場合のみDBに書き込む
  • 既存のCLI実行を壊さないよう防衛的に実装
  • src/nexuscore/core/orchestrator_db_hook.py で Orchestrator イベントをDBに記録

8. サンドボックス実行の安定化

実装内容:

  • src/nexuscore/core/sandbox_executor.py を作成
  • タイムアウト制御（デフォルト300秒）
  • リトライ戦略（指数バックオフ、最大3回）
  • 例外分類（RATE_LIMIT, TIMEOUT, INVALID_OUTPUT, EXECUTION_ERROR, NETWORK_ERROR）
  • SandboxResult データクラスで結果を返す

9. Gradioダッシュボードの実装

実装内容:

  • src/nexuscore/ui/nexus_dashboard.py を作成
  • Tab1: 解析（プロジェクト概要・コンテキスト表示）
  • Tab2: 修正（自己修復フロー、パッチ生成・適用）
  • Tab3: テスト（テスト実行と結果表示）
  • Tab4: 履歴（Run / ExecutionLog / PatchRecord 一覧）
  • 複数プロジェクト・複数ユーザーで共通利用できるテンプレ化

10. パッチ適用前プレビュー機能の実装

実装内容:

  • Gradioダッシュボードの「修正」タブに実装
  • ステップ1: Debugger を実行し、patch（diff文字列）を取得
  • ステップ2: UI 上で diff をプレビュー表示
  • ステップ3: ユーザーが「適用する」ボタンを押したときのみ PatchApplier.apply() を呼び出し
  • ステップ4: 適用結果を PatchRecord と ExecutionLog に記録

変更ファイル一覧

新規作成ファイル

  1. src/nexuscore/webapp/__init__.py
  2. src/nexuscore/webapp/models.py
  3. src/nexuscore/webapp/auth.py
  4. src/nexuscore/webapp/views_projects.py
  5. src/nexuscore/webapp/views_logs.py
  6. src/nexuscore/webapp/views_dashboard.py
  7. src/nexuscore/webapp/db_logger.py
  8. src/nexuscore/core/orchestrator_db_hook.py
  9. src/nexuscore/core/sandbox_executor.py
  10. src/nexuscore/ui/nexus_dashboard.py
  11. docs/saas_mvp_setup.md
  12. docs/saas_mvp_implementation_summary.md

変更ファイル

  1. requirements.txt - Flask-SQLAlchemy, Flask-Migrate, authlib を追加
  2. src/nexuscore/npe/logger.py - DBログフックを追加（既存動作を維持）

動作確認結果

静的解析結果

  • リンターエラーなし
  • 型チェックエラーなし（mypyレベル）

既存コードとの互換性

  • ✅ 既存の CLI 実行 (python orchestrator.py ...) は独立して動作
  • ✅ 既存の Orchestrator / NPE / Agents のインターフェース互換性を維持
  • ✅ 既存のエージェント（RequirementAgent / PlannerAgent / ArchitectAgent など）は影響を受けない

設計上の改善点

アーキテクチャの改善

  1. モジュール分離: Web UI と既存の Orchestrator / NPE を完全に分離
  2. 拡張性: 将来のフルSaaS展開に耐えられる設計
  3. 防衛的実装: Flaskアプリコンテキストが存在する場合のみDBに書き込む

コード品質の向上

  1. 型ヒント: すべての関数に型ヒントを追加
  2. docstring: すべての関数・クラスにdocstringを追加
  3. エラーハンドリング: 適切な例外処理とログ記録

既知の制約・注意事項

既存コードとの互換性

  • 既存の CLI 実行は影響を受けない（Flaskアプリコンテキストが存在しない場合）
  • 既存のエージェントのインターフェースは変更されていない

制限事項

  1. HTMLテンプレート: 現在は簡易HTMLを直接生成。将来的にはJinja2テンプレートを使用
  2. 非同期実行: プロジェクト実行は現在同期的。将来的にはCeleryを使用
  3. APIキー管理UI: 現在は実装されていない。将来的には /settings/api-keys を実装

移行時の注意点

  • データベースの初期化が必要（flask db init と flask db migrate）
  • GitHub OAuth アプリケーションの設定が必要
  • 環境変数の設定が必要（.env ファイル）

次のステップ

推奨されるフォローアップアクション

  1. テストの追加
    • モデルのテスト（生成・保存・クエリ）
    • ビューのテスト（認証・プロジェクト管理・ログビューア）
    • 認証のテスト（OAuth フロー）
  2. UIの改善
    • Jinja2テンプレートを使用したHTMLレンダリング
    • レスポンシブデザイン
    • リアルタイム更新（WebSocket）
  3. 非同期実行
    • Celery を使用した非同期タスク実行
    • タスクキューの実装
    • 進捗表示
  4. APIキー管理
    • /settings/api-keys の実装
    • APIキーの発行・削除・一覧表示
  5. セキュリティ強化
    • CSRF保護
    • レート制限
    • 入力検証

結論

NexusCore SaaS基盤のMVP実装が完了しました。 既存のアーキテクチャを壊さずに、Web UI と API を提供する基盤が整いました。

次のフェーズでは、テストの追加、UIの改善、非同期実行の実装などを進めることを推奨します。

This site uses Just the Docs, a documentation theme for Jekyll.