読書テストアプリ API 仕様書 (Version 2.2)

概要

本APIは、ユーザーが読書メモ（テキストまたはURL）とオプション（difficulty, questionCount）を送信し、テストプレビューを生成する機能および、ユーザーがプレビューされたテスト問題に解答を入力・送信して最終結果を統合・保存する機能を提供します。

最終結果はJSON形式で保存され、各問題には「userAnswer」フィールドとしてユーザーの解答情報が含まれます。統合結果は外部のGCSアップロードモジュールで保存され、保存された結果のUUIDが返却されます。

システムは完全にステートレスに設計され、すべてのリクエスト・レスポンスはJSON形式で行われます。

エンドポイント

1. POST /test

目的:

• ユーザーが読書メモ（テキストまたはURL）およびオプション（difficulty, questionCount）を送信し、テストプレビュー（生成されたテスト問題）を作成する。
• このエンドポイントでは、前処理、チャンク化、埋め込み生成、FAISS検索、LLM（ChatGPT-4）の呼び出し、PydanticOutputParserによるパース、結果統合を実施し、プレビュー結果としてテスト問題が返されます。

リクエスト仕様:

• URL: /test

• HTTPメソッド: POST

• ヘッダー:

  • Content-Type: application/json

• リクエストボディ (JSON形式):

  {
    "type": "text" | "url",
    "content": "入力された読書メモまたはクロール対象のURL",
    "difficulty": "easy" | "normal" | "hard",
    "questionCount": 10
  }
  
  

  • type: 入力種別。Enum定義により "text" または "url" のみ許容。
  • content: 読書メモの内容またはURL。最大入力長は100,000文字（超過時は400エラーを返す）。
  • difficulty: テストの難易度。Enum定義により "easy", "normal", "hard" のみ許容。
  • questionCount: 生成する問題数。整数、最小5、最大20（バリデーション適用）。

成功レスポンス (HTTP 200 OK):

プレビュー結果として、生成されたテスト問題のプレビューが返されます。例:

{
  "preview": {
    "questions": [
      {
        "content": "クイズの内容",
        "options": {
          "A": "問題A",
          "B": "問題B",
          "C": "問題C",
          "D": "問題D"
        },
        "answer": "B",
        "explanation": "Bが正解の理由"
      }
      // ... 複数の問題
    ]
  }
}

エラーレスポンス: