云学院上游组件与 edu_user 迁移设计

更新：2026-10-27

目标与边界

后端采用 com.wulicode.weiran:weiran-dependencies:0.2.10 管理公共组件版本，并从 GitHub Packages 获取 weiran-framework、weiran-system、weiran-region。本仓只编译 weiran-education 五层业务模块。参考项目为 qidian-zhongxi/mono4j。

sys_user 归上游系统模块管理，承载系统后台账号。edu_user 归云学院管理，承载平台管理员、学校管理员、老师和学生账号；四种身份用角色码区分，不接学校单点登录。

账号与授权

角色	账号表	登录入口	数据范围
系统超级管理员	sys_user	/api-backend/n/system/auth/login	系统后台
平台管理员	edu_user，role=ykt_platform_admin	/api-backend/n/education/auth/login	云学院平台
学校管理员	edu_user，role=ykt_school_admin	/api-backend/n/education/auth/login	所在学校
老师	edu_user，role=ykt_teacher	同上	所在学校与任教班级
学生	edu_user，role=ykt_student	同上	所在学校与主班

edu_user 保存登录名、BCrypt 密码摘要、角色、启停状态和 token_version。新建账号会检查与已启用系统后台账号的登录名冲突。edu_school_user 保存学校账号的归属及学号；平台管理员不关联学校。登录和每次认证都核对账号状态；学校账号另核对学校归属及学校状态。令牌使用单独的 edu. 前缀和 HMAC 签名；统一认证拦截器按前缀转发给云学院或上游认证器。角色的接口权限沿用 sys_role、sys_role_menu 和 sys_menu 中的 ykt_* 菜单授权；业务服务再次检查学校和班级范围。

2026-11-03 调整：四类云学院账号都属于前台用户，统一存于 edu_user，user_type=web；系统后台账号仍存于 sys_user。身份与数据范围由角色码及学校/班级归属决定。增量迁移 V202611030001 将旧平台管理员复制到 edu_user，保留 ID，撤回旧后台角色，并在系统后台新增“前台用户”菜单，可管理平台和各学校账号。新库没有旧平台管理员时，由系统超级管理员在此页面开通首个前台平台管理员。前台登录只使用云学院认证入口。

密码重置、账号禁用、学校停用和退出登录递增 token_version，使已签发的云学院令牌失效。浏览器沿用上游 HttpOnly 认证 Cookie 和 CSRF Cookie。学校恢复只恢复停用前启用的账号。

数据迁移

Flyway V202610272200__education_user.sql 在上游 V202610271900 和 V202610272100 后运行，迁移学校管理员、老师和学生。后续 V202611030001 迁移平台管理员。两次迁移均保留旧 ID；随后撤销旧 sys_user 的对应云学院角色，并禁用仅有云学院角色的旧后台账号。拥有其他后台角色的旧账号可继续使用后台能力，云学院身份由 edu_user 承接。

原有 23 张 edu_* 业务表保持原名，新增账号表同样使用 edu_ 前缀。历史 Flyway 脚本保持原样以保留校验值。

新 edu_user 的自增 ID 从 1000000000000 开始，避免与历史 sys_user ID 交叠。教育业务中的账号读取、学校停用和硬删除均改为操作 edu_user。硬删除学校时删除其云学院账号及业务数据，不删除仍有其他后台角色的 sys_user 记录。

升级前备份数据库；回滚应用版本时同时恢复升级前数据库备份，不能只回滚镜像。若旧数据中有多个云学院账号共用登录名或手机号、一个账号持有多个云学院角色，迁移会因唯一约束或角色歧义失败，应先清理冲突后重试。上游 V202610271900 还要求旧 backend/web 账号在用户名及手机号上全局唯一；须先通过该上游迁移。

构建与发布

本地 Gradle 使用 gpr.user、gpr.key 或 GITHUB_ACTOR、GITHUB_TOKEN 读取 GitHub Packages。镜像工作流使用 WEIRAN_PACKAGES_USER、WEIRAN_PACKAGES_TOKEN；未设置时回退到工作流身份。令牌需有 weiran-tech/weiran4j 包的读取权限。Docker 构建通过 BuildKit secret 注入令牌，令牌不会写入镜像层。

验收

1. 新建平台管理员、学校管理员、老师和学生，确认均只写入 edu_user；平台管理员无学校归属。
2. 四种云学院账号经云学院入口登录后访问各自允许的接口；跨校和跨班访问应拒绝。
3. 系统超级管理员仍经上游系统入口登录，并可在后台开通前台平台管理员。
4. 禁用账号、停用学校、退出登录后，旧令牌立即失效；恢复学校只恢复先前启用的账号。
5. 在包含旧教育业务数据的数据库执行 Flyway，核对账号数、历史 ID 和课程、考试、直播、竞赛的姓名查询。