SaaS UX 強化・テスト・運用設定 実装完了レポート

実装日時

2025-11-28

概要

SaaS基盤のUX強化、同期/非同期切り替え、テスト追加、実運用設定の整理を実装しました。

目的

  • Run 実行フローの UX を強化（デモしやすくする）
  • 同期/非同期の切り替えを環境変数で制御（デバッグ時は同期、本番は Celery）
  • Webapp 周りの最小テストを追加（壊れたらすぐ気付くようにする）
  • 実運用を意識した Celery/Redis の設定整理（手動起動から卒業）

原則

  • 既存の挙動を壊さない（後方互換100%）
  • 小さく安全な diff を生成
  • テストは最小限だが効果的

実装ステップ

タスク1: Run 実行フローの UX 強化

1-1. Run 一覧テーブルの改善

変更内容:

  • Run ID を /logs/runs/<run.run_id> へのリンクに変更（/runs/ から /logs/runs/ に統一）
  • Status に応じた簡易表示を追加：
    • PENDING: グレー
    • RUNNING: 青・太字・▶ アイコン
    • SUCCESS: 緑
    • FAILED: 赤
  • CSS スタイルを追加（色分けと強調表示）

実装ファイル:

  • src/nexuscore/webapp/views_projects.py

1-2. フラッシュメッセージの追加

変更内容:

  • trigger_run の HTML レスポンスでフラッシュメッセージを表示
  • 「Run がキューに入りました。実行状態は上記の Run 一覧で確認できます。ログは Run ID をクリックしてください。」という説明を追加
  • project_detail でフラッシュメッセージを取得・表示

実装ファイル:

  • src/nexuscore/webapp/views_projects.py

タスク2: 同期/非同期の切り替えを環境変数で制御

2-1. 環境変数 NEXUS_USE_CELERY の追加

変更内容:

  • trigger_run() の中で環境変数 NEXUS_USE_CELERY をチェック
  • デフォルトは "1"（非同期実行）
  • "0" の場合は同期実行

実装ファイル:

  • src/nexuscore/webapp/views_projects.py

2-2. 同期ブロックの関数化

変更内容:

  • 同期実行ブロックを run_orchestrator_inline() 関数に切り出し
  • src/nexuscore/webapp/orchestrator_inline.py を新規作成
  • 共通利用可能な形に整理

実装ファイル:

  • src/nexuscore/webapp/orchestrator_inline.py（新規作成）
  • src/nexuscore/webapp/views_projects.py

コード例:

# 環境変数で切り替え
use_celery = os.getenv("NEXUS_USE_CELERY", "1") == "1"

if use_celery:
    # Celery 非同期実行
    from nexuscore.webapp.celery_app import run_orchestrator_task
    async_result = run_orchestrator_task.delay(run.id)
else:
    # 同期実行（デバッグ用）
    from nexuscore.webapp.orchestrator_inline import run_orchestrator_inline
    run_orchestrator_inline(run, project, requirement, autonomy_level, fast_lane)

タスク3: Webapp 周りの最小テスト追加

3-1. test_logging_service.py の作成

テスト内容:

  • app context ありで log_execution_event() → ExecutionLog 1件
  • app context なしで何も起きない（例外にならない）
  • run_id を指定した場合のテスト

実装ファイル:

  • tests/webapp/test_logging_service.py（新規作成）

3-2. test_trigger_run.py の作成

テスト内容:

  • 認証済みで /projects/<id>/run に POST → Run が1件増える & 状態が PENDING
  • requirement 未指定なら 400
  • 未認証で /projects/<id>/run に POST → リダイレクト（ログインページ）
  • 別ユーザーのプロジェクトにアクセス → 404

実装ファイル:

  • tests/webapp/test_trigger_run.py（新規作成）

3-3. test_logs_views.py の作成

テスト内容:

  • /logs/projects/<id> が 200 & 自分のプロジェクト
  • /logs/projects/<id> が 404 & 自分のプロジェクト以外
  • /logs/runs/<run_id> が 200 & ownership チェック
  • /logs/runs/<run_id> が 404 & ownership チェック失敗
  • /logs/runs/<run_id> が リダイレクト（未認証）

実装ファイル:

  • tests/webapp/test_logs_views.py（新規作成）

タスク4: 実運用を意識した Celery/Redis の設定整理

4-1. Docker Compose サンプルの追加

変更内容:

  • docker-compose.saas.yml を新規作成
  • Flask Web アプリケーション、Celery Worker、Redis、PostgreSQL を含む構成
  • 環境変数の設定例を含む

実装ファイル:

  • docker-compose.saas.yml（新規作成）

4-2. systemd サービス設定例の追加

変更内容:

  • docs/saas_celery_systemd.service を新規作成
  • Celery Worker を systemd で管理するための設定例
  • 自動起動・再起動設定を含む

実装ファイル:

  • docs/saas_celery_systemd.service（新規作成）

4-3. supervisor 設定例の追加

変更内容:

  • docs/saas_celery_supervisor.conf を新規作成
  • Celery Worker を supervisor で管理するための設定例
  • ログファイルの設定を含む

実装ファイル:

  • docs/saas_celery_supervisor.conf（新規作成）

4-4. AppConfig の Celery 設定を整理

変更内容:

  • CELERY_BROKER_URL と CELERY_RESULT_BACKEND のデフォルト値を整理
  • REDIS_URL 環境変数もサポート（開発/本番で切り替え可能）
  • コメントで開発/本番環境の使い分けを説明

