REST API
API 前缀 /api，JWT 使用 Authorization: Bearer。成功/失败结构以 lib/http.ts 为准，
校验错误映射 422 VALIDATION_ERROR，表格体积超限为 413 IMPORT_TOO_LARGE。
全部挂载入口以 modules/registry.ts 为准；完整参数、返回类型、权限和枚举以模块的 module/schemas/service 与 shared 契约为准。
本页列常用入口，不重复复制每条路由实现。
身份与班级
| 方法与路径（省略 /api） | 行为及边界 |
|---|---|
| POST /auth/login、/auth/class-login | 员工/班级登录，共享登录限流；学生无账号 |
| GET /auth/me；POST /auth/logout；PATCH /auth/password | 当前身份、退出、员工本人改密码 |
| GET/POST /classes；GET/PATCH/DELETE /classes/:id | 班级查询/管理，读取 class:read；写入 class:manage 且仅管理员 |
| PATCH /classes/:id/class-account、/classes/:id/head-teacher | 班级凭据 class:account + 班主任；班主任分配仅管理员 |
| PUT /classes/:id/subject-teachers | 任课关系设置，Course 为唯一来源 |
| GET/PATCH /classes/:id/student-grade-query | 查看/修改班级个人成绩查询开关，班级端不能修改 |
| GET/POST /classes/:id/students；DELETE /classes/:id/students/:studentId | 本班名单及维护，受名单功能权限和班级关系约束 |
| /students、/teachers | 名单与账号 CRUD；读/写使用不同权限键，具体角色限制读取对应模块 |
| POST /teachers/:id/reset-password | 指定新密码或默认重置；学生无对应接口 |
| /permissions/me、/catalog、/groups、/users | 当前有效权限、目录、组与账号分组 |
教学与文件
| 路径/动作 | 行为及边界 |
|---|---|
| /courses | 班级科目与任课关系 |
| GET /schedules、/grid、/current、/active-week | 新关系模型的兼容投影，按班级范围读取 |
| POST/PATCH/DELETE /schedules[/:id] | 兼容 CRUD，写新模型，不双写旧 Schedule |
| POST /schedules/swap、/overlay、/scheduled；GET /schedules/scheduled；DELETE /schedules/scheduled/:id | 换课、临时层、预定 |
| /time-layouts；POST /time-layouts/:id/clone、/:id/import | 时间表 CRUD/克隆/导入，写入 timetable:manage |
| /class-plans；PUT /class-plans/:id/entries；PATCH /class-plans/:id/enabled | 日课表 CRUD、整表保存、启用，写入 schedule:write + 班主任/管理员 |
| POST /class-plans/:id/clone、/class-plans/import、/class-plans/import/profile；GET /class-plans/:id/export | 复制、导入导出及完整档案导入；导入另需 import:schedule |
| /class-plan-groups；GET /class-plan-groups/selection；POST /class-plan-groups/select | 群组及当前/临时选择 |
| /homeworks、/homeworks/bulk、/:id/status、/:id/submissions | 作业、批量、完成与未交；员工功能键+科目检查，班级端可录作业 |
| /notifications、/notifications/bulk、/days、/creators、/unread-count、/:id/read、/read-all | 通知、归档和已读；发布需 notification:publish，课堂紧急须确认 |
| POST /calls | 叫人，call:create + 范围检查 |
| /grades、/grades/bulk、/stats、/levels、/my、/overview、/collective、/student/:studentNo、/exams、/ranking | 成绩与隐私，查询列表参数用 studentId，写入仍按科目 |
| /imports/template、/table/preview、/table/commit | 表格导入，按 kind 再检查对应导入键、管理键、班级和科目 |
| /imports/class-plan/preview、/imports/class-plan | 预览与提交均需 import:schedule + schedule:write；提交走关系化导入 |
| POST /imports/class-plan/yaml/preview、/imports/class-plan/yaml | YAML 预览/导入；同课表导入权限与班级范围，支持 all/odd/even 与 HHMMSS，提交复用完整档案事务 |
| /imports/time-layout[/:id]、/time-layout/preview | 时间配置兼容入口，导入需 import:schedule + timetable:manage，删除需 timetable:manage |
| GET /class-plans/profile?classId= | 完整档案导出，按班级范围读取，保留时间点与课表关联 |
| GET /courseware、/courseware/:id、/:id/download | 课件目录/详情/下载；员工需 courseware:read，班级端按可见范围 |
| POST /courseware/upload、/:id/push；PATCH /courseware/:id/visibility；DELETE /courseware/:id | 写入 courseware:write + 员工身份；本人文件、任课班级与可见范围限制 |
| GET/POST /courseware/folders；PATCH /courseware/:id/folder | 员工 courseware:write；目录与课件均限本人 |
| GET /courseware/transfers；POST /courseware/transfers/:id/ack | 班级端补领、逐设备回执 |
设备、系统与运维
| 路径/动作 | 行为及边界 |
|---|---|
| POST /clients/heartbeat、/clients/commands/:id/ack | 登录设备心跳/回执，校验 deviceKey 和归属 |
| POST /clients/update-progress | 设备上传下载、校验、等待、安装和失败状态，校验设备班级归属 |
| GET /clients/devices；DELETE /clients/devices/:id | 设备读取/维护，分别检查功能键和范围 |
| POST /clients/commands | remote:control + 对应范围，白名单动作 |
| POST /clients/updates | client:update-push，安装策略 immediate/after-school/idle |
| GET /update/check | 员工需 update:check；强制刷新另检查 update:force |
| GET /update/client/releases | 缓存版本读取，按路由允许的读取权限 |
| POST /update/client/fetch、/update/client/releases；DELETE /update/client/releases/:version | 安装包写入口仅管理员 client:update |
| GET /update/client/download/:version | 本班 CLASS_DEVICE 或 client:read + 有效班级范围 |
| /term；POST /term/auto；GET /term/holidays | 学期读取/编辑/假日建议，term:read/term:write |
| GET/PUT /term/promotion；POST /term/promotion/run | 升级计划与执行，promotion:manage + 全校范围，执行要求确认与计划哈希 |
| /archives、/archives/transferred、/archives/transferred/:id/restore | 历史归档需 archive:manage 全校范围；撤回转出需 roster:manage；不提供手动创建归档 |
| /database/status、/test-connection、/backups、/export、/import、/sqlite-file、/backup-schedule、/switch | database:manage；目标空库、快照及换库子进程保护 |
| /system/settings、/autostart、/diagnostics | system:manage，非安装形态自启动返回不可用原因 |
| /ai/settings、/interpret、/audit、/capabilities、/plans/:id | ai:manage/ai:use；查询遵循业务权限，写入计划确认后调用原接口，密钥只进不出 |
| /dashboard/summary、/dashboard/term | 按范围读取看板与周次 |
探针 /healthz 和 /readyz 不带 API 前缀；/api/health 提供版本与模块详情。 课件上传是原始文件流，512 MB 限制独立于表格 JSON 的 12 MB 限制；metadata 走上传查询 schema。 心跳 agentProtocol:2 使用统一响应 data，旧协议兼容字段只用于升级过渡。 更多说明见权限、实时事件、数据模型。
权限治理与学生年度流程
| 方法与路径（省略 /api） | 参数与权限边界 |
|---|---|
| GET /permissions/scopes | permission:manage；返回可选年级、部建议和计划年级 |
| GET /permissions/groups/:id/members | permission:manage；包含显式分组及角色默认回落的生效成员 |
| GET /permissions/audit?page=&pageSize= | permission:manage；分页操作人、目标、前后 JSON，pageSize 最大 100 |
| POST/PATCH/DELETE /permissions/groups[/:id] | 仅 ADMIN；仅可分配键，范围校验，教师默认模板固定 TEACHING，内置组不可删 |
| PUT /permissions/users/:id/groups | assignments 整体替换，每项 groupId/scope/scopeValue；兼容 groupIds 按建议范围分配；空数组恢复教师默认模板；ADMIN 不可分配 |
| GET /students?status=&includeArchived= | roster:read；默认 active，归档单独筛选；历史状态不会再被在读条件覆盖 |
| POST /students | roster:manage；仅 active/inactive，学号重复 409，班级不得归档 |
| PATCH /students/:id | roster:manage；仅资料字段；classId/status 明确返回 400 |
| POST /students/transfer | roster:manage；studentIds、toClassId（null 表示移出）、note；跨年级需 ADMIN、allowGradeChange=true 与备注 |
| POST /students/transfer-out | roster:manage；studentIds、note、toSchool；仅 active/inactive，毕业/归档/重复转出 409 |
| POST /students/transfer-in | roster:manage；指定 toClassId，新建用 studentNo/name，重入用 studentId；可传 fromSchool/note |
| POST /students/:id/restore | roster:manage；可传 toClassId/note；转出或停用恢复，原班归档时应另选在读班 |
| POST /archives/transferred/:id/restore | 兼容同上，权限改为 roster:manage |
| DELETE /students/:id | roster:manage；默认停用；hard=true&confirm=true 仅 ADMIN，存在业务或历史则 409 |
| GET /students/transfers；GET /students/:id/transfers | roster:read；不排除转出状态；支持 studentId/classId/batchId/academicYear 与分页 |
| GET/PUT /term/promotion | promotion:manage 全校范围；读取计划、执行时间、应执行学年与记录；保存兼容旧 month/day/hour/classCount，也接受 plan |
| POST /term/promotion/preview | promotion:manage 全校范围；year；只读返回逐轨道逐班统计、阻断项、警告、新班码、周次影响、planHash |
| POST /term/promotion/run | promotion:manage 全校范围；year、planHash、confirm:true；过去学年还须 ADMIN + catchUp:true；未来年份 400；阻断或哈希变化 409 带 details |
| POST /classes/promote | promotion:manage 与各目标范围；仅 classIds，不收自由 grade；从计划推导下一学段，毕业学段 409 |
| PATCH /classes/:id | 不再接受 grade，旧请求返回 400；改年级须走升级入口 |
| DELETE /archives/:id | archive:manage 全校范围；仅撤销归档标记，保留转出与停用状态，不回滚年级、新班及周次 |
生命周期历史以 kind 为事实源，mode 为派生兼容字段；新响应另含 batchId、academicYear、fromGrade/toGrade、fromSchool/toSchool。 归档详情含 inactive 列表、inactiveCount 和按学生去重的 transferInCount；升级记录含 operatorId/operatorName、detailsJson、snapshotSha256、error。 所有学生与历史写入在同一事务，提交后再广播旧班与新班。班级详情只有持 roster:read 且在对应范围内的员工才能获得学生明细。
分配级范围与班级设置
GET /permissions/catalog 增加 meta（kind/risk/relation/allowedScopes）。模板 DTO 的 defaultScope/defaultScopeValue/defaultScopeLabel 及兼容 scope 字段都是建议范围；kind、inactiveKeys、warnings 展示模板类别和停用键。成员 DTO 的 assignments 是实际分配，groupIds 为派生值；ADMIN fixed=true。
GET /permissions/users/:id/effective 仅 ADMIN，返回 permissions、entries（每键 scopes/classes/classCount）、conflicts、headOnlyKeys。可选 query assignments 为 JSON 数组，预览尚未保存的整体分配；预览与实际授权共用求值器。
PATCH /classes/:id/settings 使用 class:settings + 本班班主任（ADMIN 例外）保存 termWeeks/termStartDate。管理员 PATCH /classes/:id 只接收 enrollmentYear/classIndex。PATCH /classes/:id/class-account 使用 class:account + 本班班主任。全局周次仅管理员，带 classId 的周次写走 class:settings + 班主任。时间表写入按存储 classId 分流，班级时间表需要 schedule:write + 班主任，全校时间表仅管理员。
成绩 overview/collective/exams/ranking 显式检查 grade:read，班级端由服务断言限本班并执行查询开关。设备 heartbeat/update-progress/commands/:id/ack 仅接受绑定本班的 CLASS_DEVICE，不接受教师个人设备。
GET /permissions/me 同时返回 classScopes、manageScopes、allScopeKeys，供 Web 按钮与班级选择器显示实际能力范围；manageScopes 对名单、日课表、导入和考试配置叠加班主任或显式组织范围规则。界面范围提示不替代服务端断言。
AI 操作计划
跨班作业与通知会归一为逐班步骤，分别调用单班业务接口。成功班级保持成功状态，后续重试跳过这些步骤。
客户端安装包缓存允许 clients.releases 查询，以及仅限 ADMIN + client:update 的 clients.release-fetch/register/delete。写入均要求专门确认，并核对版本、已有登记及缓存文件状态。更新模块只开放固定的 /update/client/releases 查询、/update/client/fetch 抓取、/update/client/releases 登记及按版本删除；没有服务器更新、配置或任意下载地址入口。抓取复用现有官方项目下载地址与流式校验，不推送或安装。
POST /ai/interpret 接收 text、可选班级、当前会话的 messages 和附件元数据 attachments，返回 planId/message/steps/results，并保留旧响应字段的兼容形状。附件包含 id、文件名、大小与 SHA256；普通课件内容不发送给模型。
POST /ai/models 仅管理员可用，接收可选 baseUrl/apiKey（未传时使用已保存配置），通过兼容 /models 获取模型及支持的推理档位，密钥不回传。设置增加 reasoningEffort：auto/none/low/medium/high/max，auto 不附加推理参数。
后台任务接口均要求 ai:use，并校验归属及实际业务权限：
POST /ai/tasks创建任务；PUT /ai/tasks/:id/files/:attachmentId以二进制暂存已声明附件，校验大小与 SHA256，不发布课件。POST /ai/tasks/:id/start提交后台规划，完整附件上传后才允许开始。GET /ai/tasks列出本人最近任务；GET /ai/tasks/:id读取状态并重新授权结果数据。GET /ai/tasks/:id/events以 SSE 返回status/message/result/error，关闭连接仅停止订阅，不取消任务。POST /ai/tasks/:id/execute接收与计划确认相同的确认字段，后台逐步调用白名单业务接口，使用持久步骤去重。失败停止后续依赖项，重试不重做成功步骤。POST /ai/tasks/:id/stop主动停止后台任务；已发出的业务请求可完成，后续步骤停止。
后台任务保存在 AiTask，输入、结果与进度加密，纳入快照并兼容旧快照缺表。助手页面统一使用后台任务接口。服务重启保留任务，未知业务执行结果须核对后继续。
GET /ai/capabilities：当前操作者可用的动作及参数契约，目录不包含数据库维护、服务器运维和密钥操作。GET /ai/plans/:id：本人计划和分步状态；业务权限及范围重新校验。POST /ai/plans/:id/prepare：结构化附件经哈希核对后复用原导入解析器生成预览，不发布业务数据。POST /ai/plans/:id/confirm：提交明确确认、必要的高影响操作确认和专用敏感字段；返回绑定后的业务请求。DELETE /ai/plans/:id：取消尚未执行的步骤。
前端以 x-classhelper-ai-step 关联既有业务接口。服务端核对操作者、方法、路径、查询和正文后原子领取步骤，再由原接口执行完整鉴权。上传另核对文件哈希；已成功步骤返回保存的结果，不重复操作。连接中断或结果不明的步骤需先核对业务状态。自动化入口为 pnpm verify:ai，仅使用隔离库和模型 stub。