QOOP Scoring API v1

認証

POST/api/v1/token/

JWT トークン取得 — {"username": "...", "password": "..."}

POST/api/v1/token/refresh/

トークンリフレッシュ — {"refresh": "..."}

全APIリクエストに Authorization: Bearer <access_token> ヘッダーが必要です（health を除く）。

回答・採点

POST/api/v1/answer/

回答提出（全5タイプ対応）— 問題IDと回答データを送信し、自動採点結果を取得

POST/api/v1/score/

記述式の単一採点 — 問題文・模範解答・生徒回答を直接送信して採点

POST/api/v1/score/batch/

記述式のバッチ採点 — 複数の生徒回答を一括採点

POST/api/v1/score/detailed/

記述式の詳細採点 — 6観点スコア＋フィードバック付き

POST/api/v1/score/csv-batch/

CSV一括採点 — CSVファイルをアップロードして一括採点

AI 生成

POST教師/api/v1/model-answer/generate/

模範解答の自動生成 — 問題文とキーワードから模範解答を生成

POST/api/v1/expression/convert/

表現レベル変換 — テキストの難易度を平易/標準/高度に変換

問題管理

GET/api/v1/questions/

問題一覧 — ?subject=理科&question_type=essay でフィルタ可能

POST教師/api/v1/questions/create/

問題作成 — 5タイプ（単一選択・正誤・短答・穴埋め・記述）に対応

GETPUTDELETE /api/v1/questions/{id}/

問題の詳細取得・更新・削除

POST教師/api/v1/questions/{id}/status/

ステータス変更 — {"status": "active"} で実施中に変更

採点結果

GET/api/v1/results/

採点結果一覧 — ?question_id=1&student_id=S001 でフィルタ可能

GET/api/v1/results/{id}/

採点結果の詳細（6観点スコア・フィードバック含む）

GET/api/v1/results/export/

CSV エクスポート — 採点結果をCSV形式でダウンロード

分析・統計

GET/api/v1/analytics/scores/

スコア統計 — 平均・最高・最低・回答数

GET/api/v1/analytics/criteria/

観点別統計 — C1〜C6 各観点の平均スコア

GET/api/v1/analytics/performance/

パフォーマンス分析 — 得点分布

GET/api/v1/analytics/trend/

トレンド分析 — 日別スコア推移

GET/api/v1/analytics/students/

生徒別サマリー — 各生徒の平均点・回答数

マスタ管理

GET/api/v1/users/

ユーザー一覧

GET/api/v1/synonyms/

類義語辞書一覧 — ?keyword=光合成 でフィルタ

GET/api/v1/rag/

RAGドキュメント一覧

POST/api/v1/rag/search/

RAG検索 — クエリに関連するドキュメントをTF-IDFで検索

設定・ヘルス

GETPUT/api/v1/config/weights/

採点ウェイト設定 — 6観点の重み（C1〜C6）を取得・変更

GET/api/v1/health/

ヘルスチェック — 認証不要

利用シナリオ

シナリオ1: 教師が問題を作成し、生徒が回答する

1

JWTトークン取得

POST /api/v1/token/
{"username": "teacher1", "password": "pass1234"}

2

記述式問題を作成

POST /api/v1/questions/create/
Authorization: Bearer <token>
{
  "question_type": "essay",
  "title": "地球温暖化について",
  "question_text": "地球温暖化の原因と対策を300字で論じなさい。",
  "model_answer": "地球温暖化の主な原因は...",
  "keywords": ["温室効果ガス", "二酸化炭素", "省エネルギー"],
  "subject": "理科", "grade": "1年",
  "max_score": 100, "difficulty": 2
}

3

ステータスを「実施中」に変更

POST /api/v1/questions/{id}/status/
{"status": "active"}

4

生徒が回答を提出

POST /api/v1/answer/
{
  "question_id": 1,
  "answer_data": {"answer": "地球温暖化は二酸化炭素の排出が原因で..."},
  "student_id": "S001",
  "student_name": "伊藤翔太"
}

レスポンスに採点結果（score, criterion_details, feedback）が含まれます。

シナリオ2: 選択式・正誤問題の自動採点

1

単一選択式の問題に回答

POST /api/v1/answer/
{
  "question_id": 5,
  "answer_data": {"selected_choice": "ア"},
  "student_id": "S002"
}

正解なら "is_correct": true, "score": 100.0、不正解なら "is_correct": false, "score": 0.0

2

穴埋め式の問題に回答

POST /api/v1/answer/
{
  "question_id": 10,
  "answer_data": {"blanks": {"1": "立法権", "2": "行政権", "3": "司法権"}},
  "student_id": "S002"
}

各空欄の正誤と部分点が返されます。

シナリオ3: 成績分析ダッシュボード

1

クラス全体のスコア統計を取得

GET /api/v1/analytics/scores/?question_id=1

平均点・最高点・最低点・回答数を取得。

2

6観点別の弱点を把握

GET /api/v1/analytics/criteria/?question_id=1

C1〜C6 各観点の平均スコア。「論理構成」が低い生徒が多い、など。

3

生徒ごとの進捗確認

GET /api/v1/analytics/students/

4

CSV一括エクスポート

GET /api/v1/results/export/?question_id=1

Excel等で分析可能なCSVをダウンロード。

シナリオ4: AIアシスタント（模範解答生成 + 表現レベル変換）

1

模範解答を自動生成

POST /api/v1/model-answer/generate/
{
  "question_text": "メディアリテラシーの重要性を論じなさい。",
  "subject": "公民",
  "keywords": ["フェイクニュース", "批判的思考", "情報リテラシー"],
  "max_length": 400
}

2

生徒の回答を平易な表現に変換

POST /api/v1/expression/convert/
{
  "text": "フェイクニュースの蔓延は...",
  "target_level": "easy"
}

レベル: easy（平易）/ standard（標準）/ advanced（高度）

記述式採点の6観点

ID	観点	ウェイト	評価内容
`C1`	主張の明確さ	15%	冒頭・末尾に明確な主張があるか
`C2`	理由の妥当性	15%	「なぜなら」等の接続表現で具体的な根拠を示しているか
`C3`	論理構成	15%	導入→本論→結論の3部構成、5文以上
`C4`	意味類似度	20%	模範解答との内容の一致度（意味的類似性）
`C5`	キーワード網羅性	15%	指定キーワード（＋類義語）の使用率
`C6`	文法・語彙	20%	文法の正確さ＋語彙の豊かさ（TTR）