学習アプリ API (0.1.0)

Download OpenAPI specification:

学習アプリサポート: support@example.jp

小学生向け学習・スクリーニングアプリのバックエンド API。

認証

多くのエンドポイントは Cognito User Pool が発行する ID Token を Authorization: Bearer <token> ヘッダで要求する。

ロールと認可

認可は以下のロール階層で行う:

ロール	範囲
`system_admin`	全学校・全リソース
`school_admin`	自校全体
`shunin` (学年主任)	自学年の全クラス
`tannin` (担任)	自クラスのみ
`student`	自分のデータのみ

shunin と tannin は必ずクラスに所属する (担任兼務)。

エラーレスポンス

すべてのエラーは共通フォーマットで返す。

{
  "error": {
    "code": "MACHINE_READABLE_CODE",
    "message": "人間向けメッセージ",
    "details": {}
  }
}

ページネーション

一覧取得は cursor ベースのページネーションを使う。next_cursor が null の時、それ以上のデータはない。

Self

認証ユーザー自身の情報

認証ユーザー自身の情報を取得

JWT から解決された Actor 情報を返す。フロントエンドは認証直後にこのエンドポイントを呼んで、表示・遷移先を決定する。

Authorizations:

cognitoAuth

Responses

Response samples

200
401
500

Content type

application/json

{"role": "system_admin",
"user_id": "string",
"school_id": "string",
"class_id": 0,
"school_year": 0,
"grade": 0,
"email": "user@example.com",
"family_name": "string",
"given_name": "string"
}

ログイン記録 (student_status 更新)

生徒のログイン時に呼び出す。student_status.last_login_date と login_streak を更新する。

認可: 認証済みユーザー (student のみ更新対象、それ以外はノーオペで 200 を返す)
同日内の複数回呼び出しでは streak は変化しない
前日からの継続なら streak +1、それ以外は 1 にリセット
クライアントの local 日付を渡すこと (端末のタイムゾーン基準で「今日」を判定)

Authorizations:

cognitoAuth

Request Body schema: application/json
required

client_date

required

string <date>

クライアント端末のローカル日付 (例 "2026-05-07")

Responses

Request samples

Payload

Content type

application/json

{"client_date": "2019-08-24"
}

Response samples

200
400
401
500

Content type

application/json

{"logged_in": true,
"login_streak": 0,
"previous_login_date": "2019-08-24",
"is_new_day": true
}

Dashboard

教員ダッシュボード横断の集計 (アラート / 概況 / 活動)

教員ダッシュボードの要対応アラート

ロールに応じたスコープで、要対応アラートを集計して返す。

スコープ (自動決定):

system_admin: 全校 (school_id クエリパラで絞り込み可)
school_admin: 自校
shunin: 自学年
tannin: 自クラス

各アラートは「件数」を返し、UI 側でバッジ等として表示。

Authorizations:

cognitoAuth

query Parameters

school_id

string

system_admin が学校を指定する場合のみ

Responses

Response samples

200
401
403

Content type

application/json

{"scope": {"type": "class",
"school_id": "string",
"school_name": "string",
"class_id": 0,
"class_name": "string",
"grade": 0
},
"alerts": {"ai_support_unreviewed": {"count": 0,
"label": "string",
"severity": "low"
},
"teacher_support_count": {"count": 0,
"label": "string",
"severity": "low"
},
"teacher_unreviewed_count": {"count": 0,
"label": "string",
"severity": "low"
},
"tests_this_week": {"count": 0,
"label": "string",
"severity": "low"
}
}
}

教員ダッシュボードの概況サマリ

ロールに応じたスコープで、利用状況の概況メトリクスを返す。

スコープ (自動決定):

system_admin: 全校 (school_id クエリパラで絞り込み可)
school_admin: 自校
shunin: 自学年
tannin: 自クラス

Authorizations:

cognitoAuth

query Parameters

school_id	string
period	string Default: "last_7_days" Enum: "last_7_days" "last_30_days" "current_school_year"

Responses

Response samples

200
401
403

Content type

application/json

{"scope": {"type": "class",
"school_id": "string",
"school_name": "string",
"class_id": 0,
"class_name": "string",
"grade": 0
},
"metrics": {"test_completion_rate": {"value": 0.1,
"numerator": 0,
"denominator": 0,
"label": "string",
"definition": "string"
},
"learning_continuation_rate": {"value": 0.1,
"numerator": 0,
"denominator": 0,
"label": "string",
"definition": "string"
},
"ai_support_rate": {"value": 0.1,
"numerator": 0,
"denominator": 0,
"label": "string",
"definition": "string"
},
"teacher_review_rate": {"value": 0.1,
"numerator": 0,
"denominator": 0,
"label": "string",
"definition": "string"
}
},
"period": {"start": "2019-08-24",
"end": "2019-08-24"
}
}

最近の活動一覧 (時系列)

ロールに応じたスコープで、最近のイベント (セッション完了・レビュー等) を時系列で返す。

スコープ (自動決定):

system_admin: 全校
school_admin: 自校
shunin: 自学年
tannin: 自クラス

Authorizations:

cognitoAuth

query Parameters

limit	integer [ 1 .. 200 ] Default: 50 取得件数
cursor	string ページネーション用カーソル (前回レスポンスの `next_cursor`)

Responses

Response samples

200
401
403

Content type

application/json

{"next_cursor": "string",
"items": [{"type": "screening_completed",
"occurred_at": "2019-08-24T14:15:22Z",
"student": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"family_name": "string",
"given_name": "string",
"class_id": 0,
"student_no": 0
},
"session_id": 0,
"test_type": "screening",
"actor": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"family_name": "string",
"given_name": "string"
}
}
]
}

Schools

学校マスタ (system_admin / school_admin)

学校を作成

新しい学校を登録する。同時に以下を行う:

クラスを自動生成 (auto_generate_classes 指定時)
初代 school_admin を作成
school_admin に招待メールを送信 (send_invitation: true の場合)

認可: system_admin のみ

Authorizations:

cognitoAuth

Request Body schema: application/json
required

id required	string [ 1 .. 64 ] characters ^[a-zA-Z0-9_-]+$ 学校 ID (人間可読、英数字・ハイフン・アンダースコア)
name required	string [ 1 .. 100 ] characters
	object (AutoGenerateClassesOptions)
required	object (InitialSchoolAdmin)
send_invitation	boolean Default: true 初代管理者へ招待メールを送信するか

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"name": "string",
"auto_generate_classes": {"school_year": 0,
"classes_per_grade": 6,
"naming_pattern": "number"
},
"initial_admin": {"email": "user@example.com",
"family_name": "string",
"given_name": "string",
"family_name_kana": "string",
"given_name_kana": "string"
},
"send_invitation": true
}

Response samples

Content type

application/json

