Commit 8f292bcfb6939019f5208b5ce6389e533cf0a204
1 parent
7de7347d
docs(module_usr): add specs and plans for REQ-USR-002 and REQ-USR-003
Showing
4 changed files
with
1008 additions
and
0 deletions
docs/superpowers/plans/2026-05-08-REQ-USR-002.md
0 → 100644
| 1 | +--- | ||
| 2 | +req_id: REQ-USR-002 | ||
| 3 | +date: 2026-05-08 | ||
| 4 | +spec_ref: docs/superpowers/specs/2026-05-08-REQ-USR-002.md | ||
| 5 | +--- | ||
| 6 | + | ||
| 7 | +# 修改用户 Implementation Plan | ||
| 8 | + | ||
| 9 | +> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. | ||
| 10 | + | ||
| 11 | +**Goal:** 实现 `PUT /api/usr/users/{userId}`，允许超级管理员修改用户类型、语言、权限等，并在前端用户列表增加"修改"按钮触发编辑抽屉。 | ||
| 12 | + | ||
| 13 | +**Architecture:** 后端遵循现有三层（Controller → Service → Mapper）模式，新增 UserUpdateReqDTO/UserUpdateRespVO，UserServiceImpl.updateUser 做权限、存在性、自身角色三重校验后执行字段更新 + 权限组先删后插；前端复用 UserFormDrawer（新增 userId/initialData props 区分 create/edit 模式），UserListPage 增加"操作"列。 | ||
| 14 | + | ||
| 15 | +**Tech Stack:** Spring Boot 3 / MyBatis-Plus LambdaUpdateWrapper / @Transactional / React 18 / Ant Design 5 / Vitest | ||
| 16 | + | ||
| 17 | +--- | ||
| 18 | + | ||
| 19 | +## Schema 改动 | ||
| 20 | + | ||
| 21 | +无（不需要新 migration） | ||
| 22 | + | ||
| 23 | +## 文件变更清单 | ||
| 24 | + | ||
| 25 | +- Create: `backend/src/main/java/com/example/erp/module/usr/dto/UserUpdateReqDTO.java` — 修改用户请求体 | ||
| 26 | +- Create: `backend/src/main/java/com/example/erp/module/usr/vo/UserUpdateRespVO.java` — 修改用户响应 VO | ||
| 27 | +- Modify: `backend/src/main/java/com/example/erp/common/constants/UsrErrorCode.java` — 追加 USER_NOT_FOUND=40400 / SELF_ADMIN_CHANGE=40301 | ||
| 28 | +- Modify: `backend/src/main/java/com/example/erp/module/usr/service/UserService.java` — 追加 updateUser 接口方法 | ||
| 29 | +- Modify: `backend/src/main/java/com/example/erp/module/usr/service/impl/UserServiceImpl.java` — 实现 updateUser | ||
| 30 | +- Modify: `backend/src/main/java/com/example/erp/module/usr/controller/UserController.java` — 追加 PUT /users/{userId} | ||
| 31 | +- Modify: `backend/src/test/java/com/example/erp/module/usr/UserServiceTest.java` — 追加 updateUser 测试 | ||
| 32 | +- Modify: `backend/src/test/java/com/example/erp/module/usr/UserControllerTest.java` — 追加 HTTP 测试 | ||
| 33 | +- Modify: `frontend/src/api/usr.ts` — 追加 UserUpdateReq / UserUpdateResp / updateUser() | ||
| 34 | +- Modify: `frontend/src/pages/usr/UserFormDrawer.tsx` — 支持 edit 模式（userId + initialData props） | ||
| 35 | +- Modify: `frontend/src/pages/usr/UserListPage.tsx` — 追加操作列 + editingUser 状态 | ||
| 36 | +- Modify: `frontend/src/test/UserListPage.test.tsx` — 追加编辑流程测试 | ||
| 37 | + | ||
| 38 | +--- | ||
| 39 | + | ||
| 40 | +## 任务步骤 | ||
| 41 | + | ||
| 42 | +### Task 1: 错误码 + DTO/VO 数据结构 | ||
| 43 | + | ||
| 44 | +**Files:** | ||
| 45 | +- Modify: `backend/src/main/java/com/example/erp/common/constants/UsrErrorCode.java` | ||
| 46 | +- Create: `backend/src/main/java/com/example/erp/module/usr/dto/UserUpdateReqDTO.java` | ||
| 47 | +- Create: `backend/src/main/java/com/example/erp/module/usr/vo/UserUpdateRespVO.java` | ||
| 48 | +- Test: `backend/src/test/java/com/example/erp/module/usr/UserServiceTest.java` | ||
| 49 | + | ||
| 50 | +**API shape:** | ||
| 51 | +``` | ||
| 52 | +UserUpdateReqDTO { | ||
| 53 | + String userType; // "普通用户" | "超级管理员" | ||
| 54 | + String language; // "中文" | "英文" | "繁体" | ||
| 55 | + boolean canEditDoc; | ||
| 56 | + boolean isDisabled; | ||
| 57 | + String employeeId; // nullable | ||
| 58 | + List<String> permGroupIds; | ||
| 59 | +} | ||
| 60 | + | ||
| 61 | +UserUpdateRespVO { | ||
| 62 | + String userId; | ||
| 63 | + String username; | ||
| 64 | + LocalDateTime updatedAt; | ||
| 65 | +} | ||
| 66 | + | ||
| 67 | +UsrErrorCode.USER_NOT_FOUND = 40400 | ||
| 68 | +UsrErrorCode.SELF_ADMIN_CHANGE = 40301 | ||
| 69 | +``` | ||
| 70 | + | ||
| 71 | +- [ ] **Step 1: 写失败测试** | ||
| 72 | + - 测试名: `UserServiceTest#updateUser_dtoDefaults` | ||
| 73 | + - 意图: `new UserUpdateReqDTO()` 后各字段可 set/get；`new UserUpdateRespVO()` 可 set/get userId/username/updatedAt；`UsrErrorCode.USER_NOT_FOUND == 40400`，`UsrErrorCode.SELF_ADMIN_CHANGE == 40301` | ||
| 74 | + - 子会话确认 FAIL（类不存在） | ||
| 75 | + | ||
| 76 | +- [ ] **Step 2: 实现最小代码** | ||
| 77 | + - 在 UsrErrorCode 追加两个常量 | ||
| 78 | + - 创建 UserUpdateReqDTO（@Getter @Setter，6 个字段） | ||
| 79 | + - 创建 UserUpdateRespVO（@Getter @Setter，3 个字段：userId/username/updatedAt: LocalDateTime） | ||
| 80 | + | ||
| 81 | +- [ ] **Step 3: 子会话验证 PASS** | ||
| 82 | + | ||
| 83 | +- [ ] **Step 4: Commit** | ||
| 84 | + - `git add backend/src/main/java/com/example/erp/common/constants/UsrErrorCode.java backend/src/main/java/com/example/erp/module/usr/dto/UserUpdateReqDTO.java backend/src/main/java/com/example/erp/module/usr/vo/UserUpdateRespVO.java backend/src/test/java/com/example/erp/module/usr/UserServiceTest.java` | ||
| 85 | + - `git commit -m "feat(usr): 添加 UserUpdateReqDTO / UserUpdateRespVO / 错误码 REQ-USR-002"` | ||
| 86 | + | ||
| 87 | +--- | ||
| 88 | + | ||
| 89 | +### Task 2: UserService.updateUser 实现（含权限校验与权限组 replace） | ||
| 90 | + | ||
| 91 | +**Files:** | ||
| 92 | +- Modify: `backend/src/main/java/com/example/erp/module/usr/service/UserService.java` | ||
| 93 | +- Modify: `backend/src/main/java/com/example/erp/module/usr/service/impl/UserServiceImpl.java` | ||
| 94 | +- Test: `backend/src/test/java/com/example/erp/module/usr/UserServiceTest.java` | ||
| 95 | + | ||
| 96 | +**API shape:** | ||
| 97 | +``` | ||
| 98 | +UserService#updateUser(String userId, UserUpdateReqDTO req, UserPrincipal principal) : UserUpdateRespVO | ||
| 99 | +``` | ||
| 100 | + | ||
| 101 | +业务逻辑约束（按顺序执行）： | ||
| 102 | +1. `!"超级管理员".equals(principal.userType())` → `BizException(PERMISSION_DENIED, "权限不足")` | ||
| 103 | +2. `userMapper.selectOne(sId=userId AND sBrandsId=brandId)` == null → `BizException(USER_NOT_FOUND, "用户不存在")` | ||
| 104 | +3. `principal.userId().equals(userId) && !"超级管理员".equals(req.getUserType())` → `BizException(SELF_ADMIN_CHANGE, "禁止修改自己的管理员角色")` | ||
| 105 | +4. `req.getEmployeeId() != null` → staffMapper 校验存在性，不存在 → `BizException(EMPLOYEE_NOT_FOUND, "员工不存在")` | ||
| 106 | +5. 用 `LambdaUpdateWrapper<UsrUserEntity>` 更新 sUserType/sLanguage/bCanEditDoc/bIsDisabled/sEmployeeId（按 sId=userId AND sBrandsId=brandId） | ||
| 107 | +6. `userPermissionMapper.delete(sUserId=userId AND sBrandsId=brandId)`，再批量 insert 新 UserPermissionEntity 列表（permGroupIds 为空时只删不插） | ||
| 108 | +7. 返回 UserUpdateRespVO（userId, username=entity.sUsername, updatedAt=LocalDateTime.now()） | ||
| 109 | + | ||
| 110 | +- [ ] **Step 1: 写失败测试（共 6 个）** | ||
| 111 | + | ||
| 112 | + **T1** `updateUser_nonAdmin_throws40300` | ||
| 113 | + - 意图: principal.userType="普通用户" → BizException.code==40300 | ||
| 114 | + - principal: new UserPrincipal("u1","admin","普通用户","b1") | ||
| 115 | + | ||
| 116 | + **T2** `updateUser_userNotFound_throws40400` | ||
| 117 | + - 意图: 超级管理员 principal，userMapper.selectOne 返回 null → BizException.code==40400 | ||
| 118 | + | ||
| 119 | + **T3** `updateUser_selfAdminChange_throws40301` | ||
| 120 | + - 意图: principal.userId=="u1"，userId=="u1"，req.userType="普通用户" → BizException.code==40301 | ||
| 121 | + - userMapper.selectOne 需 stub 返回一个存在的用户实体 | ||
| 122 | + | ||
| 123 | + **T4** `updateUser_invalidEmployee_throws40001` | ||
| 124 | + - 意图: req.employeeId="bad-emp"，staffMapper.selectOne 返回 null → BizException.code==40001 | ||
| 125 | + - userMapper.selectOne stub 返回有效用户；principal.userId!="u-target" 确保不触发 40301 | ||
| 126 | + | ||
| 127 | + **T5** `updateUser_happyPath_updatesAndReturnsResp` | ||
| 128 | + - 意图: 一切校验通过 → userMapper 执行 update；permissionMapper 先 delete 再 insert；返回 vo.userId/username/updatedAt 非 null | ||
| 129 | + - Stub: userMapper.selectOne 返回含 sUsername="alice" 的实体；staffMapper.selectOne 返回非 null（若 employeeId 非 null）；userMapper.update 返回 1；delete/insert 正常 | ||
| 130 | + | ||
| 131 | + **T6** `updateUser_emptyPermGroupIds_onlyDeletes` | ||
| 132 | + - 意图: req.permGroupIds=[] → userPermissionMapper.delete 被调用；insert 不被调用 | ||
| 133 | + - verify(userPermissionMapper, never()).insert(anyList()) | ||
| 134 | + | ||
| 135 | + - 子会话确认 6 个测试均 FAIL（方法不存在） | ||
| 136 | + | ||
| 137 | +- [ ] **Step 2: 在 UserService 接口追加方法声明，在 UserServiceImpl 实现 updateUser** | ||
| 138 | + - 使用 @Transactional | ||
| 139 | + - 注意: UsrUserEntity 已有 sId / sUserType / sLanguage / bCanEditDoc / bIsDisabled / sEmployeeId 字段（来自现有代码） | ||
| 140 | + | ||
| 141 | +- [ ] **Step 3: 子会话验证全部 PASS** | ||
| 142 | + | ||
| 143 | +- [ ] **Step 4: Commit** | ||
| 144 | + - `git add backend/src/main/java/com/example/erp/module/usr/service/ backend/src/test/java/com/example/erp/module/usr/UserServiceTest.java` | ||
| 145 | + - `git commit -m "feat(usr): UserService.updateUser 三重校验 + 权限组 replace REQ-USR-002"` | ||
| 146 | + | ||
| 147 | +--- | ||
| 148 | + | ||
| 149 | +### Task 3: UserController PUT /api/usr/users/{userId} | ||
| 150 | + | ||
| 151 | +**Files:** | ||
| 152 | +- Modify: `backend/src/main/java/com/example/erp/module/usr/controller/UserController.java` | ||
| 153 | +- Test: `backend/src/test/java/com/example/erp/module/usr/UserControllerTest.java` | ||
| 154 | + | ||
| 155 | +**API shape:** | ||
| 156 | +``` | ||
| 157 | +@PutMapping("/users/{userId}") | ||
| 158 | +public Result<UserUpdateRespVO> updateUser( | ||
| 159 | + @PathVariable String userId, | ||
| 160 | + @Valid @RequestBody UserUpdateReqDTO req, | ||
| 161 | + @AuthenticationPrincipal UserPrincipal principal) | ||
| 162 | +// REQ-USR-002: 修改用户 | ||
| 163 | +``` | ||
| 164 | + | ||
| 165 | +- [ ] **Step 1: 写失败测试（共 2 个）** | ||
| 166 | + | ||
| 167 | + **T1** `updateUser_withToken_returns200` | ||
| 168 | + - 意图: PUT /api/usr/users/u-target，含超级管理员 Token，body={userType,language,canEditDoc,isDisabled,permGroupIds} | ||
| 169 | + - stub: userService.updateUser(any,any,any) 返回 UserUpdateRespVO{userId="u-target",username="alice",updatedAt=now} | ||
| 170 | + - 断言: HTTP 200, $.code==200, $.data.userId=="u-target", $.data.username=="alice" | ||
| 171 | + | ||
| 172 | + **T2** `updateUser_noAuth_returns401` | ||
| 173 | + - 意图: 无 Token → HTTP 401 | ||
| 174 | + | ||
| 175 | + - 子会话确认 FAIL（endpoint 不存在） | ||
| 176 | + | ||
| 177 | +- [ ] **Step 2: 在 UserController 追加 PUT /users/{userId} 方法，加 // REQ-USR-002: 修改用户 注释** | ||
| 178 | + | ||
| 179 | +- [ ] **Step 3: 子会话验证 PASS** | ||
| 180 | + | ||
| 181 | +- [ ] **Step 4: Commit** | ||
| 182 | + - `git add backend/src/main/java/com/example/erp/module/usr/controller/UserController.java backend/src/test/java/com/example/erp/module/usr/UserControllerTest.java` | ||
| 183 | + - `git commit -m "feat(usr): PUT /api/usr/users/{userId} REQ-USR-002"` | ||
| 184 | + | ||
| 185 | +--- | ||
| 186 | + | ||
| 187 | +### Task 4: 前端 API + UserFormDrawer edit 模式 | ||
| 188 | + | ||
| 189 | +**Files:** | ||
| 190 | +- Modify: `frontend/src/api/usr.ts` | ||
| 191 | +- Modify: `frontend/src/pages/usr/UserFormDrawer.tsx` | ||
| 192 | +- Test: `frontend/src/test/UserListPage.test.tsx` | ||
| 193 | + | ||
| 194 | +**API shape (usr.ts):** | ||
| 195 | +```ts | ||
| 196 | +export interface UserUpdateReq { | ||
| 197 | + userType: string | ||
| 198 | + language: string | ||
| 199 | + canEditDoc: boolean | ||
| 200 | + isDisabled: boolean | ||
| 201 | + employeeId: string | null | ||
| 202 | + permGroupIds: string[] | ||
| 203 | +} | ||
| 204 | + | ||
| 205 | +export interface UserUpdateResp { | ||
| 206 | + userId: string | ||
| 207 | + username: string | ||
| 208 | + updatedAt: string | ||
| 209 | +} | ||
| 210 | + | ||
| 211 | +export function updateUser(userId: string, req: UserUpdateReq): Promise<UserUpdateResp> | ||
| 212 | +// → request.put(`/usr/users/${userId}`, req) | ||
| 213 | +``` | ||
| 214 | + | ||
| 215 | +**UserFormDrawer props 扩展:** | ||
| 216 | +```ts | ||
| 217 | +interface Props { | ||
| 218 | + open: boolean | ||
| 219 | + onClose: () => void | ||
| 220 | + onSuccess: () => void | ||
| 221 | + userId?: string // 非 null = edit 模式 | ||
| 222 | + initialData?: { | ||
| 223 | + userType: string | ||
| 224 | + language: string | ||
| 225 | + canEditDoc: boolean | ||
| 226 | + isDisabled: boolean | ||
| 227 | + employeeId?: string | null | ||
| 228 | + } | ||
| 229 | +} | ||
| 230 | +``` | ||
| 231 | +edit 模式行为： | ||
| 232 | +- 抽屉 title="修改用户"，隐藏 userCode/username Form.Item | ||
| 233 | +- open 时用 initialData 初始化 form（form.setFieldsValue），selectedPermIds=[] | ||
| 234 | +- 提交调 updateUser(userId, req) 而非 createUser；req.isDisabled 从 form.values.isDisabled 读取（Checkbox valuePropName="checked"） | ||
| 235 | + | ||
| 236 | +- [ ] **Step 1: 写失败测试** | ||
| 237 | + | ||
| 238 | + 在 `UserListPage.test.tsx` vi.mock 里追加: | ||
| 239 | + ```ts | ||
| 240 | + updateUser: vi.fn().mockResolvedValue({ userId: 'u1', username: 'alice', updatedAt: '2026-05-08T10:00:00' }) | ||
| 241 | + ``` | ||
| 242 | + | ||
| 243 | + **T1** `editMode_drawerTitle_shows修改用户` | ||
| 244 | + - renderPage，设 drawerOpen=true + editingUser 存在（通过点击模拟行上的修改按钮） | ||
| 245 | + - 断言: screen 中存在 "修改用户" 文本 | ||
| 246 | + | ||
| 247 | + **T2** `editMode_submit_callsUpdateUser` | ||
| 248 | + - 打开 edit 抽屉，点击确认 | ||
| 249 | + - waitFor: vi.mocked(updateUser) 被调用 1 次 | ||
| 250 | + | ||
| 251 | + - 子会话确认 FAIL（updateUser 不存在于 mock 和 usr.ts） | ||
| 252 | + | ||
| 253 | +- [ ] **Step 2: 在 usr.ts 追加 UserUpdateReq / UserUpdateResp / updateUser；改造 UserFormDrawer 支持 edit props** | ||
| 254 | + | ||
| 255 | +- [ ] **Step 3: 子会话验证 PASS** | ||
| 256 | + | ||
| 257 | +- [ ] **Step 4: Commit** | ||
| 258 | + - `git add frontend/src/api/usr.ts frontend/src/pages/usr/UserFormDrawer.tsx frontend/src/test/UserListPage.test.tsx` | ||
| 259 | + - `git commit -m "feat(usr): updateUser API + UserFormDrawer edit 模式 REQ-USR-002"` | ||
| 260 | + | ||
| 261 | +--- | ||
| 262 | + | ||
| 263 | +### Task 5: UserListPage 操作列 + editingUser 状态 | ||
| 264 | + | ||
| 265 | +**Files:** | ||
| 266 | +- Modify: `frontend/src/pages/usr/UserListPage.tsx` | ||
| 267 | +- Test: `frontend/src/test/UserListPage.test.tsx` | ||
| 268 | + | ||
| 269 | +**行为:** | ||
| 270 | +- columns 末尾追加 "操作" 列，每行渲染 `<PermButton permission="usr:edit" onClick={() => setEditingUser(row)}>修改</PermButton>` | ||
| 271 | +- 新增状态: `const [editingUser, setEditingUser] = useState<UserListItemVO | null>(null)` | ||
| 272 | +- UserFormDrawer 新增两个 props： | ||
| 273 | + - `open={drawerOpen || editingUser !== null}`（或用 editDrawerOpen 独立状态） | ||
| 274 | + - `userId={editingUser?.sId}` | ||
| 275 | + - `initialData={editingUser ? { userType: editingUser.sUserType, language: editingUser.sLanguage, canEditDoc: false, isDisabled: editingUser.bIsDisabled === 1, employeeId: null } : undefined}` | ||
| 276 | + - 注意：UserListItemVO 不含 bCanEditDoc，edit 模式下默认 false，用户可手动勾选 | ||
| 277 | + - `onSuccess={() => { setEditingUser(null); load(1) }}` | ||
| 278 | + - `onClose={() => setEditingUser(null)}` | ||
| 279 | + | ||
| 280 | + 注意：区分新增抽屉（drawerOpen）和编辑抽屉（editingUser !== null），两者可独立触发 UserFormDrawer，也可复用同一个实例——推荐独立实例避免状态冲突：新增用 drawerOpen/setDrawerOpen，编辑用 editingUser/setEditingUser。 | ||
| 281 | + | ||
| 282 | +- [ ] **Step 1: 写失败测试** | ||
| 283 | + | ||
| 284 | + **T1** `editButton_openEditDrawer` | ||
| 285 | + - mock getUserList 返回 1 行（sId='u1',sUsername='alice',...） | ||
| 286 | + - renderPage('超级管理员') | ||
| 287 | + - waitFor: screen 中有 "alice" 渲染出来 | ||
| 288 | + - 点击 "修改" 按钮 | ||
| 289 | + - waitFor: screen 中有 "修改用户" 文本（抽屉标题） | ||
| 290 | + | ||
| 291 | + - 子会话确认 FAIL（无"修改"按钮） | ||
| 292 | + | ||
| 293 | +- [ ] **Step 2: 在 UserListPage 追加操作列和编辑抽屉逻辑；追加 // REQ-USR-002: 修改用户 注释** | ||
| 294 | + | ||
| 295 | +- [ ] **Step 3: 子会话验证 PASS（全量测试：后端 45+ / 前端 11+）** | ||
| 296 | + | ||
| 297 | +- [ ] **Step 4: Commit** | ||
| 298 | + - `git add frontend/src/pages/usr/UserListPage.tsx frontend/src/test/UserListPage.test.tsx` | ||
| 299 | + - `git commit -m "feat(usr): UserListPage 修改按钮 + 编辑抽屉 REQ-USR-002"` | ||
| 300 | + | ||
| 301 | +--- | ||
| 302 | + | ||
| 303 | +## 提交计划 | ||
| 304 | + | ||
| 305 | +- `feat(usr): 添加 UserUpdateReqDTO / UserUpdateRespVO / 错误码 REQ-USR-002`（覆盖 Task 1） | ||
| 306 | +- `feat(usr): UserService.updateUser 三重校验 + 权限组 replace REQ-USR-002`（覆盖 Task 2） | ||
| 307 | +- `feat(usr): PUT /api/usr/users/{userId} REQ-USR-002`（覆盖 Task 3） | ||
| 308 | +- `feat(usr): updateUser API + UserFormDrawer edit 模式 REQ-USR-002`（覆盖 Task 4） | ||
| 309 | +- `feat(usr): UserListPage 修改按钮 + 编辑抽屉 REQ-USR-002`（覆盖 Task 5） |
docs/superpowers/plans/2026-05-08-REQ-USR-003.md
0 → 100644
| 1 | +--- | ||
| 2 | +req_id: REQ-USR-003 | ||
| 3 | +date: 2026-05-08 | ||
| 4 | +spec_ref: docs/superpowers/specs/2026-05-08-REQ-USR-003.md | ||
| 5 | +--- | ||
| 6 | + | ||
| 7 | +# Plan: REQ-USR-003 查询用户 | ||
| 8 | + | ||
| 9 | +> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. | ||
| 10 | + | ||
| 11 | +**Goal:** 实现 `GET /api/usr/users` 动态查询分页接口（8 字段 × 3 匹配方式，LEFT JOIN tStaff）及前端搜索列表页。 | ||
| 12 | + | ||
| 13 | +**Architecture:** 自定义 MyBatis XML Mapper 实现 LEFT JOIN 动态 SQL + MyBatis-Plus `IPage` 分页；Service 层负责 pageSize 上限截断与 queryValue 空值短路；Controller 收 `@RequestParam`，`@AuthenticationPrincipal` 取 brandId。前端用 `useEffect` 初始加载 + 搜索按钮触发重新查询，Ant Design Table 接收 `PageVO` 分页数据。 | ||
| 14 | + | ||
| 15 | +**Tech Stack:** Spring Boot 3 / MyBatis-Plus 3.x / JUnit 5 + Mockito / React 18 / Ant Design 5 / Vitest + @testing-library/react | ||
| 16 | + | ||
| 17 | +--- | ||
| 18 | + | ||
| 19 | +## Schema 改动 | ||
| 20 | +无（V1 已包含 usr_user、tStaff 所有字段） | ||
| 21 | + | ||
| 22 | +## 文件变更清单 | ||
| 23 | + | ||
| 24 | +- Create: `backend/src/main/java/com/example/erp/common/vo/PageVO.java` — 通用分页包装（含 `static of(IPage<T>)` 工厂） | ||
| 25 | +- Create: `backend/src/main/java/com/example/erp/module/usr/dto/UserListQueryDTO.java` — 查询入参 DTO | ||
| 26 | +- Create: `backend/src/main/java/com/example/erp/module/usr/vo/UserListItemVO.java` — 列表项 VO（11 字段） | ||
| 27 | +- Create: `backend/src/main/resources/mapper/UsrUserMapper.xml` — LEFT JOIN 动态分页 SQL | ||
| 28 | +- Modify: `backend/src/main/java/com/example/erp/module/usr/mapper/UsrUserMapper.java` — 添加 `selectUserList` | ||
| 29 | +- Modify: `backend/src/main/java/com/example/erp/module/usr/service/UserService.java` — 添加 `getUserList` 签名 | ||
| 30 | +- Modify: `backend/src/main/java/com/example/erp/module/usr/service/impl/UserServiceImpl.java` — 实现 `getUserList` | ||
| 31 | +- Modify: `backend/src/main/java/com/example/erp/module/usr/controller/UserController.java` — 添加 `GET /api/usr/users` | ||
| 32 | +- Modify: `backend/src/test/java/com/example/erp/module/usr/UserServiceTest.java` — 添加 `getUserList` 测试 | ||
| 33 | +- Modify: `backend/src/test/java/com/example/erp/module/usr/UserControllerTest.java` — 添加 `getUsers` 测试 | ||
| 34 | +- Modify: `frontend/src/api/usr.ts` — 添加 `UserListQueryReq`, `UserListItemVO`, `PageVO`, `getUserList()` | ||
| 35 | +- Modify: `frontend/src/pages/usr/UserListPage.tsx` — 搜索表单 + 真实 Table + 分页 | ||
| 36 | +- Modify: `frontend/src/test/UserListPage.test.tsx` — 添加列表初始加载测试 | ||
| 37 | + | ||
| 38 | +## 任务步骤 | ||
| 39 | + | ||
| 40 | +--- | ||
| 41 | + | ||
| 42 | +### Task 1: 后端 VO/DTO 骨架（PageVO + UserListItemVO + UserListQueryDTO） | ||
| 43 | + | ||
| 44 | +**Files:** | ||
| 45 | +- Create: `backend/src/main/java/com/example/erp/common/vo/PageVO.java` | ||
| 46 | +- Create: `backend/src/main/java/com/example/erp/module/usr/dto/UserListQueryDTO.java` | ||
| 47 | +- Create: `backend/src/main/java/com/example/erp/module/usr/vo/UserListItemVO.java` | ||
| 48 | +- Test: `backend/src/test/java/com/example/erp/module/usr/UserServiceTest.java` | ||
| 49 | + | ||
| 50 | +**API shape（锁定签名）：** | ||
| 51 | +```java | ||
| 52 | +// PageVO<T> — com.example.erp.common.vo | ||
| 53 | +@Getter @Setter | ||
| 54 | +public class PageVO<T> { | ||
| 55 | + private long total; | ||
| 56 | + private long page; | ||
| 57 | + private long pageSize; | ||
| 58 | + private List<T> list; | ||
| 59 | + | ||
| 60 | + public static <T> PageVO<T> of(IPage<T> iPage) { | ||
| 61 | + PageVO<T> vo = new PageVO<>(); | ||
| 62 | + vo.total = iPage.getTotal(); | ||
| 63 | + vo.page = iPage.getCurrent(); | ||
| 64 | + vo.pageSize = iPage.getSize(); | ||
| 65 | + vo.list = iPage.getRecords(); | ||
| 66 | + return vo; | ||
| 67 | + } | ||
| 68 | +} | ||
| 69 | + | ||
| 70 | +// UserListQueryDTO — com.example.erp.module.usr.dto | ||
| 71 | +@Getter @Setter | ||
| 72 | +public class UserListQueryDTO { | ||
| 73 | + private String queryField = "username"; | ||
| 74 | + private String matchType = "contains"; | ||
| 75 | + private String queryValue; | ||
| 76 | + private int page = 1; | ||
| 77 | + private int pageSize = 20; | ||
| 78 | +} | ||
| 79 | + | ||
| 80 | +// UserListItemVO — com.example.erp.module.usr.vo（全部字段加 @JsonProperty） | ||
| 81 | +@Getter @Setter | ||
| 82 | +public class UserListItemVO { | ||
| 83 | + @JsonProperty("sId") private String sId; | ||
| 84 | + @JsonProperty("sUsername") private String sUsername; | ||
| 85 | + @JsonProperty("sUserCode") private String sUserCode; | ||
| 86 | + @JsonProperty("sUserType") private String sUserType; | ||
| 87 | + @JsonProperty("sLanguage") private String sLanguage; | ||
| 88 | + @JsonProperty("bIsDisabled") private Integer bIsDisabled; | ||
| 89 | + @JsonProperty("tLastLoginDate") private LocalDateTime tLastLoginDate; | ||
| 90 | + @JsonProperty("sCreatorUsername") private String sCreatorUsername; | ||
| 91 | + @JsonProperty("tCreateDate") private LocalDateTime tCreateDate; | ||
| 92 | + @JsonProperty("sStaffName") private String sStaffName; | ||
| 93 | + @JsonProperty("sDepartment") private String sDepartment; | ||
| 94 | +} | ||
| 95 | +``` | ||
| 96 | + | ||
| 97 | +- [ ] **Step 1: 写失败测试** | ||
| 98 | + - 在 `UserServiceTest.java` 顶部 import `UserListQueryDTO` | ||
| 99 | + - 添加占位测试方法（方法体可为空，仅引用该类型使编译失败）： | ||
| 100 | + ```java | ||
| 101 | + @Test | ||
| 102 | + void getUserList_capsPageSizeAt100() { | ||
| 103 | + UserListQueryDTO q = new UserListQueryDTO(); | ||
| 104 | + q.setPageSize(200); | ||
| 105 | + } | ||
| 106 | + ``` | ||
| 107 | + - 子会话确认：`mvn test -pl backend -Dtest=UserServiceTest` 编译失败（`UserListQueryDTO` 符号找不到） | ||
| 108 | + | ||
| 109 | +- [ ] **Step 2: 创建 VO/DTO** | ||
| 110 | + - 创建 `PageVO.java`（含 `of()` 工厂） | ||
| 111 | + - 创建 `UserListQueryDTO.java` | ||
| 112 | + - 创建 `UserListItemVO.java` | ||
| 113 | + | ||
| 114 | +- [ ] **Step 3: 子会话验证 PASS** | ||
| 115 | + - `mvn test -pl backend -Dtest=UserServiceTest` 全部通过 | ||
| 116 | + | ||
| 117 | +- [ ] **Step 4: Commit** | ||
| 118 | + - `git add backend/src/main/java/com/example/erp/common/vo/PageVO.java backend/src/main/java/com/example/erp/module/usr/dto/UserListQueryDTO.java backend/src/main/java/com/example/erp/module/usr/vo/UserListItemVO.java backend/src/test/java/com/example/erp/module/usr/UserServiceTest.java` | ||
| 119 | + - `git commit -m "feat(usr): 添加 PageVO / UserListQueryDTO / UserListItemVO REQ-USR-003"` | ||
| 120 | + | ||
| 121 | +--- | ||
| 122 | + | ||
| 123 | +### Task 2: 自定义 Mapper（UsrUserMapper.xml + 方法声明） | ||
| 124 | + | ||
| 125 | +**Files:** | ||
| 126 | +- Create: `backend/src/main/resources/mapper/UsrUserMapper.xml` | ||
| 127 | +- Modify: `backend/src/main/java/com/example/erp/module/usr/mapper/UsrUserMapper.java` | ||
| 128 | +- Test: `backend/src/test/java/com/example/erp/module/usr/UserServiceTest.java` | ||
| 129 | + | ||
| 130 | +**API shape（锁定方法签名）：** | ||
| 131 | +```java | ||
| 132 | +// UsrUserMapper.java — 新增方法 | ||
| 133 | +IPage<UserListItemVO> selectUserList( | ||
| 134 | + IPage<UserListItemVO> page, | ||
| 135 | + @Param("brandId") String brandId, | ||
| 136 | + @Param("queryField") String queryField, | ||
| 137 | + @Param("matchType") String matchType, | ||
| 138 | + @Param("queryValue") String queryValue | ||
| 139 | +); | ||
| 140 | +``` | ||
| 141 | + | ||
| 142 | +**XML SQL 完整内容（UsrUserMapper.xml）：** | ||
| 143 | +```xml | ||
| 144 | +<?xml version="1.0" encoding="UTF-8"?> | ||
| 145 | +<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" | ||
| 146 | + "http://mybatis.org/dtd/mybatis-3-mapper.dtd"> | ||
| 147 | +<mapper namespace="com.example.erp.module.usr.mapper.UsrUserMapper"> | ||
| 148 | + | ||
| 149 | + <select id="selectUserList" resultType="com.example.erp.module.usr.vo.UserListItemVO"> | ||
| 150 | + SELECT u.sId, u.sUsername, u.sUserCode, u.sUserType, u.sLanguage, | ||
| 151 | + u.bIsDisabled, u.tLastLoginDate, u.sCreatorUsername, u.tCreateDate, | ||
| 152 | + s.sStaffName, s.sDepartment | ||
| 153 | + FROM usr_user u | ||
| 154 | + LEFT JOIN tStaff s ON u.sEmployeeId = s.sId | ||
| 155 | + AND s.sBrandsId = u.sBrandsId | ||
| 156 | + AND s.bDeleted = 0 | ||
| 157 | + WHERE u.sBrandsId = #{brandId} | ||
| 158 | + <if test="queryValue != null and queryValue != ''"> | ||
| 159 | + <choose> | ||
| 160 | + <when test="queryField == 'username'"> | ||
| 161 | + <choose> | ||
| 162 | + <when test="matchType == 'contains'">AND u.sUsername LIKE CONCAT('%', #{queryValue}, '%')</when> | ||
| 163 | + <when test="matchType == 'notContains'">AND u.sUsername NOT LIKE CONCAT('%', #{queryValue}, '%')</when> | ||
| 164 | + <otherwise>AND u.sUsername = #{queryValue}</otherwise> | ||
| 165 | + </choose> | ||
| 166 | + </when> | ||
| 167 | + <when test="queryField == 'staffName'"> | ||
| 168 | + <choose> | ||
| 169 | + <when test="matchType == 'contains'">AND s.sStaffName LIKE CONCAT('%', #{queryValue}, '%')</when> | ||
| 170 | + <when test="matchType == 'notContains'">AND s.sStaffName NOT LIKE CONCAT('%', #{queryValue}, '%')</when> | ||
| 171 | + <otherwise>AND s.sStaffName = #{queryValue}</otherwise> | ||
| 172 | + </choose> | ||
| 173 | + </when> | ||
| 174 | + <when test="queryField == 'userCode'"> | ||
| 175 | + <choose> | ||
| 176 | + <when test="matchType == 'contains'">AND u.sUserCode LIKE CONCAT('%', #{queryValue}, '%')</when> | ||
| 177 | + <when test="matchType == 'notContains'">AND u.sUserCode NOT LIKE CONCAT('%', #{queryValue}, '%')</when> | ||
| 178 | + <otherwise>AND u.sUserCode = #{queryValue}</otherwise> | ||
| 179 | + </choose> | ||
| 180 | + </when> | ||
| 181 | + <when test="queryField == 'department'"> | ||
| 182 | + <choose> | ||
| 183 | + <when test="matchType == 'contains'">AND s.sDepartment LIKE CONCAT('%', #{queryValue}, '%')</when> | ||
| 184 | + <when test="matchType == 'notContains'">AND s.sDepartment NOT LIKE CONCAT('%', #{queryValue}, '%')</when> | ||
| 185 | + <otherwise>AND s.sDepartment = #{queryValue}</otherwise> | ||
| 186 | + </choose> | ||
| 187 | + </when> | ||
| 188 | + <when test="queryField == 'userType'"> | ||
| 189 | + <choose> | ||
| 190 | + <when test="matchType == 'contains'">AND u.sUserType LIKE CONCAT('%', #{queryValue}, '%')</when> | ||
| 191 | + <when test="matchType == 'notContains'">AND u.sUserType NOT LIKE CONCAT('%', #{queryValue}, '%')</when> | ||
| 192 | + <otherwise>AND u.sUserType = #{queryValue}</otherwise> | ||
| 193 | + </choose> | ||
| 194 | + </when> | ||
| 195 | + <when test="queryField == 'creator'"> | ||
| 196 | + <choose> | ||
| 197 | + <when test="matchType == 'contains'">AND u.sCreatorUsername LIKE CONCAT('%', #{queryValue}, '%')</when> | ||
| 198 | + <when test="matchType == 'notContains'">AND u.sCreatorUsername NOT LIKE CONCAT('%', #{queryValue}, '%')</when> | ||
| 199 | + <otherwise>AND u.sCreatorUsername = #{queryValue}</otherwise> | ||
| 200 | + </choose> | ||
| 201 | + </when> | ||
| 202 | + <when test="queryField == 'disabled'"> | ||
| 203 | + <choose> | ||
| 204 | + <when test="queryValue == '是'">AND u.bIsDisabled = 1</when> | ||
| 205 | + <when test="queryValue == '否'">AND u.bIsDisabled = 0</when> | ||
| 206 | + </choose> | ||
| 207 | + </when> | ||
| 208 | + <when test="queryField == 'lastLoginDate'"> | ||
| 209 | + AND DATE(u.tLastLoginDate) = #{queryValue} | ||
| 210 | + </when> | ||
| 211 | + </choose> | ||
| 212 | + </if> | ||
| 213 | + ORDER BY u.tCreateDate DESC | ||
| 214 | + </select> | ||
| 215 | + | ||
| 216 | +</mapper> | ||
| 217 | +``` | ||
| 218 | + | ||
| 219 | +注：`mybatis-plus.mapper-locations` 默认为 `classpath*:/mapper/**/*.xml`，文件放 `src/main/resources/mapper/UsrUserMapper.xml` 会自动扫描到。 | ||
| 220 | + | ||
| 221 | +- [ ] **Step 1: 写失败测试** | ||
| 222 | + - 在 `UserServiceTest.java` 中添加 mock stub 引用 `selectUserList`： | ||
| 223 | + ```java | ||
| 224 | + @Test | ||
| 225 | + void getUserList_callsSelectUserList() { | ||
| 226 | + IPage<UserListItemVO> mockPage = new Page<>(1, 20, 0); | ||
| 227 | + when(userMapper.selectUserList(any(), eq("b1"), any(), any(), any())) | ||
| 228 | + .thenReturn(mockPage); | ||
| 229 | + // getUserList 方法此时不存在于 UserService → 编译失败 | ||
| 230 | + } | ||
| 231 | + ``` | ||
| 232 | + - 同时 `@Mock private UsrUserMapper userMapper` 已有，直接 `userMapper.selectUserList(...)` 引用即可触发编译失败 | ||
| 233 | + - 子会话确认 FAIL（`selectUserList` 方法不存在） | ||
| 234 | + | ||
| 235 | +- [ ] **Step 2: 实现 Mapper** | ||
| 236 | + - `UsrUserMapper.java` 添加 `selectUserList` 方法（带 `@Param` 注解，需 import `com.baomidou.mybatisplus.extension.plugins.pagination.Page`） | ||
| 237 | + - 创建 `src/main/resources/mapper/UsrUserMapper.xml` | ||
| 238 | + | ||
| 239 | +- [ ] **Step 3: 子会话验证 PASS** | ||
| 240 | + - `mvn test -pl backend -Dtest=UserServiceTest` 通过 | ||
| 241 | + | ||
| 242 | +- [ ] **Step 4: Commit** | ||
| 243 | + - `git commit -m "feat(usr): 添加 selectUserList XML 动态分页查询 REQ-USR-003"` | ||
| 244 | + | ||
| 245 | +--- | ||
| 246 | + | ||
| 247 | +### Task 3: Service 层 + Controller 端点 | ||
| 248 | + | ||
| 249 | +**Files:** | ||
| 250 | +- Modify: `backend/src/main/java/com/example/erp/module/usr/service/UserService.java` | ||
| 251 | +- Modify: `backend/src/main/java/com/example/erp/module/usr/service/impl/UserServiceImpl.java` | ||
| 252 | +- Modify: `backend/src/main/java/com/example/erp/module/usr/controller/UserController.java` | ||
| 253 | +- Test: `UserServiceTest.java`（service 层）、`UserControllerTest.java`（HTTP 层） | ||
| 254 | + | ||
| 255 | +**API shape（锁定签名）：** | ||
| 256 | +```java | ||
| 257 | +// UserService 接口 | ||
| 258 | +PageVO<UserListItemVO> getUserList(UserListQueryDTO query, String brandId); | ||
| 259 | + | ||
| 260 | +// UserServiceImpl — getUserList 实现逻辑 | ||
| 261 | +@Transactional(readOnly = true) | ||
| 262 | +public PageVO<UserListItemVO> getUserList(UserListQueryDTO query, String brandId) { | ||
| 263 | + int cappedSize = Math.min(query.getPageSize(), 100); | ||
| 264 | + IPage<UserListItemVO> iPage = new Page<>(query.getPage(), cappedSize); | ||
| 265 | + userMapper.selectUserList(iPage, brandId, | ||
| 266 | + query.getQueryField(), query.getMatchType(), | ||
| 267 | + query.getQueryValue() == null ? "" : query.getQueryValue()); | ||
| 268 | + return PageVO.of(iPage); | ||
| 269 | +} | ||
| 270 | + | ||
| 271 | +// UserController — 新增端点 | ||
| 272 | +@GetMapping("/users") | ||
| 273 | +public Result<PageVO<UserListItemVO>> getUsers( | ||
| 274 | + @RequestParam(defaultValue = "username") String queryField, | ||
| 275 | + @RequestParam(defaultValue = "contains") String matchType, | ||
| 276 | + @RequestParam(defaultValue = "") String queryValue, | ||
| 277 | + @RequestParam(defaultValue = "1") int page, | ||
| 278 | + @RequestParam(defaultValue = "20") int pageSize, | ||
| 279 | + @AuthenticationPrincipal UserPrincipal principal) { | ||
| 280 | + UserListQueryDTO q = new UserListQueryDTO(); | ||
| 281 | + q.setQueryField(queryField); | ||
| 282 | + q.setMatchType(matchType); | ||
| 283 | + q.setQueryValue(queryValue); | ||
| 284 | + q.setPage(page); | ||
| 285 | + q.setPageSize(pageSize); | ||
| 286 | + return Result.ok(userService.getUserList(q, principal.brandId())); | ||
| 287 | +} | ||
| 288 | +``` | ||
| 289 | + | ||
| 290 | +- [ ] **Step 1: 写失败测试（Service）** | ||
| 291 | + - 测试名: `UserServiceTest#getUserList_capsPageSizeAt100_callsMapper` | ||
| 292 | + - 意图：`pageSize=200` → mapper 被调用时 `iPage.getSize() == 100`；返回的 `PageVO.getTotal() == 5` | ||
| 293 | + - 断言 sketch： | ||
| 294 | + ```java | ||
| 295 | + UserListQueryDTO q = new UserListQueryDTO(); | ||
| 296 | + q.setPageSize(200); | ||
| 297 | + IPage<UserListItemVO> mockPage = new Page<>(1, 100, 5); | ||
| 298 | + when(userMapper.selectUserList(argThat(p -> p.getSize() == 100), eq("b1"), any(), any(), any())) | ||
| 299 | + .thenReturn(mockPage); | ||
| 300 | + PageVO<UserListItemVO> result = userService.getUserList(q, "b1"); // 编译失败 | ||
| 301 | + assertEquals(5, result.getTotal()); | ||
| 302 | + ``` | ||
| 303 | + - 子会话确认 FAIL（`getUserList` 不在接口/实现中） | ||
| 304 | + | ||
| 305 | +- [ ] **Step 2: 实现 Service** | ||
| 306 | + - `UserService.java` 添加 `getUserList` 方法签名 | ||
| 307 | + - `UserServiceImpl.java` 实现（pageSize cap + delegate + `PageVO.of`） | ||
| 308 | + | ||
| 309 | +- [ ] **Step 3: 子会话验证 Service PASS** | ||
| 310 | + - `mvn test -pl backend -Dtest=UserServiceTest` 通过 | ||
| 311 | + | ||
| 312 | +- [ ] **Step 4: 写失败测试（Controller）** | ||
| 313 | + - 测试名: `UserControllerTest#getUsers_withToken_returns200` | ||
| 314 | + - 意图：带 JWT Token 的 `GET /api/usr/users` → HTTP 200，响应 JSON 中 `$.data.total` 存在 | ||
| 315 | + - mock stub：`when(userService.getUserList(any(), eq("b1"))).thenReturn(pageVO)`（pageVO.total=0, pageVO.list=[]） | ||
| 316 | + - 子会话确认 FAIL（端点不存在 → Spring 返回 404 或方法签名缺失导致编译失败） | ||
| 317 | + | ||
| 318 | +- [ ] **Step 5: 实现 Controller 端点** | ||
| 319 | + - `UserController.java` 添加 `@GetMapping("/users")` 方法 | ||
| 320 | + | ||
| 321 | +- [ ] **Step 6: 子会话验证 Controller PASS** | ||
| 322 | + - `mvn test -pl backend -Dtest=UserControllerTest` 通过 | ||
| 323 | + | ||
| 324 | +- [ ] **Step 7: Commit** | ||
| 325 | + - `git commit -m "feat(usr): getUserList service + GET /api/usr/users 端点 REQ-USR-003"` | ||
| 326 | + | ||
| 327 | +--- | ||
| 328 | + | ||
| 329 | +### Task 4: 前端 API 类型 + 用户列表页 | ||
| 330 | + | ||
| 331 | +**Files:** | ||
| 332 | +- Modify: `frontend/src/api/usr.ts` | ||
| 333 | +- Modify: `frontend/src/pages/usr/UserListPage.tsx` | ||
| 334 | +- Modify: `frontend/src/test/UserListPage.test.tsx` | ||
| 335 | + | ||
| 336 | +**API shape（锁定 usr.ts 新增部分）：** | ||
| 337 | +```ts | ||
| 338 | +export interface UserListQueryReq { | ||
| 339 | + queryField?: string; | ||
| 340 | + matchType?: string; | ||
| 341 | + queryValue?: string; | ||
| 342 | + page?: number; | ||
| 343 | + pageSize?: number; | ||
| 344 | +} | ||
| 345 | + | ||
| 346 | +export interface UserListItemVO { | ||
| 347 | + sId: string; | ||
| 348 | + sUsername: string; | ||
| 349 | + sUserCode: string; | ||
| 350 | + sUserType: string; | ||
| 351 | + sLanguage: string; | ||
| 352 | + bIsDisabled: number; | ||
| 353 | + tLastLoginDate: string | null; | ||
| 354 | + sCreatorUsername: string | null; | ||
| 355 | + tCreateDate: string; | ||
| 356 | + sStaffName: string | null; | ||
| 357 | + sDepartment: string | null; | ||
| 358 | +} | ||
| 359 | + | ||
| 360 | +export interface PageVO<T> { | ||
| 361 | + total: number; | ||
| 362 | + page: number; | ||
| 363 | + pageSize: number; | ||
| 364 | + list: T[]; | ||
| 365 | +} | ||
| 366 | + | ||
| 367 | +export function getUserList(params?: UserListQueryReq): Promise<PageVO<UserListItemVO>> { | ||
| 368 | + return request.get('/usr/users', { params }) | ||
| 369 | +} | ||
| 370 | +``` | ||
| 371 | + | ||
| 372 | +**UserListPage.tsx 结构（含搜索表单）：** | ||
| 373 | +```tsx | ||
| 374 | +export default function UserListPage() { | ||
| 375 | + const [data, setData] = useState<PageVO<UserListItemVO> | null>(null) | ||
| 376 | + const [queryField, setQueryField] = useState('username') | ||
| 377 | + const [matchType, setMatchType] = useState('contains') | ||
| 378 | + const [queryValue, setQueryValue] = useState('') | ||
| 379 | + const [page, setPage] = useState(1) | ||
| 380 | + | ||
| 381 | + const load = (pg = 1) => { | ||
| 382 | + getUserList({ queryField, matchType, queryValue, page: pg, pageSize: 20 }).then(setData) | ||
| 383 | + setPage(pg) | ||
| 384 | + } | ||
| 385 | + | ||
| 386 | + useEffect(() => { load() }, []) // 初始加载 | ||
| 387 | + | ||
| 388 | + const columns: ColumnsType<UserListItemVO> = [ | ||
| 389 | + { title: '用户名', dataIndex: 'sUsername' }, | ||
| 390 | + { title: '员工名', dataIndex: 'sStaffName' }, | ||
| 391 | + { title: '用户号', dataIndex: 'sUserCode' }, | ||
| 392 | + { title: '部门', dataIndex: 'sDepartment' }, | ||
| 393 | + { title: '用户类型', dataIndex: 'sUserType' }, | ||
| 394 | + { title: '语言', dataIndex: 'sLanguage' }, | ||
| 395 | + { title: '作废', dataIndex: 'bIsDisabled', render: v => v ? '是' : '否' }, | ||
| 396 | + { title: '登录日期', dataIndex: 'tLastLoginDate' }, | ||
| 397 | + { title: '制单人', dataIndex: 'sCreatorUsername' }, | ||
| 398 | + { title: '制单日期', dataIndex: 'tCreateDate' }, | ||
| 399 | + ] | ||
| 400 | + | ||
| 401 | + return ( | ||
| 402 | + <div> | ||
| 403 | + <Space style={{ marginBottom: 16 }}> | ||
| 404 | + <Select value={queryField} onChange={setQueryField} style={{ width: 120 }}> | ||
| 405 | + <Select.Option value="username">用户名</Select.Option> | ||
| 406 | + <Select.Option value="staffName">员工名</Select.Option> | ||
| 407 | + <Select.Option value="userCode">用户号</Select.Option> | ||
| 408 | + <Select.Option value="department">部门</Select.Option> | ||
| 409 | + <Select.Option value="userType">用户类型</Select.Option> | ||
| 410 | + <Select.Option value="disabled">作废</Select.Option> | ||
| 411 | + <Select.Option value="lastLoginDate">登录日期</Select.Option> | ||
| 412 | + <Select.Option value="creator">制单人</Select.Option> | ||
| 413 | + </Select> | ||
| 414 | + <Select value={matchType} onChange={setMatchType} style={{ width: 100 }}> | ||
| 415 | + <Select.Option value="contains">包含</Select.Option> | ||
| 416 | + <Select.Option value="notContains">不包含</Select.Option> | ||
| 417 | + <Select.Option value="equals">等于</Select.Option> | ||
| 418 | + </Select> | ||
| 419 | + <Input value={queryValue} onChange={e => setQueryValue(e.target.value)} placeholder="查询值" /> | ||
| 420 | + <Button type="primary" onClick={() => load(1)}>搜索</Button> | ||
| 421 | + <PermButton permission="usr:create" type="primary" onClick={() => setDrawerOpen(true)}>新增</PermButton> | ||
| 422 | + </Space> | ||
| 423 | + <Table | ||
| 424 | + dataSource={data?.list ?? []} | ||
| 425 | + columns={columns} | ||
| 426 | + rowKey="sId" | ||
| 427 | + pagination={{ | ||
| 428 | + total: data?.total ?? 0, | ||
| 429 | + pageSize: 20, | ||
| 430 | + current: page, | ||
| 431 | + onChange: load, | ||
| 432 | + }} | ||
| 433 | + /> | ||
| 434 | + <UserFormDrawer open={drawerOpen} onClose={() => setDrawerOpen(false)} onSuccess={() => { setDrawerOpen(false); load(1) }} /> | ||
| 435 | + </div> | ||
| 436 | + ) | ||
| 437 | +} | ||
| 438 | +``` | ||
| 439 | + | ||
| 440 | +注：`drawerOpen` state 也需添加（与 Task 1 中 UserListPage 原来的 `drawerOpen` 合并）。 | ||
| 441 | + | ||
| 442 | +- [ ] **Step 1: 写失败测试** | ||
| 443 | + - 测试名: `UserListPage.test.tsx#initialLoad_rendersTableRows` | ||
| 444 | + - 意图：mock `getUserList` 返回含 1 条 `{ sId:'u1', sUsername:'alice', ... }` 的 PageVO → 等待 data 渲染后 table 中有 "alice" 文本 | ||
| 445 | + - 断言 sketch： | ||
| 446 | + ```ts | ||
| 447 | + vi.mock('@/api/usr', async (importOriginal) => { | ||
| 448 | + const actual = await importOriginal<typeof import('@/api/usr')>() | ||
| 449 | + return { ...actual, getUserList: vi.fn().mockResolvedValue({ total: 1, page: 1, pageSize: 20, list: [{ sId:'u1', sUsername:'alice', sUserCode:'UC001', sUserType:'普通用户', sLanguage:'中文', bIsDisabled:0, tLastLoginDate:null, sCreatorUsername:'admin', tCreateDate:'2026-01-01', sStaffName:null, sDepartment:null }] }) } | ||
| 450 | + }) | ||
| 451 | + // render + waitFor → screen.getByText('alice') | ||
| 452 | + ``` | ||
| 453 | + - 子会话确认 FAIL（`getUserList` 不在 `usr.ts` 中 → import 报错） | ||
| 454 | + | ||
| 455 | +- [ ] **Step 2: 实现前端** | ||
| 456 | + - `usr.ts` 添加 `UserListQueryReq`, `UserListItemVO`, `PageVO`, `getUserList()` | ||
| 457 | + - `UserListPage.tsx` 重构为搜索表单 + 真实 Table（保留 `drawerOpen` 和 `UserFormDrawer`） | ||
| 458 | + | ||
| 459 | +- [ ] **Step 3: 子会话验证 PASS** | ||
| 460 | + - `pnpm test --run` 全部通过 | ||
| 461 | + | ||
| 462 | +- [ ] **Step 4: Commit** | ||
| 463 | + - `git commit -m "feat(usr): 用户列表搜索表单 + 分页表格 REQ-USR-003"` | ||
| 464 | + | ||
| 465 | +--- | ||
| 466 | + | ||
| 467 | +## 提交计划 | ||
| 468 | + | ||
| 469 | +- `feat(usr): 添加 PageVO / UserListQueryDTO / UserListItemVO REQ-USR-003`（覆盖 Task 1） | ||
| 470 | +- `feat(usr): 添加 selectUserList XML 动态分页查询 REQ-USR-003`（覆盖 Task 2） | ||
| 471 | +- `feat(usr): getUserList service + GET /api/usr/users 端点 REQ-USR-003`（覆盖 Task 3） | ||
| 472 | +- `feat(usr): 用户列表搜索表单 + 分页表格 REQ-USR-003`（覆盖 Task 4） |
docs/superpowers/specs/2026-05-08-REQ-USR-002.md
0 → 100644
| 1 | +--- | ||
| 2 | +req_id: REQ-USR-002 | ||
| 3 | +date: 2026-05-08 | ||
| 4 | +module: usr | ||
| 5 | +--- | ||
| 6 | + | ||
| 7 | +# Spec: REQ-USR-002 — 修改用户 | ||
| 8 | + | ||
| 9 | +## 目标 | ||
| 10 | +超级管理员可通过 userId 定位已有用户，更新其用户类型、语言、单据修改权限、启/停用状态、关联员工和权限组，修改立即生效；用户名不可修改，密码由单独接口重置。 | ||
| 11 | + | ||
| 12 | +## 输入 / 触发 | ||
| 13 | + | ||
| 14 | +HTTP 请求：`PUT /api/usr/users/{userId}`（需 Bearer Token 鉴权） | ||
| 15 | + | ||
| 16 | +Path 参数：`userId`（`usr_user.sId`，目标用户的业务 ID） | ||
| 17 | + | ||
| 18 | +Request Body（JSON）： | ||
| 19 | + | ||
| 20 | +| 字段 | 类型 | 必填 | 说明 | | ||
| 21 | +|---|---|---|---| | ||
| 22 | +| userType | String | 是 | `普通用户` 或 `超级管理员` | | ||
| 23 | +| language | String | 是 | `中文` / `英文` / `繁体` | | ||
| 24 | +| canEditDoc | boolean | 是 | 是否有单据修改权限 | | ||
| 25 | +| isDisabled | boolean | 是 | true = 禁用账号 | | ||
| 26 | +| employeeId | String\|null | 否 | 关联职员 sId，null = 取消关联 | | ||
| 27 | +| permGroupIds | String[] | 是 | 权限组 sId 列表（空数组 = 清空所有权限） | | ||
| 28 | + | ||
| 29 | +## 输出 / 结果 | ||
| 30 | + | ||
| 31 | +HTTP 200，`Result<UserUpdateRespVO>` | ||
| 32 | + | ||
| 33 | +```json | ||
| 34 | +{ | ||
| 35 | + "code": 200, | ||
| 36 | + "data": { | ||
| 37 | + "userId": "string", | ||
| 38 | + "username": "string", | ||
| 39 | + "updatedAt": "2026-05-08T10:00:00" | ||
| 40 | + } | ||
| 41 | +} | ||
| 42 | +``` | ||
| 43 | + | ||
| 44 | +`updatedAt` 为服务端处理时的 `LocalDateTime.now()`，序列化为 ISO-8601。 | ||
| 45 | + | ||
| 46 | +## 业务规则 | ||
| 47 | + | ||
| 48 | +1. **权限校验**：`principal.userType() != "超级管理员"` → 抛 BizException(40300)，与 createUser 逻辑一致（来源：`UserServiceImpl.createUser`） | ||
| 49 | +2. **用户存在性**：按 `sId = userId AND sBrandsId = brandId` 查 `usr_user`；找不到 → 抛 BizException(40400) | ||
| 50 | +3. **自身角色保护**：`principal.userId().equals(userId)` 时，禁止将 `userType` 从 `超级管理员` 改为其他值 → 抛 BizException(40301)（防止唯一管理员自我降权导致系统锁死；即使目标 userType 已是普通用户也拦截，保持规则简单） | ||
| 51 | +4. **employeeId 校验**：若 `employeeId != null`，需确认 `tStaff.sId = employeeId AND sBrandsId = brandId` 存在；不存在 → 抛 BizException(40001) | ||
| 52 | +5. **更新字段**：仅更新 `sUserType / sLanguage / bCanEditDoc / bIsDisabled / sEmployeeId`；`sUsername / sUserCode / sPasswordHash / sCreatorUsername / tCreateDate` 不修改 | ||
| 53 | +6. **权限组 replace 策略**：先 `DELETE FROM usr_user_permission WHERE sUserId = userId AND sBrandsId = brandId`，再批量 INSERT 新的关联记录（与 createUser 的 permGroupIds 处理方式一致）；permGroupIds 为空数组时仅删除，不插入 | ||
| 54 | +7. **多租户隔离**：所有查询和写入均带 `sBrandsId = principal.brandId()` | ||
| 55 | + | ||
| 56 | +## 边界与约束 | ||
| 57 | + | ||
| 58 | +- 接口为写操作，需加 `@Transactional` | ||
| 59 | +- 鉴权失败返回 401（SecurityConfig 已配置） | ||
| 60 | +- `userType` / `language` 仅接受指定枚举值；违反 → 由 `@Valid` + `@NotNull` 在 DTO 层拦截返回 40001 | ||
| 61 | +- 密码不在此接口处理，`sPasswordHash` 保持原值不变 | ||
| 62 | +- 响应 JSON 不返回 sPasswordHash / iLoginFailCount / tLockUntil | ||
| 63 | + | ||
| 64 | +## 依赖的 schema 表 / 字段 | ||
| 65 | + | ||
| 66 | +- `usr_user (别名 u)`：sId, sUserType, sLanguage, bCanEditDoc, bIsDisabled, sEmployeeId, sBrandsId（查找 + 更新） | ||
| 67 | +- `tStaff`：sId, sBrandsId（校验 employeeId 存在性） | ||
| 68 | +- `usr_permission_group`：仅前端下拉，不涉及后端写操作 | ||
| 69 | +- `usr_user_permission`：sUserId, sPermGroupId, sBrandsId, sId, tCreateDate（先删后插） | ||
| 70 | + | ||
| 71 | +## 依赖的接口 | ||
| 72 | + | ||
| 73 | +- `POST /api/auth/login`（REQ-USR-004，获取 Bearer Token） | ||
| 74 | +- `GET /api/usr/users`（REQ-USR-003，获取列表后点击行触发修改抽屉） | ||
| 75 | +- `GET /api/usr/users/staffs`（REQ-USR-001，前端抽屉加载员工下拉） | ||
| 76 | +- `GET /api/usr/users/permission-groups`（REQ-USR-001，前端抽屉加载权限组列表） | ||
| 77 | + | ||
| 78 | +## 验收标准 | ||
| 79 | + | ||
| 80 | +1. `PUT /api/usr/users/{validId}` Body 合法 → HTTP 200，返回 userId/username/updatedAt，数据库对应字段已更新 | ||
| 81 | +2. `userId` 不存在（或属于其他 brand）→ 返回 40400 | ||
| 82 | +3. 非超级管理员 Token 调用 → 返回 40300 | ||
| 83 | +4. 超级管理员修改自己的 userType → 返回 40301 | ||
| 84 | +5. `isDisabled=true` 修改后，目标用户再登录 → 返回 40101（账号已禁用） | ||
| 85 | +6. permGroupIds 为空数组 → 该用户权限组被清空，下次查询 permission-groups 对应关联为空 | ||
| 86 | +7. permGroupIds 非空 → 权限组先删后插，关联记录与提交值一致 | ||
| 87 | +8. 无 Token → 返回 401 | ||
| 88 | +9. 前端：UserListPage 表格行有"修改"按钮，点击弹出预填修改抽屉；提交后关闭抽屉并刷新列表 | ||
| 89 | + | ||
| 90 | +## 前端交互设计 | ||
| 91 | + | ||
| 92 | +**UserFormDrawer 改造（复用已有组件）**： | ||
| 93 | +- 新增 props：`userId?: string`，`initialData?: { userType, language, canEditDoc, isDisabled, employeeId, permGroupIds: string[] }` | ||
| 94 | +- 当 `userId` 存在时（edit 模式）： | ||
| 95 | + - 抽屉标题改为 "修改用户" | ||
| 96 | + - 隐藏用户号和用户名 Form.Item（或显示为只读文本） | ||
| 97 | + - `open` 时用 `initialData` 初始化 form 和 selectedPermIds | ||
| 98 | + - 提交调 `updateUser(userId, req)` 而非 `createUser` | ||
| 99 | +- 当 `userId` 不存在时（create 模式）：行为与现有完全一致 | ||
| 100 | + | ||
| 101 | +**UserListPage 改造**： | ||
| 102 | +- columns 末尾加"操作"列，包含"修改"按钮（PermButton，权限 `usr:edit`） | ||
| 103 | +- 点击"修改"按钮：将该行 `UserListItemVO` 转换为 `initialData`（permGroupIds 需额外从后端获取或在列表中推导——因列表不返回 permGroupIds，修改抽屉打开时无法预填权限组复选框，初始化为空数组即可，用户可重新勾选） | ||
| 104 | +- 新增状态：`editingUser: UserListItemVO | null`，控制修改抽屉开关 | ||
| 105 | + | ||
| 106 | +**新增 API 函数**（`frontend/src/api/usr.ts`）： | ||
| 107 | +```ts | ||
| 108 | +export interface UserUpdateReq { | ||
| 109 | + userType: string | ||
| 110 | + language: string | ||
| 111 | + canEditDoc: boolean | ||
| 112 | + isDisabled: boolean | ||
| 113 | + employeeId: string | null | ||
| 114 | + permGroupIds: string[] | ||
| 115 | +} | ||
| 116 | + | ||
| 117 | +export interface UserUpdateResp { | ||
| 118 | + userId: string | ||
| 119 | + username: string | ||
| 120 | + updatedAt: string | ||
| 121 | +} | ||
| 122 | + | ||
| 123 | +export function updateUser(userId: string, req: UserUpdateReq): Promise<UserUpdateResp> { | ||
| 124 | + return request.put(`/usr/users/${userId}`, req) | ||
| 125 | +} | ||
| 126 | +``` |
docs/superpowers/specs/2026-05-08-REQ-USR-003.md
0 → 100644
| 1 | +--- | ||
| 2 | +req_id: REQ-USR-003 | ||
| 3 | +date: 2026-05-08 | ||
| 4 | +module: usr | ||
| 5 | +--- | ||
| 6 | + | ||
| 7 | +# Spec: REQ-USR-003 — 查询用户 | ||
| 8 | + | ||
| 9 | +## 目标 | ||
| 10 | +超级管理员可按 8 种查询字段 + 3 种匹配方式组合筛选，分页浏览本品牌下的用户列表；列表同时展示关联职员的员工名与部门。 | ||
| 11 | + | ||
| 12 | +## 输入 / 触发 | ||
| 13 | +HTTP 请求：`GET /api/usr/users`（需 Bearer Token 鉴权） | ||
| 14 | + | ||
| 15 | +Query 参数： | ||
| 16 | + | ||
| 17 | +| 参数 | 类型 | 必填 | 默认值 | 说明 | | ||
| 18 | +|---|---|---|---|---| | ||
| 19 | +| queryField | String | 否 | `username` | 查询字段枚举，见下表 | | ||
| 20 | +| matchType | String | 否 | `contains` | 匹配方式枚举：`contains` / `notContains` / `equals` | | ||
| 21 | +| queryValue | String | 否 | — | 查询值；空字符串或不传 = 全部 | | ||
| 22 | +| page | int | 否 | 1 | 页码，从 1 开始 | | ||
| 23 | +| pageSize | int | 否 | 20 | 每页条数，最大 100 | | ||
| 24 | + | ||
| 25 | +queryField 枚举（前端显示名 → 参数值 → 后端列）： | ||
| 26 | + | ||
| 27 | +| 前端显示 | 参数值 | 后端列 | | ||
| 28 | +|---|---|---| | ||
| 29 | +| 用户名 | `username` | `u.sUsername` | | ||
| 30 | +| 员工名 | `staffName` | `s.sStaffName` | | ||
| 31 | +| 用户号 | `userCode` | `u.sUserCode` | | ||
| 32 | +| 部门 | `department` | `s.sDepartment` | | ||
| 33 | +| 用户类型 | `userType` | `u.sUserType` | | ||
| 34 | +| 作废 | `disabled` | `u.bIsDisabled` | | ||
| 35 | +| 登录日期 | `lastLoginDate` | `u.tLastLoginDate` | | ||
| 36 | +| 制单人 | `creator` | `u.sCreatorUsername` | | ||
| 37 | + | ||
| 38 | +## 输出 / 结果 | ||
| 39 | +HTTP 200，`Result<PageVO<UserListItemVO>>` | ||
| 40 | + | ||
| 41 | +`PageVO<T>` 结构（通用分页包装）： | ||
| 42 | +```json | ||
| 43 | +{ | ||
| 44 | + "total": 25, | ||
| 45 | + "page": 1, | ||
| 46 | + "pageSize": 20, | ||
| 47 | + "list": [ ...UserListItemVO... ] | ||
| 48 | +} | ||
| 49 | +``` | ||
| 50 | + | ||
| 51 | +`UserListItemVO` 字段（禁止返回 sPasswordHash / iLoginFailCount / tLockUntil）： | ||
| 52 | + | ||
| 53 | +| JSON 字段 | 来源列 | 可 null | | ||
| 54 | +|---|---|---| | ||
| 55 | +| sId | usr_user.sId | 否 | | ||
| 56 | +| sUsername | usr_user.sUsername | 否 | | ||
| 57 | +| sUserCode | usr_user.sUserCode | 否 | | ||
| 58 | +| sUserType | usr_user.sUserType | 否 | | ||
| 59 | +| sLanguage | usr_user.sLanguage | 否 | | ||
| 60 | +| bIsDisabled | usr_user.bIsDisabled | 否 | | ||
| 61 | +| tLastLoginDate | usr_user.tLastLoginDate | 是 | | ||
| 62 | +| sCreatorUsername | usr_user.sCreatorUsername | 是 | | ||
| 63 | +| tCreateDate | usr_user.tCreateDate | 否 | | ||
| 64 | +| sStaffName | tStaff.sStaffName | 是（LEFT JOIN） | | ||
| 65 | +| sDepartment | tStaff.sDepartment | 是（LEFT JOIN） | | ||
| 66 | + | ||
| 67 | +## 业务规则 | ||
| 68 | + | ||
| 69 | +1. **多租户隔离**：所有查询必须附加 `u.sBrandsId = principal.brandId()` | ||
| 70 | +2. **queryValue 为空**：忽略查询条件，返回该品牌全部用户 | ||
| 71 | +3. **匹配方式映射**（文本字段：username / staffName / userCode / department / userType / creator）： | ||
| 72 | + - `contains` → `LIKE '%value%'` | ||
| 73 | + - `notContains` → `NOT LIKE '%value%'` | ||
| 74 | + - `equals` → `= 'value'` | ||
| 75 | +4. **布尔字段（disabled）**：仅有意义的匹配是 equals；queryValue="是" → `bIsDisabled = 1`；"否" → `bIsDisabled = 0`；其他值（包括 contains/notContains 的非 "是"/"否"）忽略条件 | ||
| 76 | +5. **日期字段（lastLoginDate）**：queryValue 格式 `YYYY-MM-DD`；无论 matchType 为何，均使用 `DATE(tLastLoginDate) = 'YYYY-MM-DD'` | ||
| 77 | +6. **pageSize 截断**：pageSize > 100 时强制截断为 100 | ||
| 78 | +7. **分页越界**：page 超出总页数时返回最后一页（MyBatis-Plus `Page` 默认行为） | ||
| 79 | +8. **职员 JOIN**：`LEFT JOIN tStaff s ON u.sEmployeeId = s.sId AND s.sBrandsId = u.sBrandsId AND s.bDeleted = 0`；未关联职员时 sStaffName / sDepartment 为 null | ||
| 80 | + | ||
| 81 | +## 边界与约束 | ||
| 82 | +- 接口为只读，无写副作用 | ||
| 83 | +- 鉴权失败返回 401（SecurityConfig.authenticationEntryPoint 已配置） | ||
| 84 | +- 单次最多返回 100 条 | ||
| 85 | + | ||
| 86 | +## 依赖的 schema 表 / 字段 | ||
| 87 | +- `usr_user (别名 u)`：sId, sUsername, sUserCode, sUserType, sLanguage, bIsDisabled, sEmployeeId, sCreatorUsername, tLastLoginDate, tCreateDate, sBrandsId | ||
| 88 | +- `tStaff (别名 s)`：sId, sStaffName, sDepartment, sBrandsId, bDeleted | ||
| 89 | + | ||
| 90 | +## 依赖的接口 | ||
| 91 | +- `POST /api/auth/login`（REQ-USR-004，获取 Bearer Token 供本接口鉴权使用） | ||
| 92 | + | ||
| 93 | +## 验收标准 | ||
| 94 | +1. `GET /api/usr/users`（无参）HTTP 200，返回本品牌所有用户，不含密码字段 | ||
| 95 | +2. `queryField=username&matchType=contains&queryValue=admin` 仅返回 sUsername 含 "admin" 的用户 | ||
| 96 | +3. `queryField=disabled&matchType=equals&queryValue=是` 仅返回 bIsDisabled=1 的记录 | ||
| 97 | +4. 无匹配条件时返回 `{ total: 0, list: [] }` 而非 4xx/5xx | ||
| 98 | +5. page=999（超出总页）返回最后一页而不报错 | ||
| 99 | +6. Token 品牌 A 无法查到品牌 B 的用户（多租户隔离） | ||
| 100 | +7. 响应 JSON 中不含 sPasswordHash / iLoginFailCount / tLockUntil | ||
| 101 | +8. 无 Token 请求返回 401 |