Appearance
API 設計（ドラフト）
ステータス: ドラフト（2026-04-15 起案） 対象: Next.js Route Handlers による REST ライクなエンドポイント。M1 ではモック応答のみ。関連: data-model.md / auth-rbac.md（策定予定） 注意: 本書はインターフェース契約の叩き台。実装・認証トークン仕様・レート制限は別 ADR で確定。
1. 規約
- ベース URL:
/api/v1 - 認証: Bearer トークン（NextAuth セッション、M1 はモック）
- ロール認可は auth-rbac.md に従う（HTTP 403 を返す）
- 時刻は ISO 8601 / UTC
- エラー形式：
{ "error": { "code": "...", "message": "...", "details": {...} } }
1.0 認可スコープ（共通原則）
すべての /admin, /org, /employer, /governance, /learner エンドポイントに以下を強制適用する。サーバ側で自動的にフィルタされ、リクエスト側でスコープ外 ID を指定した場合は 403 を返す。
| ロール | スコープ | 禁止事項 |
|---|---|---|
| LR（学習者） | user_id == self | 他人のデータ取得は 403 |
| TA（講師） | organization_id ∈ 自組織 かつ learner ∈ 担当クラス | 他組織・非担当学習者は 403 |
| OA（組織管理者） | organization_id ∈ 自組織 | 他組織は 403 |
| TM（研修責任者） | 引継ぎ受理済み学習者のみ | 引継ぎ前学習者は 403 |
| EM（企業採用） | DisclosurePolicy.visible=true かつ契約済み組織の候補者のみ・要約系エンドポイントのみ | 生ログ系・他組織候補者は 403 |
| SA（送出し機関Mgr） | 自機関配下のコホート | 他機関は 403 |
| SU（運用） | 匿名化済みエンドポイントのみ | 個別特定系は 403 |
越境禁止の原則: すべての :id（learnerId, attemptId, candidateId 等）は必ずテナント／担当スコープチェックを通し、スコープ外への遷移は 404 ではなく 403（存在の秘匿方針は §1.0b で定義）を返す。
1.0b 存在秘匿
権限外リソースに対して、存在を推定させないため、以下ルールを採用：
- LR が他人の
user_id指定：404（存在を秘匿） - TA / OA 等 組織境界越え：403（境界越え違反の可視化を優先）
- EM が非公開候補者：404
1.1 主要ステータスコード
| コード | 用途 |
|---|---|
| 200 | 成功 |
| 201 | 作成成功 |
| 204 | 成功（ボディなし） |
| 400 | 入力不正（details に Zod エラー） |
| 401 | 未認証 |
| 403 | 権限不足 |
| 404 | 不在 |
| 409 | 競合（同時更新等） |
| 422 | 業務ルール違反 |
| 429 | レート制限 |
| 500 | サーバエラー |
1.2 ページング
- クエリ:
?cursor=<opaque>&limit=<int, max 100> - 応答:
{ "items": [...], "nextCursor": "..." | null }
2. 認証・同意
| メソッド | パス | 概要 | 認可 |
|---|---|---|---|
| POST | /auth/login | ログイン（メール＋パスワード） | 公開 |
| POST | /auth/logout | ログアウト | 認証済 |
| POST | /auth/reset/request | パスワードリセット要求 | 公開 |
| POST | /auth/reset/confirm | リセット確定 | 公開 |
| GET | /me | 自プロフィール取得 | 認証済 |
| PATCH | /me | プロフィール更新 | 認証済 |
| GET | /me/consents | 同意履歴 | 認証済 |
| POST | /me/consents | 同意付与 | 認証済 |
| POST | /me/consents/withdraw | 同意撤回 | 認証済 |
| POST | /me/delete-request | 削除請求 | 認証済 |
3. 学習者向け（LR）
| メソッド | パス | 概要 |
|---|---|---|
| GET | /learner/today | 今日のタスク一覧 |
| GET | /learner/vocab-sets | 担当単語セット一覧 |
| GET | /learner/vocab-sets/:id | 単語リスト |
| POST | /learner/vocab-sets/:id/progress | 単語習得状態を更新 |
| POST | /learner/quizzes/:id/attempts | クイズ開始（QuizAttempt 生成） |
| POST | /learner/quiz-attempts/:attemptId/answers | 回答送信 |
| POST | /learner/quiz-attempts/:attemptId/submit | 提出 |
| GET | /learner/videos | 動画一覧 |
| POST | /learner/videos/:id/watch-events | 視聴イベント送信（区間・完了） |
| GET | /learner/progress | 自分の進捗サマリー |
| GET | /learner/credibility | 自分の一貫性スコア |
| POST | /learner/appeals | 異議申立を作成 |
4. 講師（TA）
| メソッド | パス | 概要 |
|---|---|---|
| GET | /admin/learners | 学習者一覧（フィルタ・検索） |
| GET | /admin/learners/:id | 学習者詳細 |
| GET | /admin/learners/:id/progress | 進捗データ |
| GET | /admin/learners/:id/vocab-stats | 単語習得率 |
| GET | /admin/learners/:id/credibility | 一貫性ビュー（OA 有効時のみ） |
| GET | /admin/learners/:id/exams | テスト成績 |
| POST | /admin/learners/:id/notes | 面談メモ作成 |
| GET | /admin/curricula | カリキュラム一覧 |
| POST | /admin/curricula | カリキュラム作成 |
| PATCH | /admin/curricula/:id | 更新 |
| POST | /admin/exams | テスト作成 |
| POST | /admin/exams/:id/results | 成績記録（個別・一括） |
| POST | /admin/messages | 学習者へメッセージ送信 |
| POST | /admin/exports | CSV／PDF エクスポート |
5. 組織管理者（OA）ガバナンス
| メソッド | パス | 概要 |
|---|---|---|
| GET | /governance/audit-logs | 監査ログ検索 |
| GET | /governance/consents | 同意状況一覧 |
| POST | /governance/consents/:id/revoke | 同意撤回の受理・実行 |
| GET | /governance/appeals | 異議申立一覧 |
| PATCH | /governance/appeals/:id | 判定・対応 |
| GET | /governance/roles | ロール付与状況 |
| POST | /governance/roles | ロール付与 |
| DELETE | /governance/roles/:id | ロール剥奪 |
| PATCH | /governance/settings | 一貫性ビューの有効／開示範囲 |
6. 企業採用（EM）
| メソッド | パス | 概要 |
|---|---|---|
| GET | /employer/candidates | 公開同意済み候補者一覧 |
| GET | /employer/candidates/:id | 候補者レポート（要約） |
| GET | /employer/candidates/compare | 複数候補者比較 |
| POST | /employer/candidates/:id/favorite | お気に入り登録 |
| POST | /employer/candidates/:id/pdf | PDF 生成 |
7. 送出し機関（SA）
| メソッド | パス | 概要 |
|---|---|---|
| GET | /org/cohorts | クラス・期別一覧 |
| GET | /org/reports | レポート一覧 |
| POST | /org/reports | レポート生成 |
| PATCH | /org/disclosure/:userId | 学習者の公開可否切替（学習者同意前提） |
8. 運用（SU）
| メソッド | パス | 概要 |
|---|---|---|
| GET | /ops/health | ヘルスチェック |
| GET | /ops/metrics | 匿名化済みメトリクス |
| GET | /ops/audit-logs | 運用監査（匿名化済み） |
9. レート制限（暫定）
- 一般 API: 60 req/min/user
- /auth/login: 10 req/min/IP
- 動画 watch-events: 240 req/min/user（視聴中高頻度送信）
10. 未確定事項
- OpenAPI スキーマ自動生成（
@asteasolutions/zod-to-openapi等）の採否 - Webhook 必要性（外部連携）
- バッチ系エンドポイント（大量データインポート）
11. 改訂履歴
- 2026-04-15: 初版ドラフト作成