{"school": {"id": "string",
"name": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
},
"classes": [{"id": 0,
"school_id": "string",
"school_year": 0,
"grade": 1,
"name": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"classes_summary": {"classes_created": 0,
"grades_covered": [0
],
"school_year": 0
},
"initial_admin": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"school_id": "string",
"class_id": 0,
"email": "user@example.com",
"family_name": "string",
"given_name": "string",
"family_name_kana": "string",
"given_name_kana": "string",
"role": "school_admin",
"has_signed_up": true,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
},
"invitation": {"queued": true,
"invitation_id": "string",
"expires_at": "2019-08-24T14:15:22Z"
}
}

学校一覧を取得

登録されている学校の一覧を取得。認可: system_admin のみ

Authorizations:

cognitoAuth

query Parameters

limit	integer [ 1 .. 200 ] Default: 50 取得件数
cursor	string ページネーション用カーソル (前回レスポンスの `next_cursor`)

Responses

Response samples

200
401
403
500

Content type

application/json

{"next_cursor": "string",
"items": [{"id": "string",
"name": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
]
}

学校の個別取得

認可:

system_admin: 任意の学校
school_admin: 自校のみ

Authorizations:

cognitoAuth

path Parameters

schoolId

required

string^[a-zA-Z0-9_-]+$

学校 ID

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": "string",
"name": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"summary": {"class_count": 0,
"student_count": 0,
"teacher_count": 0,
"current_school_year": 0
}
}

学校情報の更新

認可:

system_admin: 任意の学校
school_admin: 自校のみ

更新可能なフィールドは name のみ。id (主キー) は変更不可。

Authorizations:

cognitoAuth

path Parameters

schoolId

required

string^[a-zA-Z0-9_-]+$

学校 ID

Request Body schema: application/json
required

name	string [ 1 .. 100 ] characters

Responses

Request samples

Payload

Content type

application/json

{"name": "string"
}

Response samples

200
400
401
403
404

Content type

application/json

{"id": "string",
"name": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}

Classes

クラスマスタ (system_admin / school_admin)

クラスの一括作成

指定したクラスを一括作成する。

認可: system_admin または school_admin (自校のみ)
1 リクエストにつき最大 100 件
(school_year, grade, name) の組が一意でなければ重複エラー

Authorizations:

cognitoAuth

path Parameters

schoolId

required

string^[a-zA-Z0-9_-]+$

学校 ID

Request Body schema: application/json
required

required	Array of objects (ClassCreate) [ 1 .. 100 ] items
on_conflict	string Default: "error" Enum: "error" "skip"

Responses

Request samples

Payload

Content type

application/json

{"classes": [{"school_year": 2020,
"grade": 1,
"name": "string"
}
],
"on_conflict": "error"
}

Response samples

207
400
401
403

Content type

application/json

{"summary": {"total": 0,
"succeeded": 0,
"failed": 0,
"skipped": 0
},
"results": [{"row": 0,
"status": "created",
"id": 0,
"school_year": 0,
"grade": 0,
"name": "string",
"error": {"code": "CLASS_ALREADY_EXISTS",
"message": "string"
}
}
]
}

クラスの規則的生成

指定された school_year について、1〜6年生の各学年に同数のクラスを自動生成する。

認可: system_admin または school_admin (自校のみ)
命名パターンは number (1組, 2組, ...) または letter (A組, B組, ...)
既存クラスとの重複は on_conflict の指定に従う
学校作成時の auto_generate_classes と同じロジック

Authorizations:

cognitoAuth

path Parameters

schoolId

required

string^[a-zA-Z0-9_-]+$

学校 ID

Request Body schema: application/json
required

school_year required	integer
classes_per_grade	integer [ 1 .. 10 ] Default: 6
naming_pattern	string Default: "number" Enum: "number" "letter"
on_conflict	string Default: "skip" Enum: "error" "skip" generate のデフォルトは `skip` (新年度準備で使うことを想定し、既存は維持)

Responses

Request samples

Payload

Content type

application/json

{"school_year": 0,
"classes_per_grade": 6,
"naming_pattern": "number",
"on_conflict": "error"
}

Response samples

207
400
401
403

Content type

application/json

{"summary": {"total": 0,
"succeeded": 0,
"failed": 0,
"skipped": 0
},
"results": [{"row": 0,
"status": "created",
"id": 0,
"school_year": 0,
"grade": 0,
"name": "string",
"error": {"code": "CLASS_ALREADY_EXISTS",
"message": "string"
}
}
]
}

クラス一覧の取得

ロールに応じた絞り込み:

system_admin / school_admin: 学校全体
shunin: 自学年のみ
tannin: 自クラスのみ

Authorizations:

cognitoAuth

path Parameters

schoolId

required

string^[a-zA-Z0-9_-]+$

学校 ID

query Parameters

school_year	integer 年度で絞り込み (省略時は現在の年度)
grade	integer [ 1 .. 6 ] 学年で絞り込み
limit	integer [ 1 .. 200 ] Default: 50 取得件数
cursor	string ページネーション用カーソル (前回レスポンスの `next_cursor`)

Responses

Response samples

200
401
403

Content type

application/json

{"next_cursor": "string",
"items": [{"id": 0,
"school_id": "string",
"school_year": 0,
"grade": 1,
"name": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"summary": {"student_count": 0,
"tannin": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"family_name": "string",
"given_name": "string"
}
}
}
]
}

クラス集計の取得

クラス全体のテスト結果集計を返す。教員ダッシュボードのクラス統計画面で使用。

認可:
- tannin: 自クラスのみ
- shunin: 自学年のクラス
- school_admin: 自校のクラス
- system_admin: 全校
集計は事前テーブルではなく動的クエリで算出 (MVP の規模では十分高速)
period で対象期間を切り替え。history を返すかどうかも include_history で制御

Authorizations:

cognitoAuth

path Parameters

classId

required

integer <int64>

クラス ID (school_class.id)

query Parameters

test_type	string (TestType) Enum: "screening" "posttest" 省略時は screening
period	string Default: "last_30_days" Enum: "last_7_days" "last_30_days" "current_school_year" "all"
from	string <date> period=custom 用 (period が指定されない場合)
to	string <date>
include_history	boolean Default: false 過去のテスト回トレンドを含めるか

Responses

Response samples

200
401
403
404

Content type

application/json

{"class": {"id": 0,
"school_id": "string",
"school_year": 0,
"grade": 1,
"name": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"student_count": 0
},
"test_type": "screening",
"period": {"start": "2019-08-24",
"end": "2019-08-24"
},
"metrics": {"submission_count": 0,
"submission_rate": 0.1,
"avg_correct_rate": 0.1,
"ai_detected_count": 0,
"needs_support_count": 0,
"teacher_reviewed_count": 0
},
"teacher_judgment_distribution": {"normal": 0,
"watch": 0,
"support": 0,
"unreviewed": 0
},
"history": [{"round": 0,
"date": "2019-08-24",
"submission_count": 0,
"avg_correct_rate": 0.1,
"ai_detected_count": 0,
"needs_support_count": 0
}
]
}

クラスの個別取得

Authorizations:

cognitoAuth

path Parameters

classId

required

integer <int64>

クラス ID (school_class.id)

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": 0,
"school_id": "string",
"school_year": 0,
"grade": 1,
"name": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"summary": {"student_count": 0,
"tannin": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"family_name": "string",
"given_name": "string"
}
}
}

クラス情報の更新

認可: system_admin / school_admin (自校)
更新可能なのは name のみ。school_year / grade は変更不可

Authorizations:

cognitoAuth

path Parameters

classId

required

integer <int64>

クラス ID (school_class.id)

Request Body schema: application/json
required

name	string [ 1 .. 30 ] characters

Responses

Request samples

Payload

Content type

application/json

{"name": "string"
}

Response samples

Content type

application/json

{"id": 0,
"school_id": "string",
"school_year": 0,
"grade": 1,
"name": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}

クラスの削除

認可: system_admin / school_admin (自校)
生徒または教員が所属しているクラスは削除できない (409)
学習ログが紐づいていても、clas削除後の集計を維持するため削除を拒否することがある

Authorizations:

cognitoAuth

path Parameters

classId

required

integer <int64>

クラス ID (school_class.id)

Responses

Response samples

401
403
404
409

Content type

application/json

{"error": {"code": "INVALID_EMAIL_FORMAT",
"message": "メールアドレスの形式が不正です",
"details": null
}
}

Students

生徒の管理

生徒の一括登録

指定された学校に複数の生徒を一括登録する。

認可:
- system_admin: 任意の学校
- school_admin: 自校全体
- shunin: 自学年内のクラスへの登録のみ (リクエストの class_id が自学年外の場合 403)
- tannin: 自クラスへの登録のみ (リクエストの class_id が自クラス外の場合 403)
1 リクエストにつき最大 1000 件
on_conflict: error の場合は全件成功 / 全件ロールバック
on_conflict: skip の場合は重複行をスキップして残りを処理
レスポンスは 207 (Multi-Status)。results に行単位の結果を含む

