# 智价云（药店版） - 测试文档

> **⚠️ MVP 阶段说明**  
> 本项目为**全新项目，尚未上线**，当前处于 **MVP（最小可行产品）阶段**。  
> 本文档记录的是 MVP 版本的测试用例和覆盖率目标，后续会持续补充和完善。
>
> 版本：v1.1-MVP | 更新日期：2026-07-01 | 状态：开发中

---

## 1. 测试概述

### 1.1 测试范围

| 层次 | 说明 |
|------|------|
| 单元测试 | Service 层业务逻辑 |
| 集成测试 | Controller + Service + DB 端到端 |
| 安全测试 | 认证、授权、白名单验证 |
| 限流测试 | Redis 滑动窗口限流策略 |
| 接口测试 | API 参数校验、响应格式 |

### 1.2 技术栈

| 工具 | 说明 |
|------|------|
| JUnit 5 | 测试框架 |
| Spring Boot Test | 集成测试 |
| MockMvc | HTTP 接口模拟 |
| H2 Database | 嵌入式测试数据库 |
| Mockito | Mock Redis 等外部依赖 |

### 1.3 测试环境

- Profile: `test`
- 数据库: H2（MySQL 兼容模式）
- Redis: Mock（Mockito 模拟）
- 建表脚本: `test-schema.sql`

---

## 2. 测试用例清单

### 2.1 认证模块测试 (AuthControllerTest)

| 编号 | 用例 | 预期结果 |
|------|------|----------|
| AUTH-01 | POST /api/auth/sms/send - 手机号格式错误 | 400, code=400 |
| AUTH-02 | POST /api/auth/sms/send - 场景参数无效 | 400 |
| AUTH-03 | POST /api/auth/sms/login - 验证码格式错误 | 400 |
| AUTH-04 | POST /api/auth/sms/login - 验证码错误 | 200, 业务错误码 |
| AUTH-05 | GET /api/auth/wechat/url - 获取微信登录URL | 200, 返回URL字符串 |
| AUTH-06 | GET /api/auth/wechat/callback - 微信回调 | 200, 返回重定向URL |
| AUTH-07 | GET /api/auth/user/info - 有效Token | 200, 返回用户信息 |

### 2.2 安全访问测试 (SecurityAccessTest)

| 编号 | 用例 | 预期结果 |
|------|------|----------|
| SEC-01 | GET /api/level/list - 无Token公开访问 | 200 |
| SEC-02 | POST /api/auth/sms/send - 无Token公开访问 | 非401 |
| SEC-03 | POST /api/auth/sms/login - 无Token公开访问 | 非401 |
| SEC-04 | GET /api/auth/wechat/url - 无Token公开访问 | 非401 |
| SEC-05 | GET /api/level/my - 无Token | 401 |
| SEC-06 | GET /api/crawler/status - 无Token | 401 |
| SEC-07 | GET /api/coupon/my - 无Token | 401 |
| SEC-08 | GET /api/auth/user/info - 无Token | 401 |
| SEC-09 | GET /api/level/my - 有效Token | 200 |
| SEC-10 | GET /api/crawler/status - 有效Token | 200 |
| SEC-11 | 携带无效Token | 401 |

### 2.3 网关过滤器测试 (GatewayFilterTest)

| 编号 | 用例 | 预期结果 |
|------|------|----------|
| GW-01 | 请求日志记录 | 日志包含请求路径、耗时 |
| GW-02 | 慢请求告警 | 超过1000ms打印WARN |
| GW-03 | 限流-正常请求 | 200 |
| GW-04 | 限流-超出阈值 | 429 |
| GW-05 | 限流-短信接口更严格 | 10次/60s |
| GW-06 | 排除路径不记录日志 | /actuator/health 不记录 |

### 2.4 用户等级测试 (UserLevelControllerTest)

