1. 页面概览
用户管理页是 LightAIP 管理后台（Admin）的账号治理入口，路由为 /admin/users。它提供用户列表、新建/编辑用户、分配角色、重置密码、锁定/解锁与删除能力。页面顶部有「新建用户」按钮，列表中每行按需提供操作按钮；当前登录用户不显示删除按钮。
所有能力对接 AIP 后端 18080 的 /api/v1/users、/api/v1/roles、/api/v1/me 路由组，均要求管理员角色。一句话总结：用户管理页是"账号生命周期 + 角色挂载"的管理员控制台。
2. 访问入口
2.1 路由与菜单
| 项目 | 值 |
|---|---|
| 路由 path | /admin/users（父路由 /admin） |
| 路由 name | AdminUsers |
| 路由 title | 用户管理 |
| requiresAuth | true；父路由 meta requiresAdmin: true |
| 菜单位置 | Admin 后台菜单（AdminLayout.vue）「用户管理」 |
| 前端源码 | action/web/src/views/UsersPage.vue |
| 路由注册 | action/web/src/router/index.js |
2.2 认证与权限
/admin 父路由挂 requiresAdmin，非管理员被前端路由守卫拦截；请求经 action/web/src/api/aipClient.js（baseURL /aip-api/v1）附 localStorage.aip_token，后端 admin 组再经 adminMiddleware() 二次校验管理员角色。
2.3 端口与 API 前缀
AIP 后端默认端口 18080，API 前缀 /aip-api，实际请求路径 /aip-api/v1/users。
3. 界面布局
+--------------------------------------------------+
| 用户管理 [新建用户] |
+--------------------------------------------------+
| [操作结果提示 alert（有消息时显示，可关闭）] |
+--------------------------------------------------+
| 用户列表（card） |
| 表格：ID|用户名|邮箱|姓名|锁定状态|角色|操作 |
| 操作：[编辑][分配角色][重置密码][锁定/解锁][删除] |
+--------------------------------------------------+
| 新建/编辑用户弹窗：用户名* 密码*（新建时） 邮箱 姓名 |
| 分配角色弹窗：角色勾选列表（勾选即生效） |
| 重置密码弹窗：新密码* |
+--------------------------------------------------+各板块职责：
- 用户列表：全量用户表格，锁定状态用绿/红徽标（正常/已锁定），角色列展示用户已挂角色标签。
- 新建/编辑用户：同一弹窗复用，新建需密码（至少 6 位），编辑仅改资料。
- 分配角色：勾选即调接口生效（分配或移除），无需额外保存按钮。
- 重置密码：管理员代设新密码（至少 6 位）。
4. 交互元素
| 控件 | 位置 | 含义与作用 |
|---|---|---|
| 新建用户按钮 | 页头 | 打开新建用户弹窗（用户名、密码必填，密码至少 6 位） |
| 编辑按钮 | 列表行 | 打开编辑弹窗，可改用户名/邮箱/姓名（PUT /users/:id） |
| 分配角色按钮 | 列表行 | 打开角色分配弹窗：并行拉取 /roles 与 /users/:id/roles，勾选/取消立即 POST/DELETE 生效 |
| 重置密码按钮 | 列表行 | 先 confirm 再开弹窗，提交 POST /users/:id/password |
| 锁定/解锁按钮 | 列表行 | 文案随状态切换，confirm 后 PUT /users/:id/lock，body {locked: !is_locked} |
| 删除按钮 | 列表行 | 当前登录用户自身不显示；confirm 后 DELETE /users/:id，不可撤销 |
5. 后端关联
5.1 端点表
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /users | 全部用户列表 {users: [...]} |
| GET | /me | 当前登录用户（含 is_admin），回写 localStorage.aip_is_admin |
| POST | /users | 创建用户，body {username, password, email?, name?} |
| PUT | /users/:id | 更新用户资料（不含密码） |
| DELETE | /users/:id | 删除用户；禁止删除自己（400 cannot delete yourself） |
| GET | /users/:id/roles | 用户已挂角色 {roles: [...]} |
| POST | /users/:id/roles | 分配角色，body {role_id}，重复分配 409 |
| DELETE | /users/:id/roles/:roleId | 移除角色（服务层含"admin 不能移除自己"自护） |
| POST | /users/:id/password | 重置密码，body {password}，至少 6 位 |
| PUT | /users/:id/lock | 锁定/解锁，body {locked: bool}（必填） |
5.2 关键机制
- 角色即权限载体：用户不直接配权限，而是挂角色；
GET /me返回is_admin供前端标记管理员身份并回写aip_is_admin。 - 写操作防呆：密码与锁定位数字段均有后端强校验（至少 6 位、locked 必填）；删除自己被后端 400 拦截，前端同时隐藏自己的删除按钮。
- 分配角色立即生效：前端把勾选状态直接映射为 POST/DELETE 调用，每次切换都是一次完整请求，成功后重新拉取用户列表。
6. 权限与安全
- 路由双重校验：前端
/admin父路由requiresAdmin+ 后端adminMiddleware()，缺任一层都不可达。 - 用户 ID 为 UUID，非 UUID 路径参数返回 400；密码由 RBAC 服务层哈希存储，重置后旧 Token 需重新登录。
- 写操作（创建/编辑/删除/重置/锁定）全部只对管理员开放，普通用户接口返回 403。
7. 常见问题与排错
问题 1：页面提示"加载用户列表失败"
现象：用户表格不出数，红色 alert。
原因：后端 401（Token 失效/非管理员被拒）或后端未启动。
处理：确认 Token 有效且当前账号为管理员；查看 Network 中 /aip-api/v1/users 响应码，401 重新登录，403 检查角色。
问题 2：保存用户报"密码至少 6 位"
现象：新建/重置密码被前端拦截。
原因：前端与后端校验一致（"password must be at least 6 characters"），输入过短。
处理：输入不少于 6 位密码；重置弹窗同样校验。
问题 3：分配角色后列表角色没变化
现象：勾选后提示成功但用户行角色标签未变。
原因：onRoleToggle 成功后会重新 fetchUsers，若刷新失败或列表未更新。
处理：手动刷新页面重拉列表；确认 POST/DELETE /users/:id/roles 响应正常。
8. 已知缺陷与边界
| 项 | 说明 |
|---|---|
| 密码策略简单 | 仅校验长度 ≥6，无复杂度要求 |
| 无邮箱验证 | 邮箱为可选文本，不做唯一性/格式强校验（前端 type=email） |
| 无法删除自己 | 前后端双重禁止，属有意设计 |
注：用户列表全量拉取无分页（用户量大时页面渲染较慢）已于 2026-09-06 修复（前端本地分页）。