# 测试策略

xiangqin 所有涉及第三方（SMS / 支付 / 实名 / 绿网 / OSS）的测试分三层。目标：**闭环测试完全由 Claude 程序化跑，不依赖老板**。

## 三层测试金字塔

| 层 | 方式 | 用途 | 何时跑 |
|---|---|---|---|
| **L1 单测** | mock（pytest monkeypatch / respx） | 业务逻辑正确性；CI 飞快 | 每次 push / PR |
| **L2 E2E** | 厂商**沙箱**（真协议假数据） + **测试号白名单**（真环境下选中号码走 mock） | 协议对接正确、签名、回调时序、DB 状态流 | staging 部署后自动跑 |
| **L3 冒烟** | 真号 / 真钱 ¥0.01 | 生产配置 / 风控 / 签名密钥正确 | 每次大 release 手动 |

## 各依赖的策略

### SMS 验证码（auth 流程）

**业界做法**（Google / Stripe / Twilio / Firebase / 钉钉 / 飞书）：**测试手机号白名单 + 固定 OTP**。苹果 App Store 审核也要求必须提供这种 test account。

**xiangqin 实现**：
- env `XIANGQIN_TEST_PHONES` = 白名单号段，逗号分隔（如 `13900000001,13900000002`）
- env `XIANGQIN_TEST_OTP` = 固定验证码（staging 每次部署随机长 code，prod 留空 = 关闭）
- `auth.register()` 命中白名单时：**不调 SMS provider**（不花钱）+ code = `TEST_OTP`
- `auth.verify()` 不改：正常比 hash，业务规则（TTL / used / invalid code）都走真路径

为什么不直接切 `XIANGQIN_SMS_PROVIDER=mock`：
- mock 是**全局**的，测试态会污染 prod 真实用户
- 白名单方案让 **prod 环境都能挂白名单跑 E2E**（比如上架后定期 health check 用）

安全：
- `XIANGQIN_TEST_OTP` 必须 ≥ 6 位 + 每次 staging 部署随机轮换；别用 `000000`（暴力扫）
- 白名单号选不存在的号段（如 `139 00000 001`），避免撞真用户

### 支付（alipay / wechat pay）

**业界做法**：**官方沙箱环境**。支付宝 `openapi.alipaydev.com`（免费申请沙箱 APPID + RSA 公私钥），微信 sandbox mch_id。

**xiangqin 实现**：
- env `XIANGQIN_ALIPAY_SANDBOX=1` 切沙箱 endpoint + 沙箱 APPID / key
- 沙箱完全走真协议（RSA 签名、precreate、异步 webhook），只是不扣真钱
- L3 冒烟：每次大 release 手动跑一笔 ¥1 真付 + 立刻退款（0.6% 手续费 < ¥0.01 可接受）

### 实名认证（暂未做）

**业界做法**：阿里云实人认证 RPBasic / 腾讯云 faceid 都提供**测试身份证号白名单**——官方公布的一批测试号（如阿里云文档里的 test ID），调接口返回成功、不走征信、不扣钱。

**xiangqin 计划**（做 issue #009 时一并接）：
- env `XIANGQIN_REALNAME_SANDBOX=1` 切厂商 test endpoint
- 用官方测试身份证号 + 测试姓名跑 E2E
- **绝不自己 mock**——漏协议 bug 风险大

### 绿网内容审核（pending）

阿里云内容安全 / 腾讯云 COS 绿网都有**测试账号 + 测试图集**（故意违规的 samples）。沙箱调通后真 AK/SK 切过来就行。

### OSS 照片存储

- **test bucket**：`agentaily-xiangqin-photos-test`（独立 bucket 隔离）
- **prod bucket**：`agentaily-xiangqin-photos-prod`
- E2E 用 test bucket，跑完自动清理（testing fixture 负责）

## 实施优先级

1. **P0**：SMS 测试号白名单 → 注册/登录 E2E 自动化（阻塞所有后续 E2E）
2. **P1**：支付宝沙箱 → 买信封 E2E
3. **P2**：实名沙箱（等 #009 做到再接）
4. **P3**：绿网沙箱（等 FEAT-010 做到再接）

## 相关

- [chaos-engineering.md](chaos-engineering.md) — L2/L3 里的稀有事件演练
- issue [#026](../issues/026-e2e-testing.md) — 本策略的实施追踪
- ADR（未来）：如果引入新测试基础设施（如 pact / cypress），补 `decisions/<date>-<slug>.md`
