班级上下文
?class 规则、无班级/越权错误与接口总览
路径未版本化
最后更新：2026-10-25
班级上下文
多班级架构下，待办、课表、日历、分组和通知都需要知道“这次请求属于哪个班”。已认证请求可以带查询参数：
GET /api/todos?class=3
GET /api/todos?class=demo-class?class=的值全是数字时按班级 id 查，否则按班级 slug 查。- 不传时使用调用者自己加入的班级；没有加入班级时
classId为null。 - 指定的班级不存在：
404 NOT_FOUND；存在但调用者不是成员：403 FORBIDDEN。 - 平台超级管理员（
admin_level=3）可以指定任意班级，并在该班按admin角色处理。 - 需要班级的接口在没有班级时返回
400 BAD_REQUEST，不会退化成“全平台查询”：GET/POST /api/todos、POST /api/todos/:id/toggle、GET /api/schedule、GET /api/calendar/events、GET /api/groups。 GET /api/me、通知和身份接口不强制要求班级，但带?class=会改变返回的班级字段或通知过滤范围。
班级参数在身份解析之后、路由之前统一处理；如果班级无效，请求在进入具体接口前就会被拒绝。
接口总览
| 方法 | 路径 | 认证 | 班级 | 用途 |
|---|---|---|---|---|
| GET | /api/health | 否 | 否 | 健康检查 |
| GET | /api/platforms | 否 | 否 | 平台注册表 |
| POST | /api/auth/token | 是（Cookie） | 否 | 会话换令牌 |
| GET | /api/me | 是 | 可选 | 当前用户与班级上下文 |
| POST | /api/me | 是 | 否 | 修改姓名/性别/宿舍 |
| POST | /api/me/password | 是 | 否 | 设置/修改密码 |
| POST | /api/me/password/clear | 是 | 否 | 关闭密码登入 |
| GET | /api/todos | 是 | 必需 | 待办列表 |
| POST | /api/todos | 是 | 必需 | 发布班级/个人待办 |
| POST | /api/todos/:id/toggle | 是 | 必需 | 勾选/取消完成 |
| GET | /api/schedule | 是 | 必需 | 课表视图 |
| GET | /api/calendar/events | 是 | 必需 | 手机日历事件 |
| GET | /api/groups | 是 | 必需 | 本班分组 |
| GET | /api/notices | 是 | 可选 | 通知列表 |
| GET | /api/notices/unread | 是 | 可选 | 未读数 |
| GET | /api/notices/pending | 是 | 可选 | 增量通知 |
| POST | /api/notices/:id/read | 是 | 可选 | 标记单条已读 |
| POST | /api/notices/read-all | 是 | 可选 | 全部已读 |
| GET | /api/identities | 是 | 否 | 已绑定平台 |
| POST | /api/identities/linkcode | 是 | 否 | 生成绑定码 |
| GET | /api/identities/linkcode/:code | 是 | 否 | 查询绑定码状态 |
| POST | /api/identities/bind | 否 | 否 | 用绑定码绑定平台 |
| POST | /api/auth/desk | 否 | 否 | 创建扫码登入会话 |
| GET | /api/auth/desk/:scene | 否 | 否 | 轮询扫码状态 |
| GET | /api/auth/desk/:scene/qrcode | 否 | 否 | 小程序码图片 |
| POST | /api/auth/mini | 否 | 否 | 小程序扫码回调 |
| GET | /api/auth/mini/status | 否 | 否 | 小程序配置诊断 |
| GET | /api/app/version | 否 | 否 | App 版本（不在 API router 内） |