Skip to content

Latest commit

 

History

History
747 lines (613 loc) · 74.6 KB

architecture.md

File metadata and controls

747 lines (613 loc) · 74.6 KB

システム構成

全体アーキテクチャ

graph TB
    subgraph Browser["ブラウザ (Smalruby Editor)"]
        GUI["scratch-gui<br/>React / Redux"]
        API_CLIENT["classroom-api.js<br/>API クライアント"]
        TEACHER_AUTH["teacher-auth.js<br/>認証抽象化 (Google / Microsoft)"]
        GC_AUTH["google-classroom-auth.js<br/>Google Classroom OAuth"]
    end

    subgraph AWS["AWS (ap-northeast-1)"]
        APIGW["API Gateway HTTP API"]
        LAMBDA["Lambda (Node.js 20)"]
        DDB_C["DynamoDB<br/>Classrooms"]
        DDB_M["DynamoDB<br/>ClassroomMemberships"]
        DDB_S["DynamoDB<br/>ClassroomSubmissions"]
        S3["S3<br/>提出ファイル"]
    end

    subgraph GCP["Google Cloud Platform"]
        GAUTH["Google OAuth 2.0<br/>(ID Token 検証)"]
        GC_API["Google Classroom API"]
    end

    subgraph Azure["Microsoft Azure"]
        MSAUTH["Microsoft Identity Platform<br/>(ID Token 検証)"]
    end

    GUI --> API_CLIENT
    GUI --> TEACHER_AUTH
    GUI --> GC_AUTH
    API_CLIENT -->|"HTTPS"| APIGW
    TEACHER_AUTH -->|"Google ログイン"| GAUTH
    TEACHER_AUTH -->|"Microsoft ログイン"| MSAUTH
    GC_AUTH -->|"OAuth 同意"| GAUTH
    APIGW --> LAMBDA
    LAMBDA --> DDB_C
    LAMBDA --> DDB_M
    LAMBDA --> DDB_S
    LAMBDA -->|"Presigned URL 生成"| S3
    LAMBDA -->|"Google ID Token 検証"| GAUTH
    LAMBDA -->|"Microsoft ID Token 検証 (JWKS)"| MSAUTH
    LAMBDA -->|"コース取得 / 課題投稿"| GC_API
    Browser -->|"Presigned URL で直接アップロード"| S3
Loading

認証フロー

sequenceDiagram
    participant T as 先生 (ブラウザ)
    participant S as 生徒 (ブラウザ)
    participant API as Lambda
    participant G as Google OAuth
    participant MS as Microsoft Identity
    participant DB as DynamoDB

    Note over T,G: 先生の認証 (Google or Microsoft)
    alt Google ログイン
        T->>G: Google ログイン
        G-->>T: ID Token (iss: accounts.google.com)
    else Microsoft ログイン
        T->>MS: MSAL popup ログイン
        MS-->>T: ID Token (iss: login.microsoftonline.com)
    end
    T->>API: Authorization: Bearer {idToken}
    API->>API: iss クレームで Google / Microsoft を自動判別
    alt Google
        API->>G: verifyIdToken(idToken)
        G-->>API: { sub: "teacher-google-id" }
    else Microsoft
        API->>MS: JWKS で JWT 検証
        MS-->>API: { oid: "teacher-microsoft-id" }
    end
    API->>DB: teacherSub で操作

    Note over S,DB: 生徒の認証 (Session Token)
    S->>API: POST /classrooms/join {joinCode, seatNumber}
    API->>DB: 席番号チェック & メンバー登録
    DB-->>API: OK
    API-->>S: {sessionToken: "uuid-..."}
    S->>API: Authorization: Bearer {sessionToken}
    API->>DB: sessionToken-index で検索
    DB-->>API: メンバー情報

    Note over T,MS: サイレント再認証 (トークン期限切れ時)
    T->>T: 30秒ごとの自動リフレッシュで 401 検出
    alt Google
        T->>G: google.accounts.id.prompt({auto_select: true})
        G-->>T: 新しい ID Token (サイレント)
    else Microsoft
        T->>MS: acquireTokenSilent({forceRefresh: true})
        MS-->>T: 新しい ID Token (サイレント)
    end
    T->>API: 新トークンで再試行
    Note over T: 再認証失敗時は Alert バナーを表示
Loading

先生セッション管理

項目 内容
認証方式 Google ID Token (JWT) または Microsoft ID Token (JWT)
有効期限 1時間(Google / Microsoft 共通)。stg は ID_TOKEN_MAX_AGE_SECONDS で短縮可
サイレント再認証 Google: auto_select: true(FedCM 10分制限あり)、Microsoft: acquireTokenSilent({ forceRefresh: true })
再認証失敗時 Alert バナー「セッションが無効になりました。」+ 「参加しなおす」ボタン
自動リフレッシュ 30秒ごとにメンバー情報を更新(refreshMembersOnly、詳細パネルの状態は保持)

Google サインイン UI の置き場所

One Tap が表示できない環境(Windows や Playwright では毎回)では、GIS が描画する 「Google でログイン」ボタンを使う。このボタンは モーダル内のスロット (components/google-sign-in-slot/、教師ログイン画面と不具合報告モーダルに配置)へ 描画する。React の外(document.body 直下の固定オーバーレイ)に描画すると、 ログインを中断してもカードが画面中央に残り、ログインを開始するたびに増えていく。

  • 進行中のログインは常に 1 つだけ(loginWithGoogle は開始時に前回を中止する)。
  • スロットのアンマウント(モーダルを閉じる / フェーズ移動)、Microsoft ログインへの 切り替え、ログイン完了・失敗のいずれでも cancelGoogleLogin() が走り、ボタン削除・ One Tap の cancel()・Promise の settle をまとめて行う。
  • 表示判定に FedCM 必須化で機能しなくなる isNotDisplayed() / isSkippedMoment() / isDisplayMoment() を使わない(use_fedcm_for_prompt: true。サイレント再認証は dismiss とタイムアウトのみで失敗を判定する)。

生徒セッション管理

項目 内容
認証方式 Session Token (UUID)、DynamoDB に保存
有効期限 90日(stg は 1日)。verify-session ごとに TTL を延長
セッション期限切れ時 Alert バナー + 「参加しなおす」ボタンで参加コード入力画面に戻る

AWS サービス

