# 后端 API 测试文档

> **位置**: `gym-manage-api/` | **框架**: JUnit 5 + Mockito + Maven | **用例数**: 1,094 | **通过率**: 100%

---

## 一、概览

后端 API 由 15 个 Maven 模块组成，采用 **Spring WebFlux** 响应式架构，测试覆盖 Handler（HTTP 入口）、Service（业务逻辑）、Util（工具类）、Filter（过滤器）、Converter（数据转换）等全层级。

| 维度 | 值 |
|---|---|
| 测试框架 | JUnit 5 + Mockito + Spring Test + Reactor Test |
| 构建工具 | Maven |
| 测试文件数 | 105 |
| 测试用例数 | 1,094 |
| 通过 | 1,094 |
| 失败 | 0 |
| 跳过 | 24（集成测试需数据库） |
| 运行命令 | `mvn test -DfailIfNoTests=false` |

---

## 二、模块测试详情

### 2.1 manage-sys（系统管理核心）— 658 tests

最核心的模块，覆盖用户、角色、菜单、字典、配置、日志、审计、认证、安全等全部子系统。

#### Handler 层（HTTP 入口，共 135 tests）

| 测试类 | 文件 | 用例数 | 测试内容 |
|---|---|---|---|
| `SysAuthHandlerTest` | `handler/auth/` | 9 | 登录、注册、登出 |
| `SysUserHandlerTest` | `handler/user/` | 20 | 用户 CRUD、分页、批量操作、角色分配 |
| `SysRoleHandlerTest` | `handler/role/` | 16 | 角色 CRUD、软删除/恢复、权限分配 |
| `MenuHandlerTest` | `handler/menu/` | 13 | 菜单树查询、按类型筛选、父子关系 |
| `MenuHandlerDataIntegrityTest` | `handler/menu/` | 11 | 菜单数据完整性、循环引用检测、并发 |
| `SysDictHandlerTest` | `handler/dict/` | 17 | 字典类型+数据 CRUD、缓存刷新 |
| `DictionaryHandlerTest` | `handler/dictionary/` | 9 | 字典管理完整流程 |
| `SysConfigHandlerTest` | `handler/config/` | 9 | 系统配置增删改查、按 key 查询 |
| `SysLogHandlerTest` | `handler/log/` | 18 | 登录日志查询、筛选、统计 |
| `OperationLogHandlerTest` | `handler/log/` | 7 | 操作日志查询、按模块筛选 |
| `StatsHandlerTest` | `handler/stats/` | 1 | 统计概览 |
| `AuditLogControllerTest` | `audit/controller/` | 11 | 审计日志 CRUD、按实体/操作人/时间查询 |

#### Service 层（业务逻辑，共 157 tests）

| 测试类 | 用例数 | 测试内容 |
|---|---|---|
| `SysUserServiceTest` | 30 | 用户创建、密码加密、角色绑定、分页、批量删除 |
| `SysUserServiceIntegrationTest` | 20 | 集成测试：用户+角色关联、事务回滚 |
| `SysRoleServiceTest` | 25 | 角色权限分配、菜单绑定、软删除恢复 |
| `SysMenuServiceTest` | 15 | 菜单树构建、排序、层级校验 |
| `SysDictTypeServiceTest` | 12 | 字典类型 CRUD、数据校验 |
| `SysDictDataServiceTest` | 12 | 字典数据 CRUD、类型关联 |
| `DictionaryServiceTest` | 10 | 字典管理综合逻辑 |
| `SysConfigServiceTest` | 8 | 配置参数校验、默认值 |
| `SysLoginLogServiceTest` | 10 | 登录日志记录、统计 |
| `SysExceptionLogServiceTest` | 8 | 异常日志记录、堆栈截断 |
| `OperationLogServiceTest` | 7 | 操作日志切面逻辑 |
| `AuditLogServiceTest` | 5 | 审计日志持久化、DTO转换 |

#### Domain / Primitive / DTO（值对象校验，共 180 tests）

| 测试类 | 用例数 | 测试内容 |
|---|---|---|
| `SysUserTest` | 23 | 用户领域模型验证（字段约束、状态转换） |
| `UsernameTest` | 15 | 用户名格式校验（长度、字符集、特殊字符） |
| `PasswordTest` | 45 | 密码强度规则、加密格式、哈希验证 |
| `PasswordDetailedTest` | 40 | 密码复杂性详细规则（大小写、数字、特殊字符） |
| `EmailTest` | 18 | 邮箱格式校验（RFC标准、中文邮箱） |
| `SysUserQueryTest` | 8 | 用户查询对象（分页、排序、筛选条件） |
| `SysRoleQueryTest` | 6 | 角色查询对象 |
| `CreateUserCommandTest` | 10 | 创建用户命令校验 |
| `UpdateUserCommandTest` | 8 | 更新用户命令校验 |
| `CreateRoleCommandTest` | 7 | 创建角色命令校验 |
| `UserResponseTest` | 5 | 用户响应 DTO |
| `AuthResponseTest` | 3 | 认证响应 DTO |
| `FilePreviewResponseTest` | 3 | 文件预览响应 DTO |
| `AuditLogTest` | 6 | 审计日志领域模型 |
| `AuditLogQueryRequestTest` | 5 | 审计查询请求校验 |

