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

- 方案B：后端聚合查询 + Redis缓存 - 新增聚合接口 /user/admin/user/{id}/aggregate - 批量列表查询优化，避免N+1 - 缓存策略与失效机制设计 - 保持向后兼容
2026-06-06 13:14:13 +08:00
parent 47d8af24f0
commit a8c164459a
1 changed files with 522 additions and 0 deletions
@@ -0,0 +1,522 @@
+# 用户聚合查询设计规格
+
+> **日期**: 2026-06-06  
+> **状态**: 已批准  
+> **作者**: AI Assistant  
+> **相关模块**: rui-service-user
+
+---
+
+## 1. 背景与问题
+
+### 1.1 现状
+
+当前用户数据分散在4张表中：
+
+| 表名 | 说明 |
+|------|------|
+| `uc_user` | 用户基础信息（用户名、密码、状态等） |
+| `uc_user_detail` | 用户详情（昵称、邮箱、手机号等） |
+| `uc_user_dept` | 用户部门关联（支持多部门，有主部门标记） |
+| `uc_user_post` | 用户岗位关联（支持多岗位） |
+
+### 1.2 问题
+
+- **前端请求过多**：获取完整用户信息需要3个独立请求
+- **列表页性能差**：100条用户数据需要 1 + 100 + 100 = 201 个请求
+- **数据一致性难保证**：多个请求可能部分失败
+
+### 1.3 约束条件
+
+- 一个用户通常关联 **1个主部门 + 少量岗位**
+- 需要支持 **多租户**（tenantId）
+- 必须 **保持向后兼容**
+- 需要 **缓存优化**
+
+---
+
+## 2. 设计目标
+
+1. **减少前端请求**：从3个减少到1个
+2. **优化列表页性能**：批量查询，避免 N+1
+3. **引入缓存**：Redis 缓存用户聚合数据
+4. **保持兼容性**：现有接口不受影响
+
+---
+
+## 3. 技术方案
+
+### 3.1 总体架构
+
+```
+┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
+│   前端       │────▶│  UserController  │────▶│ UserService  │
+└─────────────┘     └──────────────────┘     └──────┬───────┘
+                                                    │
+                       ┌────────────────────────────┼────────────────────────────┐
+                       │                            │                            │
+                       ▼                            ▼                            ▼
+              ┌─────────────────┐        ┌─────────────────┐          ┌─────────────────┐
+              │   Redis Cache   │        │  uc_user_dept   │          │  uc_user_post   │
+              │  user:agg:{id}  │        │   (主部门+关联)  │          │   (岗位关联)     │
+              └─────────────────┘        └─────────────────┘          └─────────────────┘
+```
+
+### 3.2 核心策略
+
+- **保留关联表**：不改表结构，保持多对多关系的灵活性
+- **聚合查询**：后端做 JOIN 或批量 IN 查询，一次性返回
+- **两级缓存**：
+  - L1：单用户聚合数据缓存（Redis）
+  - L2：批量查询结果不缓存（避免缓存过大）
+- **缓存失效**：数据变更时主动失效
+
+---
+
+## 4. 数据模型
+
+### 4.1 新增 VO 对象
+
+```java
+package com.rui.service.user.vo;
+
+import com.rui.service.user.entity.User;
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+import java.util.List;
+
+/**
+ * 用户聚合信息（包含部门、岗位）
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+@Schema(description = "用户聚合信息")
+public class UserAggregateVO extends User {
+
+    @Schema(description = "用户详情")
+    private UserDetailVO detail;
+
+    @Schema(description = "部门列表")
+    private List<UserDeptVO> depts;
+
+    @Schema(description = "岗位列表")
+    private List<UserPostVO> posts;
+
+    @Schema(description = "主部门ID")
+    private Long mainDeptId;
+
+    @Schema(description = "主部门名称")
+    private String mainDeptName;
+}
+```
+
+### 4.2 部门/岗位 VO
+
+```java
+@Data
+@Schema(description = "用户部门信息")
+public class UserDeptVO {
+    @Schema(description = "部门ID")
+    private Long deptId;
+
+    @Schema(description = "部门名称")
+    private String deptName;
+
+    @Schema(description = "是否主部门")
+    private Boolean main;
+}
+
+@Data
+@Schema(description = "用户岗位信息")
+public class UserPostVO {
+    @Schema(description = "岗位ID")
+    private Long postId;
+
+    @Schema(description = "岗位名称")
+    private String postName;
+}
+```
+
+---
+
+## 5. 接口设计
+
+### 5.1 新增接口
+
+#### 5.1.1 获取用户聚合信息（单用户）
+
+```
+GET /user/admin/user/{id}/aggregate
+```
+
+**响应示例：**
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "id": 1,
+    "username": "admin",
+    "userNo": "U001",
+    "userType": 2,
+    "status": 1,
+    "detail": {
+      "nickname": "管理员",
+      "realName": "系统管理员",
+      "email": "admin@example.com",
+      "phone": "13800138000"
+    },
+    "depts": [
+      {
+        "deptId": 1,
+        "deptName": "技术部",
+        "main": true
+      },
+      {
+        "deptId": 2,
+        "deptName": "产品部",
+        "main": false
+      }
+    ],
+    "posts": [
+      {
+        "postId": 1,
+        "postName": "Java开发工程师"
+      }
+    ],
+    "mainDeptId": 1,
+    "mainDeptName": "技术部"
+  }
+}
+```
+
+#### 5.1.2 用户列表（增强版）
+
+复用现有 `/user/admin/user` 列表接口，在响应中增加 `depts` 和 `posts` 字段。
+
+**实现方式：**
+- 列表查询时，先查询用户基础数据
+- 批量查询所有用户的部门和岗位
+- 组装到响应中
+
+### 5.2 现有接口保持不变
+
+以下接口继续保留，不受影响：
+
+- `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）
+
+---
+
+## 6. 缓存设计
+
+### 6.1 缓存策略
+
+| 缓存项 | Key 格式 | TTL | 说明 |
+|--------|---------|-----|------|
+| 用户聚合信息 | `user:agg:{tenantId}:{userId}` | 10分钟 | 单用户完整数据 |
+| 用户部门列表 | `user:dept:{tenantId}:{userId}` | 10分钟 | 部门ID列表 |
+| 用户岗位列表 | `user:post:{tenantId}:{userId}` | 10分钟 | 岗位ID列表 |
+
+### 6.2 缓存失效
+
+**触发时机：**
+- 用户部门变更（assignDepts、setMainDept）
+- 用户岗位变更（assignPosts）
+- 用户信息变更（update）
+- 用户删除
+
+**失效逻辑：**
+
+```java
+private void evictUserCache(Long userId) {
+    Long tenantId = AuthUtil.getTenantId();
+    redisUtil.del(String.format("user:agg:%s:%s", tenantId, userId));
+    redisUtil.del(String.format("user:dept:%s:%s", tenantId, userId));
+    redisUtil.del(String.format("user:post:%s:%s", tenantId, userId));
+}
+```
+
+### 6.3 缓存穿透防护
+
+- 查询不到数据时，缓存空值（TTL 1分钟）
+- 使用布隆过滤器（可选，初期可不用）
+
+---
+
+## 7. 查询逻辑
+
+### 7.1 单用户聚合查询
+
+```java
+@Cacheable(value = "user:agg", key = "#tenantId + ':' + #userId")
+public UserAggregateVO getUserAggregate(Long userId, Long tenantId) {
+    // 1. 查询用户基础信息
+    User user = userMapper.selectById(userId);
+    if (user == null) {
+        return null;
+    }
+
+    // 2. 查询用户详情
+    UserDetail detail = userDetailMapper.selectOne(
+        new LambdaQueryWrapper<UserDetail>()
+            .eq(UserDetail::getUserId, userId)
+    );
+
+    // 3. 查询部门（带名称）
+    List<UserDeptVO> depts = userDeptMapper.selectDeptListByUserId(userId);
+
+    // 4. 查询岗位（带名称）
+    List<UserPostVO> posts = userPostMapper.selectPostListByUserId(userId);
+
+    // 5. 组装
+    UserAggregateVO vo = new UserAggregateVO();
+    BeanUtils.copyProperties(user, vo);
+    vo.setDetail(convertDetail(detail));
+    vo.setDepts(depts);
+    vo.setPosts(posts);
+
+    // 6. 提取主部门
+    depts.stream()
+        .filter(UserDeptVO::getMain)
+        .findFirst()
+        .ifPresent(main -> {
+            vo.setMainDeptId(main.getDeptId());
+            vo.setMainDeptName(main.getDeptName());
+        });
+
+    return vo;
+}
+```
+
+### 7.2 批量列表查询优化
+
+**问题：** 列表页有100条数据，不能每条都查一次数据库
+
+**方案：** 批量 IN 查询
+
+```java
+public Page<UserAggregateVO> listUserAggregate(Page<User> page, QueryWrapper<User> query) {
+    // 1. 查询用户基础数据
+    Page<User> userPage = userMapper.selectPage(page, query);
+    List<User> users = userPage.getRecords();
+
+    if (users.isEmpty()) {
+        return new Page<>();
+    }
+
+    // 2. 提取所有用户ID
+    List<Long> userIds = users.stream()
+        .map(User::getId)
+        .collect(Collectors.toList());
+
+    // 3. 批量查询部门（一次查询）
+    Map<Long, List<UserDeptVO>> deptMap = userDeptMapper
+        .selectDeptListByUserIds(userIds)
+        .stream()
+        .collect(Collectors.groupingBy(UserDeptVO::getUserId));
+
+    // 4. 批量查询岗位（一次查询）
+    Map<Long, List<UserPostVO>> postMap = userPostMapper
+        .selectPostListByUserIds(userIds)
+        .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. 组装
+    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()
+            .filter(UserDeptVO::getMain)
+            .findFirst()
+            .ifPresent(main -> {
+                vo.setMainDeptId(main.getDeptId());
+                vo.setMainDeptName(main.getDeptName());
+            });
+
+        return vo;
+    }).collect(Collectors.toList());
+
+    // 7. 构建分页结果
+    Page<UserAggregateVO> result = new Page<>();
+    result.setCurrent(userPage.getCurrent());
+    result.setSize(userPage.getSize());
+    result.setTotal(userPage.getTotal());
+    result.setRecords(records);
+
+    return result;
+}
+```
+
+**SQL 示例（批量查询部门）：**
+
+```xml
+<select id="selectDeptListByUserIds" resultType="com.rui.service.user.vo.UserDeptVO">
+    SELECT 
+        ud.user_id as userId,
+        ud.dept_id as deptId,
+        d.name as deptName,
+        ud.is_main as main
+    FROM uc_user_dept ud
+    INNER JOIN uc_dept d ON ud.dept_id = d.id
+    WHERE ud.user_id IN
+    <foreach collection="userIds" item="id" open="(" separator="," close=")">
+        #{id}
+    </foreach>
+    AND ud.deleted = 0
+    AND d.deleted = 0
+</select>
+```
+
+---
+
+## 8. 性能优化点
+
+### 8.1 数据库层面
+
+1. **索引优化**：确保 `uc_user_dept.user_id` 和 `uc_user_post.user_id` 有索引
+2. **批量查询**：使用 IN 代替循环查询
+3. **按需加载**：列表页只加载必要的字段
+
+### 8.2 缓存层面
+
+1. **单用户缓存**：详情页使用缓存，10分钟TTL
+2. **列表页不缓存**：列表数据变化频繁，直接查数据库
+3. **缓存预热**：系统启动时可选择预热（可选）
+
+### 8.3 代码层面
+
+1. **并行查询**：单用户查询时，部门、岗位、详情可并行（CompletableFuture）
+2. **懒加载**：如果前端不需要详情，可以不加载 `uc_user_detail`
+
+---
+
+## 9. 边界情况处理
+
+### 9.1 用户无部门/岗位
+
+- `depts` 返回空列表 `[]`
+- `posts` 返回空列表 `[]`
+- `mainDeptId` 和 `mainDeptName` 为 `null`
+
+### 9.2 缓存穿透
+
+- 用户不存在时，缓存空值（TTL 1分钟）
+- 使用 `Optional` 包装返回
+
+### 9.3 缓存雪崩
+
+- TTL 加随机偏移：`10分钟 + random(0, 60)秒`
+- 使用互斥锁（可选）
+
+### 9.4 数据更新同步
+
+- 所有更新操作后主动失效缓存
+- 使用事务确保数据库和缓存一致性
+
+---
+
+## 10. 兼容性
+
+### 10.1 向后兼容
+
+- 现有接口完全保留
+- 新增 `/aggregate` 接口，不影响旧接口
+- 前端可以逐步迁移
+
+### 10.2 前端迁移路径
+
+1. **第一阶段**：新增聚合接口，前端详情页切换到新接口
+2. **第二阶段**：列表页切换到批量查询
+3. **第三阶段**：废弃旧接口（可选）
+
+---
+
+## 11. 安全考虑
+
+1. **权限校验**：复用现有 `@AutoPermission("uc:user")`
+2. **数据隔离**：所有查询自动加上 `tenant_id` 条件
+3. **敏感信息**：密码字段不返回
+
+---
+
+## 12. 监控与日志
+
+1. **缓存命中率**：监控 `user:agg:*` 的命中情况
+2. **查询耗时**：记录批量查询的执行时间
+3. **慢查询**：超过100ms的查询记录日志
+
+---
+
+## 13. 风险评估
+
+| 风险 | 概率 | 影响 | 缓解措施 |
+|------|------|------|----------|
+| 缓存数据不一致 | 中 | 中 | 更新时主动失效缓存 |
+| 批量查询性能差 | 低 | 高 | 索引优化 + 分页 |
+| 内存占用过高 | 低 | 中 | 控制缓存TTL + 分页大小 |
+
+---
+
+## 14. 附录
+
+### 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`（修改）
+
+### 14.2 数据库索引检查
+
+确保以下索引存在：
+
+```sql
+-- uc_user_dept 表
+CREATE INDEX idx_user_dept_user_id ON uc_user_dept(user_id);
+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);
+```
+
+---
+
+## 15. 决策记录
+
+| 决策 | 选择 | 理由 |
+|------|------|------|
+| 是否改表结构 | 否 | 关联表设计合理，保持灵活性 |
+| 列表页是否缓存 | 否 | 数据变化频繁，直接查库更可靠 |
+| 单用户查询方式 | 并行查询 | 减少RT，提升用户体验 |
+| 缓存失效策略 | 主动失效 | 数据更新时立即失效，保证一致性 |
+| 是否返回密码 | 否 | 安全考虑，聚合数据不包含敏感字段 |