rui/rui-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(spec): 更新用户聚合查询设计规格

Browse Source 
- 添加 phone 字段迁移到 uc_user 表的设计
- 新增统一认证接口 /user/inner/auth/load（POST）
- 支持 AccountType 枚举：USERNAME/PHONE/EMAIL
- 废弃旧的 loadByUsername 接口
- 添加数据库变更 SQL 脚本
This commit is contained in:
pigeon
2026-06-06 13:30:23 +08:00
parent a8c164459a
commit de78c21799
1 changed files with 168 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files
superpowers/specs/2026-06-06-user-aggregate-query-design.md
+168 -51
View File
@@ -25,6 +25,8 @@
- **前端请求过多**：获取完整用户信息需要3个独立请求
- **列表页性能差**：100条用户数据需要 1 + 100 + 100 = 201 个请求
- **数据一致性难保证**：多个请求可能部分失败
- **手机号位置不合理**：手机号在 `uc_user_detail` 表，但短信登录需要频繁查询，应该提升到 `uc_user` 表
- **认证接口不灵活**：当前 `loadByUsername` 只支持用户名，无法扩展支持手机号、邮箱等多种登录方式
### 1.3 约束条件
@@ -32,6 +34,7 @@
- 需要支持 **多租户**（tenantId）
- 必须 **保持向后兼容**
- 需要 **缓存优化**
- 手机号需要 **唯一约束**（按租户）
---
@@ -40,7 +43,9 @@
1. **减少前端请求**：从3个减少到1个
2. **优化列表页性能**：批量查询，避免 N+1
3. **引入缓存**：Redis 缓存用户聚合数据
4. **保持兼容性**：现有接口不受影响
4. **手机号迁移**：将 `phone` 从 `uc_user_detail` 迁移到 `uc_user` 表
5. **统一认证接口**：支持多种登录方式（用户名、手机号、邮箱等）
6. **保持兼容性**：现有接口不受影响
---
@@ -95,9 +100,6 @@ import java.util.List;
@Schema(description = "用户聚合信息")
public class UserAggregateVO extends User {
@Schema(description = "用户详情")
private UserDetailVO detail;
@Schema(description = "部门列表")
private List<UserDeptVO> depts;
@@ -109,6 +111,12 @@ public class UserAggregateVO extends User {
@Schema(description = "主部门名称")
private String mainDeptName;
@Schema(description = "部门编码")
private String deptCode;
@Schema(description = "岗位编码")
private String postCode;
}
```
@@ -118,9 +126,15 @@ public class UserAggregateVO extends User {
@Data
@Schema(description = "用户部门信息")
public class UserDeptVO {
@Schema(description = "用户ID")
private Long userId;
@Schema(description = "部门ID")
private Long deptId;
@Schema(description = "部门编码")
private String deptCode;
@Schema(description = "部门名称")
private String deptName;
@@ -131,9 +145,15 @@ public class UserDeptVO {
@Data
@Schema(description = "用户岗位信息")
public class UserPostVO {
@Schema(description = "用户ID")
private Long userId;
@Schema(description = "岗位ID")
private Long postId;
@Schema(description = "岗位编码")
private String postCode;
@Schema(description = "岗位名称")
private String postName;
}
@@ -160,23 +180,20 @@ GET /user/admin/user/{id}/aggregate
"data": {
"id": 1,
"username": "admin",
"phone": "13800138000",
"userNo": "U001",
"userType": 2,
"status": 1,
"detail": {
"nickname": "管理员",
"realName": "系统管理员",
"email": "admin@example.com",
"phone": "13800138000"
},
"depts": [
{
"deptId": 1,
"deptCode": "TECH",
"deptName": "技术部",
"main": true
},
{
"deptId": 2,
"deptCode": "PROD",
"deptName": "产品部",
"main": false
}
@@ -184,11 +201,14 @@ GET /user/admin/user/{id}/aggregate
"posts": [
{
"postId": 1,
"postCode": "JAVA_DEV",
"postName": "Java开发工程师"
}
],
"mainDeptId": 1,
"mainDeptName": "技术部"
"mainDeptName": "技术部",
"deptCode": "TECH",
"postCode": "JAVA_DEV"
}
}
```
@@ -202,14 +222,87 @@ GET /user/admin/user/{id}/aggregate
- 批量查询所有用户的部门和岗位
- 组装到响应中
### 5.2 现有接口保持不变
#### 5.1.3 统一用户认证查询（内部接口）
以下接口继续保留，不受影响：
```
POST /user/inner/auth/load
```
**请求体：**
```json
{
"account": "13800138000",
"loginType": "PHONE"
}
```
**AccountType 枚举：**
```java
public enum AccountType {
USERNAME("用户名"),
PHONE("手机号"),
EMAIL("邮箱");
private final String description;
AccountType(String description) {
this.description = description;
}
}
```
**响应：** 与现有 `loadByUsername` 保持一致，返回用户认证信息
**实现逻辑：**
```java
@PostMapping("/auth/load")
public Result<JSONObject> loadUser(@RequestBody LoginAccountDTO loginAccount) {
User user;
switch (loginAccount.getLoginType()) {
case PHONE:
user = userService.lambdaQuery()
.eq(User::getPhone, loginAccount.getAccount())
.one();
break;
case EMAIL:
user = userService.lambdaQuery()
.eq(User::getEmail, loginAccount.getAccount())
.one();
break;
case USERNAME:
default:
user = userService.lambdaQuery()
.eq(User::getUsername, loginAccount.getAccount())
.one();
break;
}
if (user == null) {
return Result.ok(null);
}
// 组装认证信息（与现有逻辑一致）
JSONObject info = buildAuthInfo(user);
return Result.ok(info);
}
```
### 5.2 现有接口处理
**保留但标记为弃用：**
- `GET /user/inner/auth/loadByUsername/{username}` — **@Deprecated**，建议迁移到新的 `/auth/load`
**继续保留的接口：**
- `GET /user/admin/user/{id}` — 用户基础信息
- `GET /user/admin/user-dept/user/{userId}` — 用户部门列表
- `GET /user/admin/user-post/user/{userId}` — 用户岗位列表
- `GET /user/admin/detail` — 用户详情（uc_user_detail）
- `GET /user/admin/detail` — 用户详情（uc_user_detail，phone 字段将移除）
---
@@ -262,22 +355,15 @@ public UserAggregateVO getUserAggregate(Long userId, Long tenantId) {
return null;
}
// 2. 查询用户详情
UserDetail detail = userDetailMapper.selectOne(
new LambdaQueryWrapper<UserDetail>()
.eq(UserDetail::getUserId, userId)
);
// 3. 查询部门（带名称）
// 2. 查询部门（带名称）
List<UserDeptVO> depts = userDeptMapper.selectDeptListByUserId(userId);
// 4. 查询岗位（带名称）
// 3. 查询岗位（带名称）
List<UserPostVO> posts = userPostMapper.selectPostListByUserId(userId);
// 5. 组装
// 4. 组装
UserAggregateVO vo = new UserAggregateVO();
BeanUtils.copyProperties(user, vo);
vo.setDetail(convertDetail(detail));
vo.setDepts(depts);
vo.setPosts(posts);
@@ -327,22 +413,12 @@ public Page<UserAggregateVO> listUserAggregate(Page<User> page, QueryWrapper<Use
.stream()
.collect(Collectors.groupingBy(UserPostVO::getUserId));
// 5. 批量查询详情（一次查询）
Map<Long, UserDetail> detailMap = userDetailMapper
.selectList(
new LambdaQueryWrapper<UserDetail>()
.in(UserDetail::getUserId, userIds)
)
.stream()
.collect(Collectors.toMap(UserDetail::getUserId, Function.identity()));
// 6. 组装
// 5. 组装
List<UserAggregateVO> records = users.stream().map(user -> {
UserAggregateVO vo = new UserAggregateVO();
BeanUtils.copyProperties(user, vo);
vo.setDepts(deptMap.getOrDefault(user.getId(), Collections.emptyList()));
vo.setPosts(postMap.getOrDefault(user.getId(), Collections.emptyList()));
vo.setDetail(convertDetail(detailMap.get(user.getId())));
// 提取主部门
vo.getDepts().stream()
@@ -481,20 +557,62 @@ public Page<UserAggregateVO> listUserAggregate(Page<User> page, QueryWrapper<Use
### 14.1 涉及文件清单
- `rui-service-user/src/main/java/com/rui/service/user/vo/UserAggregateVO.java`（新增）
- `rui-service-user/src/main/java/com/rui/service/user/vo/UserDeptVO.java`（新增）
- `rui-service-user/src/main/java/com/rui/service/user/vo/UserPostVO.java`（新增）
- `rui-service-user/src/main/java/com/rui/service/user/service/IUserService.java`（修改）
- `rui-service-user/src/main/java/com/rui/service/user/service/impl/UserServiceImpl.java`（修改）
- `rui-service-user/src/main/java/com/rui/service/user/controller/UserController.java`（修改）
- `rui-service-user/src/main/java/com/rui/service/user/mapper/UserDeptMapper.java`（修改）
- `rui-service-user/src/main/java/com/rui/service/user/mapper/UserPostMapper.java`（修改）
- `rui-service-user/src/main/resources/mapper/UserDeptMapper.xml`（修改）
- `rui-service-user/src/main/resources/mapper/UserPostMapper.xml`（修改）
**新增文件：**
- `rui-service-user/src/main/java/com/rui/service/user/vo/UserAggregateVO.java`
- `rui-service-user/src/main/java/com/rui/service/user/vo/UserDeptVO.java`
- `rui-service-user/src/main/java/com/rui/service/user/vo/UserPostVO.java`
- `rui-service-user/src/main/java/com/rui/service/user/dto/LoginAccountDTO.java`
- `rui-service-user/src/main/java/com/rui/service/user/enums/AccountType.java`
### 14.2 数据库索引检查
**修改文件：**
- `rui-service-user/src/main/java/com/rui/service/user/entity/User.java`（添加 phone 字段）
- `rui-service-user/src/main/java/com/rui/service/user/entity/UserDetail.java`（移除 phone 字段）
- `rui-service-user/src/main/java/com/rui/service/user/service/IUserService.java`
- `rui-service-user/src/main/java/com/rui/service/user/service/impl/UserServiceImpl.java`
- `rui-service-user/src/main/java/com/rui/service/user/controller/UserController.java`
- `rui-service-user/src/main/java/com/rui/service/user/controller/inner/UserInnerController.java`
- `rui-service-user/src/main/java/com/rui/service/user/mapper/UserDeptMapper.java`
- `rui-service-user/src/main/java/com/rui/service/user/mapper/UserPostMapper.java`
- `rui-service-user/src/main/resources/mapper/UserDeptMapper.xml`
- `rui-service-user/src/main/resources/mapper/UserPostMapper.xml`
- `rui-common/rui-common-oauth2/src/main/java/com/rui/common/oauth2/feign/UserAuthFeign.java`
确保以下索引存在：
**SQL 脚本：**
- `sql/upgrade-v2.x-add-phone-to-user.sql`（新增）
### 14.2 数据库变更
#### 14.2.1 uc_user 表添加 phone 字段
```sql
-- 添加 phone 字段
ALTER TABLE rui_uc_user
ADD COLUMN phone VARCHAR(20) DEFAULT NULL COMMENT '手机号' AFTER username;
-- 添加唯一索引（按租户）
ALTER TABLE rui_uc_user
ADD UNIQUE KEY uk_phone (tenant_id, phone);
-- 添加普通索引（用于查询）
ALTER TABLE rui_uc_user
ADD INDEX idx_phone (phone);
```
#### 14.2.2 uc_user_detail 表移除 phone 字段
```sql
-- 迁移数据（如果有）
-- UPDATE rui_uc_user u
-- JOIN rui_uc_user_detail d ON u.id = d.user_id
-- SET u.phone = d.phone
-- WHERE u.phone IS NULL AND d.phone IS NOT NULL;
-- 移除 phone 字段
ALTER TABLE rui_uc_user_detail
DROP COLUMN phone;
```
#### 14.2.3 索引检查
```sql
-- uc_user_dept 表
@@ -504,9 +622,6 @@ CREATE INDEX idx_user_dept_dept_id ON uc_user_dept(dept_id);
-- uc_user_post 表
CREATE INDEX idx_user_post_user_id ON uc_user_post(user_id);
CREATE INDEX idx_user_post_post_id ON uc_user_post(post_id);
-- uc_user_detail 表
CREATE INDEX idx_user_detail_user_id ON uc_user_detail(user_id);
```
---
@@ -515,7 +630,9 @@ CREATE INDEX idx_user_detail_user_id ON uc_user_detail(user_id);
| 决策 | 选择 | 理由 |
|------|------|------|
| 是否改表结构 | 否 | 关联表设计合理，保持灵活性 |
| 是否改表结构 | 是 | 手机号是登录凭证，应提升到 uc_user 表 |
| 手机号位置 | uc_user 表 | 便于认证查询，支持唯一约束 |
| 认证接口方式 | POST + JSON + 枚举 | 支持多种登录方式，便于扩展 |
| 列表页是否缓存 | 否 | 数据变化频繁，直接查库更可靠 |
| 单用户查询方式 | 并行查询 | 减少RT，提升用户体验 |
| 缓存失效策略 | 主动失效 | 数据更新时立即失效，保证一致性 |