# 测试指南

<cite>
**本文档引用的文件**   
- [pom.xml](file://pom.xml)
- [crm-auth/pom.xml](file://crm-auth/pom.xml)
- [crm-base/pom.xml](file://crm-base/pom.xml)
- [crm-file/pom.xml](file://crm-file/pom.xml)
- [AuthServiceImplTest.java](file://crm-auth/src/test/java/com/crm/auth/service/impl/AuthServiceImplTest.java)
- [AuthUserServiceImplTest.java](file://crm-auth/src/test/java/com/crm/auth/service/impl/AuthUserServiceImplTest.java)
- [SysDeptServiceImplTest.java](file://crm-auth/src/test/java/com/crm/auth/service/impl/SysDeptServiceImplTest.java)
- [UserListIntegrationTest.java](file://crm-auth/src/test/java/com/crm/auth/service/impl/UserListIntegrationTest.java)
- [DingTalkAuthClientTest.java](file://crm-auth/src/test/java/com/crm/auth/service/client/DingTalkAuthClientTest.java)
- [ThirdPartyAuthClientFactoryTest.java](file://crm-auth/src/test/java/com/crm/auth/service/client/ThirdPartyAuthClientFactoryTest.java)
- [DataScopeIntegrationTest.java](file://crm-auth/src/test/java/com/crm/auth/security/scope/DataScopeIntegrationTest.java)
- [FileApiImplTest.java](file://crm-file/src/test/java/com/crm/file/service/impl/FileApiImplTest.java)
- [KkFileViewClientTest.java](file://crm-file/src/test/java/com/crm/file/service/KkFileViewClientTest.java)
- [OrphanChunkCleanupTaskTest.java](file://crm-file/src/test/java/com/crm/file/task/Or orphanChunkCleanupTaskTest.java)
- [DataVisibilityTest.java](file://crm-base/src/test/java/com/crm/base/security/DataVisibilityTest.java)
</cite>

## 更新摘要
**所做更改**   
- 新增用户列表集成测试章节，详细介绍UserListIntegrationTest的实现与最佳实践
- 更新核心组件部分，增加用户列表功能测试的说明
- 完善详细组件分析，补充用户列表相关的测试策略和断言方法
- 扩展依赖分析，体现用户列表功能的测试覆盖范围

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本测试指南面向CRM后端项目的开发与维护人员，系统阐述测试策略、框架选择与落地实践。内容覆盖单元测试、集成测试、端到端测试的实施方法；Mock对象创建、测试数据准备、断言语句编写等高质量用例设计要点；覆盖率要求、持续集成中的测试执行、性能测试与安全测试的实施建议；以及最佳实践与常见问题解决方案，帮助团队保障代码质量与系统稳定性。

## 项目结构
本项目采用多模块Maven工程组织，测试代码按模块划分在各自src/test目录下：
- crm-auth：认证授权相关服务与控制器，包含丰富的单元测试与集成测试
- crm-base：基础能力与通用安全逻辑，包含数据可见性相关测试
- crm-file：文件上传下载与预览能力，包含服务层与任务类测试
- crm-app：应用启动入口（当前未提供测试）

```mermaid
graph TB
subgraph "根工程"
ROOT["根POM"]
end
subgraph "认证模块 crm-auth"
AUTH_SRC["src/main/java"]
AUTH_TEST["src/test/java"]
AUTH_RES["src/test/resources"]
end
subgraph "基础模块 crm-base"
BASE_SRC["src/main/java"]
BASE_TEST["src/test/java"]
end
subgraph "文件模块 crm-file"
FILE_SRC["src/main/java"]
FILE_TEST["src/test/java"]
end
ROOT --> AUTH_SRC
ROOT --> BASE_SRC
ROOT --> FILE_SRC
AUTH_TEST --> AUTH_SRC
BASE_TEST --> BASE_SRC
FILE_TEST --> FILE_SRC
```

图表来源
- [pom.xml](file://pom.xml)
- [crm-auth/pom.xml](file://crm-auth/pom.xml)
- [crm-base/pom.xml](file://crm-base/pom.xml)
- [crm-file/pom.xml](file://crm-file/pom.xml)

章节来源
- [pom.xml](file://pom.xml)
- [crm-auth/pom.xml](file://crm-auth/pom.xml)
- [crm-base/pom.xml](file://crm-base/pom.xml)
- [crm-file/pom.xml](file://crm-file/pom.xml)

## 核心组件
- 测试框架与工具
  - JUnit 5：统一测试运行器与注解
  - Mockito：模拟外部依赖与行为
  - Spring Boot Test：上下文加载、Web测试、数据库集成测试支持
  - AssertJ：链式断言，提升可读性与表达力
- 分层测试策略
  - 单元测试：针对Service实现、工具类、客户端调用进行隔离测试
  - 集成测试：结合Spring容器与测试数据库验证跨层交互
  - 端到端测试：通过HTTP接口验证完整业务流程（可按需扩展）
- 关键测试样例
  - 认证服务单元测试：登录流程、用户信息处理、权限校验
  - 第三方认证客户端测试：钉钉等外部接口的Mock与边界条件
  - 数据权限范围集成测试：基于注解的数据范围过滤与SQL注入
  - **用户列表集成测试：完整的用户查询、分页、过滤与权限控制验证**
  - 文件服务单元测试：分片上传、会话清理、预览客户端调用
  - 基础安全能力测试：数据可见性上下文与工具方法

章节来源
- [AuthServiceImplTest.java](file://crm-auth/src/test/java/com/crm/auth/service/impl/AuthServiceImplTest.java)
- [AuthUserServiceImplTest.java](file://crm-auth/src/test/java/com/crm/auth/service/impl/AuthUserServiceImplTest.java)
- [SysDeptServiceImplTest.java](file://crm-auth/src/test/java/com/crm/auth/service/impl/SysDeptServiceImplTest.java)
- [UserListIntegrationTest.java](file://crm-auth/src/test/java/com/crm/auth/service/impl/UserListIntegrationTest.java)
- [DingTalkAuthClientTest.java](file://crm-auth/src/test/java/com/crm/auth/service/client/DingTalkAuthClientTest.java)
- [ThirdPartyAuthClientFactoryTest.java](file://crm-auth/src/test/java/com/crm/auth/service/client/ThirdPartyAuthClientFactoryTest.java)
- [DataScopeIntegrationTest.java](file://crm-auth/src/test/java/com/crm/auth/security/scope/DataScopeIntegrationTest.java)
- [FileApiImplTest.java](file://crm-file/src/test/java/com/crm/file/service/impl/FileApiImplTest.java)
- [KkFileViewClientTest.java](file://crm-file/src/test/java/com/crm/file/service/KkFileViewClientTest.java)
- [OrphanChunkCleanupTaskTest.java](file://crm-file/src/test/java/com/crm/file/task/OrphanChunkCleanupTaskTest.java)
- [DataVisibilityTest.java](file://crm-base/src/test/java/com/crm/base/security/DataVisibilityTest.java)

## 架构总览
下图展示认证模块的测试调用链与依赖关系，体现从Controller到Service再到Mapper/外部客户端的分层测试思路。

```mermaid
sequenceDiagram
participant T as "测试用例"
participant C as "认证控制器"
participant S as "认证服务"
participant U as "用户服务"
participant M as "数据访问层"
participant E as "外部客户端"
T->>C : "发起登录请求(模拟)"
C->>S : "调用登录逻辑"
S->>U : "查询并校验用户信息"
U->>M : "持久化查询"
M-->>U : "返回用户实体"
U-->>S : "组装用户DTO"
S->>E : "可选：第三方认证校验"
E-->>S : "返回认证结果"
S-->>C : "返回登录结果"
C-->>T : "响应测试断言"
```

图表来源
- [AuthServiceImplTest.java](file://crm-auth/src/test/java/com/crm/auth/service/impl/AuthServiceImplTest.java)
- [AuthUserServiceImplTest.java](file://crm-auth/src/test/java/com/crm/auth/service/impl/AuthUserServiceImplTest.java)
- [DingTalkAuthClientTest.java](file://crm-auth/src/test/java/com/crm/auth/service/client/DingTalkAuthClientTest.java)

## 详细组件分析

### 认证服务单元测试
- 目标：验证登录流程、用户信息查询、角色权限装配等核心逻辑
- 关键点：
  - 使用Mock对象隔离Mapper与外部客户端
  - 构造典型与边界输入参数（空值、非法格式、异常场景）
  - 使用链式断言验证返回结构与状态码
- 推荐实践：
  - 每个用例聚焦单一职责，命名清晰表达意图
  - 对异常路径进行显式断言，确保错误分支稳定
  - 避免过度Mock业务内部细节，保持测试可维护性

章节来源
- [AuthServiceImplTest.java](file://crm-auth/src/test/java/com/crm/auth/service/impl/AuthServiceImplTest.java)
- [AuthUserServiceImplTest.java](file://crm-auth/src/test/java/com/crm/auth/service/impl/AuthUserServiceImplTest.java)

### 部门服务单元测试
- 目标：验证部门树构建、层级关系处理、分页转换等
- 关键点：
  - Mock数据访问层返回不同层级结构
  - 断言树形结构的父子关系与排序
  - 验证分页参数与结果映射正确性

章节来源
- [SysDeptServiceImplTest.java](file://crm-auth/src/test/java/com/crm/auth/service/impl/SysDeptServiceImplTest.java)

### 用户列表集成测试
- 目标：验证用户列表功能的完整性和正确性，包括查询、分页、过滤、权限控制等
- 关键点：
  - 使用@SpringBootTest加载完整Spring上下文
  - 配置测试数据库，准备用户、角色、部门等关联数据
  - 模拟不同权限级别的用户，验证数据权限控制
  - 验证复杂查询条件组合与分页性能
  - 断言返回数据的完整性、准确性与格式规范
- 测试场景覆盖：
  - 基础用户列表查询与分页
  - 按用户名、邮箱、状态等条件筛选
  - 角色权限过滤与数据范围控制
  - 部门维度数据隔离
  - 异常情况处理与错误响应
- 推荐实践：
  - 使用@Transactional保证测试数据隔离
  - 采用@Sql或@TestConfiguration初始化测试数据
  - 合理拆分测试用例，每个用例验证单一业务场景
  - 使用AssertJ进行链式断言，提高可读性

章节来源
- [UserListIntegrationTest.java](file://crm-auth/src/test/java/com/crm/auth/service/impl/UserListIntegrationTest.java)

### 第三方认证客户端测试
- 目标：验证钉钉等第三方认证客户端的调用与异常处理
- 关键点：
  - Mock网络请求或HTTP客户端，模拟成功与失败响应
  - 断言重试机制、超时与错误码处理
  - 验证Token获取与缓存逻辑

章节来源
- [DingTalkAuthClientTest.java](file://crm-auth/src/test/java/com/crm/auth/service/client/DingTalkAuthClientTest.java)
- [ThirdPartyAuthClientFactoryTest.java](file://crm-auth/src/test/java/com/crm/auth/service/client/ThirdPartyAuthClientFactoryTest.java)

### 数据权限范围集成测试
- 目标：验证基于注解的数据范围过滤与SQL注入是否正确生效
- 关键点：
  - 使用测试数据库与事务回滚保证数据隔离
  - 构造不同用户与部门上下文，断言查询结果集
  - 检查生成的SQL是否包含正确的数据范围条件

章节来源
- [DataScopeIntegrationTest.java](file://crm-auth/src/test/java/com/crm/auth/security/scope/DataScopeIntegrationTest.java)

### 文件服务单元测试
- 目标：验证分片上传、会话管理、预览客户端调用与清理任务
- 关键点：
  - Mock存储与预览服务，模拟大文件与异常场景
  - 断言会话生命周期与过期清理逻辑
  - 验证并发上传时的幂等性与一致性

章节来源
- [FileApiImplTest.java](file://crm-file/src/test/java/com/crm/file/service/impl/FileApiImplTest.java)
- [KkFileViewClientTest.java](file://crm-file/src/test/java/com/crm/file/service/KkFileViewClientTest.java)
- [OrphanChunkCleanupTaskTest.java](file://crm-file/src/test/java/com/crm/file/task/OrphanChunkCleanupTaskTest.java)

### 基础安全能力测试
- 目标：验证数据可见性上下文与工具方法的正确性
- 关键点：
  - 设置不同可见性级别，断言工具方法输出
  - 验证上下文切换与线程隔离

章节来源
- [DataVisibilityTest.java](file://crm-base/src/test/java/com/crm/base/security/DataVisibilityTest.java)

## 依赖分析
各模块测试依赖关系如下，便于理解测试范围与隔离策略。

```mermaid
graph LR
AUTH_TEST["crm-auth 测试"] --> AUTH_MAIN["crm-auth 主代码"]
AUTH_TEST --> BASE_MAIN["crm-base 主代码"]
FILE_TEST["crm-file 测试"] --> FILE_MAIN["crm-file 主代码"]
FILE_TEST --> BASE_MAIN
BASE_TEST["crm-base 测试"] --> BASE_MAIN
```

图表来源
- [crm-auth/pom.xml](file://crm-auth/pom.xml)
- [crm-file/pom.xml](file://crm-file/pom.xml)
- [crm-base/pom.xml](file://crm-base/pom.xml)

章节来源
- [crm-auth/pom.xml](file://crm-auth/pom.xml)
- [crm-file/pom.xml](file://crm-file/pom.xml)
- [crm-base/pom.xml](file://crm-base/pom.xml)

## 性能考虑
- 单元测试性能
  - 控制Mock与内存对象数量，避免不必要的复杂对象构造
  - 使用并行执行时注意线程安全与共享资源隔离
- 集成测试性能
  - 使用嵌入式数据库或轻量级测试库，减少IO开销
  - 合理拆分测试套件，避免全量加载大型上下文
  - **用户列表集成测试应关注大数据量场景下的查询性能**
- 性能测试建议
  - 引入压测工具（如JMeter、Gatling）对关键接口进行基准测试
  - 关注慢查询与锁竞争，结合监控指标定位瓶颈
  - **对用户列表等高频接口进行专门的性能测试**

[本节为通用指导，不直接分析具体文件]

## 故障排查指南
- 常见测试问题
  - 上下文加载失败：检查测试配置与依赖注入是否正确
  - Mock行为未生效：确认@MockBean或Mockito.when()调用时机
  - 数据库事务未回滚：确保使用@Transactional或测试后手动清理
  - 并发测试不稳定：避免共享状态，增加等待与重试机制
  - **集成测试数据污染：确保测试数据隔离与清理机制**
- 调试技巧
  - 打印关键变量与中间结果，缩小问题范围
  - 使用IDE断点与日志级别调整定位异常
  - 将失败用例最小化复现，便于快速修复
  - **对于用户列表测试，重点关注SQL生成与权限过滤逻辑**

章节来源
- [DataScopeIntegrationTest.java](file://crm-auth/src/test/java/com/crm/auth/security/scope/DataScopeIntegrationTest.java)
- [OrphanChunkCleanupTaskTest.java](file://crm-file/src/test/java/com/crm/file/task/OrphanChunkCleanupTaskTest.java)
- [UserListIntegrationTest.java](file://crm-auth/src/test/java/com/crm/auth/service/impl/UserListIntegrationTest.java)

## 结论
通过分层测试策略与规范的用例设计，本项目在认证、文件与安全等核心能力上建立了可靠的测试保障。**新增的用户列表集成测试进一步完善了用户管理功能的测试覆盖，确保了复杂业务场景下的功能正确性**。建议持续完善覆盖率指标、引入自动化CI流水线与性能/安全测试，进一步提升交付质量与系统稳定性。

[本节为总结性内容，不直接分析具体文件]

## 附录
- 测试覆盖率要求
  - 行覆盖率≥80%，分支覆盖率≥70%
  - 关键业务模块（认证、权限、文件、用户管理）覆盖率≥90%
- 持续集成中的测试执行
  - 在CI中并行执行单元测试与集成测试
  - 生成覆盖率报告并设置阈值门禁
  - **用户列表集成测试应在CI中专门执行，确保数据权限逻辑正确**
- 安全测试实施
  - 引入静态扫描与依赖漏洞检测
  - 对敏感接口进行渗透测试与越权验证
  - **重点验证用户列表的数据权限控制与越权访问防护**
- 最佳实践清单
  - 用例命名清晰，描述预期行为
  - 优先断言结果而非实现细节
  - 保持测试数据独立与可重复
  - 定期清理过时用例与冗余Mock
  - **集成测试应覆盖主要业务场景与边界条件**

[本节为通用指导，不直接分析具体文件]