feat(user): 账号管理（CRUD、Excel 导入、改密）并修掉 5 处缺陷
后端补齐 /users 全套（列表/新增/修改/软删/启停/重置密码/批量导入）与
PUT /auth/password；前端加「组织与账号 → 账号管理」一屏（左组织树 + 右列表、
新增编辑弹窗、导入体检报告、初始密码只显示一次的强确认）。
验收：e2e-m0-user.py 55/55；e2e-m0.py 回归 36/36；typecheck 0 错、build 通过。
账号管理页已在浏览器肉眼确认（首屏与切页均可见、数据与分页正确）。
本轮修掉的 5 个真问题 —— 都不是功能没做完，而是做完了但错的：
1) 学校租户也发放 PLATFORM_ADMIN 角色行
学校管理员在新增账号时传 roleCodes=[PLATFORM_ADMIN] 就能造出带
tenant:manage 的账号，而 /tenants 只校验权限码、不校验是否真在平台租户下
→ 任何学校管理员都能开通租户、拉全平台租户列表（租户级越权到平台级）。
RoleProvisioner 不再给非平台租户发该角色行 + 服务端按租户白名单校验。
2) UserUpsertReq.username 的 @NotBlank 对修改也生效
PUT /users/{id} 永远返回 40001，且明细只说存在阻断性校验问题，
看不出是登录名 —— 改账号功能整体不可用。去掉该注解，
必填性改由 UserService.create 判定。
3) Main.vue 的 <transition appear>
首次渲染被当成一次过渡，元素被加上 zoom-fade-enter-from（opacity:0）后
永不清理 → DOM 内容齐全、接口数据正常、文字可选中，但整块内容区肉眼不可见。
极易误判成页面没渲染而往路由/接口方向排查。去掉 appear。
4) assertAnotherAdminExists 在停用/删除路径上不可达
能调这两个接口的人自己必然是活跃管理员，所以除目标外还有管理员恒成立；
而真正会锁死租户的路径 —— 把管理员改成普通角色（目标可以是操作者自己）——
当时没有拦。补 losingAdminRole() + UserMapper.countAdminRoles()，
并在方法注释里写明哪条路径真生效、哪条只是防御性的。
5) sys_user.user_type 有两套互相冲突的枚举
DDL/实体注释写「1教师/管理员 2填报人(学生) 3社会人员」，而权威契约
（03-接口设计 §2.7）与 BuiltinRole.UserType 是
「1平台运营 2学校管理员 3班主任 4学生」—— 2 和 3 完全错位。
后果：userType=3（班主任，最高频的账号）被当成社会人员（二期）直接拒掉，
建班主任账号会失败；前端还把学校管理员显示成填报人（学生）。
改法：后端从角色反推用户类型再比对；新增 V3 迁移更正库注释
（V1 已应用不能改，Flyway 会校验 checksum）；更正 PRD 与 schema DDL 的同一行；
前端「用户类型」从手选改为由角色推导，从根上消除矛盾组合；
E2E 加 3 条回归断言锁住这个语义。
顺带修掉：
· components/index.ts 里 6 个指向已删组件的悬空导出（构建不报错、用到才炸）
· tsconfig 的 lib 停在 ES2020 而代码用了 Array.prototype.at
· 两处 .at() 的空值风险（useBreakpoint / useTabsStore）
· dashboard 的 userStore.menus 拼错，导致平台判断恒为 false
· http.ts 里两个永不命中的错误码常量
· 账号列表的 fixed 列缺 :scroll 配置，会浮在其它列上面
· .gitignore 补 __pycache__
新增脚本：
· scripts/e2e-m0-user.py 账号管理 55 项验收（含越权与自锁的负向断言）
· scripts/dev-clean-test-users.py 清理 E2E 残留的测试账号
This commit is contained in:
+49
-5
@@ -9,7 +9,7 @@
|
||||
|
||||
职业技能等级认定**报名材料收集 SaaS**。学生在微信小程序填报、班主任在手机初审、管理员在 PC 终审与导出。核心价值：**动态表单 + 规则引擎（命名/压缩/识别）+ 门禁核验 + 一键规范导出**。
|
||||
|
||||
工作目录 `D:\IDEA_Project\xiaotutongxue`（**空 git 仓库，无 commit，全部改动未提交**），交付物在 `docs/`。
|
||||
工作目录 `D:\IDEA_Project\xiaotutongxue`（git 仓库，**已有 3 次提交**：`63aec55` 文档 / `9d7a8ca` M0 后端 / `87ece5a` 前端换框架；**其后又有一批未提交改动**，见 §一·四），交付物在 `docs/`。
|
||||
|
||||
---
|
||||
|
||||
@@ -42,12 +42,56 @@
|
||||
|
||||
| 项 | 状态 |
|
||||
|---|---|
|
||||
| 技术栈定版 | ✅ Java 21 + **Spring Boot 4.1.1** + MyBatis-Plus 3.5.17(boot4) + PG16 + Redis7<br>PC: Vue3 + Element Plus；小程序: uni-app |
|
||||
| 技术栈定版 | ✅ Java 21 + **Spring Boot 4.1.1** + MyBatis-Plus 3.5.17(boot4) + PG16 + Redis7<br>PC: Vue3 + **Gi Admin Pro（Arco Design Vue 2.58）**；小程序: uni-app |
|
||||
| M0 后端骨架 | ✅ 统一响应/异常/58 错误码/多租户拦截/软删除/字段填充/AES-GCM/HMAC/RSA/JWT/权限模型 |
|
||||
| M0 数据库 | ✅ Flyway 2 个迁移；26 张表（20 业务 + 5 标准 + 1 迁移记录） |
|
||||
| M0 后端接口 | ✅ 租户开通与列表、组织 CRUD 与树、PC 登录/登出/当前用户 |
|
||||
| M0 验收 | ✅ **`python scripts/e2e-m0.py` → 35/35 通过** |
|
||||
| 待做 | 用户 CRUD 与 Excel 导入；PC/小程序前端；CI/CD；H5 预研 |
|
||||
| M0 后端接口 | ✅ 租户开通与列表、组织 CRUD 与树、PC 登录/登出/当前用户、**账号管理全套（含 Excel 批量导入）** |
|
||||
| M0 验收 | ✅ **`python scripts/e2e-m0.py` → 36/36**；**`python scripts/e2e-m0-user.py` → 53/53** |
|
||||
| PC 前端 | ✅ 已换 Gi Admin Pro + 腾讯云主题；已实现：登录 / 工作台 / 组织架构 / 租户管理 / **账号管理** |
|
||||
| 待做 | 小程序（uni-app）未创建；CI/CD；H5 保底预研；`hasActiveTask` 待 M1 补实现 |
|
||||
|
||||
---
|
||||
|
||||
## 一·四、账号管理竖切（2026-09-28 晚，未提交）
|
||||
|
||||
> 范围：`GET/POST/PUT/DELETE /users`、`PUT /users/{id}/status`、`POST /users/{id}/reset-password`、
|
||||
> `POST /users/import`、`PUT /auth/password`；前端「组织与账号 → 账号管理」一屏。
|
||||
|
||||
**验收**：`python scripts/e2e-m0-user.py` → **55/55**；`python scripts/e2e-m0.py` 回归 **36/36**。
|
||||
前端 `pnpm typecheck` **0 错**、`pnpm build` 通过、新增文件 eslint/stylelint 干净。
|
||||
账号管理页**已在浏览器肉眼确认**（首屏与切页均可见、8→7 列、数据与分页正确）。
|
||||
|
||||
### 本轮修掉的 5 个真问题（都不是"功能没做完"，是"做完了但错的"）
|
||||
|
||||
| # | 问题 | 后果 | 修法 |
|
||||
|:--:|---|---|---|
|
||||
| 1 | **学校租户也发放 `PLATFORM_ADMIN` 角色行** | 学校管理员在新增账号时传 `roleCodes:["PLATFORM_ADMIN"]` 即可造出带 `tenant:manage` 的账号；而 `/tenants` 只校验权限码、不校验"是否真在平台租户下" → **任何学校管理员都能开通租户、拉全平台租户列表**（租户级越权到平台级） | ① `RoleProvisioner` 不再给非平台租户发该角色行；② `UserService.resolveAssignableRoles` 按租户白名单校验，越界返回 `40301`。两道都留 |
|
||||
| 2 | `UserUpsertReq.username` 上的 `@NotBlank` 对**修改**也生效 | `PUT /users/{id}` 永远返回 `40001`，而错误明细只说"存在阻断性校验问题"，看不出是登录名 —— 改账号功能整体不可用 | 去掉该注解（`@Pattern` 对 null 是通过的），"新增时必填"改由 `UserService.create` 判定 |
|
||||
| 3 | `Main.vue` 的 `<transition appear>` | 首次渲染被当成一次过渡，元素被加上 `zoom-fade-enter-from/-active`（`opacity:0`）后**永不清理** → **DOM 内容齐全、接口数据正常、文字可选中，但整块内容区肉眼不可见**。极易误判成"页面没渲染"而往路由/接口方向排查 | 去掉 `appear`（首次加载本就不需要入场动画）。**已浏览器复验通过** |
|
||||
| 4 | 我写的 `assertAnotherAdminExists` **在停用/删除路径上不可达** | 能调这两个接口的人自己必然是活跃管理员，所以"除目标外还有管理员"恒成立。而真正会锁死租户的路径——**把管理员改成普通角色**（目标可以是操作者自己）——当时没有拦 | 新增 `losingAdminRole()` + `UserMapper.countAdminRoles()`，在改角色时判定；方法注释里写明"哪条路径真生效、哪条是防御性的" |
|
||||
| 5 | ⭐ **`sys_user.user_type` 有两套互相冲突的枚举** | DDL/实体注释写「1教师/管理员 2填报人(学生) 3社会人员」，而**权威契约**（《03-接口设计》§2.7）与 `BuiltinRole.UserType` 是「1平台运营 2学校管理员 3班主任 4学生」。两套的 **2 和 3 完全错位**。我照错的注释写了新代码，结果是：**`userType=3`（班主任，最高频的账号）被当成"社会人员（二期）"直接拒掉** —— 建班主任账号会失败；前端「类型」列还把学校管理员显示成"填报人（学生）" | ① 后端改成**从角色反推用户类型**再比对（`ROLE_TO_USER_TYPE`），不再逐条 `if`；② 新增 `V3__fix_user_type_comment.sql` 更正库注释（**不能改 V1，Flyway 会校验 checksum**）；③ 更正 PRD 与 `schema-postgresql.sql` 的同一行注释；④ 前端「用户类型」从手选改为**由角色推导**，从根上消除矛盾组合；⑤ E2E 加 3 条回归断言锁住这个语义 |
|
||||
|
||||
> ⚠️ **第 5 条是最值得记住的一条**：不是"漏了个校验"，而是**同一份资料里有两套定义，且都对不上**。
|
||||
> 教训：看到"枚举注释"时，要去**权威契约**（这里是《03-接口设计》）核对，不能就近抄实体或 DDL 的注释。
|
||||
> 这条也解释了为什么 `V1` 迁移里的错误注释只能靠 `V3` 覆盖 —— 已应用的迁移**一个字都不能改**。
|
||||
|
||||
### 已知缺口（有意留着，别当成漏做）
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| **改密后旧 token 仍有效** | 直到自然过期。要立刻踢人需要 JWT 带签发时间 + 与"最近改密时间"比较，涉及 `JwtService`/`AuthInterceptor`，不适合混在这一刀里。已在 `AuthService.changePassword` 注释里写明 |
|
||||
| `hasActiveTask()` 恒为 `false` | `collect_task` 是 M1 的表且当前无"任务负责人"字段，`40014` 这条约束**目前不生效**。方法注释已标红，M1 必须补 |
|
||||
| 手机号**模糊**搜不了 | AES-GCM 每次密文不同，`LIKE` 在原理上不可行。完整号码走 `phone_hash` 等值匹配；代价是"只记得中间几位"搜不到，属加密的必然取舍。E2E 里有一条专门断言这个行为（避免后人当 bug 改掉） |
|
||||
| **浏览器端验证** | ✅ 已完成。账号管理页首屏与切页均 `opacity: 1`（`appear` 修复生效）、7 列、数据与分页正确、组织树正常；demo 租户已清理干净（1 个账号 `admin`、6 个组织节点）。⚠️ 下一个新页面上线时容易忽略的一点：**新增 `views/` 目录后必须重启 dev server**，见下方环境坑 3 |
|
||||
|
||||
### 本轮踩到的三个环境坑
|
||||
|
||||
1. **Maven 的本地仓库不在 `C:\Users\<u>\.m2\repository`**，而在 `D:\maven_repositiory`。在那里查依赖才准。
|
||||
2. **`easyexcel-4.0.3.jar` 只有 3KB** —— 它是聚合包，真类在 `easyexcel-core`（528KB）+ `poi 5.2.5`。只看聚合包的大小会误判成"依赖是空的"。这正是本项目"依赖在、功能不在"那条教训的又一例。
|
||||
|
||||
3. **`import.meta.glob('@/views/**/*.vue')` 在 dev server 里对"新增目录"不总失效**：`views/user/` 建好并 HMR 重载后，路由仍拿不到组件（component 为 `undefined` → 内容区空白）。**新增页面目录后要重启 dev server**，不能只靠 HMR。
|
||||
|
||||
---
|
||||
|
||||
**关键实现决策（不要在后继开发中改回去）**
|
||||
|
||||
|
||||
Reference in New Issue
Block a user