Authorizations:

cognitoAuth

path Parameters

schoolId

required

string^[a-zA-Z0-9_-]+$

学校 ID

Request Body schema: application/json
required

required	Array of objects (StudentCreate) [ 1 .. 1000 ] items
on_conflict	string Default: "error" Enum: "error" "skip" 重複時の挙動: `error`: 1 件でも重複があれば全件ロールバック (400) `skip`: 重複行はスキップして残りを処理

Responses

Request samples

Payload

Content type

application/json

{"students": [{"class_id": 0,
"student_no": 1,
"gakuseki_no": "string",
"email": "user@example.com",
"family_name": "string",
"given_name": "string",
"family_name_kana": "string",
"given_name_kana": "string"
}
],
"on_conflict": "error"
}

Response samples

207
400
401
403
500

Content type

application/json

{"summary": {"total": 0,
"succeeded": 0,
"failed": 0,
"skipped": 0
},
"results": [{"row": 0,
"status": "created",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"gakuseki_no": "string",
"email": "user@example.com",
"error": {"code": "EMAIL_ALREADY_EXISTS",
"message": "string",
"field": "string",
"value": null
}
}
]
}

学校配下の生徒一覧

指定された学校配下の生徒を一覧取得する。ロールに応じて自動的に絞り込まれる:

system_admin / school_admin: 学校全体
shunin: 自学年のクラスのみ
tannin: 自クラスのみ

Authorizations:

cognitoAuth

path Parameters

schoolId

required

string^[a-zA-Z0-9_-]+$

学校 ID

query Parameters

class_id	integer 特定クラスで絞り込む (任意)
grade	integer [ 1 .. 6 ] 学年で絞り込む (任意)
has_signed_up	boolean サインアップ済みかで絞り込む: `true`: cognito_sub IS NOT NULL の生徒のみ `false`: cognito_sub IS NULL の生徒のみ (招待状況確認等) 省略時: 両方含む
limit	integer [ 1 .. 200 ] Default: 50 取得件数
cursor	string ページネーション用カーソル (前回レスポンスの `next_cursor`)

Responses

Response samples

200
401
403
500

Content type

application/json

{"next_cursor": "string",
"items": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"school_id": "string",
"class_id": 0,
"student_no": 1,
"gakuseki_no": "string",
"email": "user@example.com",
"family_name": "string",
"given_name": "string",
"family_name_kana": "string",
"given_name_kana": "string",
"has_signed_up": true,
"created_at": "2019-08-24T14:15:22Z",
"last_active_at": "2019-08-24T14:15:22Z"
}
]
}

生徒の個別取得

認可:

system_admin / school_admin: 自校の任意の生徒
shunin: 自学年の生徒
tannin: 自クラスの生徒
student: 自分のみ

Authorizations:

cognitoAuth

path Parameters

studentId

required

string <uuid>

生徒 ID (UUID v7)

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"school_id": "string",
"class_id": 0,
"student_no": 1,
"gakuseki_no": "string",
"email": "user@example.com",
"family_name": "string",
"given_name": "string",
"family_name_kana": "string",
"given_name_kana": "string",
"has_signed_up": true,
"created_at": "2019-08-24T14:15:22Z",
"last_active_at": "2019-08-24T14:15:22Z"
}

生徒情報の更新

認可:

system_admin / school_admin: 自校の任意の生徒
shunin: 自学年の生徒
tannin: 自クラスの生徒

メールアドレス変更時の注意:

旧 email が email_suppression にあっても、新 email は別物として扱われる
すでにサインアップ済み (cognito_sub != null) のユーザーの email 変更は、Cognito 側との同期が必要 (運用フローで対応)

Authorizations:

cognitoAuth

path Parameters

studentId

required

string <uuid>

生徒 ID (UUID v7)

Request Body schema: application/json
required

class_id	integer
student_no	integer [ 1 .. 99 ]
gakuseki_no	string or null
email	string <email>
family_name	string
given_name	string
family_name_kana	string
given_name_kana	string

Responses

Request samples

Payload

Content type

application/json

{"class_id": 0,
"student_no": 1,
"gakuseki_no": "string",
"email": "user@example.com",
"family_name": "string",
"given_name": "string",
"family_name_kana": "string",
"given_name_kana": "string"
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"school_id": "string",
"class_id": 0,
"student_no": 1,
"gakuseki_no": "string",
"email": "user@example.com",
"family_name": "string",
"given_name": "string",
"family_name_kana": "string",
"given_name_kana": "string",
"has_signed_up": true,
"created_at": "2019-08-24T14:15:22Z",
"last_active_at": "2019-08-24T14:15:22Z"
}

Teachers

教員の管理

教員の一括登録

指定された学校に複数の教員を一括登録する。

認可: system_admin または school_admin (自校のみ)
1 リクエストにつき最大 1000 件
tannin / shunin は class_id 必須
school_admin は class_id 任意

Authorizations:

cognitoAuth

path Parameters

schoolId

required

string^[a-zA-Z0-9_-]+$

学校 ID

Request Body schema: application/json
required

required	Array of objects (TeacherCreate) [ 1 .. 1000 ] items
on_conflict	string Default: "error" Enum: "error" "skip"

Responses

Request samples

Payload

Content type

application/json

{"teachers": [{"class_id": 0,
"email": "user@example.com",
"family_name": "string",
"given_name": "string",
"family_name_kana": "string",
"given_name_kana": "string",
"role": "school_admin"
}
],
"on_conflict": "error"
}

Response samples

207
400
401
403
500

Content type

application/json

{"summary": {"total": 0,
"succeeded": 0,
"failed": 0,
"skipped": 0
},
"results": [{"row": 0,
"status": "created",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"email": "user@example.com",
"error": {"code": "EMAIL_ALREADY_EXISTS",
"message": "string",
"field": "string",
"value": null
}
}
]
}

学校配下の教員一覧

ロールに応じた絞り込み:

system_admin / school_admin: 学校全体
shunin: 自学年に紐づく教員 + 自分自身
tannin: 自分自身のみ

Authorizations:

cognitoAuth

path Parameters

schoolId

required

string^[a-zA-Z0-9_-]+$

学校 ID

query Parameters

role	string (TeacherRole) Enum: "school_admin" "shunin" "tannin" ロールで絞り込む (任意)
limit	integer [ 1 .. 200 ] Default: 50 取得件数
cursor	string ページネーション用カーソル (前回レスポンスの `next_cursor`)

Responses

Response samples

200
401
403
500

Content type

application/json

{"next_cursor": "string",
"items": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"school_id": "string",
"class_id": 0,
"email": "user@example.com",
"family_name": "string",
"given_name": "string",
"family_name_kana": "string",
"given_name_kana": "string",
"role": "school_admin",
"has_signed_up": true,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
]
}

教員の個別取得

Authorizations:

cognitoAuth

path Parameters

teacherId

required

string <uuid>

教員 ID (UUID v7)

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"school_id": "string",
"class_id": 0,
"email": "user@example.com",
"family_name": "string",
"given_name": "string",
"family_name_kana": "string",
"given_name_kana": "string",
"role": "school_admin",
"has_signed_up": true,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}

教員情報の更新

認可:

system_admin: 任意の教員
school_admin: 自校の教員
自分自身: 自分の name/kana のみ (role の変更は不可)

Authorizations:

cognitoAuth

path Parameters

teacherId

required

string <uuid>

教員 ID (UUID v7)

Request Body schema: application/json
required

class_id	integer or null
email	string <email>
family_name	string
given_name	string
family_name_kana	string
given_name_kana	string
role	string (TeacherRole) Enum: "school_admin" "shunin" "tannin" `school_admin`: 校長や ICT 担当などの学校管理者 `shunin`: 学年主任 (担任兼務、class_id 必須) `tannin`: 担任 (class_id 必須)

Responses