#### 安全 / 过滤器（共 52 tests）

| 测试类 | 用例数 | 测试内容 |
|---|---|---|
| `JwtTokenProviderTest` | 20 | JWT 生成/解析/过期/签名验证/刷新 |
| `JwtAuthenticationFilterTest` | 15 | 认证过滤器（Token提取、路径白名单、401响应） |
| `RateLimitFilterTest` | 12 | 限流过滤器（IP限制、令牌桶、滑动窗口） |
| `SecurityConfigTest` | 5 | Spring Security 配置验证 |

#### 工具类 / 辅助（共 20 tests）

| 测试类 | 用例数 |
|---|---|
| `IpUtilsTest` | 12 |
| `UserAgentParserTest` | 8 |

#### 回归测试（共 37 tests）

| 测试类 | 用例数 | 测试场景 |
|---|---|---|
| `SystemConfigRegressionTest` | 37 | 边界条件、并发操作、SQL注入防护、大菜单性能、事务回滚 |

---

### 2.2 manage-gateway（网关）— 171 tests

微服务网关，负责 JWT 认证、RBAC 授权、签名验证、限流、熔断、路由、负载均衡。

#### 过滤器（共 65 tests）

| 测试类 | 用例数 | 测试内容 |
|---|---|---|
| `GatewayJwtAuthenticationFilterTest` | 13 | JWT 解析：有效Token放行、无Token→401、无效Token→401、过期Token→401、公开路径放行 |
| `RbacAuthorizationFilterTest` | 13 | RBAC 授权：管理员全路径、普通用户受限、多 HTTP 方法、权限继承 |
| `SignatureFilterTest` | 9 | 请求签名：生成/验证/过期/篡改检测/重放防护 |
| `ResilienceFilterTest` | 7 | 弹性策略：超时、重试、熔断半开状态 |
| `RateLimitFilterTest` | 12 | 限流：IP维度、用户维度、令牌桶算法、并发控制 |
| `CompressionFilterTest` | 11 | 响应压缩：gzip、brotli、大小阈值 |

#### 服务层（共 55 tests）

| 测试类 | 用例数 | 测试内容 |
|---|---|---|
| `SignatureServiceImplTest` | 12 | 签名服务实现 |
| `PermissionServiceImplTest` | 10 | 权限校验服务 |
| `JwtKeyServiceImplTest` | 8 | JWT 密钥管理 |
| `DynamicRouteServiceTest` | 8 | 动态路由加载/更新/删除 |
| `RequestCacheServiceTest` | 5 | 请求缓存 |
| `AuditLogServiceTest` | 7 | 网关审计日志 |
| `CustomLoadBalancerTest` | 5 | 自定义负载均衡 |

#### 集成测试（共 6 tests）

| 测试类 | 用例数 | 测试内容 |
|---|---|---|
| `RbacIntegrationTest` | 6 | `/api/admin/users`→403 拦截，`/api/users/profile`→放行 |

#### 监控 / 指标（共 30 tests）

| 测试类 | 用例数 |
|---|---|
| `GatewayMetricsTest` | 12 |
| `PerformanceMonitorTest` | 8 |
| `GatewayHealthIndicatorTest` | 5 |
| `ResilienceConfigTest` | 5 |

---

### 2.3 manage-db（数据库）— 72 tests

| 测试类 | 用例数 | 测试内容 |
|---|---|---|
| `QueryUtilTest` | 8 | 动态 SQL 构建（等值、范围、IN、LIKE、排序） |
| `QueryUtilOrTest` | 6 | OR 条件组合查询 |
| `QueryUtilDetailedTest` | 8 | 嵌套查询、子查询 |
| `SysUserConverterTest` | 5 | PO ↔ VO 转换 |
| `SysRoleConverterTest` | 5 | 角色转换 |
| `SysMenuConverterTest` | 5 | 菜单转换 |
| `SysLoginLogConverterTest` | 5 | 登录日志转换 |
| `SysExceptionLogConverterTest` | 5 | 异常日志转换 |
| `SysDictTypeConverterTest` | 5 | 字典类型转换 |
| `SysDictDataConverterTest` | 5 | 字典数据转换 |
| `SysConfigConverterTest` | 5 | 配置转换 |
| `OperationLogConverterTest` | 5 | 操作日志转换 |
| `DictionaryConverterTest` | 5 | 字典转换 |

