詳細設計書 - 読書テストアプリ (Submit API 追加版)

1. システム概要

目的:

• ユーザーがトップページで読書メモまたはURLを入力し、即座にテスト問題のプレビューを取得する。
• ユーザーはプレビューされたテスト問題に解答し、解答送信後、バックエンドが解答内容と生成済みテスト問題を統合してスコア計算を実施する。
• 統合結果JSONは外部のGCSアップロードモジュールにより保存され、UUIDが生成される。
• FastAPIは最終的にこのUUIDをレスポンスとして返し、フロントエンドはそのUUIDを利用して結果ページにリダイレクトする。

主な機能:

• トップページ:
  • ユーザー入力フォーム（テキスト入力／URL入力、難易度、問題数）
  • 生成されたテスト問題のプレビュー表示
  • ユーザー解答入力フォームおよび「解答送信 (submit)」ボタン
• 結果ページ:
  • UUIDをもとにバックエンドから結果JSONを取得し、問題内容、ユーザー解答、正解、解説、スコア（storeキー配下に正解数と総問題数）を表示

2. システム構成

2.1 フロントエンド (Next.js)

• トップページ:
  • 入力フォーム (テキスト／URL、難易度、問題数)
  • テスト問題プレビューエリア
  • 解答入力フォーム
  • 解答送信ボタン → POST /test/submit を呼び出す
• 結果ページ:
  • GET /result/{uuid} を呼び出して結果JSONを取得し、表示
  • エラーメッセージ、再読み込み、トップページ戻るボタンなど

2.2 バックエンド (FastAPI + LangChain)

• API エンドポイント:
  • POST /test:
    • ユーザー入力を受け、前処理済みテキストチャンク群からRAG処理を実施し、テスト問題のプレビューを生成して返す。
  • POST /test/submit:
    • ユーザー解答を受け取り、生成済みテスト問題と統合し、スコア計算を行い、統合結果JSONを作成。
    • 統合結果JSONは外部のGCSアップロードモジュールで保存され、UUIDが生成され返却される。
  • GET /result/{uuid}:
    • GCSから該当の結果JSONを取得し、返却する。
  • GET /health:
    • ヘルスチェック用。
• 内部のRAG処理 (AI Agent のコア部分):
  • 前処理済みテキストチャンク群を入力として、以下の処理を順次実行する。
    1. 埋め込み生成
    2. FAISS検索
    3. LLM呼び出し
    4. PydanticOutputParserによる出力パース
    5. 統合結果の作成
  • 各ステップは再試行・エラーハンドリングが実装され、最終的なTestResultオブジェクトを生成する。

2.3 外部連携

• FireCrawl: URL入力時にWebページ本文抽出