# 快手行业电子凭证接口测试指南

## 接口地址

| 接口 | 路径 | 要求 |
|------|------|------|
| 通知商家发码 | `POST /api/v1/open/kuaishou-industry/send-code` | 100 TPS, 平均 100ms |
| 查询商家卡券 | `POST /api/v1/open/kuaishou-industry/query-code` | 500 QPS, 平均 100ms |
| 通知商家销毁 | `POST /api/v1/open/kuaishou-industry/destroy-code` | 100 TPS, 平均 100ms |

## 测试脚本

```bash
cd apps/backend
```

### 功能测试（9 项检查）

```bash
# 本地
npm run test:industry:http

# 远程 - 自定义地址 + 命令行密钥
npm run test:industry:http -- \
  --baseUrl=https://xxx.xxx.com \
  --appKey=ks660621772091030245 \
  --signSecret=xxx

# 远程 - 使用 .env 中的密钥
npm run test:industry:http -- --baseUrl=https://ks.khhao.com
```

测试内容：发码 → 幂等性 → 查询全部 → 查询单个 → 不存在订单 → 销毁 → 销毁验证 → 整单销毁 → 签名错误拦截

### 压力测试（TPS/QPS 验证）

```bash
# 全部接口 100 TPS
npm run test:industry:http -- \
  --baseUrl=https://ks.khhao.com \
  --load --tps=100 --duration=10

# 单接口 500 QPS
npm run test:industry:http -- \
  --baseUrl=https://ks.khhao.com \
  --load --endpoint=query-code --tps=500 --duration=30

# 测试环境（自签证书）
npm run test:industry:http -- \
  --baseUrl=https://xxx.xxx.com \
  --insecure --load --tps=100 --duration=10
```

### 输出示例

```
╔══════════════════════════════════════════════════════╗
║  压测: query-code                                    ║
║  目标: 500  TPS, 持续 10 s                        ║
╚══════════════════════════════════════════════════════╝
  实际 TPS    : 2028.0
  总请求数    : 20290
  成功数      : 20290
  失败数      : 0
  平均耗时    : 4.9 ms
  P50         : 5.0 ms
  P95         : 7.0 ms
  P99         : 9.0 ms
  最小耗时    : 1.0 ms
  最大耗时    : 48.0 ms
```

## 参数说明

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--baseUrl` | `http://127.0.0.1:3000` | 目标服务地址 |
| `--appKey` | .env 中读取 | 快手分配的 appKey |
| `--signSecret` | .env 中读取 | 签名密钥 |
| `--signMethod` | `MD5` | 签名算法: MD5 / HMAC_SHA256 |
| `--load` | false | 启用压力测试 |
| `--tps` | 100 | 目标 TPS/QPS |
| `--duration` | 10 | 持续时间（秒） |
| `--endpoint` | 全部 | 指定接口: send-code / query-code / destroy-code |
| `--insecure` | false | 跳过 SSL 验证（测试环境用） |

## 配置密钥

三种方式任选：

**1. .env 文件（推荐）**
```bash
KUASHOU_INDUSTRY_APP_KEY=ks660621772091030245
KUASHOU_INDUSTRY_SIGN_SECRET=你的signSecret
```

**2. 命令行**
```bash
npm run test:industry:http -- --appKey=xxx --signSecret=xxx
```

**3. 环境变量**
```bash
KUASHOU_INDUSTRY_APP_KEY=xxx \
KUASHOU_INDUSTRY_SIGN_SECRET=xxx \
npm run test:industry:http
```

## 压测前调高限流

服务端默认限流 120 req/min，压测需要调高：

```bash
# docker-compose.dev.yml 已支持，重启时传入即可
KUASHOU_INDUSTRY_RATE_LIMIT_MAX=60000 docker compose -f docker-compose.dev.yml up -d backend
```

## 直接调用服务层（不需启动 HTTP）

```bash
npm run test:industry          # 直接调用 handler，绕过 HTTP 层
```

## 签名算法

请求签名流程：

1. 所有参数（除 sign）按 key 字典序排序
2. 用 `&` 拼接为 `key=value` 格式
3. 末尾追加 `&signSecret=xxx`
4. MD5 或 HMAC_SHA256 计算签名

脚本内置了签名计算，自动处理。

## 注意事项

- 测试环境需将出口 IP 加入快手白名单
- 远程压力测试避免影响线上业务，建议先功能测试再逐步加量
- 签名密钥勿提交到 git，通过 .env 或命令行传入