grid_skeleton/docs/TESTING_PLAN.md

测试与可观测性计划

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

---

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 执行链

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 并阻止新开仓。

运行命令：

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 回测命令

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

输出：

• reports/grid/{timestamp}/summary.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 压测

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	计算并输出最新值

自动化检查：

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. 文档维护

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