| 编号 | 用例 | 预期结果 |
|------|------|----------|
| LVL-01 | GET /api/level/list - 获取等级列表（公开） | 200, 包含3个等级(PLUS/PRO/ULTRA) |
| LVL-02 | GET /api/level/my - 获取当前用户等级 | 200, 含 membershipExpireAt/membershipDaysRemaining |
| LVL-03 | GET /api/level/{id} - 获取等级详情 | 200, 含 pricingPlans（PLUS无套餐） |
| LVL-04 | GET /api/level/999 - 不存在的等级 | 200, code=4001 |

### 2.5 会员体系测试 (MembershipControllerTest)

| 编号 | 用例 | 预期结果 |
|------|------|----------|
| MEM-01 | GET /api/membership/my - 查询我的会员信息 | 200, level/effectiveTo/source |
| MEM-02 | GET /api/membership/benefits?level=PRO | 200, 返回PRO等级权益列表 |
| MEM-03 | POST /api/admin/membership/grant - 运营发放PRO会员 | 200, 会员立即生效 |
| MEM-04 | POST /api/admin/membership/grant - 无效等级 | 200, 业务错误码 |
| MEM-05 | GET /api/admin/memberships - 分页查询会员记录 | 200, 支持按userId/level筛选 |

### 2.6 支付模块测试 (PaymentControllerTest)

| 编号 | 用例 | 预期结果 |
|------|------|----------|
| PAY-01 | GET /api/payment/plans - 无需认证返回方案列表 | 200, 方案数组(当前2个:月卡/年卡) |
| PAY-02 | GET /api/payment/plans - 方案含价格、会员等级等字段 | 200, price/membershipLevel/durationDays存在 |
| PAY-03 | POST /api/payment/order/create - 微信支付返回二维码 | 200, channel=WECHAT, qrCodeBase64存在 |
| PAY-04 | POST /api/payment/order/create - 支付宝返回二维码 | 200, channel=ALIPAY |
| PAY-05 | POST /api/payment/order/create - 无效渠道返回错误 | 200, code=2004 |
| PAY-06 | POST /api/payment/order/create - 无Token返回401 | 401 |
| PAY-07 | GET /api/payment/order/{orderNo} - 查询存在订单 | 200, 返回详情 |
| PAY-08 | GET /api/payment/order/{orderNo} - 不存在订单返回错误 | 200, code=2001 |
| PAY-09 | POST /api/payment/order/{orderNo}/pay - 模拟支付成功 | 200, status=PAID, paidTime存在 |
| PAY-10 | POST /api/payment/order/{orderNo}/pay - 已支付订单再次支付 | 200, code=2005 |
| PAY-11 | GET /api/payment/orders - 查询用户订单列表 | 200, data为数组 |
| PAY-12 | POST /api/payment/callback/wechat - 缺少订单号 | 200, 返回FAIL |
| PAY-13 | POST /api/payment/callback/alipay - 缺少订单号 | 200, 返回fail |

---

## 3. 待补充测试

### 3.1 邀请系统测试

| 编号 | 用例 | 优先级 | 状态 |
|------|------|--------|------|
| INV-01 | GET /api/invite/code - 获取邀请码 | P1 | ✅ |
| INV-02 | GET /api/invite/stats - 邀请统计（含crawlerTodayRemaining/crawlerQuotaFromInvites） | P1 | ✅ |
| INV-03 | GET /api/invite/page/{code} - 落地页（公开） | P1 | ✅ |
| INV-04 | POST /api/invite/click/{code} - 点击追踪 | P2 | ✅ |
| INV-05 | GET /api/invite/rewards - 邀请记录 | P1 | ✅ |
| INV-06 | 邀请注册→发放1个月PRO会员+可选额外爬虫配额 | P1 | ✅ |
| INV-07 | 多渠道落地页（channel=app/wechat/miniapp） | P2 | ✅ |
| INV-08 | GET /api/invite/my-inviter - 查询邀请人信息 | P1 | ✅ |
| INV-09 | 未被邀请返回invited=false | P1 | ✅ |
| INV-10 | POST /api/invite/bind - 补填邀请码成功 | P1 | ✅ |
| INV-11 | 补填邀请码→邀请人获1个月PRO（统一入口grantInviteReward） | P1 | ✅ |
| INV-12 | 已有邀请关系拒绝重复绑定 | P2 | ✅ |
| INV-13 | 邀请奖励上限30人，超限不再发放 | P1 | ✅ |
| INV-14 | 邀请页crawlerTodayRemaining与爬虫状态页一致 | P2 | ✅ |