Request samples

Payload

Content type

application/json

{"class_id": 0,
"email": "user@example.com",
"family_name": "string",
"given_name": "string",
"family_name_kana": "string",
"given_name_kana": "string",
"role": "school_admin"
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"school_id": "string",
"class_id": 0,
"email": "user@example.com",
"family_name": "string",
"given_name": "string",
"family_name_kana": "string",
"given_name_kana": "string",
"role": "school_admin",
"has_signed_up": true,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}

Invitations

招待 token の発行・検証・再送

招待一覧の取得

招待状況の一覧を返す。教員ダッシュボードの「招待状況」画面で使用。

スコープ (自動決定):

system_admin: 全校 (school_id クエリパラで絞り込み可)
school_admin: 自校
shunin: 自学年の student に対する招待のみ
tannin: 自クラスの student に対する招待のみ

各招待の status:

active: 未消費・未期限切れ
expired: 期限切れ
consumed: 消費済み (サインアップ完了)

can_resend_at は次に再送できる時刻 (3 分のレート制限)。

Authorizations:

cognitoAuth

query Parameters

school_id	string
class_id	integer <int64>
user_type	string Enum: "student" "teacher"
status	string Enum: "active" "expired" "consumed" 複数指定する場合はカンマ区切り (例: `active,expired`)。省略時は全 status を返す。
limit	integer [ 1 .. 200 ] Default: 50 取得件数
cursor	string ページネーション用カーソル (前回レスポンスの `next_cursor`)

Responses

Response samples

200
401
403

Content type

application/json

{"next_cursor": "string",
"items": [{"user_type": "student",
"user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
"user": {"family_name": "string",
"given_name": "string",
"class_id": 0,
"student_no": 0
},
"email": "user@example.com",
"status": "active",
"expires_at": "2019-08-24T14:15:22Z",
"sent_at": "2019-08-24T14:15:22Z",
"consumed_at": "2019-08-24T14:15:22Z",
"can_resend_at": "2019-08-24T14:15:22Z"
}
],
"summary": {"total": 0,
"active": 0,
"expired": 0,
"consumed": 0
}
}

招待メールの送信

指定された複数のユーザー (student / teacher) に招待メールを送信する。

招待 token は 3日間 (72時間) 有効、options.expires_in_hours で上書き可能
1 リクエストにつき最大 100 targets
既にサインアップ済み (cognito_sub != null) のユーザーは skip_already_signed_up でスキップ可能
email_suppression にあるユーザーへの送信は失敗扱い
同一ユーザーに複数 active な招待がある場合、古い方は invalidate される
メール送信は SQS 経由で非同期実行されるため、API は 202 Accepted を返す

認可:

system_admin: 任意のユーザー (student / teacher)
school_admin: 自校の任意のユーザー (student / teacher)
shunin: 自学年の student のみ (teacher は招待不可)
tannin: 自クラスの student のみ (teacher は招待不可)

targets に権限外のユーザーが含まれる場合、その行は failed (reason: permission_denied) として扱う。

Authorizations:

cognitoAuth

Request Body schema: application/json
required

required	Array of objects (InvitationTarget) [ 1 .. 100 ] items
	object

Responses

Request samples

Payload

Content type

application/json

{"targets": [{"user_type": "student",
"user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}
],
"options": {"skip_already_signed_up": true,
"expires_in_hours": 72
}
}

Response samples

202
400
401
403
500

Content type

application/json

{"summary": {"total": 0,
"queued": 0,
"skipped": 0,
"failed": 0
},
"results": [{"user_type": "student",
"user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
"status": "queued",
"invitation_id": "string",
"reason": "already_signed_up"
}
]
}

招待 token の検証

フロントエンドが招待リンクを踏んだ直後に呼ぶエンドポイント。 token が有効かどうかを確認し、サインアップ画面に表示する情報 (氏名、学校名、有効期限) を返す。

このエンドポイントは認証不要。token そのものが認証として機能する。

path Parameters

token

required

string >= 32 characters

招待 token (URL-safe base64)

Responses

Response samples

200
404
410
500

Content type

application/json

{"valid": true,
"user_type": "student",
"email": "user@example.com",
"family_name": "string",
"given_name": "string",
"school_name": "string",
"expires_at": "2019-08-24T14:15:22Z"
}

招待メールの再送

指定されたユーザーに招待を再送する。

前回送信から 3 分以内 の再送は 429 Too Many Requests
既存の active な invitation があれば invalidate して新しい token を発行
再送先のメールアドレスは student/teacher テーブルの最新の email を使用
email_suppression にあるアドレスは送信されない

認可:

system_admin: 任意のユーザー
school_admin: 自校の任意のユーザー (student / teacher)
shunin: 自学年の student のみ
tannin: 自クラスの student のみ

teacher の再送は school_admin 以上のみ。

Authorizations:

cognitoAuth

path Parameters

userId

required

string <uuid>

query Parameters

user_type

required

string

Enum: "student" "teacher"

Responses

Response samples

Content type

application/json

{"user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
"user_type": "student",
"status": "queued",
"invitation_id": "string",
"expires_at": "2019-08-24T14:15:22Z"
}

EmailSuppressions

メール送信停止リストの管理

学校配下の suppression list 取得

指定された学校に所属する student/teacher のうち、メール送信が停止されているアドレス一覧を取得する。

認可と取得スコープ:

system_admin: 任意の学校
school_admin: 自校全体
shunin: 自学年に所属する student の email のみ
tannin: 自クラスに所属する student の email のみ

ロールに応じてサーバ側で自動的に絞り込まれる。

Authorizations:

cognitoAuth

path Parameters

schoolId

required

string^[a-zA-Z0-9_-]+$

学校 ID

query Parameters

reason	string Enum: "hard_bounce" "complaint" "manual"
limit	integer [ 1 .. 200 ] Default: 50 取得件数
cursor	string ページネーション用カーソル (前回レスポンスの `next_cursor`)

Responses

Response samples

200
401
403
500

Content type

application/json

{"next_cursor": "string",
"items": [{"email": "user@example.com",
"reason": "hard_bounce",
"bounce_subtype": "string",
"diagnostic": "string",
"suppressed_at": "2019-08-24T14:15:22Z",
"notes": "string",
"user": {"user_type": "student",
"user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
"family_name": "string",
"given_name": "string",
"class_id": 0,
"student_no": 0,
"teacher_role": "school_admin"
}
}
]
}

suppression list からの削除

指定されたメールアドレスを suppression list から削除する。 AWS SES のアカウントレベル Suppression List からも削除される。操作は suppression_action_log に記録される。

認可:

system_admin: 任意のアドレス
school_admin: 自校に所属する user の email のみ
shunin: 自学年に所属する student の email のみ
tannin: 自クラスに所属する student の email のみ

Authorizations:

cognitoAuth

path Parameters

email

required

string <email>

Responses

Response samples

401
403
404
500

Content type

application/json

{"error": {"code": "INVALID_EMAIL_FORMAT",
"message": "メールアドレスの形式が不正です",
"details": null
}
}

Assessments

スクリーニング・事後テストのセッション

アセスメント (screening / posttest) セッション開始

スクリーニングまたは事後テストのセッションを開始する。

認可: student のみ (自分のセッション)
1 つのアクティブな (未終了の) アセスメントセッションを同時に複数持つことは推奨しない (UI で制御)

Authorizations:

cognitoAuth

Request Body schema: application/json
required

test_type required	string (TestType) Enum: "screening" "posttest"
device_model	string デバイスモデル名 (任意)

Responses

Request samples

Payload

Content type

application/json

{"test_type": "screening",
"device_model": "string"
}

Response samples

201
400
401
403
500

Content type

application/json

{"session_id": 0,
"category": "screening",
"started_at": "2019-08-24T14:15:22Z",
"student_id": "8e4ec631-d04e-4769-bc05-342d3d37b815",
"enrollment_id": 0,
"block_id": "string",
"block_ids": ["string"
]
}

アセスメントセッションの取得

Authorizations:

cognitoAuth

path Parameters

sessionId

required

integer <int64>

セッション ID (letter_session_log.id)

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"session_id": 0,
"category": "screening",
"student_id": "8e4ec631-d04e-4769-bc05-342d3d37b815",
"enrollment_id": 0,
"date": "2019-08-24",
"started_at": "2019-08-24T14:15:22Z",
"ended_at": "2019-08-24T14:15:22Z",
"duration_seconds": 0,
"is_finished": true,
"device_model": "string",
"max_volume_input": 0.1,
"button_mash_count": 0,
"errant_tap_count": 0
}