サービス リソース名 用途
API Gateway ClassroomApi-{stage} HTTP API エンドポイント
Lambda ClassroomHandler-{stage} ビジネスロジック (Node.js 22, 256MB, 30秒)
Lambda ClassroomArchiver-{stage} DynamoDB Streams の REMOVE を S3 へスナップショット(下記「削除スナップショットと長期保持」)
DynamoDB Classrooms-{stage} 課題(1 授業)情報(Streams: OLD_IMAGE)
DynamoDB ClassroomMemberships-{stage} メンバー (生徒) 情報(Streams: OLD_IMAGE)
DynamoDB ClassroomSubmissions-{stage} 提出情報(Streams: OLD_IMAGE)
DynamoDB ClassroomGroups-{stage} クラス(学級)情報(Streams: OLD_IMAGE)
DynamoDB ClassroomLessonProgress-{stage} レッスンの進み具合(席 × 課題で 1 件・TTL は課題を写す・Streams: OLD_IMAGE)
DynamoDB SharedAssignments-{stage} みんなの課題(TTL なし・prod RETAIN + PITR)
DynamoDB SharedAssignmentReports-{stage} みんなの課題の通報(TTL 90日)
DynamoDB ClassroomNotifications-{stage} お知らせ(EPIC #1111。TTL は書き手の admin スタックが付与・既定 180 日)
S3 smalruby-shared-assignments-{stage} 共有課題のスナップショット(lifecycle なし = 永続・prod RETAIN)
S3 smalruby-classroom-submissions-{stage} 提出ファイル (.sb3, サムネイル, スクリーンショット) + ddb-archive/ スナップショット。lifecycle = ARCHIVE_RETENTION_DAYS(既定 365 日)
Route53 A レコード カスタムドメイン
ACM SSL 証明書 HTTPS
CloudWatch Logs /aws/lambda/ClassroomHandler-{stage} / /aws/lambda/ClassroomArchiver-{stage} ログ (stg: 1週間, prod: 1ヶ月)

カスタムドメイン

Stage ドメイン
stg stg.classroom.api.smalruby.app
prod classroom.api.smalruby.app

GCP サービス

サービス 用途
Google OAuth 2.0 先生のログイン (ID Token 発行・検証)
Google Classroom API コース一覧取得、生徒数取得、課題投稿

Google Classroom API スコープ

スコープ 用途
classroom.courses.readonly コース一覧の取得
classroom.rosters.readonly 生徒名簿の取得 (人数カウントのみ)
classroom.coursework.students 課題の作成・投稿

API ルート

先生用 (Google ID Token 認証)

Method Path 説明
POST /classrooms 課題作成。任意の meshGroupLimit(6 / 0・Issue #1255)でメッシュのグループの人数の上限を設定する(0 = 制限なし。送らなくても 6 を必ず保存する。それ以外の値は 400)。レスポンスに meshGroupLimit を含む
GET /classrooms 課題一覧(既定は active のみ。?includeArchived=1 でアーカイブ済みも返す。各要素に status と meshGroupLimit(未設定は 0 = 制限なし)、archivedAt(アーカイブした日時。active は null、日時を持たない古いアーカイブ済み課題は updatedAt)を含む。任意の unreturnedCount = 返却していない提出の数。下の「返却していない提出の数」参照)
GET /classrooms/{id} 課題詳細(archivedAt(active なので常に null)と meshGroupLimit を含む。未設定は 0 = 制限なし)
PATCH /classrooms/{id} 課題更新。{status: 'active'} でアーカイブ済み課題の復元も行う。任意の meshGroupLimit(6 / 0)を受け付ける(送らなければ保存済みの値を変えない。それ以外の値は 400)。レスポンスに meshGroupLimit と archivedAt を含む。archived にすると archivedAt を記録し、active に戻すと消す
DELETE /classrooms/{id} 課題削除 (アーカイブ)。archivedAt を記録する。soft-delete でメンバー・提出メタ・S3 は保持され、PATCH で復元可能。生徒の遮断は status ガード(join / lookup / verify-session / 提出がすべて非 active を拒否)
GET /classrooms/{id}/co-teachers 共同管理者一覧 ({ownerSub, coTeacherEmails})
POST /classrooms/{id}/co-teachers 共同管理者を email で招待 ({email})。冪等・最大10・email 形式検証
DELETE /classrooms/{id}/co-teachers/{email} 共同管理者を解除
GET /classrooms/{id}/members メンバー一覧 (kicked 行は除外)。各メンバーに任意の aiUsage(ルビティーの上限と今日の回数。下記)
DELETE /classrooms/{id}/members/{memberId} メンバー削除 = ソフト kick (1h tombstone を残し、kicked: true をマーク)。verify-session が 410 reason='kicked' を返せるようにするための仕様。席が別の生徒に使われても 410 を返せるよう、kick marker の行も書く(下記)。lookup の takenSeats も即座に空く
GET /classrooms/{id}/kick-requests 退室リクエスト一覧 (Issue #692)
POST /classrooms/{id}/kick-requests/{requestId}/approve 承認 = handleDeleteMember (= kick) + 同席への全リクエスト削除
DELETE /classrooms/{id}/kick-requests/{requestId} 却下 = リクエストのみ削除、メンバーは残る
GET /kick-requests/pending 先生に見える課題(GET /classrooms と同じ範囲)をまたいだ未処理の退室依頼。?since=<ISO> でそれ以降に作られた依頼だけ。各要素は requestId, classroomId, className, assignmentName, groupId, seatNumber, reason, occupantName, createdAt、ほかに activeAssignmentCount。下の「退室依頼の先生への通知」参照
GET /classrooms/{id}/submissions 提出一覧 (ダウンロード URL 付き)。各提出に screenshotLabels(スプライト名の配列。無い古い提出は null)と hiddenFromPeers(既定 false・Issue #1239)を含む
PATCH /classrooms/{id}/submissions/{subId} 提出の返却・コメント。任意の hiddenFromPeers(boolean・Issue #1239)で、その提出を他者参照で「他の生徒に見せない」に切り替える
PUT /classrooms/{id}/assignment 課題コンテンツの設定・更新(ページ + スターター。画像/スターターの Presigned upload URL を返す。空 body で削除)。任意の startFromPrevious(boolean・Issue #1202)で「前回の提出物から始めさせる」を設定する(GUI はもう送らない。送らなければ保存済みの値を変えない。課題コンテンツを空にしても設定は残る)。任意の peerView(none / always / afterSubmit・Issue #1239)で他者参照を設定する(扱いは startFromPrevious と同じ)。レスポンスに startFromPrevious と peerView を含む。任意の lesson(下記「レッスンの設定」・EPIC #1592)でレッスンを紐付ける(送らなければ保存済みの値を変えない・null で外す・課題コンテンツを空にしても残る。不正な値は 400)。レスポンスに lesson(無ければ null)を含む
PATCH /classrooms/{id}/assignment/lesson-scoring レッスンの点(lesson.scoring)だけを更新する。本文は {scoring}(形と検証は下記「レッスンの設定」の scoring と同じ・null で既定の「点の設定なし」に戻す・scoring を送らない本文は 400)。書くのは lesson.scoring と課題の updatedAt だけで、ページ・画像・開始プロジェクト・lesson のほかの項目・課題の設定には触らない(PUT /assignment と違い、参照されなくなった画像・スターターの後片付けもしない。採点の画面が保存の直前に読んだ pages を送り返さずに済む)。認可は PUT /assignment と同じ(所有者か共同管理者・ほかは 401、無い・非 active は 404)。lesson の無い課題は 400(読んだあとで lesson が外されたときも条件付き更新で 400)。レスポンスは {lesson}(更新後の設定)
POST /classroom-groups クラス(学級)の作成(name, year, 任意で studentCount / googleClassroomCourseId)
GET /classroom-groups 自分のクラス一覧(active + archived、共同管理分は role=co-teacher で合流)。各要素に生成AI・ルビティーの設定 genai / rubytee(下記「クラス単位の AI 設定」。未設定は両方無効)を含む
PATCH /classroom-groups/{groupId} クラスのリネーム・年度変更・人数・GC 紐づけ・共同管理者・アーカイブ/復帰・生成AI / ルビティーの設定(genai / rubytee。送った項目だけ保存済みの値に重ねる部分更新。条件を満たさない値は 400)
POST /classroom-groups/migrate v1→v2 冪等 bulk migration(未所属課題のクラス自動作成・割当 + フィールド引き上げ)
PATCH /classroom-groups/{groupId}/topics トピックの add / remove / rename(rename・remove は課題へ一括追従)
POST /classrooms/{id}/duplicate 課題(1 授業)の複製。課題コンテンツの S3 オブジェクトもコピー。groupId / className / assignmentName を上書き可。メンバー・提出は複製しない。meshGroupLimit は元の保存値をそのまま写し(未設定なら未設定のまま)、レスポンスにも含む
GET /classrooms/{id}/lesson-progress レッスンの進み具合(EPIC #1592)。{lesson, progress: [{memberId, seatNumber, challenges, current, updatedAt}]} を席番号順に返す(lesson は課題の設定・無ければ null。TTL 切れの行と、いま別の生徒が座っている席の前の人の行は除く)。challenges には今の lesson.challengeIds に無い ID も含まれる(サーバーは課題の設定を変える前の記録も残す)ので、できた数・完了の条件・得点は lesson.challengeIds で絞って数えること。形は下記「ClassroomLessonProgress テーブル」
POST /classrooms/{id}/evaluate AI 評価支援。静的解析結果(シグナル + 擬似コード)を Anthropic API にリレーし、mode: grade は S/A/B/C 案 + 根拠 + needsReview、mode: comment は生徒向けポジティブコメント下書きを返す。1リクエスト最大10提出(API GW の30秒制限対策、クライアントがチャンク分割)。先生ごとにレート制限(既定 60回/時)
GET /notifications お知らせ一覧(EPIC #1111)。自分宛て(teacherSub)の直近 50 件 + unreadCount を返す。書き込みは admin スタックのみ(単一ライター)
POST /notifications/mark-read お知らせ既読化。{notificationIds?} — 省略時は一覧窓(直近 50 件)の未読を全既読化(パネルを開いたらバッジが消える UX)

みんなの課題 (共有課題ライブラリ・先生 ID Token 認証)

全国の先生が課題(説明ページ + スターター + 補足資料 URL)を共有・再利用する機能(EPIC #1066。設計の正典は spike #1067)。

Method Path 説明
POST /shared-assignments 課題を共有。visibility(省略時 public)で公開範囲を選ぶ。public=みんなの課題カタログ(CC BY 4.0 同意・属性・著者名 必須)。limited=合言葉限定公開(#1109。同意・属性・著者名は任意で、参加コード同型の合言葉を発行)。スターター 50MB 上限・10件/日制限
GET /shared-assignments カタログ一覧(新着順・schoolLevel/subject/grade/tag で絞り込み・cursor ページネーション・mine=1 で自分の投稿一覧)。公開カタログは限定公開を除外。mine=1 は自分の合言葉を含む
GET /shared-assignments/{id} 詳細(ページ・画像/スターターの presigned URL・投稿者表示名。authorSub は返さない)。限定公開は sharedId を知っていても非著者には 404(合言葉ルックアップ経由でのみアクセス)
POST /shared-assignments/lookup 合言葉プレビュー(#1109)。{passcode} → summary(sharedId は返さない)
POST /shared-assignments/import-by-passcode 合言葉で取り込み(#1109)。{passcode, groupId, assignmentName?} → 自分のクラスに課題として取り込み。sharedId を露出しない内輪取り込み
POST /shared-assignments/{id}/import 自分のクラス(groupId)に課題として取り込み(全体公開のみ。限定公開は import-by-passcode を使う)。S3 逆コピー + reuseCount 増分
PATCH /shared-assignments/{id} 更新(投稿者本人のみ。メタデータ + classroomId 指定で内容の再スナップショット=上書き)。visibility を limited→public に広げる時は CC BY 同意・属性・著者名を必須化
DELETE /shared-assignments/{id} 取り下げ = status: 'unlisted'(物理削除しない。本人のみ)
POST /shared-assignments/{id}/report 通報(理由必須・20件/日制限。reporterSub は内部保持のみ)
  • 公開範囲(#1109): 項目は visibility(public/limited)を持つ。#1109 以前の項目は属性を持たず public とみなす(後方互換)。limited は passcode(合言葉)を持ち、公開カタログには出ない。「限定公開(合言葉・内輪)→ Admin が把握 → 推薦 → 全体公開」パイプラインの土台
  • Admin 推薦(#1110): 項目は recommendedAt / recommendedBy(admin email)を持ちうる。書き込みは admin API(POST/DELETE /admin/shared-assignments/{id}/recommend)のみ。先生側 API には boolean の recommended だけを投影(recommendedBy は内部情報)。推薦時は著者へお知らせ(#1111・type shared_recommended・link.kind='shared-mine')が飛ぶ
  • データ: SharedAssignments{suffix}(TTL なし・prod は RETAIN + PITR。GSI: status-createdAt-index / authorSub-createdAt-index / passcode-index(合言葉ルックアップ・#1109))、SharedAssignmentReports{suffix}(TTL 90日)
  • ファイル: 専用バケット smalruby-shared-assignments{suffix}(lifecycle なし = 永続、shared/{sharedId}/ プレフィックス)。課題側の保存期限と完全に分離
  • 共有/取り込みの実体は既存 duplicate と同じ S3 サーバー側コピー(クロスバケット)
  • レッスンの設定(EPIC #1592): 共有すると課題の lesson を項目の lesson に写し(内容の再スナップショットでも写す。元の課題に無ければ消す)、取り込むと新しい課題に載る(取り込みのレスポンスにも hasLesson)。詳細は lesson(無ければ null)、一覧・詳細の summary は hasLesson を返す。ページもスターターも無いレッスンだけの課題も共有できる(何も無い課題はいままでどおり 400)

生徒用 (認証不要 / Session Token)

Method Path 認証 説明
POST /classrooms/lookup 不要 参加コードで課題を検索。課題が属するクラス(学級)の groupId(クラスに属さない課題・クラスが見つからない課題は null。同じ学級の別の課題で前回の番号を引くため)、meshGroupLimit(6 / 0 = 制限なし。未設定の課題は 0・Issue #1255)と、課題が属するクラスの genai: {enabled, service, url} / rubytee: {enabled}(confirmed は含めない。設定の無いクラス・クラスに属さない課題は両方無効)を含む
POST /classrooms/lookup/kick-request 不要 「使用中の席」を空けてもらう依頼を先生に送信 (Issue #692)
POST /classrooms/join 不要 課題に参加 (→ sessionToken 取得)。meshGroupLimit / genai / rubytee(lookup と同じ)を含む
POST /classrooms/verify-session Session Token セッション検証 + 提出状況取得。kick された生徒には 410 + {reason: 'kicked', joinCode, className, seatNumber} を返す。課題が非 active(アーカイブ/期限切れ)なら 401。meshGroupLimit / genai / rubytee(lookup と同じ。参加後に先生が変えた値もここで届く)を含む
POST /classrooms/{id}/submissions Session Token 提出 (Presigned URL 取得)。課題が非 active なら 404。任意の screenshotLabels(各ブロック画像のスプライト名の配列・screenshotCount 以下・各100文字以内・Issue #1239)を保存する
DELETE /classrooms/{id}/members/me Session Token 自主退出
GET /classrooms/{id}/assignment Session Token または 先生 ID Token 課題コンテンツ取得(ページ + 画像/スターターのダウンロード URL)。startFromPrevious(未設定は false)と peerView(未設定は none)も返す(assignment: null のときも)。lookup / join / verify-session は hasAssignment フラグを返す。lesson(レッスンの設定・無ければ null)も返す(ページもスターターも無いレッスンだけの課題でも返す)。課題一覧・課題詳細・複製(duplicate)とみんなの課題の取り込みのレスポンスは hasLesson を返す
GET /classrooms/{id}/continuable-submissions Session Token 続きに使える提出物(Issue #1201)。{current, previous, startFromPrevious} を返す(startFromPrevious は課題の設定・Issue #1202。GUI は読まない)。current = この課題での自分の席の提出物、previous = 同じクラスのこの課題より前に作られた課題(最大3回分遡る)での同じ席番号の提出物。各要素は {classroomId, assignmentName, projectName, submittedAt, projectUrl}(projectUrl は project.sb3 の Presigned GET URL)か null。TTL 切れの提出物・課題、project.sb3 の無い記録は返さない。パスの課題とセッションの課題が違えば 401、課題が非 active なら 404
PUT /classrooms/{id}/lesson-progress Session Token レッスンの進み具合を送る(EPIC #1592)。その席・その課題の 1 件をまとめて送る: {challenges?: {<challengeId>: {completedAt, before?}}, current?: {challengeId, openedAt} | null}。サーバーはマージする — 課題の対象外のチャレンジは捨てる・保存済みの「できた」は消さず、時刻も before も変えない(あとから来た記録で上書きしない)・current は送ったときだけ変える(null で外す。対象外のチャレンジは無視)・未来の日時は今に丸める。変わらない送信は書き込まない(はじめてでも中身が空なら行を作らない。{} を送ると今の記録を返し、まだ無ければ空の記録 {challenges: {}, current: null, updatedAt: null} を返す)。席に別の生徒が座ったあと(kick・退出のあと別の人が参加)は、前の人の行に重ねずに作り直す。レスポンスはマージ後の 1 件(GET の progress の要素と同じ形)。ID の形の違い・日時でない値・101 件以上は 400。席ごとに 1 分 20 回まで(超えると 400)。レッスンの無い課題は 400、非 active・TTL 切れは 404、パスの課題とセッションの課題が違えば 401。同じ席の同時送信は version で楽観ロックし、読み直して最大 3 回試す(だめなら 409)
GET /classrooms/{id}/peer-submissions Session Token 他者参照(Issue #1239)。同じ課題の提出済みクラスメイトを {peerView, submissions: [{seatNumber, submittedAt, thumbnailUrl, screenshotUrls, screenshotLabels}]} で席番号順に返す(URL は Presigned GET・screenshotLabels は無ければ null)。.sb3 の URL・ニックネーム・作品名・先生のコメントは返さない。自分・先生が hiddenFromPeers にした提出・TTL 切れは除く。peerView が none なら 403 {reason:'peer-view-off'}、afterSubmit で自分が未提出なら 403 {reason:'not-submitted'}。パスの課題とセッションの課題が違えば 401、課題が非 active なら 404

Google Classroom 連携 (ID Token + Access Token)

Method Path 説明
GET /classrooms/google-courses Google Classroom のコース一覧
GET /classroom-groups/{groupId}/google-course-access 押す先生自身が紐付け先コースの GC 教師かの判定({courseId, status, linkedByEmail, linkedByMe}。status = teacher / notTeacher / notLinked / unknown)
POST /classrooms/google-import コースをインポートして課題を作成(Classrooms に書き込む)
POST /classrooms/{id}/google-assignment Google Classroom に課題を投稿

Google API 失敗時のレスポンス

Google Classroom API の失敗は、Google が返した error.status / error.message を そのまま透過し、UI が翻訳するための安定キー reason を付けて返す (詳細は CloudWatch にも Google Classroom API error として記録する。アクセストークンは記録しない)。

Google の HTTP 返す HTTP reason 典型的な原因
401 401 googleTokenExpired Google のアクセストークンが失効
403 403 googlePermissionDenied 権限(スコープ)不足 / そのコースの先生ではない
404 404 googleCourseNotFound ひもづけたコースが削除された / そのコースにアクセスできない
404(課題配信時・押した先生が連携者でない) 404 googleNotCourseTeacher 押した先生がそのコースの GC 教師ではない(Google は未参加のコースを 404 で隠すため)
404(課題配信時・押した先生が連携者) 404 googleCourseNotFound 連携者はそのコースの教師なので、404 はコース消失/到達不能を意味する(「連携し直す」案内にする)
400 400 googleInvalidRequest Google がリクエストを拒否(FAILED_PRECONDITION 等を含む)
その他 502 googleApiError レート超過・Google 側障害など

レスポンス本文: {error, reason, googleStatus?, googleMessage?}。

共有できる先生の判定(GC 教師かどうか)

課題配信は 押した先生自身の Google アクセストークンで courseWork を作成するため、 Google はその先生がそのコースの教師であることを要求する。Smalruby のクラス共同担当は Smalruby 上の権限であって GC の教師とは別物なので、両者が食い違うと Google 側で失敗する。

既定はブロックで、共有できるのは次のどちらかに当てはまる先生だけ:

  1. そのコースを連携した先生(googleClassroomLinkedBy。既存データはクラス作成者 teacherSub にフォールバック)。サーバーが真偽値 linkedByMe を返し、クライアントは メール文字列を突き合わせない(大小文字・別名でぶれるため)。 GET /classroom-groups も googleClassroomLinkedByMe を返す。
  2. GC 教師であることを実際に確認できた先生。 GET /classroom-groups/{groupId}/google-course-access が courses/{courseId}/teachers/me を caller のトークンで引き、200 なら teacher、404 なら notTeacher。401/403/5xx などは unknown(判定不能)。

既定を「押させて失敗させる」から「ブロック」に反転したのは、別の Google ワークスペース (Workspace 契約の無い個人アカウント等)の共同担当は、運用でコースの教師になることが できないため。この先生はそもそも Classroom のトークンを取得できず、判定は常に unknown になる。判定不能を「押させる」側に倒すと、この先生だけが救われないまま残る。

正当な GC 共同教師の救済は明示的なオプトイン: UI のブロック表示に「自分もこの Google Classroom のクラスの先生です(確認する)」を置き、 押されたときだけ同意(requestClassroomAccessToken())→ 上記の判定を実行し、teacher なら 共有を解禁する。自動では同意ポップアップを出さない方針は維持する(クラスを開いた時点の 判定は、すでに取得済みのトークンがあるときだけ走る)。同意が得られない / notTeacher の ときはエラーバナーを出さず、ブロック表示のまま「確認できませんでした」に差し替える。

連携した先生本人は判定を一切経ずに共有でき、404 になったときの文言も「依頼してください」では なく googleCourseNotFound(連携し直す案内)になる — 依頼先は本人自身だからである。

メールが分からないとき(既存データ等)は「連携した先生」と一般名詞で表示する (推測で名前を出さない)。メールドメインの一致は判定条件にしない — Workspace の設定次第で 外部ドメインの先生もコースの教師になれるため。

クライアントが取得するアクセストークンは classroom.coursework.students を含む 3 スコープを要求するが、 Google の同意画面はスコープごとにチェックボックスを出すため一部だけ許可されることがある。 クライアントは hasGrantedAllScopes で検証し、不足していれば prompt: 'consent' で再要求する。 再要求してもなお不足する場合に加え、再要求のポップアップがブラウザにブロックされた / 先生が 閉じた・拒否した場合も googlePermissionDenied として扱う(再要求は最初のクリックから時間が 経っているため、ブラウザがポップアップを開かないことがある)。ただし OAuth の state 不一致 (CSRF の疑い)はこの扱いに含めず、そのままエラーにする。

データモデル

Classrooms テーブル

erDiagram
    Classrooms {
        string classroomId PK "UUID"
        string teacherSub "Google Subject ID (GSI)"
        string joinCode "6文字英数字 (GSI)"
        string className "最大50文字"
        number studentCount "1-50"
        string googleClassroomCourseId "任意"
        list coTeacherEmails "共同管理者の email 配列 (任意, 最大10)"
        map assignment "課題コンテンツ (任意): {pages: [{text, imageKey?}], starterKey?, updatedAt}"
        boolean startFromPrevious "前回の提出物から始めさせる (#1202, 任意・既定 false)。assignment の外に置くので課題コンテンツが空でも残る。再利用 (duplicate) で引き継ぐ"
        string peerView "他者参照 (#1239, 任意): none / always / afterSubmit。未設定は none。duplicate で引き継ぐ"
        map lesson "レッスンの設定 (EPIC #1592, 任意): 下記「レッスンの設定」。無ければいままでの課題。assignment の外に置く。duplicate・みんなの課題の共有/取り込みで引き継ぐ"
        number meshGroupLimit "出席番号で作るメッシュのグループの人数の上限 (#1255, 任意): 6 / 0 (= 制限なし)。未設定 (#1255 より前の課題) は制限なしとして 0 を返す。新しく作る課題 (作成・Google Classroom 取り込み・みんなの課題の取り込み) は常に 6 を保存。duplicate は元の保存値をそのまま写す"
        string recommendedForSharingAt "共有推奨 (#1106, 任意)。書き込みは admin API のみ。先生側 API には boolean recommendedForSharing を投影"
        string recommendedForSharingBy "推奨した admin の email (内部用・先生側 API では返さない)"
        string groupId "所属する組 (任意)"
        string status "active / archived"
        string archivedAt "アーカイブした日時 ISO8601 (任意)。DELETE / PATCH {status:'archived'} で記録し、復元 (PATCH {status:'active'}) で消す。既にアーカイブ済みの課題を再度 archived にしても元の日時を保つ。この属性より前にアーカイブした課題は持たないため、API は updatedAt で代用して返す。そうした課題の updatedAt を進める書き込み(編集・再アーカイブ・トピック名の変更など)では、先にその値を archivedAt として固定する"
        string createdAt "ISO8601"
        string updatedAt "ISO8601"
        number ttl "Unix timestamp"
    }
Loading

GSI:

  • joinCode-index — 参加コードでの検索
  • teacherSub-index — 先生の課題一覧(owner 分)

共同管理(co-teacher)

1 つの課題を作成者(teacherSub)に加えて複数の先生で共同管理できる(クラス(学級)単位の共同管理は後述の ClassroomGroups 側で行う)。

  • 招待は email で行い coTeacherEmails: string[](正規化: 小文字)に保持する。ログイン前の相手も指定でき、Google / Microsoft の混在も可。
  • 先生トークン検証 (verifyTeacherIdToken) は {sub, email} を返す。Google は email_verified のときのみ email を採用、Microsoft は email / preferred_username。
  • 所有権判定は canManageClassroom(classroom, identity) = 「teacherSub === sub または coTeacherEmails に自分の email が含まれる」。全ての先生向け操作で使用。co-teacher は owner と完全同等(課題削除・共同管理者の追加/解除も可)。
  • 作成者は teacherSub で管理され coTeacherEmails には含めないため、co-teacher API から作成者を外すことはできない(管理者ゼロを防止)。
  • GET /classrooms は次の 3 つの和集合: owner 分(teacherSub-index)、課題単位の co-taught 分(逆引き索引 ClassroomCoTeacherIndex → BatchGetItem)、管理できるクラス(所有 + 共同管理)に属する課題(管理クラスを列挙し、クラスごとに groupId-index を Query)。3 つ目は作成者を問わず拾うので、共同管理者にはオーナーが作った課題が、オーナーには共同管理者が作った課題が見える。各課題は role(owner / co-teacher)を返し、フロントの「共同管理」バッジに使う。
  • 一覧経路は Scan を使わない: Scan は RCU も 1MB 上限もフィルタ適用「前」に効くため、コストと取りこぼしのリスクが「その先生に見える量」ではなくテーブル全体の量(=他の先生のデータ量)に比例して増える。そのため課題単位の共同管理は逆引き索引、クラス経由の課題は groupId-index GSI に置き換えてある。回帰は lambda/tests/handler-list-classrooms-reads.test.ts が「Classrooms / ClassroomGroups への Scan が 0 回」で固定する。
  • ページング: DynamoDB の 1MB 上限は(Query でもフィルタ適用「前」に)効くため、LastEvaluatedKey を辿らないとデータ量が増えたときにエラー無しで取りこぼす。一覧系の Query は共通ヘルパー queryAll で最後のページまで辿り、キー指定でまとめて読む経路は batchGetAll(100 キーずつ + UnprocessedKeys の再試行 — スロットリングはエラーではなく未処理キーの返却で表れるので、捨てると同じ「黙って取りこぼす」形になる)で読む。対象は GET /classrooms / GET /classroom-groups の読み取りに加え、列挙結果がそのまま書き込みを駆動する経路(組への移行 POST /classroom-groups/migrate、クラス人数の課題への伝播、課題名の重複連番、トピックのカスケード)も含む — ここで取りこぼすと「一部だけ更新されない」状態になり、読み取りの取りこぼしより気付きにくい。無限ループ防止に DDB_MAX_PAGES(既定 25、不正値は既定に戻す)でページ数を打ち切り、打ち切り時は CloudWatch に warn を残す。単一クラス内に閉じた Query(メンバー・提出物・退室依頼)と Limit 付きの「上位 N 件」系はページングしない。
  • クラス(組)単位の共同管理の判定は canManageGroup(group, identity) = 「teacherSub === sub または クラスの coTeacherEmails に自分の email が含まれる」。クラス単位の共同管理者は、そのクラスの中では owner と同等に振る舞える(課題の一覧・作成・更新・複製・トピック管理・クラス設定の編集)。例外はクラスの共同管理者リストそのもの(PATCH /classroom-groups/{groupId} の coTeacherEmails)で、これは owner のみ変更できる(共同管理者が勝手に招待・自己解除できないようにするため)。
  • 共同管理者の email は書き込み時に正規化(validateCoTeacherEmail = trim + 小文字)して保存する。認可判定(canManageClassroom / canManageGroup)は両辺を正規化して比較するので大文字小文字に左右されない。ただし一覧の絞り込みに使う DynamoDB の contains は完全一致(大文字小文字を区別)なので、一覧に出るかどうかは保存側が正規化されている前提に依存する(手で書き換えた項目に注意)。
  • 所有者でも共同管理者でもない先生には、クラスの存在を秘匿して 404 Group not found を返す。
  • ClassroomCoTeacherIndex テーブル(逆引き索引): PK coTeacherEmail / SK resourceKey(assignment#<classroomId> または group#<groupId>)。coTeacherEmails はリスト属性なので GSI のキーにできず、逆引きは別テーブルになる。行は syncCoTeacherIndex() が差分だけ書き(課題の共同管理者 追加/削除、組の coTeacherEmails 更新、v2 移行での組への引き上げ — この 4 経路すべてが書き手)、資源の ttl を写すので資源と一緒に消える。
    • 認可は索引を見ない。canManageClassroom / canManageGroup は今も item 上の coTeacherEmails を読む。索引は「一覧に出す候補を集める」ためだけのもので、読み取り側は引いた資源のリストで再確認する(索引が遅れても権限は落ちず、一覧に出るのが遅れるだけ)。
    • 既存データにはバックフィルが必要(索引は後付けなので、それ以前の共同管理者の行が存在しない)。bin/backfill-coteacher-index.ts(既定 dry-run・冪等)を読み取りを索引に切り替えた Lambda を反映する前に実行する。デプロイ順と手順は docs/classroom/operations.md。

返却していない提出の数(unreturnedCount)

GET /classrooms の各課題に付く任意の数。クラス一覧の「確認が必要な課題」に使う。一覧のたびに課題ごとの提出を読み直さないよう、数は課題の item(Classrooms)に持ち、書き込みのときに増減する(実装: lambda/unreturned-count-lib.ts が判断、handler.ts の adjustUnreturnedCount が書く)。

数え方(GUI の課題ボード enrichMembers + summarizeAssignmentRow と同じ見方):

  • 席(memberId)ごとにいちばん新しい提出だけを見る(出し直しを 2 回数えない)。
  • status が returned でないものを数える。
  • 退室した席の提出は数えない。退室 = その席にメンバーの行が無い(自分で退室した)か、先生が退室させた(kicked: true の墓標)。同じ席に次の生徒が入ると、その席の提出(前の生徒が出したもの)はまた数える。課題ボードもその席のメンバーに提出を結びつけて数えるので、それに合わせている(次の生徒が出し直すと置きかわる)。

項目を出さないとき(GUI は項目が無い課題を「確認が必要な課題」に数えない):

  • 数を持っていない課題(この項目より前に作った課題)。数を持っていない課題には増減もしない(すでにある提出のぶんずれた数ができるため)。bin/backfill-unreturned-count.ts で埋める(docs/classroom/operations.md)。
  • レッスンの課題(hasLesson。提出・返却の流れが無い)。

数が動くとき(どれも 1 回の条件付き UpdateItem。数を持っていない課題は条件で弾く。0 より下にはしない):

操作 増減 判断に使う読み込み
課題の作成・複製・GC から作成・みんなの課題から取り込み 0 で作る なし
提出(POST /classrooms/{id}/submissions) +1。同じ席の前の提出が返却していないものなら ±0 前の提出の削除を ReturnValues: ALL_OLD で返させる(追加の読み込みなし)
返却(PATCH .../submissions/{id} の status: returned) 在席の席の、返却していないものを返却したときだけ -1。同じ提出の 2 回目の返却・コメントだけの更新は ±0 更新の ReturnValues: UPDATED_OLD(前の status)+ 席のメンバーの GetItem 1 回
自分で退室(DELETE .../members/me)・先生が退室させる(DELETE .../members/{id}・退室依頼の承認) その席に返却していない提出があれば -1。もう空いていた席なら ±0 削除・更新の ReturnValues: ALL_OLD(前に在席だったか)+ その席の提出の Query 1 回(GSI classroomId-memberId-index)
空いた席への参加(POST /classrooms/join) その席に返却していない提出があれば +1 その席の提出の Query 1 回
アーカイブ・復元(PATCH status) ±0(数はそのまま残る) なし
運用の復元(bin/restore-classroom.ts) 復元するメンバーと提出から数え直す なし(スナップショットから数える)

一覧の取得(GET /classrooms)での追加の読み込みは無い(課題の item の項目を返すだけ)。

付随的な集計なので fail-open: 数の書き込みや判断の読み込みに失敗しても、提出・返却・退室・参加そのものは成功させる(.claude/rules/infra/development.md の「混雑・障害時の劣化」)。ずれうるのは、書き込みの失敗と、同じ席への同時の書き込み(例: 同じ席の同時の提出で提出が 2 件残る、参加と退室させるのが同時)のときと、退室直後の提出(セッションの確認は結果整合の GSI を読むので、退室した直後の生徒の提出が通ると、空いた席の提出を数えてしまう)のとき。ずれは bin/backfill-unreturned-count.ts --recount で直す。課題・提出・メンバーの TTL はどれも課題の TTL とそろうので、TTL での削除ではずれない。

ClassroomMemberships テーブル

erDiagram
    ClassroomMemberships {
        string classroomId PK "UUID"
        string memberId SK "seat-NN (ゼロ埋め)"
        string displayName "最大20文字"
        string role "student"
        string sessionToken "UUID (GSI)"
        string joinedAt "ISO8601"
        string lastActiveAt "ISO8601"
        number ttl "Unix timestamp"
    }
Loading

GSI:

  • sessionToken-index — セッショントークンでの認証

着席判定(lastActiveAt): lastActiveAt を更新するのは参加と verify-session(生徒がページを開いたとき・クラスのモーダルを開いたとき)だけで、定期的なハートビートは送らない(通信量を増やさないため)。先生の画面は lastActiveAt が 1 時間以内なら「着席中」と表示する目安で、正確さは求めない。席を空ける依頼(kick request)は、先生が教室で本人に確かめてから承認する前提。しきい値は packages/scratch-gui/src/lib/classroom-presence.js の 1 か所にまとめてある。verify-session の更新は「行がまだそのセッションのもので kick されていない」ことを条件にしており、退出・kick の直後に届いても行を作り直したり tombstone の TTL を延ばしたりしない(条件を満たさなければ 401)。

ClassroomKickRequests テーブル (Issue #692)

erDiagram
    ClassroomKickRequests {
        string classroomId PK "UUID"
        string requestId SK "UUID"
        number seatNumber "1-50"
        string reason "任意・最大200文字"
        string sourceIpHash "abuse trace用 (sha256 16桁)"
        string createdAt "ISO8601"
        number ttl "Unix timestamp (1h)"
    }
Loading

GSI:

  • classroomId-seatNumber-index — 承認時に同席への全リクエストを batch-delete するため

短命 (TTL 1 時間) のレコード。生徒が「使用中の席を空けてください」と先生に依頼するときに作成される。同一席への複数依頼を許容する仕様 (規制なし)。

Memberships の kick tombstone (Issue #692)

handleDeleteMember (= 教師 kick) は 行を物理削除しない:

  • kicked: true, kickedAt, kickJoinCode, kickClassName, kickSeatNumber, ttl: now+1h をセット
  • これにより、kick された生徒の次回 verify-session 呼出で 410 reason='kicked' を返せる
  • listMembers / lookup takenSeats は FilterExpression: attribute_not_exists(kicked) OR kicked <> :true で tombstone を除外
  • joinClassroom の ConditionExpression: attribute_not_exists(memberId) OR kicked = :true で新生徒が kicked 行を上書き可能 (tombstone はその時点で消滅)

Memberships の kick marker(席が使われても 410 を返す)

tombstone は席(seat-NN)がキーなので、退室依頼を承認したあと依頼した生徒がすぐその席に参加すると上書きされ、kick された生徒の verify-session が 401 になってしまう(Issue #1821)。そこで kick のとき、同じ表に席の行とは別の印の行も書く:

属性 値
classroomId (PK) kicked#<classroomId>(別の区画。課題ごとの Query — メンバー一覧・lookup・管理画面の件数・学習の進み具合 — には出ない)
memberId (SK) <seat-NN>#<sha256(sessionToken) の先頭16桁>(kick したセッションごとに 1 行)
sessionToken kick された生徒のセッショントークン(既存の GSI sessionToken-index で引ける)
kicked / kickedAt / kickJoinCode / kickClassName / kickSeatNumber / ttl tombstone と同じ値(TTL 1 時間)
  • verifySessionToken は GSI で印の行を見つけると、tombstone と同じく 410 reason='kicked' を返す。新しい表・GSI は使わない。
  • 同じ生徒がもう一度参加すると新しいセッショントークンになるので、印の行は新しいセッションに影響しない(古いトークンだけが 410 のまま)。
  • 印の書き込みは付随的なもので、失敗してもログに残すだけで kick そのものは成功させる(その場合は席が使われるまで tombstone が 410 を返す)。
  • rubytee relay の席の確かめ(GSI で引く)は kicked: true の行を席として数えないので、印の行も数えない。
  • 削除スナップショット(archiver)は kicked# の区画をスキップする。

ClassroomNotifications テーブル(お知らせ・EPIC #1111)

erDiagram
    ClassroomNotifications {
        string teacherSub PK "宛先の先生 (Google/Microsoft sub)"
        string notificationId SK "createdAt ISO + '#' + UUID (時系列ソート)"
        string type "admin_message など (リンク種別の意味付け)"
        string title "最大100文字"
        string body "最大1000文字"
        map link "任意: {kind: 'classroom', classroomId} — クリック時のジャンプ先"
        string readAt "既読日時 (未読は属性なし)"
        string createdBy "送信した admin の email (内部用・API では返さない)"
        string createdAt "ISO8601"
        number ttl "Unix timestamp (既定180日)"
    }
Loading

GSI なし — 宛先 (PK) への Query だけで受信箱になる。

  • 単一ライター: 書き込みは admin スタック(POST /admin/notifications、名前規約 import + write-only grant)のみ。classroom API は一覧と既読化だけを提供するので、エディタ側からお知らせを偽造できない
  • 宛先の teacherSub は admin SPA に出さず、admin API が classroomId から解決する
  • link.kind は whitelist(現在 classroom のみ)。エディタは未知の kind を無視する(前方互換)
  • GUI は先生モーダルのヘッダーの 🔔 から一覧を開く。パネルを開いた時点で mark-read(全件)が走りバッジが消える。60 秒間隔でポーリング

退室依頼の先生への通知(ポーリング方針)

先生がクラス管理モーダルを閉じて授業をしていても退室依頼に気付けるよう、GUI は先生のログイン中ずっと GET /kick-requests/pending を問い合わせ、新しい依頼を画面下部のトーストで知らせる(classroom-teacher-kick-alerts.jsx)。

  • 間隔は 10 秒(CLASSROOM_TEACHER_KICK_POLL_INTERVAL_MS、既定 10000)。席が空かないと生徒が参加できず授業が止まるため、先生には短い間隔のポーリングを許す。生徒側には新しい定期通信を足さない(生徒は依頼中だけ 5 秒ごとに lookup する既存の仕組みのまま)。
  • WebSocket は使わない。classroom にはリアルタイム基盤が無く、10 秒ポーリングで授業に支障が無いため。
  • GUI 全体で 1 つだけ動かす(モーダルの外)。タブが非表示の間は止め、表示に戻ったとき・ログインしたときはすぐに 1 回問い合わせる。
  • エラーが続くと間隔を倍々に伸ばす(上限 5 分)。有効な課題が 1 件も無い(activeAssignmentCount: 0)間は 6 倍(60 秒)に落とす。
  • サーバーは先生に見える課題のうち、有効(active)で直近に触れた 50 件までを対象に、課題ごとに ClassroomKickRequests をキー Query する(Scan しない・インデックス追加なし)。期限(TTL)切れの行は除外する。
  • お知らせ(🔔、1 日 1 回取得・admin が書く)とは別の流れ。退室依頼は数秒で処理されるべきものなので日次キャッシュに載せない。

ClassroomSubmissions テーブル

erDiagram
    ClassroomSubmissions {
        string classroomId PK "UUID"
        string submissionId SK "UUID"
        string memberId "seat-NN (GSI)"
        string projectName "最大100文字"
        string s3Key "S3 オブジェクトキー"
        string thumbnailS3Key "サムネイル S3 キー"
        number screenshotCount "0-20"
        list screenshotLabels "各ブロック画像のスプライト名 (#1239, 任意)"
        boolean hiddenFromPeers "先生が他者参照から外した (#1239, 任意・既定 false)"
        string status "submitted / returned"
        string submittedAt "ISO8601"
        string updatedAt "ISO8601"
        string teacherComment "最大500文字"
        number ttl "Unix timestamp"
    }
Loading

GSI:

  • classroomId-memberId-index — 生徒ごとの提出検索

ClassroomLessonProgress テーブル(レッスンの進み具合・EPIC #1592)

erDiagram
    ClassroomLessonProgress {
        string classroomId PK "課題の UUID"
        string memberId SK "seat-NN"
        map challenges "{<challengeId>: {completedAt: ISO8601, before: boolean}}。before = 課題の前から(端末の記録から)できていた"
        map current "いまやっているチャレンジ {challengeId, openedAt} または null"
        number version "楽観ロックの版(書くたびに +1)"
        string occupantJoinedAt "この行を書いた生徒の参加時刻(ClassroomMemberships の joinedAt)。席の生徒が変わったかを見分ける"
        string updatedAt "ISO8601"
        number ttl "課題(Classrooms)の ttl を写す"
    }
Loading
  • 席 × 課題で 1 件。生徒の 1 回の送信が 1 回の書き込みになる(D8: 40 人 × 11 チャレンジ × 2 回 ≒ 授業 1 回で 880 書き込みまで。変わらない送信は書かない)
  • 席が退出・kick されても消さない(提出と同じく課題に属する記録)。ただし席の生徒が変わったら引き継がない: 行に書いた生徒の occupantJoinedAt(参加時刻)を持たせ、送ってきたセッションの参加時刻と違えば前の行に重ねずに作り直す。先生の一覧は、いま別の生徒が座っている席の前の人の行を出さない(空いた席・kick された席は最後の人の行を出す)。同じ生徒でも退出して参加し直すと参加時刻が変わるので作り直しになる(端末の記録から送り直す前提・D9)
  • 課題のアーカイブ中は送れない(読み出しは先生だけ)
  • 進み具合は生徒の端末の自己申告。サーバーはコースの中身を知らないので、「できた」が本当かは確かめられない(Session Token を持つ生徒は、自分の席について課題のチャレンジを全部「できた」にできる)。評価・得点に使うときは、作品の提出や先生の確認を裏付けにする
  • 期限は課題の TTL を写すので、課題と一緒に消え、削除スナップショット・復元 CLI の対象にもなる

レッスンの設定(lesson)

課題(Classrooms の item)に任意で持たせる。サーバーはコースの中身を知らないので、形と件数だけを確かめる。

項目 型 検証
courseId string 必須。^[a-z0-9][a-z0-9_-]{0,63}$。constructor など Object.prototype の名前は使えない(チャレンジ ID も同じ。進み具合の map のキーにすると DynamoDB に保存できないため)
challengeIds string[] 必須。レッスンの順。1〜100 件・同じ形・重複なし
requiredChallengeIds string[] 任意(既定 [])。challengeIds の中から・重複なし
completion {type: 'all'} | {type: 'count', count} 任意(既定 all)。count は整数で「必須の数(最低 1)〜challengeIds の数」
submitWork boolean 任意(既定 false)。レッスンのあとに作品の提出もする
scoring {total, requiredPoints, optionalPoints} | null 任意。total(満点)は 0 より大きく 1000 以下、requiredPoints(必須を全部こなしたときの点)・optionalPoints(必須でないものの合計点)は 0〜total。得点はサーバーでは計算しない(進み具合から画面が機械的に出す・D10)

ClassroomGroups テーブル(クラス(学級)。旧称: 組)

erDiagram
    ClassroomGroups {
        string groupId PK "UUID"
        string teacherSub "先生の Subject ID (GSI)"
        string name "クラス名 (最大50文字, 例: 2年1組)"
        number year "年度 (2000-2100)"
        string status "active / archived"
        number schemaVersion "データモデル版 (v2 = クラス→課題モデル)"
        string_array topics "課題のトピック一覧 (最大20件)"
        string googleClassroomCourseId "GC コース紐づけ (クラス単位, 任意)"
        map googleClassroomLinkedBy "GC を紐付けた先生 {sub, email} (任意)"
        number studentCount "人数 (課題の座席数の真実, 任意)"
        string_array coTeacherEmails "クラス単位の共同管理者 (任意)"
        map genai "生成AI {enabled, service, url, confirmed} (#1275, 任意。未設定は無効)"
        map rubytee "ルビティー {enabled, confirmed} (#1275, 任意。未設定は無効)"
        string createdAt "ISO8601"
        string updatedAt "ISO8601"
        number ttl "Unix timestamp (既定400日)"
    }
Loading

GSI: teacherSub-index — 先生のクラス一覧

クラス単位の AI 設定(genai / rubytee)

先生がクラスごとに「生徒に生成AIのリンクを見せるか」「ルビティーを使わせるか」を決める。

項目 値 検証
genai.enabled boolean(既定 false) true にするには service と confirmed: true と url が要る
genai.service gemini / chatgpt / other それ以外(claude など 18 歳以上限定のサービスを含む)は 400
genai.url https の URL(最大 2048 文字) http・不正な URL・18 歳以上限定サービスのホスト(claude.ai / claude.com / anthropic.com)は 400。省略すると gemini = https://gemini.google.com/app、chatgpt = https://chatgpt.com/(service を変えて url を省くと新しい既定に切り替わる)
genai.confirmed boolean(既定 false) 先生が利用規約(年齢制限など)を確認した印。先生向けの応答にだけ含める
rubytee.enabled boolean(既定 false) —
rubytee.confirmed boolean(既定 false) 先生がルビティーを使わせる条件を確認した印。先生向けの応答にだけ含める。今は enabled: true に必須ではない({enabled: true} だけでも保存できる)
  • 項目の無い既存のクラスは両方無効として返す(先生向け: genai = {enabled:false, service:null, url:null, confirmed:false}、rubytee = {enabled:false, confirmed:false})。confirmed の無い既存のルビティー設定は confirmed:false として読む。
  • rubytee も genai と同じく部分更新(enabled だけ送ると保存済みの confirmed は残る)。
  • 生徒向け(lookup / join / verify-session)は課題が属するクラスの設定から confirmed(genai / rubytee とも)を除いて返す。

クラス(学級・Group)は先生側の管理概念で、1 つのクラスが年間の複数の課題(Classrooms レコード = 1 授業)を束ねる。生徒には見えない(生徒のモデル = 課題ごとの参加コード + 匿名席番号は不変)。

  • クラスは生徒の作品を持たないため、90日ではなく長期 TTL(既定400日 ≈ 年度 + バッファ、GROUP_TTL_DAYS)
  • クラスのアーカイブは表示上の整理。課題データ自体は 90 日 TTL で自然消滅する
  • 前回コメント再掲: クラスに属する課題に生徒が join すると、同じクラスの直近の授業(最大3回分遡る)で同じ席に返却されたコメントが previousComment として join レスポンスに載る(連休明けの個別リキャップ用)。前回授業の列挙は groupId 起点なので、前回を共同管理者が作っていても拾える
  • 前回の提出物から続ける(Issue #1201): 同じ席番号の対応を使い、GET /classrooms/{id}/continuable-submissions が前回の課題での同じ席の提出物(と、この課題で自分が出した提出物)のダウンロード URL を返す。生徒が自分の提出物を取れる経路はこれだけ(先生の GET /submissions とは別)
  • ⚠️ プライバシーの前提(席番号は匿名): 生徒は課題ごとに匿名の席番号で参加するだけで、本人を識別する情報は持たない。そのため「前回その席に座っていた生徒」と「今回その席に座った生徒」が同じ人だとはシステムは確かめられない。同じクラスの次の課題で同じ席番号を選んだ別の生徒も、前回の提出物を読み込める。これは前回コメント再掲(previousComment)と同じ範囲のリスクで、席番号を毎回同じにする運用(出席番号を使う)を前提にしている。別のクラスの課題・別の席の提出物は取れない
  • 他者参照のプライバシー(Issue #1239): GET /classrooms/{id}/peer-submissions は課題の peerView が許すときだけ、同じ課題の提出済みクラスメイトの画像(サムネイル・ブロック画像)とスプライト名・席番号・提出日時だけを返す。作品をそのまま写せないよう .sb3 は渡さず、誰の作品か分からないようニックネーム・作品名・先生のコメントも返さない。先生は提出ごとに hiddenFromPeers で見せないようにできる(生徒が再提出しても引き継ぐので、出し直しで外せない)。別の課題の提出は(同じクラスでも)返さない

データモデル v2(クラス→課題モデル)

schemaVersion: 2 = すべての課題がクラスに属し、クラス単位の GC 紐づけ・共同管理・人数が真実、という状態。Google Classroom の「クラス → 課題」構造に合わせた再構成で、既存データとは 冪等な bulk migration で互換を取る:

  • POST /classroom-groups/migrate(クラス一覧の初回表示時にクライアントが呼ぶ): groupId の無い既存課題を className ごとに自動作成したクラスへ割当(年度は課題作成日の JST 4月区切りから推定、同名クラスがあれば再利用)。課題単位の GC courseId(最古優先・クラス側優先)/ coTeacherEmails(和集合)/ studentCount(最大値)をクラスへ引き上げ、schemaVersion=2 をスタンプ。移行済みデータでは何もしない
  • 認可はクラス経由でも成立(canManageViaGroup / canManageGroup): クラスの所有者・クラス単位の共同管理者は、中のすべての課題を一覧・作成・管理できる(クラス単位の入口 getManageableGroup も同じ判定)。課題単位の旧 coTeacherEmails も引き続き有効(後方互換)
  • 座席数はクラスの studentCount が真実: 生徒の lookup / join はクラスの人数と課題側スナップショットの max を使う(人数を減らしても既存の着席と衝突しない増加方向のみの反映)。クラスの人数を変更するとクラス内のアクティブな課題へ波及するが、この列挙も groupId 起点なので共同管理者が作った課題の表示人数が古いまま残らない
  • クラス単位の列挙は必ず groupId 起点(トピック追従・人数の波及・前回コメント再掲・同名課題のオートナンバリング)。クラスのオーナーの teacherSub で引くと、共同管理者が作った課題を取りこぼす。例外は クラスに属さない(v1 の)課題を扱う POST /classroom-groups/migrate で、そこは引く手がかりが呼び出し元の teacherSub しか無い
  • トピック(PATCH /classroom-groups/{groupId}/topics、body {action: add|remove|rename, name, to?}): クラスの topics 配列を管理。rename / remove はクラス内の課題の topic へ一括追従(rename は付け替え、remove は解除)。追従は groupId で課題を引くので、共同管理者が作った課題(teacherSub がクラスのオーナーと異なる)も取り残さない。課題の作成・更新で新しいトピック名を使うとクラスの一覧へ自動追加される
  • AI 評価の日次上限: 先生ごとに EVAL_DAILY_LIMIT(既定 50 呼び出し/日 ≈ 1 課題分の全生徒の採点+コメントで約 5 回分)を DynamoDB のアトミックカウンタ(Classrooms テーブルの予約キー eval-quota#<teacherSub>#<日付>、TTL 2 日)で永続的に強制。インスタンス内メモリの時間窓(EVAL_RATE_LIMIT_*)は高速な一次ゲートとして併用
  • 課題の topic / sortDate: topic はクラスのトピックへの文字列参照。sortDate は並び順キー(既定=作成日・意味なし・生徒非表示・自由変更可)で、課題管理画面はトピックごと・sortDate 降順に表示する

AI 評価支援(evaluate)

先生の評価作業を支援する。AI は判定者ではなく提案者: 全結果に機械シグナルを引用した根拠と needsReview フラグが付き、先生が UI で確認・修正・承認してはじめて記録される。

  • 入力: 課題名/課題文 + 評価軸(1〜6、grade モードのみ必須)+ 厳しさ(lenient/standard/strict)+ 較正サンプル(先生が採点した実例、最大5件)+ 提出(席番号・シグナル・擬似コード最大4000字)
  • モデル: CLAUDE_MODEL(既定 claude-haiku-4-5)。システムプロンプトに prompt caching(ephemeral)を適用し、同一課題のチャンク分割呼び出しでキャッシュを共有
  • Claude は Anthropic の TypeScript SDK(@anthropic-ai/sdk)で呼ぶ。ANTHROPIC_FEDERATION_RULE_ID / ANTHROPIC_ORGANIZATION_ID / ANTHROPIC_SERVICE_ACCOUNT_ID(+ 任意の ANTHROPIC_WORKSPACE_ID)がそろえば Workload Identity Federation(Lambda の実行ロールの JWT を AWS STS GetWebIdentityToken で取り、短期トークンに交換)で呼ぶ。静的な API キーの経路は無い。値がそろわないステージではエンドポイントは 503(機能無効)。設定は docs/infra/claude-api-wif.md
  • 1 回の呼び出しは 25 秒で打ち切り(API Gateway の 30 秒の上限より前)・再送しない。タイムアウトは 504 AI_TIMEOUT、Claude のエラーと WIF の交換の失敗は 502 AI_API_ERROR
  • CloudWatch に classroom_evaluate イベント(トークン数・キャッシュヒット)を構造化ログ出力

課題コンテンツ(assignment)

課題(1 授業)には任意で課題コンテンツを持たせられる。先生が編集し、参加済みの生徒が読む。プログラム配付を自動化するための仕組み(生徒は参加するだけで課題とスターターが手に入る)。

  • pages: (数行テキスト + 画像1枚)× 最大10ページ。テキストは1ページ500文字まで
  • starterKey: スタータープロジェクト(.sb3)の S3 キー。1課題に1つ
  • 画像は image/png / image/jpeg のみ。オブジェクトは {classroomId}/assignment/ プレフィックスに置かれ、編集で参照されなくなったものは best-effort で削除される
  • PUT は pages の各要素に newImage(新規アップロード。MIME 指定)か imageKey(既存維持)を指定し、newStarter / keepStarter でスターターを制御する。レスポンスの Presigned URL にクライアントが直接 PUT する(提出フローと同型)
  • GET は生徒(Session Token)と先生(ID Token)の両対応。トークンに . を含むかで判別する(Session Token は UUID、ID Token は JWT)

S3 オブジェクト構造

smalruby-classroom-submissions-{stage}/
  {classroomId}/
    assignment/
      image-{uuid}.png|.jpg  ← 課題ページの画像
      starter-{uuid}.sb3     ← スタータープロジェクト
    {submissionId}/
      project.sb3           ← Scratch 3 プロジェクトファイル
      thumbnail.png          ← プロジェクトサムネイル
      screenshot-0.png       ← スクリーンショット (0-indexed)
      screenshot-1.png
      ...

TTL (自動削除)

項目 有効期間 (prod) 有効期間 (stg)
課題(Classrooms) 90日 1日
メンバー 課題と同じ 課題と同じ
提出 課題と同じ 課題と同じ
レッスンの進み具合 課題の ttl を写す 同左
S3 ファイル ARCHIVE_RETENTION_DAYS(365日。ライフサイクルルール) 同(stg は 30日)

ユーザーがアクセスできるのは メタデータ(DynamoDB)が生きている TTL 期間内のみ(presigned URL はメタデータからのみ発行される)。TTL 後〜ARCHIVE_RETENTION_DAYS の間は運用者のみが復元に使える(下記)。

削除スナップショットと長期保持(期限切れ復元の最後の砦)

「期限が切れたが、どうしても復元してほしい」という問い合わせに応えるための仕組み(EPIC #1049 D7)。

  • Classrooms / ClassroomMemberships / ClassroomSubmissions / ClassroomGroups / ClassroomLessonProgress に DynamoDB Streams(OLD_IMAGE)を有効化。ClassroomKickRequests(1時間 TTL の一時データ)は対象外
  • ClassroomArchiver-{stage} Lambda が REMOVE イベント(TTL 削除・明示削除の両方)を受け、削除されたアイテムを JSON で S3 に退避:
    • ddb-archive/classrooms/{classroomId}.json
    • ddb-archive/memberships/{classroomId}/{memberId}.json
    • ddb-archive/submissions/{classroomId}/{submissionId}.json
    • ddb-archive/groups/{groupId}.json
    • ddb-archive/lesson-progress/{classroomId}/{memberId}.json
    • eval-quota# プレフィックスのカウンタ行と、Memberships の kicked# 区画(kick marker)はスキップ
  • イベントソースは REMOVE のみのフィルタ + bisectBatchOnError + 有限リトライ(不正レコード 1 件で shard が詰まらない設計。S3 書き込み失敗のみ throw して再試行)
  • S3 lifecycle は ARCHIVE_RETENTION_DAYS(既定 365 日、CLASSROOM_TTL_DAYS 以上必須 — スタックがガード)
  • 復元手順は docs/classroom/operations.md(運用者向け)

CORS

Stage 許可オリジン
stg https://smalruby.app, https://smalruby.jp, http://localhost:8601〜8610, https://preview.smalruby.app(ブランチプレビュー)
prod https://smalruby.app, https://smalruby.jp

許可ヘッダー: Content-Type, Authorization, X-Google-Access-Token

レート制限

参加エンドポイント (/classrooms/lookup, /classrooms/join) にはIPベースのレート制限があります。

項目 prod stg
ウィンドウ 60秒 30秒
最大リクエスト数 50回 100回
実装方式 Lambda インメモリ Map 同左

レッスンの進み具合の送信(PUT /classrooms/{id}/lesson-progress)は席(課題 × 席)ごとに 60 秒 20 回まで(LESSON_PROGRESS_RATE_LIMIT_WINDOW_SECONDS / LESSON_PROGRESS_RATE_LIMIT_MAX・Lambda インメモリ Map)。

メンバー一覧の aiUsage(ルビティーの上限)

GET /classrooms/{id}/members の members[] には任意のフィールド aiUsage が付く(既存のフィールドは同じ)。 rubytee relay(infra/smalruby-rubytee-relay)が書く表を読み取り権限だけで読む(詳細は docs/rubytee/README.md の「利用の集計・席ごとの状況」)。relay の classroom = この課題の classroomId、seat = 出席番号の数字。

"aiUsage": {
  "takeover": {              // 「ルビティーにまかせる」の上限(1 席ごと)
    "used": 12,              // 今の窓で使った回数(窓が終わっていれば 0)
    "limit": 40,             // 上限(relay が書いた値)
    "windowMinutes": 35,
    "resetAt": "2026-11-01T10:15:00+09:00",   // 窓が終わる時刻。使っていなければ null
    "limited": false         // used >= limit
  },
  "today": {                 // 今日(日本時間)の回数
    "takeover": { "requests": 15, "rateLimited": 0, "succeeded": 14, "failed": 1 },
    "chat":     { "requests": 3,  "rateLimited": 0, "succeeded": 3,  "failed": 0 }
  }
}
  • 席に記録が無ければ used: 0 / resetAt: null、today の各値は 0。
  • Ruby タブのルビティー(chat)は IP 単位の上限なので、1 席ごとの残りは出さず today の回数だけ。
  • 読み取りは 1 課題あたり BatchGetItem(100 席ごと)+ Query 1 回。relay の表が読めない・Lambda の環境変数 RUBYTEE_RATE_LIMIT_TABLE_NAME / RUBYTEE_USAGE_TABLE_NAME が空のときは aiUsage: null で、メンバー一覧は ふつうに返す(fail-open)。
  • BatchGetItem が UnprocessedKeys を返したとき(混雑時)も再試行せずクラス全体を aiUsage: null にする。 一時的に全員分が見えなくなるのは許容する(授業中の応答を遅らせない。方針は .claude/rules/infra/development.md の「混雑・障害時の劣化」)。
  • 組み立ては lambda/ai-usage-lib.ts(純粋関数)。キーの形は relay の lambda/takeover.ts と対で変える。