# 测试与可观测性计划

> 定义单元、集成、回测、性能测试以及指标验证，确保策略在上线前经过系统性验证。

---

## 1. 测试矩阵概览

| 测试类型 | 范围 | 触发方式 | 通过标准 |
|----------|------|----------|----------|
| 单元测试 | 单模块逻辑 (GridMaker, RiskEngine, OrderRouter 等) | `pnpm test --filter unit` | 核心断言覆盖率 ≥ 80% |
| 合约测试 | REST/WS 适配器与签名 | `pnpm test --filter contract` | 对官方 sandbox 通过 |
| 私有 WS 冒烟 | Pacifica 私有频道 (orders/fills/account) | `pnpm test --filter contract -- --suite pacifica-ws` + 手动连接 | 成功订阅并收到增量，签名校验通过 |
| 集成测试 | 策略→执行→风控链闭环（Mock adapter） | `pnpm test --filter integration` | 无错误，Delta 控制达标 |
| 回测 / 仿真 | 实际行情数据回放 | `pnpm backtest --config backtest.yaml` | 指标满足门槛（下表） |
| 性能 / 压力 | OrderRouter、HedgeEngine 并发 | `pnpm test --filter perf` | CPU<60%，p99 延迟 < 20ms |
| 可观测性 | Prom 指标、日志字段存在 | `pnpm test --filter telemetry` | 指标注册完整 |

---

## 2. 单元测试

| 模块 | 文件 | 关键用例 | Mock 依赖 |
|------|------|----------|-----------|
| `GridMaker` | `packages/strategies/__tests__/gridMaker.test.ts` | 初始化 N 层、成交后补对手单、Delta 超阈触发对冲 | `ShadowBookMock`, `HedgeEngineStub` |
| `RiskEngine` | `packages/risk/__tests__/riskEngine.test.ts` | 超限拒单、Kill-switch 触发、熔断状态持久化 | 自定义 Fake Telemetry |
| `OrderRouter` | `packages/execution/__tests__/orderRouter.test.ts` | 滑点守卫、PostOnly 拒绝、clientId 去重 | `ExchangeAdapterMock` |
| `HedgeEngine` | `packages/hedge/__tests__/hedgeEngine.test.ts` | PI 控制器稳定性、重试逻辑、延迟预算 | Stub Router |
| `StrategyCoordinator` | `packages/strategies/__tests__/coordinator.test.ts` | 多策略合并、冲突解决、超时 | Faked producers |
| `PacificaSigning` | `packages/connectors/pacifica/__tests__/signing.test.ts` | body 序列化一致、时间戳漂移、错误密钥 | N/A |

- 覆盖边界条件：零深度、订单被拒、负仓位等。
- 所有单测运行时禁止真实网络（使用 nock 或本地 stub）。

---

## 3. 集成测试

### 3.1 Grid 执行链

```ts
describe('Grid strategy integration', () => {
  it('should place ladder orders, receive fills, and hedge within threshold', async () => {
    // Arrange: Fake adapter returns deterministic fills
    // Assert: risk.currentExposure().abs <= max_base_abs
  });
});
```

要求：
- 使用 `MockPacificaAdapter`，模拟下单、成交、延迟。
- 验证：订单落地 → Fill → Hedge → Exposure 回到 0 ±0.05。

### 3.2 Scalper + Coordinator

- 场景：Scalper 触发后网格已有挂单；应优先保留网格，Scalper fallback。
- 验证：冲突解决日志中包含 `resolution: "drop_scalper"`。

### 3.3 Kill-switch

- 模拟 Delta 失控：连续填充多头订单，确认 Kill-switch 进入 `REDUCE_ONLY` 并阻止新开仓。

运行命令：
```bash
pnpm test --filter integration
```

### 3.4 Pacifica 私有 WebSocket 冒烟

- 条件：本地或测试网 API key/secret/subaccount 已配置。
- 步骤：
  1. 运行 `pnpm test --filter contract -- --suite pacifica-ws`，确保签名拼接、订阅 payload 通过本地断言。
  2. 启动 Runner，调用 `PacificaWebSocket.subscribe('orders.{sub}')` 等频道，确认 10 秒内收到订单/成交/account 更新。
  3. 人为断开网络或重启 WS，确认自动重连后重新带上 auth，增量继续。
- 期望：官方日志中无鉴权错误；本地记录 `pacifica_ws_auth_fail_total=0`。

---

## 4. 回测与仿真

### 4.1 数据准备

- 行情数据：`data/replay/{symbol}_{date}.jsonl`，包含 book/trade/fill 事件。
- 转换脚本：`pnpm scripts:fetch --symbol BTC --date 2025-09-01`.

### 4.2 回测命令

```bash
pnpm backtest --config backtest/grid.yaml --from 2025-09-01 --to 2025-09-07
```

输出：
- `reports/grid/{timestamp}/summary.json`
  ```json
  {
    "ev_bps_p50": 1.9,
    "ev_bps_p10": 0.4,
    "delta_abs_p95": 0.32,
    "hedge_cost_bps": 0.6,
    "max_drawdown_pct": -0.45
  }
  ```
- 图表：`equity_curve.png`, `delta_histogram.png`.

通过标准：
- `ev_bps_p50 ≥ 1.5`
- `delta_abs_p95 ≤ 0.5`
- `max_drawdown_pct ≥ -1.0`
- `hedge_success_rate ≥ 0.95`

---

## 5. 性能测试

目标：在高频行情下，核心组件 CPU 使用率 < 60%，事件延迟满足 SLO。

### 5.1 OrderRouter 压测

```bash
pnpm test --filter perf -- --suite order-router
```

- 模拟 1000 QPS 下单请求，统计：
  - `sendLimit` 平均 9ms，p99 < 20ms
  - 重试率 < 1%

### 5.2 HedgeEngine 延迟

- 生成 100 次连续 Delta 超阈事件，确保：
  - 队列无 backlog
  - 对冲完成 P50 < 400ms, P99 < 1800ms

---

## 6. 可观测性验证

| 指标 | 验证方法 | 期望 |
|------|----------|------|
| `maker_ratio` | 回测 / 真实运行 10 分钟 | 输出至 Prom，值在 0–1 |
| `hedge_latency_ms_bucket` | 触发对冲 | 直方图 buckets 填充 |
| `delta_abs` | Grid 运行 | Gauge 反映实时 Delta |
| `pacifica_ws_reconnects_total` | 人为断网 | 指标增加，告警触发 |
| `funding_rate_correlation` | FundingMonitor | 计算并输出最新值 |

自动化检查：
```bash
pnpm test --filter telemetry
```
- 测试读取 `/metrics` 输出，确认关键指标存在并有标签。

---

## 7. 发布前检查清单

- [ ] 单元测试通过 (`pnpm test --filter unit`)
- [ ] 集成测试通过 (`pnpm test --filter integration`)
- [ ] 回测近 7 天表现达标 (`reports/grid/.../summary.json`)
- [ ] 性能测试通过 (`pnpm test --filter perf`)
- [ ] 指标面板更新，报警规则生效（见 `docs/OPERATIONS_PLAYBOOK.md`）
- [ ] 配置通过金丝雀流程验证

---

## 8. 持续验证

- 上线后每日回顾：`ev_bps`, `delta_abs`, `hedge_latency`, `funding_same_sign_ratio`。
- 每周回测最新数据，比较策略参数与实盘表现，必要时调整。

---

## 9. 文档维护

- 新增模块需更新测试覆盖项。
- 若引入新指标，必须在本文件补充验证步骤。