アセスメント中の 1 問の解答を記録

認可: セッション所有者 (student) のみ
既に finish 済みのセッションには記録不可 (409)

Authorizations:

cognitoAuth

path Parameters

sessionId

required

integer <int64>

セッション ID (letter_session_log.id)

Request Body schema: application/json
required

question_char required	string [ 1 .. 8 ] characters 出題された文字 (例 "あ")
recognized_text	string or null 認識結果 (音声認識テキスト等)
is_correct	boolean or null クライアント判定の正誤。 learning: クライアントが必ず true / false を送る screening / posttest: 省略 (or null) を許容。backend が finish 後にバッチ AI 判定で `letter_answer_log.is_correct` を埋める
response_time	number <float> >= 0 応答時間 (秒)
is_aborted	boolean Default: false 中断された解答か
client_timestamp required	string <date-time> クライアント側のタイムスタンプ (ISO 8601)
audio_upload_required	boolean Default: false true の場合、レスポンスに audio_upload (Pre-signed URL) を含める。クライアントはその URL に対して PUT で音声ファイル (wav) をアップロードする。

Responses

Request samples

Payload

Content type

application/json

{"question_char": "string",
"recognized_text": "string",
"is_correct": true,
"response_time": 0.1,
"is_aborted": false,
"client_timestamp": "2019-08-24T14:15:22Z",
"audio_upload_required": false
}

Response samples

Content type

application/json

{"answer_id": 0,
"recorded_at": "2019-08-24T14:15:22Z",
"audio_upload": {"s3_key": "string",
"presigned_url": "http://example.com",
"expires_at": "2019-08-24T14:15:22Z"
}
}

アセスメントの解答一覧 (レビュー画面用)

指定されたセッションの全 answer (解答) を取得。教員レビュー画面で文字グリッドの表示に使用。

認可:
- student: 自分の解答のみ
- tannin: 自クラスの生徒
- shunin: 自学年の生徒
- school_admin: 自校の生徒
- system_admin: 全校
各 answer に AI 判定 (ai_is_correct) と教員判定 (reviewed_is_correct) を含む
is_correct は最終的な値 (COALESCE(reviewed_is_correct, ai_is_correct))

Authorizations:

cognitoAuth

path Parameters

sessionId

required

integer <int64>

セッション ID (letter_session_log.id)

Responses

Response samples

200
401
403
404

Content type

application/json

{"items": [{"answer_id": 0,
"question_char": "string",
"recognized_text": "string",
"ai_is_correct": true,
"reviewed_is_correct": true,
"is_correct": true,
"response_time": 0.1,
"is_aborted": true,
"timestamp": "2019-08-24T14:15:22Z",
"has_audio": true,
"reviewed_by": "92ab4dbc-1b27-40ce-b24b-7dde8f4709be",
"reviewed_at": "2019-08-24T14:15:22Z"
}
]
}

アセスメントセッションの終了 + 結果計算

セッションを終了し、テスト結果を計算する。

letter_session_log の終了時刻と duration を更新
letter_test_result を作成 (correct_count, total_count, correct_rate, ai_judgment 等)
teacher_judgment は教員レビュー前のため NULL
letter_character_stat / letter_block_stat / letter_daily_record / student_status は更新しない (assessment は習熟度測定の対象外)
認可: セッション所有者 (student) のみ
二重 finish は 409 で拒否

AI 判定の確定タイミング

pending_count == 0 (= 解答すべての is_correct が確定済み): finish 時点で同期的に AI 判定 (T式準拠 correct_count < 20 ? 'support' : 'normal') を確定する
pending_count > 0 かつ test_type が screening または posttest: ai_judgment: null で先行作成し、SQS の判定キューにエンキュー。Worker が ML API で逐次判定 → letter_answer_log.is_correct を埋める → 完了したら correct_count / correct_rate / ai_judgment を再計算する。教員はリロードで結果反映を見る
判定中は pending_count > 0 のまま、完了で 0 になる。教員手動レビューで reviewed_is_correct が入ると is_correct の値に関係なく集計に反映 (COALESCE(reviewed_is_correct, is_correct))

Authorizations:

cognitoAuth

path Parameters

sessionId

required

integer <int64>

セッション ID (letter_session_log.id)

Request Body schema: application/json
required

ended_at required	string <date-time> クライアント側の終了時刻
max_volume_input	number <float> [ 0 .. 1 ]
button_mash_count	integer >= 0
errant_tap_count	integer >= 0

Responses

Request samples

Payload

Content type

application/json

{"ended_at": "2019-08-24T14:15:22Z",
"max_volume_input": 1,
"button_mash_count": 0,
"errant_tap_count": 0
}

Response samples

Content type

application/json

{"session_id": 0,
"category": "screening",
"started_at": "2019-08-24T14:15:22Z",
"ended_at": "2019-08-24T14:15:22Z",
"duration_seconds": 0,
"summary": {"total_count": 0,
"correct_count": 0,
"incorrect_count": 0,
"pending_count": 0,
"correct_rate": 1,
"average_response_time": 0.1,
"max_response_time": 0.1,
"min_response_time": 0.1
},
"result": {"test_type": "screening",
"correct_count": 0,
"total_count": 0,
"pending_count": 0,
"correct_rate": 0.1,
"ai_judgment": "normal",
"teacher_judgment": "normal"
}
}

アセスメント音声の Pre-signed URL 一覧

指定されたアセスメントセッション内の全 answer の音声ファイルの再生用 Pre-signed URL を返す。

教員レビュー画面で「文字をクリックして音声再生」のために使う
URL の有効期限は短く (15 分)
audio_s3_key が NULL の answer は items に含まれない
認可:
- student: 自分の結果
- tannin: 自クラス
- shunin: 自学年
- school_admin: 自校

Authorizations:

cognitoAuth

path Parameters

sessionId

required

integer <int64>

セッション ID (letter_session_log.id)

Responses

Response samples

200
401
403
404

Content type

application/json

{"items": [{"answer_id": 0,
"question_char": "string",
"audio_url": "http://example.com",
"expires_at": "2019-08-24T14:15:22Z"
}
]
}

個別 answer 音声の Pre-signed URL 取得

個別の answer の再生用 Pre-signed URL を返す。

audio_s3_key が NULL の場合は 404
認可: アセスメントの参照権限と同じ

Authorizations:

cognitoAuth

path Parameters

sessionId required	integer <int64> セッション ID (letter_session_log.id)
answerId required	integer <int64> 解答 ID (letter_answer_log.id)

Responses

Response samples

200
401
403
404

Content type

application/json

{"audio_url": "http://example.com",
"expires_at": "2019-08-24T14:15:22Z",
"s3_key": "string"
}

個別 answer の教員手動正誤判定

指定された answer に対して、教員が手動で正誤を上書きする (AI/自動判定をオーバーライド)。

元の is_correct は変更されず、reviewed_is_correct がセットされる
reviewed_is_correct: null を渡すと、教員レビューを取り消し (AI 判定に戻す)
サーバ側で reviewed_by = actor.userId、reviewed_at = NOW() を自動セット
認可:
- tannin: 自クラス
- shunin: 自学年
- school_admin: 自校
- system_admin: 全校
- student は不可