実装ファイル:

  • src/nexuscore/config/config.py

4-5. ドキュメントの更新

変更内容:

  • docs/saas_mvp_setup.md に実運用環境での起動方法を追加
  • Docker Compose、systemd、supervisor の使用方法を説明
  • 環境変数の説明を追加

実装ファイル:

  • docs/saas_mvp_setup.md

変更ファイル一覧

新規作成ファイル

  1. src/nexuscore/webapp/orchestrator_inline.py
    • 同期実行用のヘルパー関数
  2. tests/webapp/__init__.py
    • テストモジュールの初期化ファイル
  3. tests/webapp/test_logging_service.py
    • logging_service のテスト
  4. tests/webapp/test_trigger_run.py
    • trigger_run エンドポイントのテスト
  5. tests/webapp/test_logs_views.py
    • logs ビューのテスト
  6. docker-compose.saas.yml
    • SaaS 用 Docker Compose 設定
  7. docs/saas_celery_systemd.service
    • systemd サービス設定例
  8. docs/saas_celery_supervisor.conf
    • supervisor 設定例

変更ファイル

  1. src/nexuscore/webapp/views_projects.py
    • Run 一覧テーブルの UX 改善（リンク、ステータス表示）
    • フラッシュメッセージの追加
    • 環境変数による同期/非同期切り替え
  2. src/nexuscore/config/config.py
    • Celery 設定の整理（REDIS_URL サポート）
  3. docs/saas_mvp_setup.md
    • 実運用環境での起動方法を追加
    • 環境変数の説明を追加

動作確認結果

静的解析結果

  • リンターエラーなし
  • 型チェックエラーなし

実装確認

  • ✅ Run ID が /logs/runs/<run_id> へのリンクになっている
  • ✅ Status に応じた色分け・強調表示が動作する
  • ✅ フラッシュメッセージが表示される
  • ✅ 環境変数 NEXUS_USE_CELERY で同期/非同期を切り替えられる
  • ✅ テストファイルが作成されている

テスト実行（推奨） 

# Webapp テストを実行
cd /home/yn441611/NexusCore
source myenv_linux/bin/activate
python -m pytest tests/webapp/ -v

設計上の改善点

UX の改善

  1. Run 一覧の視認性向上:
    • Status に応じた色分けで状態が一目で分かる
    • RUNNING 状態の強調表示で実行中であることが明確
  2. ナビゲーションの改善:
    • Run ID をクリックするとログページに遷移
    • フラッシュメッセージで次のアクションが明確
  3. デバッグの容易さ:
    • 環境変数で同期/非同期を切り替え可能
    • デバッグ時は同期実行でトレースしやすい

テストの追加

  1. 最小限だが効果的なテスト:
    • 認証、権限チェック、エラーハンドリングをカバー
    • app context の有無による動作の違いを確認
  2. テストの実行容易性:
    • pytest で簡単に実行可能
    • メモリ内データベースを使用（高速）

運用設定の整理

  1. 複数の起動方法をサポート:
    • Docker Compose（開発・本番）
    • systemd（Linux 本番環境）
    • supervisor（プロセス管理）
  2. 環境変数による柔軟な設定:
    • 開発/本番で Celery 設定を切り替え可能
    • REDIS_URL もサポート

既知の制約・注意事項

既存コードとの互換性

  • ✅ 既存の CLI 実行は影響を受けない
  • ✅ 既存の Orchestrator / NPE / Agents アーキテクチャは壊れていない

制限事項やトレードオフ

  1. フラッシュメッセージの表示:
    • 現在は HTML を直接生成しているため、get_flashed_messages() を使用
    • 将来的にテンプレートエンジン（Jinja2）を使用する場合は改善可能
  2. テストのカバレッジ:
    • 最小限のテストのみ実装
    • 将来的に統合テストや E2E テストを追加可能
  3. Docker Compose 設定:
    • Dockerfile.webapp は未作成（将来的に作成が必要）
    • 現在は設定例のみ提供

移行時の注意点

  1. 環境変数の設定:
    • NEXUS_USE_CELERY を設定しない場合、デフォルトは非同期実行（"1"）
    • デバッグ時は NEXUS_USE_CELERY=0 を設定
  2. Celery Worker の起動:
    • 本番環境では systemd や supervisor を使用して自動起動
    • 開発環境では手動起動でも可

次のステップ

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

  1. テンプレートエンジンの導入:
    • Jinja2 を使用して HTML をテンプレート化
    • フラッシュメッセージの表示を改善
  2. テストの拡充:
    • 統合テストの追加
    • E2E テストの追加
    • カバレッジの向上
  3. Dockerfile の作成:
    • Dockerfile.webapp を作成
    • Docker Compose で完全に動作するようにする
  4. 進捗トラッキング:
    • Celery の AsyncResult を使用してタスクの進捗を追跡
    • Web UI でリアルタイムに進捗を表示
  5. ログの改善:
    • ログビューアの UI を改善
    • フィルタリング・検索機能の追加

関連ドキュメント

  • docs/saas_architecture.md - SaaS基盤のアーキテクチャドキュメント
  • docs/saas_mvp_setup.md - SaaS基盤のセットアップガイド
  • docs/celery_setup.md - Celery 非同期実行セットアップガイド
  • docs/completion_reports/RUN_CELERY_INTEGRATION_COMPLETION_REPORT.md - Run接続 + Celery 非同期実行 実装完了レポート
This site uses Just the Docs, a documentation theme for Jekyll.