feat: 完善学生生命周期管理与权限范围并发布 1.4.2

2026-10-23 22:55:21 +08:00
1 parent 6347d1e5aa
commit 24e8dd902b
@@ -19,8 +19,8 @@ description: 名单、班级会话、任课关系与年度升级。

 Student 存学号、姓名、班级、性别、家长电话和状态，没有密码或角色字段。
 学号为必填唯一标识，格式为 1–32 位字母、数字或 . _ -；不会自动生成登录名。
-管理员或本班班主任在具备名单管理权限后管理学生，教师也可按授权范围只读名单。
-名单表格导入仍要求管理员及相应导入权限；学号查重在 Student 表完成，不当成 User 用户名。
+具有名单管理键的管理员、本班班主任或全校名单范围的授权员工管理学生；只读账号按名单读取键和范围查看历史。
+名单表格导入要求 import:students、roster:manage 和对应班级范围；学号查重在 Student 表完成，不当成 User 用户名。
 调班保留历史内容原归属；转出独立记账并从现行业务名单过滤，学号不可复用。

 ## 教师与科目
@@ -39,5 +39,26 @@ Student 存学号、姓名、班级、性别、家长电话和状态，没有密
 范围不代替科目写权限，详见[角色与权限](../dev/permissions.md)。
 学期周数受全校可配置上限约束，默认上限 30、允许 1–60，见[课表](schedules.md)。
 学年升级按计划时间运行，执行前保存快照，以年份幂等；启动发现漏跑需管理员预览补跑。
-高三归档、高一/高二升一级，新高一不复制任课关系。归档页查看届别历史与转出记录，
-不再通过手动创建归档来代替年度升级。撤回转出等操作仍受归档与管理员业务检查约束。
+默认高中轨道按高一、高二、高三排列，毕业学段归档，其余升一级；也可配置其他轨道。新班不复制任课关系。归档页查看届别历史与转出记录，
+不再通过手动创建归档来代替年度升级。撤回转出由 roster:manage 控制，原班归档后可指定其他在读班。
+
+## 学生生命周期
+
+资料编辑仅修改学号、姓名、性别与家长电话，不接受状态或班级字段；旧客户端发送这两项会收到 400 和专用接口提示。
+默认名单只显示未归档的 active；状态筛选可查看 inactive、transferred、graduated，“包含归档”另行控制归档标记。
+
+调班、转出、转入、复学、撤回与移出班级均在一个事务内修改学生并写历史，包含批次、学年、原新班级与年级、来源去向学校、操作人和备注。
+调班需同时覆盖源班与目标班；跨年级须管理员勾选允许跨年级并填写备注。目标班必须在读。
+转出保留原班及业务历史，只接受在读或停用学生。转入支持新建学号或选择转出/停用学生，毕业或归档学生不能通过名单入口复活。
+撤回转出可选择另一个在读班，原历史保留。默认删除动作改为停用；硬删除另须管理员确认且无成绩、作业、已读或历史。
+
+## 升级预览与执行
+
+“学年升级”页面独立要求 promotion:manage，全校范围。先保存轨道、有序年级、起始班数、执行时间、开学日和周次重置策略，再预览逐班影响。
+预览包含在读/停用/转出人数、新班码、周次删除行数、阻断和警告、计划哈希。未知年级、缺失届别、重复班号、已有届别档案或新班码冲突会阻断执行。
+执行需确认学年和预览哈希；业务或配置变化后必须重新预览。未来学年禁止执行，过去学年仅 ADMIN 明确补跑。
+
+毕业班所有学生挂届别：在读转毕业，转出和停用保留状态；非毕业班只升到下一学段并清本班开学日覆盖。
+新班只有骨架，开学日取计划值（未配置时为执行学年 9 月 1 日）。保留周次时，旧逐周区间会继续覆盖新学年，页面会警告。
+同年执行幂等，执行记录显示操作人、快照路径、SHA256、明细与错误。快照失败不升级，失败事务回滚后可修正重试。
+撤销归档只清标记并将毕业生恢复在读，转出/停用不变；不回滚年级、不删除新班、不恢复已清空周次，整学年恢复需管理员手工使用快照。
@@ -8,9 +8,13 @@ description: 日课表、共享作息、轮换、临时换课和教学周。
 Web 管理端统一从「教学事务 → 课表档案」查看周课表并编辑时间表与日课表，客户端提供“今天”时间轴和“本周”视图。
 上课状态、灵动岛课程提醒和紧急通知确认共用服务端的课表判定。