Authorizations:

cognitoAuth

path Parameters

sessionId required	integer <int64> セッション ID (letter_session_log.id)
answerId required	integer <int64> 解答 ID (letter_answer_log.id)

Request Body schema: application/json
required

is_correct

required

boolean or null

教員判定の正誤。

true / false: 教員レビュー設定
null: 教員レビューを取り消し (AI 判定に戻す)

Responses

Request samples

Payload

Content type

application/json

{"is_correct": true
}

Response samples

200
400
401
403
404

Content type

application/json

{"answer_id": 0,
"question_char": "string",
"ai_is_correct": true,
"reviewed_is_correct": true,
"is_correct": true,
"reviewed_by": "92ab4dbc-1b27-40ce-b24b-7dde8f4709be",
"reviewed_at": "2019-08-24T14:15:22Z",
"response_time": 0.1
}

複数 answer の教員レビューを一括更新

モックアップの「判定を確定する」ボタンに対応。複数文字の正誤を一度に確定する。

トランザクション内で全件 UPDATE
1 件でも他の answer (別 session) を含むと 400
1 リクエストあたり最大 200 件
認可: 個別 review と同じ

Authorizations:

cognitoAuth

path Parameters

sessionId

required

integer <int64>

セッション ID (letter_session_log.id)

Request Body schema: application/json
required

required

Array of objects (BulkAnswerReviewItem) [ 1 .. 200 ] items

Responses

Request samples

Payload

Content type

application/json

{"reviews": [{"answer_id": 0,
"is_correct": true
}
]
}

Response samples

200
400
401
403
404

Content type

application/json

{"summary": {"total": 0,
"succeeded": 0,
"failed": 0
},
"items": [{"answer_id": 0,
"question_char": "string",
"ai_is_correct": true,
"reviewed_is_correct": true,
"is_correct": true,
"reviewed_by": "92ab4dbc-1b27-40ce-b24b-7dde8f4709be",
"reviewed_at": "2019-08-24T14:15:22Z",
"response_time": 0.1
}
]
}

テスト結果の取得

category=screening または posttest のセッションに紐づく test_result を取得。

認可:
- student: 自分の結果
- tannin: 自クラス
- shunin: 自学年
- school_admin: 自校

Authorizations:

cognitoAuth

path Parameters

sessionId

required

integer <int64>

セッション ID (letter_session_log.id)

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"session_id": 0,
"student_id": "8e4ec631-d04e-4769-bc05-342d3d37b815",
"enrollment_id": 0,
"test_type": "screening",
"correct_count": 0,
"total_count": 0,
"pending_count": 0,
"correct_rate": 0.1,
"ai_judgment": "normal",
"teacher_judgment": "normal",
"teacher_judgment_by": "9828032b-0743-40c5-8a73-1e0a1b844fb0",
"teacher_judgment_at": "2019-08-24T14:15:22Z",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}

テスト結果のレビュー (教員用)

教員によるレビュー結果 (teacher_judgment) を更新。

認可: tannin (自クラス) / shunin (自学年) / school_admin (自校) / system_admin
student は不可
サーバ側で teacher_judgment_by = actor.userId および teacher_judgment_at = NOW() を自動セット
teacher_judgment を null にすると、レビューを取り消し ("未レビュー" に戻す)

Authorizations:

cognitoAuth

path Parameters

sessionId

required

integer <int64>

セッション ID (letter_session_log.id)

Request Body schema: application/json
required

teacher_judgment

string or null

Enum: "normal" "watch" "support"

教員判定 (normal/watch/support)。null でレビュー取り消し

Responses

Request samples

Payload

Content type

application/json

{"teacher_judgment": "normal"
}

Response samples

200
401
403
404
500

Content type

application/json

{"session_id": 0,
"student_id": "8e4ec631-d04e-4769-bc05-342d3d37b815",
"enrollment_id": 0,
"test_type": "screening",
"correct_count": 0,
"total_count": 0,
"pending_count": 0,
"correct_rate": 0.1,
"ai_judgment": "normal",
"teacher_judgment": "normal",
"teacher_judgment_by": "9828032b-0743-40c5-8a73-1e0a1b844fb0",
"teacher_judgment_at": "2019-08-24T14:15:22Z",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}

LearningSessions

学習セッション

学習セッション開始

学習モード (category=learning) のセッションを開始する。

認可: student のみ (自分)
block_id を指定すると、アプリ側でそのブロックの問題を出題する

Authorizations:

cognitoAuth

Request Body schema: application/json
required

block_id	string 学習対象のブロック ID (単数指定の後方互換)。 `block_ids` が指定されている場合はそちらが優先される。
block_ids	Array of strings <= 20 items 学習対象のブロック ID 群 (混合練習で複数指定可)。セッションに保存され、終了時に各ブロックの習熟度を独立に更新する。空配列または省略時は「混合練習」扱いでブロック単位集計を行わない。
device_model	string

Responses

Request samples

Payload

Content type

application/json

{"block_id": "string",
"block_ids": ["string"
],
"device_model": "string"
}

Response samples

201
400
401
403
500

Content type

application/json

{"session_id": 0,
"category": "screening",
"started_at": "2019-08-24T14:15:22Z",
"student_id": "8e4ec631-d04e-4769-bc05-342d3d37b815",
"enrollment_id": 0,
"block_id": "string",
"block_ids": ["string"
]
}

学習セッションの取得

Authorizations:

cognitoAuth

path Parameters

sessionId

required

integer <int64>

セッション ID (letter_session_log.id)

Responses

Response samples

200
401
403
404

Content type

application/json

{"session_id": 0,
"category": "screening",
"student_id": "8e4ec631-d04e-4769-bc05-342d3d37b815",
"enrollment_id": 0,
"date": "2019-08-24",
"started_at": "2019-08-24T14:15:22Z",
"ended_at": "2019-08-24T14:15:22Z",
"duration_seconds": 0,
"is_finished": true,
"device_model": "string",
"max_volume_input": 0.1,
"button_mash_count": 0,
"errant_tap_count": 0
}

学習セッション中の 1 問の解答を記録

Authorizations:

cognitoAuth

path Parameters

sessionId

required

integer <int64>

セッション ID (letter_session_log.id)

Request Body schema: application/json
required

question_char required	string [ 1 .. 8 ] characters 出題された文字 (例 "あ")
recognized_text	string or null 認識結果 (音声認識テキスト等)
is_correct	boolean or null クライアント判定の正誤。 learning: クライアントが必ず true / false を送る screening / posttest: 省略 (or null) を許容。backend が finish 後にバッチ AI 判定で `letter_answer_log.is_correct` を埋める
response_time	number <float> >= 0 応答時間 (秒)
is_aborted	boolean Default: false 中断された解答か
client_timestamp required	string <date-time> クライアント側のタイムスタンプ (ISO 8601)
audio_upload_required	boolean Default: false true の場合、レスポンスに audio_upload (Pre-signed URL) を含める。クライアントはその URL に対して PUT で音声ファイル (wav) をアップロードする。

Responses

Request samples

Payload

Content type

application/json

{"question_char": "string",
"recognized_text": "string",
"is_correct": true,
"response_time": 0.1,
"is_aborted": false,
"client_timestamp": "2019-08-24T14:15:22Z",
"audio_upload_required": false
}

Response samples

Content type

application/json

{"answer_id": 0,
"recorded_at": "2019-08-24T14:15:22Z",
"audio_upload": {"s3_key": "string",
"presigned_url": "http://example.com",
"expires_at": "2019-08-24T14:15:22Z"
}
}

学習セッションの終了 + 集計

セッションを終了し、習熟度関連テーブルを更新する。

letter_session_log の終了時刻と duration を更新
letter_character_stat (文字単位習熟度) を更新
letter_block_stat (ブロック単位習熟度) を更新 (block_id 指定時のみ)
letter_daily_record (日次集計) を更新
student_status は更新しない (login 時に別途更新する)
letter_test_result は作らない (learning は評価系ではない)