### 3.2 爬虫配额测试

| 编号 | 用例 | 优先级 |
|------|------|--------|
| CRL-01 | GET /api/crawler/status - 配额状态含额外配额明细 | P1 |
| CRL-02 | POST /api/crawler/consume - 消耗等级配额 | P1 |
| CRL-03 | POST /api/crawler/consume - 消耗额外配额（快过期优先） | P1 |
| CRL-04 | POST /api/crawler/consume - 使用优惠券补充 | P2 |
| CRL-05 | POST /api/crawler/consume - 配额不足拒绝 | P1 |
| CRL-06 | 日配额耗尽 → 返回拒绝 | P1 |
| CRL-07 | 月配额耗尽 → 返回拒绝 | P1 |
| CRL-08 | 过期配额自动标记 | P2 |

### 3.3 运营管理测试

| 编号 | 用例 | 优先级 |
|------|------|--------|
| ADM-01 | GET /api/admin/invite/config - 获取邀请配置 | P1 |
| ADM-02 | PUT /api/admin/invite/config - 更新邀请配置 | P1 |
| ADM-03 | POST /api/admin/crawler/grant - 手动发放爬虫次数 | P1 |
| ADM-04 | GET /api/admin/crawler/grants - 查看发放记录 | P1 |

### 3.4 优惠券测试

| 编号 | 用例 | 优先级 |
|------|------|--------|
| CPN-01 | POST /api/coupon/issue - 发放优惠券 | P1 |
| CPN-02 | GET /api/coupon/my - 我的优惠券列表 | P1 |
| CPN-03 | GET /api/coupon/my/available - 可用优惠券 | P2 |
| CPN-04 | 爬虫消耗优先使用优惠券 | P1 |

### 3.5 JWT Token 角色区分测试

| 编号 | 用例 | 优先级 |
|------|------|--------|
| JWT-01 | 管理员Token过期时间12小时 | P0 |
| JWT-02 | 普通用户Token过期时间1小时 | P0 |
| JWT-03 | SUPER_ADMIN生成Token过期时间为12小时 | P1 |
| JWT-04 | getExpirationInSeconds("ADMIN") 返回 43200 秒 | P1 |
| JWT-05 | getExpirationInSeconds("USER") 返回 3600 秒 | P1 |
| JWT-06 | TokenVersionCache 超过10万上限时触发淘汰 | P2 |
| JWT-07 | TokenVersionCache 定时统计日志输出 | P2 |
| JWT-08 | heartbeat 缓存miss时回退查DB并回填缓存 | P1 |

### 3.6 重复支付与退款测试

| 编号 | 用例 | 优先级 |
|------|------|--------|
| DUP-01 | 渠道切换 - PENDING订单切换渠道成功 | P0 |
| DUP-02 | 渠道切换 - 已支付订单切换渠道拒绝 | P1 |
| DUP-03 | 渠道切换 - 已过期订单切换渠道拒绝 | P1 |
| DUP-04 | 重复支付回调 - 订单已PAID时第二笔回调记录重复支付 | P0 |
| DUP-05 | 重复支付回调 - 同一tradeNo幂等不重复记录 | P0 |
| DUP-06 | 自动退款 - 微信渠道重复支付触发退款（mock模式） | P0 |
| DUP-07 | 自动退款 - 支付宝渠道重复支付触发退款（mock模式） | P0 |
| DUP-08 | 退款状态 - 退款成功后refund_status=SUCCESS | P0 |
| DUP-09 | 退款失败 - 记录refund_fail_reason，refund_status=FAILED | P1 |
| DUP-10 | 退款幂等 - 同一重复支付记录不重复退款 | P1 |### 3.7 活动模块测试