---

### 2.4 manage-common（通用工具）— 62 tests

覆盖 Redis、签名、JWT、加密、序列化等公共工具类。

---

### 2.5 manage-notify（通知公告）— 21 tests

| 测试类 | 用例数 | 测试内容 |
|---|---|---|
| `SysNoticeHandlerTest` | 12 | 公告 CRUD、发布/撤回、分页 |
| `SysWebSocketHandlerTest` | 9 | WebSocket 连接、消息推送、广播/单播 |

---

### 2.6 manage-file（文件管理）— 17 tests

| 测试类 | 用例数 | 测试内容 |
|---|---|---|
| `SysFileHandlerTest` | 9 | 文件 CRUD、下载、预览 |
| `SysFileServiceTest` | 8 | 文件存储、路径生成、MIME 检测 |

---

### 2.7 manage-app（管理端）— 22 tests

| 测试类 | 用例数 | 类型 | 说明 |
|---|---|---|---|
| `RateLimitConfigTest` | 2 | 单元 | 限流配置验证 |
| `MultipartConfigTest` | 2 | 单元 | 文件上传配置 |
| `ManualTableCreationTest` | 1 | 集成 | 手动建表验证 |
| `DatabaseInitTest` | 5 | 集成 | 数据库初始化 |
| `SysUserServiceIntegrationTest` | 5 | 集成 | 用户服务集成 |
| `OperationLogIntegrationTest` | 4 | 集成 | 操作日志集成 |
| `OperationLogExportIntegrationTest` | 3 | 集成 | 日志导出 |

> 注：15 个集成测试需数据库连接，标记为 SKIP（跳过 17 个含 setup 方法）

---

### 2.8 gym-member（会员管理）✨ 新增 — 40 tests

| 测试类 | 用例数 | 测试内容 |
|---|---|---|
| `MemberCardStateMachineTest` | 18 | 状态机全路径：ACTIVE/USED_UP/EXPIRED/REFUNDED × 6 事件、非法转换拦截、`canTransition`/`validateTransition` |
| `MemberNoGeneratorTest` | 15 | GYM前缀格式、8位合法字符集、不重复性验证、不含易混淆字符（0/O/1/I/l）、批量生成唯一性、count=0边界 |
| `BeanConvertUtilTest` | 7 | 正常转换、部分字段、null输入→null、批量转换、空列表、单元素 |

#### 状态机测试覆盖表

| 状态 → 事件 | USE | RENEW | EXPIRE | REFUND | DISABLE | ACTIVATE |
|---|---|---|---|---|---|---|
| ACTIVE | ACTIVE ✅ | ACTIVE ✅ | EXPIRED ✅ | REFUNDED ✅ | 非法 ❌ | - |
| USED_UP | 非法 ❌ | ACTIVE ✅ | - | REFUNDED ✅ | - | - |
| EXPIRED | 非法 ❌ | ACTIVE ✅ | - | - | - | - |
| REFUNDED (终态) | 非法 ❌ | 非法 ❌ | 非法 ❌ | 非法 ❌ | 非法 ❌ | 非法 ❌ |

---

### 2.9 gym-auth（手机号认证）✨ 新增 — 10 tests

| 测试类 | 用例数 | 测试内容 |
|---|---|---|
| `PhoneAuthHandlerTest` | 5 | 一键登录正常返回、发送验证码成功/频率限制、验证码登录成功/错误异常传播 |
| `SmsServiceImplTest` | 5 | 60秒频率限制、首次发送、Redis缓存获取/不存在、配置属性验证 |

#### 涉及 API

| 端点 | 方法 | Handler |
|---|---|---|
| `/api/auth/one-click-login` | POST | `PhoneAuthHandler.oneClickLogin` |
| `/api/auth/send-sms-code` | POST | `PhoneAuthHandler.sendSmsCode` |
| `/api/auth/code-login` | POST | `PhoneAuthHandler.codeLogin` |

---

### 2.10 gym-dataCount（数据统计）✨ 新增 — 8 tests

| 测试类 | 用例数 | 测试内容 |
|---|---|---|
| `DataStatisticsHandlerTest` | 8 | 综合/会员/预约/签到统计正常返回、异常降级空结果、历史查询、导出Excel正常+异常降级 |

#### 涉及 API