Authorizations:

cognitoAuth

path Parameters

sessionId

required

integer <int64>

セッション ID (letter_session_log.id)

Request Body schema: application/json
required

ended_at required	string <date-time> クライアント側の終了時刻
max_volume_input	number <float> [ 0 .. 1 ]
button_mash_count	integer >= 0
errant_tap_count	integer >= 0

Responses

Request samples

Payload

Content type

application/json

{"ended_at": "2019-08-24T14:15:22Z",
"max_volume_input": 1,
"button_mash_count": 0,
"errant_tap_count": 0
}

Response samples

200
401
403
404
409

Content type

application/json

{"session_id": 0,
"category": "learning",
"started_at": "2019-08-24T14:15:22Z",
"ended_at": "2019-08-24T14:15:22Z",
"duration_seconds": 0,
"summary": {"total_count": 0,
"correct_count": 0,
"incorrect_count": 0,
"pending_count": 0,
"correct_rate": 1,
"average_response_time": 0.1,
"max_response_time": 0.1,
"min_response_time": 0.1
},
"block_progress": {"block_id": "string",
"previous_clear_count": 0,
"new_clear_count": 0,
"previous_mastery_rate": 0.1,
"new_mastery_rate": 0.1,
"is_block_cleared": true
},
"block_progresses": [{"block_id": "string",
"previous_clear_count": 0,
"new_clear_count": 0,
"previous_mastery_rate": 0.1,
"new_mastery_rate": 0.1,
"is_block_cleared": true
}
],
"character_breakdown": [{"char_id": "string",
"correct": true,
"response_time": 0.1,
"previous_status": 0,
"new_status": 0,
"previous_correct_count": 0,
"new_correct_count": 0
}
]
}

学習セッションの音声 URL 一覧

audio_s3_key が NULL の answer は items に含まれない
認可:
- student: 自分の結果
- tannin: 自クラス
- shunin: 自学年
- school_admin: 自校

Authorizations:

cognitoAuth

path Parameters

sessionId

required

integer <int64>

セッション ID (letter_session_log.id)

Responses

Response samples

200
401
403
404

Content type

application/json

{"items": [{"answer_id": 0,
"question_char": "string",
"audio_url": "http://example.com",
"expires_at": "2019-08-24T14:15:22Z"
}
]
}

学習セッションの個別 answer 音声 URL

Authorizations:

cognitoAuth

path Parameters

sessionId required	integer <int64> セッション ID (letter_session_log.id)
answerId required	integer <int64> 解答 ID (letter_answer_log.id)

Responses

Response samples

200
401
403
404

Content type

application/json

{"audio_url": "http://example.com",
"expires_at": "2019-08-24T14:15:22Z",
"s3_key": "string"
}

学習セッションの個別 answer の教員レビュー

認可: 教員 (tannin / shunin / school_admin / system_admin)
学習セッションでも教員が誤判定を訂正したいケースに対応

Authorizations:

cognitoAuth

path Parameters

sessionId required	integer <int64> セッション ID (letter_session_log.id)
answerId required	integer <int64> 解答 ID (letter_answer_log.id)

Request Body schema: application/json
required

is_correct

required

boolean or null

教員判定の正誤。

true / false: 教員レビュー設定
null: 教員レビューを取り消し (AI 判定に戻す)

Responses

Request samples

Payload

Content type

application/json

{"is_correct": true
}

Response samples

200
400
401
403
404

Content type

application/json

{"answer_id": 0,
"question_char": "string",
"ai_is_correct": true,
"reviewed_is_correct": true,
"is_correct": true,
"reviewed_by": "92ab4dbc-1b27-40ce-b24b-7dde8f4709be",
"reviewed_at": "2019-08-24T14:15:22Z",
"response_time": 0.1
}

学習セッションの answer の教員レビューを一括更新

Authorizations:

cognitoAuth

path Parameters

sessionId

required

integer <int64>

セッション ID (letter_session_log.id)

Request Body schema: application/json
required

required

Array of objects (BulkAnswerReviewItem) [ 1 .. 200 ] items

Responses

Request samples

Payload

Content type

application/json

{"reviews": [{"answer_id": 0,
"is_correct": true
}
]
}

Response samples

200

Content type

application/json

{"summary": {"total": 0,
"succeeded": 0,
"failed": 0
},
"items": [{"answer_id": 0,
"question_char": "string",
"ai_is_correct": true,
"reviewed_is_correct": true,
"is_correct": true,
"reviewed_by": "92ab4dbc-1b27-40ce-b24b-7dde8f4709be",
"reviewed_at": "2019-08-24T14:15:22Z",
"response_time": 0.1
}
]
}

Stats

学習統計・履歴

テスト結果の横断一覧

学校・クラス・生徒の枠を横断してテスト結果を取得する API。教員ダッシュボードの「結果一覧」「レビューワークフロー」で使用。

スコープ (自動決定):

system_admin: 全校 (任意のクエリパラで絞り込み)
school_admin: 自校
shunin: 自学年
tannin: 自クラス
student: 自分

フィルタの組み合わせで「未レビューのみ」「support 判定のみ」など柔軟な絞り込みが可能。

Authorizations:

cognitoAuth

query Parameters

school_id	string system_admin / school_admin の絞り込み用
class_id	integer <int64>
student_id	string <uuid>
test_type	string (TestType) Enum: "screening" "posttest"
ai_judgment	string Enum: "normal" "support" "null" AI 判定で絞り込み: `normal` / `support`: その値で絞り込み `null`: AI 判定が NULL (未算出) のもの
teacher_judgment	string Enum: "normal" "watch" "support" "null" 教員判定で絞り込み: `normal` / `watch` / `support`: その値で絞り込み `null`: 教員未レビュー (UI の「未確認」相当)
review_required	boolean true の場合、AI 判定 = 'support' かつ教員判定 = NULL のものだけ返す。教員レビュー画面の「要レビューだけ見る」絞り込みに対応する。 `ai_judgment` / `teacher_judgment` パラメータと併用された場合は AND 結合。
from	string <date> 受験日の下限 (含む)
to	string <date> 受験日の上限 (含む)
limit	integer [ 1 .. 200 ] Default: 50 取得件数
cursor	string ページネーション用カーソル (前回レスポンスの `next_cursor`)

Responses

Response samples

200
401
403

Content type

application/json

{"next_cursor": "string",
"items": [{"session_id": 0,
"student": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"family_name": "string",
"given_name": "string",
"class_id": 0,
"student_no": 0
},
"test_type": "screening",
"test_date": "2019-08-24",
"ai_judgment": "normal",
"teacher_judgment": "normal",
"teacher_judgment_at": "2019-08-24T14:15:22Z",
"correct_count": 0,
"total_count": 0,
"correct_rate": 0.1
}
],
"summary": {"total": 0,
"ai_support_count": 0,
"teacher_reviewed_count": 0,
"teacher_support_count": 0,
"teacher_watch_count": 0,
"teacher_unreviewed_count": 0,
"teacher_review_required_count": 0,
"latest_normal_count": 0,
"latest_watch_count": 0,
"latest_support_count": 0
}
}

生徒のセッション履歴 (全 category 横断)

Authorizations:

cognitoAuth

path Parameters

studentId

required

string <uuid>

生徒 ID (UUID v7)

query Parameters

category	string Enum: "screening" "learning" "posttest"
from	string <date> 開始日 (含む)
to	string <date> 終了日 (含む)
limit	integer [ 1 .. 200 ] Default: 50 取得件数
cursor	string ページネーション用カーソル (前回レスポンスの `next_cursor`)

Responses

Response samples

200
401
403

Content type

application/json