#### 3.7.1 比价抽奖活动测试

| 编号 | 用例 | 优先级 |
|------|------|--------|
| ACT-01 | GET /api/activity/lottery/status - 查询抽奖状态（活动开启） | P0 |
| ACT-02 | GET /api/activity/lottery/status - 查询抽奖状态（活动关闭） | P0 |
| ACT-03 | GET /api/activity/lottery/status - 普通会员无资格 | P0 |
| ACT-04 | GET /api/activity/lottery/status - 入驻未审核无资格 | P0 |
| ACT-05 | GET /api/activity/lottery/prizes - 获取奖品列表（不含敏感信息） | P0 |
| ACT-06 | POST /api/activity/lottery/draw - 有资格用户抽奖成功 | P0 |
| ACT-07 | POST /api/activity/lottery/draw - 无资格用户抽奖拒绝 | P0 |
| ACT-08 | POST /api/activity/lottery/draw - 无机会用户抽奖拒绝 | P0 |
| ACT-09 | POST /api/activity/lottery/draw - 重复抽奖记录违规日志 | P0 |
| ACT-10 | POST /api/activity/lottery/draw - 库存扣减正确 | P0 |
| ACT-11 | POST /api/activity/lottery/draw - 库存为0奖品不参与抽奖 | P0 |
| ACT-12 | POST /api/activity/lottery/draw - 权重计算正确（权重=份数） | P0 |
| ACT-13 | GET /api/activity/lottery/records - 查询抽奖记录 | P1 |
| ACT-14 | GET /api/admin/activity/lottery/config - 查询活动配置 | P1 |
| ACT-15 | PUT /api/admin/activity/lottery/config - 更新活动配置 | P1 |
| ACT-16 | GET /api/admin/activity/lottery/prizes - 查询奖品池（含敏感信息） | P1 |
| ACT-17 | POST /api/admin/activity/lottery/prizes - 新增奖品 | P1 |
| ACT-18 | PUT /api/admin/activity/lottery/prizes/{id} - 更新奖品 | P1 |
| ACT-19 | DELETE /api/admin/activity/lottery/prizes/{id} - 删除奖品 | P1 |
| ACT-20 | GET /api/admin/activity/lottery/records - 分页查询抽奖记录 | P1 |

---

## 4. 运行测试

### 4.1 全量测试

```bash
mvn test
```

### 4.2 指定模块测试

```bash
mvn test -pl zhijiayun-gateway
```

### 4.3 指定测试类

```bash
mvn test -pl zhijiayun-gateway -Dtest=AuthControllerTest
```

### 4.4 指定测试方法

```bash
mvn test -pl zhijiayun-gateway -Dtest="AuthControllerTest#sendCode_invalidPhone_shouldReturnBadRequest"
```

---

## 5. 测试数据

### 5.1 默认等级数据

> **注**：旧的等级版本体系（NORMAL/VIP/SVIP）已下线，统一迁移至会员体系（PLUS/PRO/ULTRA）。
> 爬虫配额现在由会员权益配置 + 日/月/年三周期 + 额外配额组成。

| membership_level | daily_quota | monthly_quota | yearly_quota | max_concurrent |
|------------------|-------------|---------------|--------------|----------------|
| PLUS | 10 | 200 | 2000 | 2 |
| PRO | 50 | 1000 | 10000 | 5 |
| ULTRA | 200 | 5000 | 50000 | 10 |

### 5.2 测试用户

通过 `generateAccessToken(userId, phone)` 动态生成 JWT Token，无需预置用户。

---

## 6. 测试覆盖率目标

| 模块 | 行覆盖率目标 | 分支覆盖率目标 |
|------|-------------|---------------|
| zhijiayun-user | 70% | 60% |
| zhijiayun-invite | 70% | 60% |
| zhijiayun-payment | 70% | 60% |
| zhijiayun-activity | 70% | 60% |
| zhijiayun-gateway | 80% | 70% |
| 整体 | 70% | 60% |