エラー処理設計

本システムにおけるエラー処理は、ユーザーエクスペリエンスの維持、システムの安定性確保、および問題の早期発見・解決を目的として設計される。

1. エラー分類

システム内で発生するエラーを以下のカテゴリに分類し、それぞれに応じた処理を行う。

• 入力検証エラー: ユーザーからの入力データが不正な形式、または制約を満たさない場合に発生。
• 認証・認可エラー: ユーザーの認証情報が不正、またはリソースへのアクセス権限がない場合に発生。
• ビジネスロジックエラー: 業務処理中に発生する予期されたエラー（例: グラフデータが見つからない）。
• 外部サービス連携エラー: LLM API、データベース、メッセージブローカーなど、外部サービスとの通信中に発生するエラー。
• システム内部エラー: 予期せぬ例外、バグ、リソース不足など、システム内部で発生するエラー。

2. エラー処理の原則

• ユーザーへの適切なフィードバック: フロントエンドは、ユーザーに分かりやすいエラーメッセージを表示し、必要に応じて対処方法を提示する。
• 機密情報の非公開: エラーメッセージには、スタックトレースやデータベース情報など、システム内部の機密情報を決して含めない。
• ログ記録: すべてのエラーは適切にログに記録され、問題の追跡と分析に利用できるようにする。
• 回復性: 可能な限り、エラー発生後もシステムが正常な状態に回復できるよう設計する。
• 冪等性: 再試行可能な操作においては、エラー発生時の再試行がシステムの整合性を損なわないように考慮する。

3. エラー処理フロー

3.1. フロントエンド

• バックエンドからのエラーレスポンスを捕捉し、ユーザーフレンドリーなメッセージに変換して表示する。
• ネットワークエラーやタイムアウトなど、クライアントサイドで発生するエラーも適切に処理する。

3.2. バックエンド (FastAPI)

• 入力検証: Pydanticモデルによる自動検証を活用し、不正なリクエストを早期に拒否する。HTTPValidationErrorを捕捉し、標準的なエラーレスポンスを返す。
• 例外ハンドリング: カスタム例外を定義し、@app.exception_handlerデコレーターを用いて一元的に処理する。
• データベースエラー: データベース操作中に発生するエラー（例: 接続エラー、制約違反）は、適切な例外に変換し、ビジネスロジック層で捕捉・処理する。
• 外部サービスエラー: LLM APIやCeleryタスクの呼び出し時に発生するエラーは、リトライメカニズムを導入し、一定回数失敗した場合はエラーとして処理する。
• WebSocketエラー: WebSocket接続中に発生するエラーは、接続を安全にクローズし、必要に応じてクライアントにエラーメッセージを送信する。

4. エラーメッセージ

• HTTPステータスコード: エラーの種類に応じて適切なHTTPステータスコード（例: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error）を返す。
• エラーレスポンスボディ: 標準的なJSON形式でエラー詳細を提供する。

  {
    "detail": "エラーメッセージ",
    "code": "エラーコード (オプション)"
  }

5. ログ記録

• エラー発生時には、エラーレベル、タイムスタンプ、発生箇所、スタックトレース、関連するリクエスト情報などをログに記録する。
• ログは集中ログ管理システム（例: Cloud Logging）に送信され、分析・監視に利用される。