feat(M02-D): 完成用户与员工权限管理

2026-06-18 14:45:01 +08:00
parent 46acb8422a
commit 5a300a82f6
21 changed files with 894 additions and 40 deletions
@@ -0,0 +1,21 @@
+# M02-D 用户与员工管理 API
+
+## 新增接口
+
+- `GET /admin-api/users`：分页查询当前租户用户，支持状态和关键词筛选；手机号与最近登录 IP 脱敏。
+- `POST /admin-api/staff`：创建员工并分配角色、门店和备注。
+- `PATCH /admin-api/users/:id`：更新资料、状态、角色、门店范围和备注。
+- `POST /admin-api/users/:id/reset-sessions`：撤销目标用户全部活动会话。
+
+## 权限与数据范围
+
+- 需要 `staff.manage`、`tenant.manage` 或平台管理员角色。
+- 门店管理员只能查看和管理自己授权门店内的员工，不能授予租户级或平台级角色。
+- 租户管理员可管理本租户员工，但所有 SQL 仍强制包含 `tenant_id`。
+- 禁止管理员修改自己的角色、状态和门店范围，避免自锁或提权绕过。
+
+## 会话与审计
+
+- 禁用、角色变化、门店范围变化会提升 `role_version` 并撤销活动会话。
+- 重置登录会话会提升 `role_version`，旧 JWT 立即失效。
+- 创建、更新和重置会话均写入 `qipai_audit_logs`，记录操作者、资源、traceId 和非敏感变更摘要。
@@ -0,0 +1,16 @@
+# M02-D 用户与员工管理数据库变更
+
+- 迁移版本：`2026061806`
+- 新表：`qipai_user_admin_profiles`
+- 新权限：`user.read`、`staff.manage`、`session.reset`
+
+`qipai_user_admin_profiles` 保存租户内用户备注及最后更新人。角色权限初始化同时接入租户首次登录路径，确保角色晚于迁移创建时仍能获得 M02-D capability。
+
+## 回滚
+
+1. 删除三项权限对应的角色绑定。
+2. 删除三项权限目录。
+3. 删除迁移版本记录。
+4. 删除 `qipai_user_admin_profiles`。
+
+回滚不会删除 `qipai_users`、角色、门店授权或审计日志。
@@ -0,0 +1,30 @@
+# M02-D 用户与员工管理
+
+- 日期：2026-06-18
+- 起始 commit：`46acb84`
+- 工程 commit：本阶段工程提交
+- ENGINEERING_DELTA=YES
+- 子阶段状态：待 push 与远端校验
+
+## 工程增量
+
+- 新增后台用户列表、员工创建、用户更新和会话重置 API。
+- 新增租户/门店两级管理边界，禁止跨租户、跨授权门店和越级角色分配。
+- 手机号与最近登录 IP 仅返回脱敏值。
+- 禁用、角色或门店范围变化立即撤销活动会话并提升 `role_version`。
+- 所有员工权限变更写入既有审计日志。
+- 新增 `2026061806` 迁移、回滚和验证 SQL。
+
+## 已执行验证
+
+- Windows `npm test`：退出码 0，M01-A 至 M02-D 全量后端测试通过。
+- WSL MySQL `8.4.9` 临时库：`up → verify → down → up → verify`，退出码 0。
+- 实测员工创建、角色/门店分配、禁用后会话撤销和两条审计日志。
+- 迁移语句数：up 33、verify 19、down 31。
+
+## 影响
+
+- 数据库迁移：`2026061806_m02d_user_management`。
+- API：新增四个 `/admin-api` 用户与员工管理接口。
+- 配置：无新增秘密或环境变量。
+- 部署：生产更新前必须备份，由 Ubuntu 菜单执行迁移；不得从 Windows 直连生产数据库。