-编辑工作区参照 [CsesWebEditor](https://github.com/SmartTeachCN/CsesWebEditor) 的资源列表、设置卡片、课时列表与快速选科布局实现。左侧集中切换课程表、时间表、科目、群组与预定、整周预览和文件预览。旧管理页地址 `/schedules` 自动进入同一工作区。
+编辑工作区参照 [ClassIsland 档案编辑器](https://github.com/ClassIsland/ClassIsland/blob/master/ClassIsland/Views/ProfileSettingsWindow.axaml) 的布局与交互实现，使用独立的深色全屏工作区。顶部切换课表、时间表、科目和调课；默认以周网格展示课程，右侧提供科目简称面板，底部可切换列表、周和月视图。旧管理页地址 `/schedules` 自动进入同一工作区，点击「返回管理」回到管理端。

-点击课时后可用右侧科目按钮快速填充；拖动课时交换课程，拖动时间点调整时间表顺序，完成后保存。时间表支持任意分钟输入；设置的课程/课间分钟数会用于新建时间点的默认起止时间。完整档案可在页头导入或导出 JSON，保留轮换、时间点类型、空课、停用、群组和预定。
+点击每天列头的「新课表」选择时间表并创建日课表。点击网格中的课时后可用右侧科目按钮快速填充，支持选择是否自动移动到下一节；方向键可移动焦点，Delete 可清空选中课程。课表名称、时间表、启用星期、轮换规则、生效周次与群组在「详细信息」中维护。
+
+列表视图保留批量排课、复制粘贴、拖动交换课程等操作；时间表页支持拖动时间点排序、任意分钟输入，以及上课、课间、分割线、行动四种时间点。设置的课程/课间分钟数用于新建时间点的默认起止时间。编辑完成点击「保存」或按 Ctrl+S；切周与实时刷新保留草稿，切换班级和离开页面时提醒未保存的修改。
+
+完整档案可在页头「导入/导出」中导入或导出 JSON，保留轮换、时间点类型、空课、停用、群组和预定。月视图提供日期导航，点击日期后由服务端解析教学周并进入周视图。

 ## 日课表与时间表

@@ -12,66 +12,96 @@ API 前缀 /api，JWT 使用 Authorization: Bearer。成功/失败结构以 `lib

 ## 身份与班级

-| 方法与路径（省略 /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:manage 与管理员业务断言            |
-| PATCH /classes/:id/class-account、/classes/:id/head-teacher             | 班级凭据/班主任维护                                            |
-| 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                              | 当前有效权限、目录、组与账号分组                               |
+| 方法与路径（省略 /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             | 班级凭据/班主任维护                                                               |
+| 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 | 复制、导入导出及完整档案导入                                           |
-| /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 | [成绩与隐私](../app/grades.md)，查询列表参数用 studentId，写入仍按科目 |
-| /imports/template、/table/preview、/table/commit                                                           | 表格导入，按 kind 再检查角色、导入权限、班级和科目                     |
-| /imports/class-plan/preview、/imports/class-plan                                                           | 旧预览与完整档案提交；提交走关系化导入                                 |
-| /imports/time-layout[/:id]、/time-layout/preview                                                           | 时间配置兼容入口，写入/删除需 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                                              | 班级端补领、逐设备回执                                                 |
+| 路径/动作                                                                                                  | 行为及边界                                                                           |
+| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| /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 | [成绩与隐私](../app/grades.md)，查询列表参数用 studentId，写入仍按科目               |
+| /imports/template、/table/preview、/table/commit                                                           | 表格导入，按 kind 再检查对应导入键、管理键、班级和科目                               |
+| /imports/class-plan/preview、/imports/class-plan                                                           | 预览与提交均需 import:schedule + schedule:write；提交走关系化导入                    |
+| /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，安装策略 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                                                                    | 已登录下载，不挂员工权限键，供班级端更新                             |
-| /term；POST /term/auto；GET /term/holidays                                                              | 学期读取/编辑/假日建议，term:read/term:write                         |
-| GET/PUT /term/promotion；POST /term/promotion/run                                                       | 升级计划、预览和执行，system:manage，执行还做业务校验                |
-| /archives、/archives/transferred、/archives/transferred/:id/restore                                     | 历史归档与撤回转出，archive: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                                                                        | ai:manage/ai:use；只解析待确认动作，密钥只进不出                     |
-| /dashboard/summary、/dashboard/term                                                                     | 按范围读取看板与周次                                                 |
+| 路径/动作                                                                                               | 行为及边界                                                                       |
+| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| 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，安装策略 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                                                                    | 已登录下载，不挂员工权限键，供班级端更新                                         |
+| /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                                                                        | ai:manage/ai:use；只解析待确认动作，密钥只进不出                                 |
+| /dashboard/summary、/dashboard/term                                                                     | 按范围读取看板与周次                                                             |

 探针 /healthz 和 /readyz 不带 API 前缀；/api/health 提供版本与模块详情。
 课件上传是原始文件流，512 MB 限制独立于表格 JSON 的 12 MB 限制；metadata 走上传查询 schema。
 心跳 agentProtocol:2 使用统一响应 data，旧协议兼容字段只用于升级过渡。
 更多说明见[权限](permissions.md)、[实时事件](realtime.md)、[数据模型](data-model.md)。
+
+## 权限治理与学生年度流程
+
+| 方法与路径（省略 /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]          | permission:manage；范围校验与防提权；默认组仅 ADMIN 可改，内置组不可删                                                                  |
+| PUT /permissions/users/:id/groups                    | groupIds 整体替换；默认组角色须匹配，空数组恢复角色默认模板；禁止越键越范围                                                             |
+| 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 且在对应范围内的员工才能获得学生明细。
@@ -10,42 +10,43 @@ description: 现行模型职责、迁移与快照边界。

 ## 模型职责

-| 模型                   | 职责                                               |
-| ---------------------- | -------------------------------------------------- |
-| `User`                 | 教师与管理员账号；学生不在此表，班级凭据在 Class   |
-| `Student`              | 学生名单、学号、在读/转出/毕业状态，无密码和角色   |
-| `StudentClassTransfer` | 调班与转出历史，保留班级/姓名快照                  |
-| `ArchivedYear`         | 毕业届别与统计快照                                 |
-| `TermWeek`             | 逐周日期区间，classId 空串为全校默认               |
-| `Class`                | 班级、班级码/密码、班主任、周数与成绩查询开关      |
-| `Course`               | 班级+科目+教师任课关系，含简称和室外标记           |
-| `Schedule`             | 旧课表迁移审计来源，现行接口不再以它为业务真值     |
-| `Homework`             | 作业与本地 assignDate；dueAt 为遗留列              |
-| `HomeworkStatus`       | 按 studentId 记录作业完成状态                      |
-| `Notification`         | 通知/叫人记录、优先级与本地 assignDate             |
-| `NotificationRead`     | 按 studentId 记录已读                              |
-| `TimeLayout`           | 共享或班级自有时间表；旧 items JSON 保留迁移审计   |
-| `Grade`                | studentId、课程、考试、分数和等级                  |
-| `PermissionGroup`      | 默认/自定义/岗位组及 scope/scopeValue              |
-| `PermissionGroupItem`  | 组内权限键                                         |
-| `UserPermissionGroup`  | 账号与组的多对多分配                               |
-| `AppSetting`           | 周次、升级、AI 和系统设置                          |
-| `ClientDevice`         | deviceKey、心跳、更新目标与状态                    |
-| `ClientCommand`        | 白名单远控、有效期与执行回执                       |
-| `ClientRelease`        | 服务端缓存安装包、SHA256 与大小                    |
-| `AiAudit`              | 助手解析审计，不保存 API Key                       |
-| `Exam`                 | 考试名称与是否计入总分                             |
-| `TimeLayoutItem`       | 有序时间点及类型，被课程显式引用                   |
-| `ClassPlanGroup`       | 班级课表群组、全局/默认标记                        |
-| `ClassPlan`            | 日课表、时间表、轮换、启用与临时层规则             |
-| `ClassPlanEntry`       | 日课表与时间点、课程的外键关联、空课/停用/换课标记 |
-| `ScheduledClassPlan`   | 按本地日期预定日课表                               |
-| `PromotionRun`         | 年度升级幂等与审计                                 |
-| `Courseware`           | 文件元数据、上传教师、存储路径与 SHA256            |
-| `CoursewareFolder`     | 教师自建分类目录，按上传者隔离                     |
-| `CoursewareVisibility` | 课件可见班级                                       |
-| `CoursewarePush`       | 按班级的推送任务                                   |
-| `CoursewareReceipt`    | 按设备的课件接收回执                               |
+| 模型                   | 职责                                                |
+| ---------------------- | --------------------------------------------------- |
+| `User`                 | 教师与管理员账号；学生不在此表，班级凭据在 Class    |
+| `Student`              | 学生名单、学号、在读/转出/毕业状态，无密码和角色    |
+| `StudentClassTransfer` | 生命周期历史，kind/batchId/学年/班级年级及学校快照  |
+| `ArchivedYear`         | 毕业届别与统计快照                                  |
+| `TermWeek`             | 逐周日期区间，classId 空串为全校默认                |
+| `Class`                | 班级、班级码/密码、班主任、周数与成绩查询开关       |
+| `Course`               | 班级+科目+教师任课关系，含简称和室外标记            |
+| `Schedule`             | 旧课表迁移审计来源，现行接口不再以它为业务真值      |
+| `Homework`             | 作业与本地 assignDate；dueAt 为遗留列               |
+| `HomeworkStatus`       | 按 studentId 记录作业完成状态                       |
+| `Notification`         | 通知/叫人记录、优先级与本地 assignDate              |
+| `NotificationRead`     | 按 studentId 记录已读                               |
+| `TimeLayout`           | 共享或班级自有时间表；旧 items JSON 保留迁移审计    |
+| `Grade`                | studentId、课程、考试、分数和等级                   |
+| `PermissionAudit`      | 权限与人工升级审计，操作人和前后 JSON，不建账号外键 |
+| `PermissionGroup`      | 默认/自定义/岗位组及 scope/scopeValue               |
+| `PermissionGroupItem`  | 组内权限键                                          |
+| `UserPermissionGroup`  | 账号与组的多对多分配                                |
+| `AppSetting`           | 周次、升级、AI 和系统设置                           |
+| `ClientDevice`         | deviceKey、心跳、更新目标与状态                     |
+| `ClientCommand`        | 白名单远控、有效期与执行回执                        |
+| `ClientRelease`        | 服务端缓存安装包、SHA256 与大小                     |
+| `AiAudit`              | 助手解析审计，不保存 API Key                        |
+| `Exam`                 | 考试名称与是否计入总分                              |
+| `TimeLayoutItem`       | 有序时间点及类型，被课程显式引用                    |
+| `ClassPlanGroup`       | 班级课表群组、全局/默认标记                         |
+| `ClassPlan`            | 日课表、时间表、轮换、启用与临时层规则              |
+| `ClassPlanEntry`       | 日课表与时间点、课程的外键关联、空课/停用/换课标记  |
+| `ScheduledClassPlan`   | 按本地日期预定日课表                                |
+| `PromotionRun`         | 年度升级幂等与审计                                  |
+| `Courseware`           | 文件元数据、上传教师、存储路径与 SHA256             |
+| `CoursewareFolder`     | 教师自建分类目录，按上传者隔离                      |
+| `CoursewareVisibility` | 课件可见班级                                        |
+| `CoursewarePush`       | 按班级的推送任务                                    |
+| `CoursewareReceipt`    | 按设备的课件接收回执                                |

 学生和账号分离：Student 没有密码/角色；教师/管理员存 User，CLASS_DEVICE 只是 Class 登录形成的会话。
 任课关系只在 Course；班主任关系在 Class.teacherId，可以与任课关系指向同一账号。
@@ -73,3 +74,14 @@ User.careMode 是预留列；当前 Web 偏好在 localStorage，客户端偏好
 2. 核对外键级联与删除护栏，特别是教师的班级、课程、作业、通知和课件。
 3. 在临时库验证新建和旧库升级；不对真实业务库运行 seed/reset。
 4. 重新生成 Prisma Client，并按修改范围执行[验收](testing.md)。
+
+## 权限与生命周期迁移
+
+`20261023000000_promotion_permission` 为已初始化的 ADMIN 默认组补 promotion:manage；默认组尚未创建时允许不插入，由运行时模板创建。
+`20261023010000_student_lifecycle_audit` 增加 PermissionAudit、StudentClassTransfer 的批次/学年/班级年级/学校快照、ArchivedYear.inactiveCount、PromotionRun 的操作人/明细/摘要/错误。
+旧 mode 按 single/batch → class-change、transfer-out → transfer-out、restore-transfer → restore 迁移后删除该列，避免双事实源。
+旧行的新字符串为空，学年为空，统计默认零；不臆造无法恢复的历史年级或批次。
+
+SNAPSHOT_TABLES 已加入 PermissionAudit，新增字段随模型导出。旧快照没有审计表可恢复为空，旧历史 mode 在恢复时转为 kind；
+没有新增列的旧行使用 schema 默认值。执行记录与升级快照不自动清理。
+升级计划存 AppSetting.term.promotionPlan，时间存 term.promotionAt，无需新增学校或学生账号模型。
@@ -21,7 +21,7 @@ description: 课表、周次、学年、岛、设备与课件的现行实现入
 默认权限组、岗位范围、科目写权限分别由 permissions/permission-scope/access 维护，范围并集不授予任课权。
 全校周数上限在 `term.maxWeeks`，默认 30、允许 1–60；开学日和逐周区间支持全校与班级设置。
 个人成绩查询关闭后只返回服务端集体聚合，个人明细、原始全班成绩与排名拒绝读取；样本不足或稀疏分段抑制。
-年度升级由 `term.promotionAt` 和 `PromotionRun.year` 管理，先存快照；运行期到点执行，启动漏跑需管理员预览补跑。
+年度升级由 `term.promotionPlan`、`term.promotionAt` 和 `PromotionRun.year` 管理，先存快照；运行期到点执行，启动漏跑需管理员预览补跑。
 毕业班归档，其余升一级，新班不复制任课关系。转出学生由 `lib/students.ts` 统一过滤。

 ## 岛与本机配置
@@ -38,3 +38,15 @@ description: 课表、周次、学年、岛、设备与课件的现行实现入
 更新从服务端缓存下载，客户端验 SHA256，按下发策略安装；远控白名单动作执行后回执，测试只用假执行器。
 课件上限 512 MB，服务端流式落盘后创建元数据和推送，客户端逐设备验摘要并回执，不自动运行文件。
 JSON 快照含课件表，完整恢复还必须带文件实体目录。细节见[课件](../app/courseware.md)。
+
+## 学生与权限写入契约
+
+学生状态/班级写入口集中在 `lib/student-lifecycle.ts`，班级名单添加/移出、名单导入、转出和转入均复用它。
+资料 PATCH 不承担状态或班级迁移。学生与历史在事务内提交，UUID 标识批次，事务后广播两端班级，历史读取不附带在读过滤。
+权限、功能对应范围、业务关系依次断言；权限只在当前请求对象上复用，下一请求重新计算。
+范围解析在 shared，默认组或分组均按当前功能键过滤，不能借另一功能的范围扩大当前操作。
+权限组或成员分配与 PermissionAudit 同事务，成员权限一次预取计算。
+
+年度升级服务由计划推导所有轨道的下一学段。预览哈希覆盖配置、班级、学生和周次，执行事务内重新计算；
+先保存全库快照并计算 SHA256，再以年份唯一键提交升级。毕业班所有状态挂届别，非毕业班仅升级及清班级开学日覆盖。
+周次是否清空由计划决定，预览公开影响。服务保留 runPromotion(year, dryRun) 内部兼容签名；HTTP 执行必须提供哈希、确认并检查年份。
@@ -35,22 +35,23 @@ HEAD/SUBJECT 是班级关系，级长/部长是岗位组，均不新增 User.rol
 | 部长        | 配置的一组年级，scopeValue 用逗号分隔         |
 | 班级端      | 登录绑定班级                                  |

-空年级/部配置不放行。设备写操作只合并含对应功能键的分组范围，不能借只读组扩权。
+空年级/部配置不放行。范围按当前功能键独立合并，不能借其他只读组扩大名单、班级或设备写权限。
 科目编辑再由 `assertCanManageSubjectContent` 检查：管理员可管理，教师仅自己任课科目，无科目内容归班主任。
 班主任不任教某科就不能改该科的作业或成绩；班级端只允许作业写入，不能写成绩。

-| 业务             | 主要功能键与额外边界                                                         |
-| ---------------- | ---------------------------------------------------------------------------- |
-| 名单读取/管理    | roster:read / roster:manage；管理仍须管理员或本班班主任断言                  |
-| 教师列表/维护    | teacher:read / teacher:manage；导入名单另检查导入权限和角色                  |
-| 日课表写入       | schedule:write + 管理员/本班班主任                                           |
-| 全校时间表写入   | timetable:manage；默认给 ADMIN                                               |
-| 作业/成绩        | homework:write / grade:write 或 grade:import，再按班级科目收口               |
-| 通知/叫人        | notification:publish / call:create，再检查班级范围                           |
-| 课件             | courseware:read / courseware:write，上传和推送自己的文件还受本人授课班级约束 |
-| 客户端维护/远控  | client:read、client:manage、remote:control，写操作按对应键范围               |
-| 版本与安装包写入 | client:update；旧 client:update-push 不再作为写入口要求                      |
-| 数据库/系统/权限 | database:manage / system:manage / permission:manage                          |
+| 业务             | 主要功能键与额外边界                                                                                  |
+| ---------------- | ----------------------------------------------------------------------------------------------------- |
+| 名单读取/管理    | roster:read / roster:manage；管理需名单键与目标班范围；关联班级仍须班主任关系，全校名单范围可跨班维护 |
+| 教师列表/维护    | teacher:read / teacher:manage；导入教师另检查 import:teachers 与 teacher:manage                       |
+| 日课表写入       | schedule:write + 管理员/本班班主任                                                                    |
+| 全校时间表写入   | timetable:manage；默认给 ADMIN                                                                        |
+| 作业/成绩        | homework:write / grade:write 或 grade:import，再按班级科目收口                                        |
+| 通知/叫人        | notification:publish / call:create，再检查班级范围                                                    |
+| 课件             | courseware:read / courseware:write，上传和推送自己的文件还受本人授课班级约束                          |
+| 客户端维护/远控  | client:read、client:manage、remote:control，写操作按对应键范围                                        |
+| 版本与安装包写入 | client:update；旧 client:update-push 不再作为写入口要求                                               |
+| 学年升级         | promotion:manage；计划、预览与执行独立授权，全校范围，默认给 ADMIN                                    |
+| 数据库/系统/权限 | database:manage / system:manage / permission:manage                                                   |

 完整键目录读取 `PERMISSION_KEYS`，不在文档维护固定键数。

@@ -67,3 +68,22 @@ Web 菜单属性来自路由，`meta.roles` 粗筛、`meta.permission` 细筛；
 `/api/clients/heartbeat` 和命令回执供已登录设备使用，不依赖班级端的空权限集合；服务端校验 deviceKey 与班级归属。
 远控从管理端确认下发，客户端执行后回传真实结果。更新文件由服务端缓存，教室机验 SHA256，
 按立即、放学后、空闲策略安装；关闭自动更新不会强制安装。详见[更新与升级](../management/upgrade.md)。
+
+## 范围配置与权限治理
+
+范围由 shared 的 `parsePermissionScope` 统一解析。关联班级只接受空值（班主任与任课班）或 HEAD（仅班主任班）；
+GRADE 必选一个年级，DIVISION 必选多个年级组成的集合；全角逗号、顿号和空白统一分隔、去重排序。
+ALL 存空范围值。年级选项来自数据库已有年级和升级计划，空范围或未知年级返回 400；旧库未配置的岗位组不放行。
+`GET /permissions/scopes` 提供选择器选项，组 DTO 的 scopeLabel 供页面展示。
+
+默认组只能分配给同角色；非 ADMIN 的权限管理员只能管理关联班级范围的自定义组，
+组原有键和新键均不得超过自己当前权限。角色默认组只有 ADMIN 可改；删除组可能触发默认回落，仅 ADMIN 可执行。
+分配空数组恢复数据库角色默认组，分配任何组则仅取所选组并集；需要保留默认时显式同时选择同角色默认组。
+
+权限页保存前展示成员与权限差异，支持复制组、查看生效成员和分页审计。
+PermissionAudit 在组或分配事务中保存操作人、目标、前后 JSON；`GET /permissions/audit` 受 permission:manage 控制。
+成员权限由一次预取组和账号后计算，不逐账号重复加载。
+
+新增迁移为旧库已有 ADMIN 默认组补 promotion:manage；新库由默认模板创建。
+自定义组和已分配其他组的管理员不会自动获得该键，需要在权限页显式授予。
+班级端权限仍为空，本班名单、课表、通知、叫人和作业代录走显式员工守卫例外；班级端发布内容归属本班班主任。
@@ -10,23 +10,24 @@ description: 隔离 API、隐藏 UI、后台客户端与显式视觉验收。

 ## 命令与前置条件

-| 命令                                             | 覆盖/前置条件                                                     |
-| ------------------------------------------------ | ----------------------------------------------------------------- |
-| pnpm lint / pnpm typecheck / pnpm check:icons    | 静态检查；typecheck 会先构建 shared                               |
-| pnpm docs:check                                  | docfx 严格构建，需 .NET SDK 与 docfx                              |
-| pnpm verify:e2e                                  | 自动临时 SQLite、种子和带前缀账号，启动随机端口服务；无需真实服务 |
-| pnpm verify:web:isolated                         | 同上隔离服务，隐藏 Electron UI 回归；先构建 Web 产物              |
-| pnpm verify:web                                  | 连接已准备测试服务，需 Web 产物和测试管理员；不应指向业务服务     |
-| pnpm verify:v14                                  | 临时库验证关系课表、周次、范围、隐私与升级等                      |
-| pnpm verify:courseware                           | 临时库和文件目录的课件专项，不向真实班级推送                      |
-| pnpm verify:client-agent                         | 假系统适配器验证命令、回执和更新策略                              |
-| pnpm verify:client-migrations                    | 临时旧库验证迁移、联动退役与默认组持久化                          |
-| pnpm verify:review-client                        | 无窗口逻辑回归                                                    |
-| pnpm verify:review-api / pnpm verify:clients-api | 需明确准备的隔离测试服务，使用 VERIFY_BASE_URL 等脚本参数         |
-| pnpm verify:desktop                              | 先 pnpm build:desktop；隐藏快速检查，独立 userData                |
-| pnpm verify:desktop:online                       | 显式联网，需要测试管理员并创建临时教师/班级                       |
-| pnpm verify:desktop:visual                       | 显式使用桌面，完整岛几何/动画/透明度/截图检查                     |
-| pnpm verify:packaged --exe <客户端EXE>           | 默认快速离线，两次启动、packaged=true；--visual 才使用桌面        |
+| 命令                                             | 覆盖/前置条件                                                                |
+| ------------------------------------------------ | ---------------------------------------------------------------------------- |
+| pnpm lint / pnpm typecheck / pnpm check:icons    | 静态检查；typecheck 会先构建 shared                                          |
+| pnpm docs:check                                  | docfx 严格构建，需 .NET SDK 与 docfx                                         |
+| pnpm verify:e2e                                  | 自动临时 SQLite、种子和带前缀账号，启动随机端口服务；无需真实服务            |
+| pnpm verify:web:isolated                         | 同上隔离服务，隐藏 Electron UI 回归；先构建 Web 产物                         |
+| pnpm verify:web                                  | 连接已准备测试服务，需 Web 产物和测试管理员；不应指向业务服务                |
+| pnpm verify:lifecycle                            | 临时 SQLite 验证权限治理、事务故障回滚、状态机、历史、多轨道、计划哈希和快照 |
+| pnpm verify:v14                                  | 临时库验证关系课表、周次、范围、隐私与升级等                                 |
+| pnpm verify:courseware                           | 临时库和文件目录的课件专项，不向真实班级推送                                 |
+| pnpm verify:client-agent                         | 假系统适配器验证命令、回执和更新策略                                         |
+| pnpm verify:client-migrations                    | 临时旧库验证迁移、联动退役与默认组持久化                                     |
+| pnpm verify:review-client                        | 无窗口逻辑回归                                                               |
+| pnpm verify:review-api / pnpm verify:clients-api | 需明确准备的隔离测试服务，使用 VERIFY_BASE_URL 等脚本参数                    |
+| pnpm verify:desktop                              | 先 pnpm build:desktop；隐藏快速检查，独立 userData                           |
+| pnpm verify:desktop:online                       | 显式联网，需要测试管理员并创建临时教师/班级                                  |
+| pnpm verify:desktop:visual                       | 显式使用桌面，完整岛几何/动画/透明度/截图检查                                |
+| pnpm verify:packaged --exe <客户端EXE>           | 默认快速离线，两次启动、packaged=true；--visual 才使用桌面                   |

 联网 packaged 使用 --online；调用方须预先准备隔离服务、临时教师和班级并显式注入凭据，该启动器不会自动创建它们。
 开发版 verify:desktop:online 则通过 provisionSmokeClass 创建和清理临时身份。--offline 保持离线。
@@ -42,6 +43,8 @@ pnpm check:icons
 pnpm docs:check
 pnpm verify:e2e
 pnpm verify:v14
+pnpm verify:lifecycle
+pnpm verify:client-migrations
 pnpm verify:courseware
 pnpm build:desktop
 pnpm verify:desktop
@@ -67,3 +70,7 @@ docs/images 为 README/文档展示图；docs/screenshots 为回归留档；webs
 Web 采集入口 `website/tools/capture-shots.mjs`，先准备隔离测试服务和数据。
 岛/客户端采集使用 smoke.mjs --visual，并按需 --online；ISLAND_SHOTS_DIR 与 ELECTRON_CLIENT_SHOTS_DIR 指向临时目录。
 日常 quick 模式不会生成完整视觉截图，不能把 quick 通过表述为动画/透明度已验证。
+
+权限与年度流程回归入口为 `scripts/verify-lifecycle.mjs`，为子进程指定临时库与测试密钥，不使用业务 .env 的登录凭据。
+旧库升级脚本动态读取最新迁移，另建重构前夹具校验 ADMIN 默认组补键、历史 kind 映射、空组保留及重复启动。
+事务回滚用 SQLite 触发器模拟历史写入失败，不能通过删除断言或放宽状态规则通过测试。
@@ -12,16 +12,16 @@ description: 登录、菜单分组、权限与移动布局。

 侧栏按以下分组组织，具体页面由路由权限筛选，并支持浅色/深色和关怀模式。

-| 分组       | 主要页面                                           |
-| ---------- | -------------------------------------------------- |
-| 工作台     | 仪表盘、AI 助手                                    |
-| 教学事务   | 课表、时间表与日课表编辑、作业、通知、课件、成绩   |
-| 班级与人员 | 班级、学生、教师、只读学生名单、学期周次、毕业归档 |
-| 设备运维   | 客户端在线状态、命令、更新与安装策略               |
-| 系统管理   | 权限组、系统设置、大模型设置、数据库管理           |
+| 分组       | 主要页面                                                     |
+| ---------- | ------------------------------------------------------------ |
+| 工作台     | 仪表盘、AI 助手                                              |
+| 教学事务   | 课表、时间表与日课表编辑、作业、通知、课件、成绩             |
+| 班级与人员 | 班级、学生、教师、只读学生名单、学期周次、学年升级、毕业归档 |
+| 设备运维   | 客户端在线状态、命令、更新与安装策略                         |
+| 系统管理   | 权限组、系统设置、大模型设置、数据库管理                     |

-班级/学生/教师管理、学期周次、归档和数据库页面还有管理员角色门槛；
-教师只读名单、教学页与设备页按权限键和数据范围开放。
+班级、学生、学期周次、学年升级和归档页面按各自生效权限开放；教师管理和数据库页面仍保留角色门槛。
+名单、教学页与设备页还按对应数据范围开放，写按钮需额外管理键。
 每次操作服务端继续校验，不是显示菜单就能改所有班和科目。详见[角色与权限](../dev/permissions.md)。
 顶栏提供本人密码、使用引导、检查更新与退出等入口。

@@ -32,3 +32,7 @@ description: 登录、菜单分组、权限与移动布局。
 同局域网手机填写服务器局域网地址，不用 localhost；公网反代见[生产部署](../management/production.md)。

 下一步：[建班级、排课表](setup-class.md)。
+
+权限页选组会替代角色默认模板，保存前可查看新增/移除权限与影响成员；保留默认能力时同时选择同角色默认组。
+名单页默认在读，历史状态与包含归档分开筛选；资料编辑、调班、转出、转入/复学各有专用入口。
+学年升级先保存计划、预览阻断项和周次影响，再输入学年确认执行；执行记录保留快照与 SHA256。