{"next_cursor": "string",
"items": [{"session_id": 0,
"category": "screening",
"date": "2019-08-24",
"started_at": "2019-08-24T14:15:22Z",
"ended_at": "2019-08-24T14:15:22Z",
"duration_seconds": 0,
"is_finished": true,
"answer_count": 0,
"correct_count": 0,
"correct_rate": 0.1,
"ai_judgment": "normal",
"teacher_judgment": "normal"
}
]
}

文字単位の習熟度

Authorizations:

cognitoAuth

path Parameters

studentId

required

string <uuid>

生徒 ID (UUID v7)

query Parameters

status	integer >= 0 status で絞り込み
limit	integer [ 1 .. 200 ] Default: 50 取得件数
cursor	string ページネーション用カーソル (前回レスポンスの `next_cursor`)

Responses

Response samples

200
401
403

Content type

application/json

{"next_cursor": "string",
"items": [{"char_id": "string",
"correct_count": 0,
"incorrect_count": 0,
"accumulated_fast_correct_count": 0,
"mastery_count": 0,
"status": 0,
"average_response_time": 0.1,
"last_3_response_times": [0.1
],
"last_5_results": [true
],
"updated_at": "2019-08-24T14:15:22Z"
}
]
}

ブロック単位の習熟度

Authorizations:

cognitoAuth

path Parameters

studentId

required

string <uuid>

生徒 ID (UUID v7)

query Parameters

limit	integer [ 1 .. 200 ] Default: 50 取得件数
cursor	string ページネーション用カーソル (前回レスポンスの `next_cursor`)

Responses

Response samples

200
401
403

Content type

application/json

{"next_cursor": "string",
"items": [{"block_id": "string",
"clear_count": 0,
"mastery_rate": 1,
"updated_at": "2019-08-24T14:15:22Z"
}
]
}

日次集計の取得

生徒の learning セッションの日次集計を返す。 screening / posttest はここには含まれない (test_result API で取得)。

Authorizations:

cognitoAuth

path Parameters

studentId

required

string <uuid>

生徒 ID (UUID v7)

query Parameters

from	string <date>
to	string <date>
limit	integer [ 1 .. 200 ] Default: 50 取得件数

Responses

Response samples

200
401
403

Content type

application/json

{"items": [{"date": "2019-08-24",
"answer_count": 0,
"total_play_duration": 0.1
}
]
}

生徒の学習状況 (ストリーク等)

Authorizations:

cognitoAuth

path Parameters

studentId

required

string <uuid>

生徒 ID (UUID v7)

Responses

Response samples

200
401
403
404

Content type

application/json

{"student_id": "8e4ec631-d04e-4769-bc05-342d3d37b815",
"last_login_date": "2019-08-24",
"login_streak": 0,
"completed_dyslexia_learning_tutorial": true,
"completed_dyslexia_screening_tutorial": true,
"updated_at": "2019-08-24T14:15:22Z"
}

生徒の学習状況を更新

チュートリアル完了フラグを更新する。 last_login_date / login_streak は POST /me/login で更新されるためこの API では変更できない。

認可: 本人 (student として自分の studentId を指定) または system_admin
教員ロール (school_admin / shunin / tannin) からは 403 を返す (チュートリアル進捗は個人状態)
student_status 行が存在しない場合は INSERT (フィールド未指定は false 初期値)、存在する場合は UPDATE

Authorizations:

cognitoAuth

path Parameters

studentId

required

string <uuid>

生徒 ID (UUID v7)

Request Body schema: application/json
required

completed_dyslexia_learning_tutorial	boolean
completed_dyslexia_screening_tutorial	boolean

Responses

Request samples

Payload

Content type

application/json

{"completed_dyslexia_learning_tutorial": true,
"completed_dyslexia_screening_tutorial": true
}

Response samples

200
400
401
403
404

Content type

application/json

{"student_id": "8e4ec631-d04e-4769-bc05-342d3d37b815",
"last_login_date": "2019-08-24",
"login_streak": 0,
"completed_dyslexia_learning_tutorial": true,
"completed_dyslexia_screening_tutorial": true,
"updated_at": "2019-08-24T14:15:22Z"
}

Admin

システム管理者 (system_admin) 専用

全体メトリクスの取得

サービス全体の利用状況メトリクスを返す。

認可: system_admin のみ
全学校横断の集計
動的クエリで算出

Authorizations:

cognitoAuth

Responses

Response samples

200
401
403

Content type

application/json

{"schools": {"total": 0,
"active_last_7_days": 0
},
"users": {"students_total": 0,
"teachers_total": 0,
"students_active_last_7_days": 0
},
"sessions": {"total_last_7_days": 0,
"screening_last_7_days": 0,
"learning_last_7_days": 0,
"posttest_last_7_days": 0
},
"alerts": {"ai_support_total_last_30_days": 0,
"teacher_support_unreviewed": 0
},
"email": {"sent_last_24h": 0,
"delivered_rate": 0.1,
"bounce_rate": 0.1,
"complaint_rate": 0.1,
"suppression_count": 0
}
}

全学校の suppression 一覧

全学校横断で email_suppression を取得する。

認可: system_admin のみ
各エントリには「どの学校・どのユーザーの email か」を含む (内部 JOIN)
学校に紐付かない email (例: 既に削除されたユーザーや、自前管理対象外) は含まれない

Authorizations:

cognitoAuth

query Parameters

school_id	string 学校で絞り込み
reason	string Enum: "hard_bounce" "complaint" "manual"
user_type	string Enum: "student" "teacher"
limit	integer [ 1 .. 200 ] Default: 50 取得件数
cursor	string ページネーション用カーソル (前回レスポンスの `next_cursor`)

Responses

Response samples

200
401
403

Content type

application/json

{"next_cursor": "string",
"items": [{"email": "user@example.com",
"school_id": "string",
"school_name": "string",
"user_type": "student",
"user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
"user": {"family_name": "string",
"given_name": "string"
},
"reason": "hard_bounce",
"bounce_subtype": "string",
"suppressed_at": "2019-08-24T14:15:22Z"
}
]
}

操作監査ログの取得 (Phase 2)

システムへの操作監査ログを返す。

認可: system_admin のみ
MVP では suppression_action_log のみを対象 (学校作成や生徒登録などは将来対象に追加)
将来は汎用 audit_log テーブルに統合する想定

Authorizations:

cognitoAuth

query Parameters

action_type	string Enum: "suppression_added" "suppression_removed" 操作種別で絞り込み
performed_by	string <uuid> 操作者で絞り込み
from	string <date-time>
to	string <date-time>
limit	integer [ 1 .. 200 ] Default: 50 取得件数
cursor	string ページネーション用カーソル (前回レスポンスの `next_cursor`)

Responses

Response samples

200
401
403

Content type

application/json

{"next_cursor": "string",
"items": [{"id": 0,
"action_type": "suppression_added",
"target_email": "user@example.com",
"performed_by": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"family_name": "string",
"given_name": "string"
},
"performed_at": "2019-08-24T14:15:22Z",
"notes": "string"
}
]
}

学習アプリ API (0.1.0)

認証

ロールと認可

エラーレスポンス

ページネーション

Self

認証ユーザー自身の情報を取得

Authorizations:

Responses

Response samples

ログイン記録 (student_status 更新)

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Dashboard

教員ダッシュボードの要対応アラート

Authorizations:

query Parameters

Responses

Response samples

教員ダッシュボードの概況サマリ

Authorizations:

query Parameters

Responses

Response samples

最近の活動一覧 (時系列)

Authorizations:

query Parameters

Responses

Response samples

Schools

学校を作成

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

学校一覧を取得

Authorizations:

query Parameters

Responses

Response samples

学校の個別取得

Authorizations:

path Parameters

Responses

Response samples

学校情報の更新

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Classes

クラスの一括作成

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

クラスの規則的生成

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

クラス一覧の取得

Authorizations:

path Parameters

query Parameters

Responses

Response samples

クラス集計の取得

Authorizations:

path Parameters

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required