| 端点 | 测试场景 |
|---|---|
| `GET /api/statistics/summary` | MemberStatistics + BookingStatistics + SignInStatistics 聚合 |
| `GET /api/statistics/member` | 新增/活跃/累计/签到/预约/取消会员 |
| `GET /api/statistics/booking` | 新增/取消/出席/缺席/出席率/取消率 |
| `GET /api/statistics/signin` | 总数/成功/失败/成功率/扫码/手动/人脸 |
| `GET /api/statistics/history` | 历史统计列表 |
| `GET /api/statistics/export` | Excel 导出（4 Sheet） |

---

### 2.11 gym-checkIn（签到）— 10 tests

| 测试类 | 用例数 | 测试内容 |
|---|---|---|
| `CheckInModuleTest` | 10 | 二维码生成/有效性校验、签到成功/失败（无效二维码/不存在）、记录查询/单条/不存在、统计/每日统计、导出 |

#### 涉及 API

| 端点 | 方法 |
|---|---|
| `/api/checkin/qrcode` | GET |
| `/api/checkin` | POST |
| `/api/checkin/records` | GET |
| `/api/checkin/records/{id}` | GET |
| `/api/checkin/stats` | GET |
| `/api/checkin/stats/daily` | GET |
| `/api/checkin/records/export` | GET |

---

### 2.12 gym-groupCourse（团课）— 3 tests

| 测试类 | 用例数 | 测试内容 |
|---|---|---|
| `QRCodeUtilTest` | 3 | QR 码生成、内容编码/解码、边界尺寸 |

---

### 2.13 无测试模块

| 模块 | 状态 | 原因 |
|---|---|---|
| gym-payment | 0 tests | 模块未编写测试 |
| manage-audit | 0 tests | 模块未编写测试 |

---

## 三、完整的 API 路由覆盖汇总

| 分类 | API 路由 | 测试数 | 覆盖层 |
|---|---|---|---|
| 认证 | `POST /api/auth/login`, `/register`, `/logout` | 9 | Handler |
| 认证 | `POST /api/auth/one-click-login`, `/send-sms-code`, `/code-login` | 5 | Handler |
| 用户 | `GET/POST /api/users`, `GET/PUT/DEL /api/users/{id}`, `/page`, `/batch` | 20 | Handler |
| 角色 | `GET/POST /api/roles`, `GET/DEL /api/roles/{id}`, `/page` | 16 | Handler |
| 菜单 | `GET/POST /api/menus`, `GET /api/menus/{id}`, `/tree`, `/parent/{id}` | 24 | Handler |
| 字典 | `GET/POST /api/dict-types`, `GET/POST /api/dict-data` | 26 | Handler |
| 配置 | `GET/POST /api/configs`, `GET /api/configs/{id}`, `/key/{key}` | 9 | Handler |
| 文件 | `GET/POST /api/files`, `GET/DEL /api/files/{id}`, `/download`, `/preview` | 17 | Handler+Service |
| 通知 | `GET/POST /api/notices`, `GET/PUT/DEL /api/notices/{id}` | 21 | Handler |
| 操作日志 | `GET /api/operation-logs`, `/page`, `/export` | 7 | Handler+集成 |
| 登录日志 | `GET /api/logs/login` | 18 | Handler |
| 审计日志 | `GET /api/audit-logs/*` | 11 | Handler |
| 签到 | `GET /api/checkin/qrcode`, `POST /api/checkin`, `GET /...{id}`, `/stats`, `/export` | 10 | Handler |
| 统计 | `GET /api/statistics/summary`, `/member`, `/booking`, `/signin`, `/history`, `/export` | 8 | Handler |
| 统计 | `GET /api/stats/overview` | 1 | Handler |
| 网关 | JWT/RBAC/签名/限流/熔断/路由（非HTTP端点） | 171 | Filter+Service |

---

## 四、运行方式

```bash
# 进入后端目录
cd gym-manage-api

# 运行全量测试
mvn test -DfailIfNoTests=false

# 运行单个模块
mvn test -pl gym-member -DfailIfNoTests=false

# 运行单个测试类
mvn test -pl gym-member "-Dtest=cn.novalon.gym.manage.member.handler.MemberCardStateMachineTest"

# 编译但不运行测试
mvn compile -DskipTests
```

---

## 五、测试架构

```
测试层级:
  Handler  → Mock Service   → 验证 HTTP 状态码 + 响应体
  Service  → Mock Repository → 验证业务逻辑 + 事务
  Filter   → Mock Exchange   → 验证过滤规则 + 异常处理
  Util     → 纯单元测试       → 验证输入输出 + 边界
  Domain   → 值对象测试       → 验证构造/校验/不变性
  Converter→ Mock 源对象      → 验证字段映射完整
  Integration → 真实 DB/H2  → 端到端业务流程
```

---

**文档生成时间**: 2026-07-21 | **测试工具**: JUnit 5 + Mockito + Reactor Test + Maven