# Pacifica Delta-Neutral 策略代码交付计划

## 0. 启动准备（第 0 周）
- **签名链路**：实现 `packages/connectors/pacifica/src/signing.ts`，依据官方规范补全 Ed25519 签名流程，并撰写单元测试验证时间戳、Payload 序列化、Header 注入。
- **CI 基线**：配置 `pnpm lint`、`pnpm test`，在 PR 流程中强制执行；准备 `.env` 与 `config.yaml` 模板及 `zod` 校验器确保配置完整性。
- **文档基线**：在启动开发前确认下列规范与当前需求一致，所有代码改动必须遵守或同步更新这些文档：
  - `docs/API_CONNECTOR_SPEC.md`
  - `docs/MODULE_INTERFACES.md`
  - `docs/SEQUENCE_FLOW.md`
  - `docs/CONFIG_REFERENCE.md`
  - `docs/TESTING_PLAN.md`
  - `docs/OPERATIONS_PLAYBOOK.md`
  - 如需偏离，先更新对应文档并在 PR 描述中说明变更理由与影响范围。

## 0.5 策略选择决策点

在 M1 完成后，团队需要决定优先实现哪个策略：

| 选项 | 时间 | 风险 | 收益潜力 | 建议场景 |
|------|------|------|---------|---------|
| **M1.5 网格 MVP** | 2-3 天 | 低 | 中（1-2%/月） | **优先推荐**：快速验证对冲架构 |
| **M2 剥头皮** | 2-3 周 | 高 | 高（3-5%/月） | 若有充足历史数据支持 EV>0 |
| **两者并行** | 同时 | 中 | 最高 | 团队 ≥2 人 |

**推荐路径**：M1 → M1.5（网格 MVP）→ 验证 2-4 小时 → 若成功再决定 M2.5（增强网格）或 M2（剥头皮）

---

## 1. M1 核心骨架 + 多账户基础设施（第 1 周）
- `domain/types.ts`：定义订单、成交、行情、仓位等核心类型，供全局复用。
- `packages/connectors/pacifica/adapter.ts`：封装下单、撤单、批量撤、持仓、资金费率接口，加入限频器与错误码映射。
  - **多账户支持（新增）**：每个 adapter 实例绑定一个账户（address + subaccount），通过 adapterRegistry 管理 maker/hedger 账户。
- 所有连接层实现需对照 `docs/API_CONNECTOR_SPEC.md` 的端点、签名、限频及错误映射；若接口差异无法避免，必须同步更新文档。
- `packages/registry/` **（新增模块）**：
  - `SymbolRegistry.ts`：多标的生命周期管理（启动/暂停/卸载）
  - `RiskAllocator.ts`：全局风险预算分配器，按标的流动性与相关性分配限额
  - `SymbolScorer.ts`：标的自动评分与筛选（流动性、funding rate 相关性）
- `packages/execution/globalCoordinator.ts` **（新增）**：
  - 跨账户订单注册表（clientId + account + symbol + side + px）
  - 跨账户 STP 检查基础框架
  - 降级策略触发器接口
- `packages/utils/shadowBook.ts`：实现影子订单簿合并、Mid/Spread/OBI/RV 等派生特征，并记录行情延迟与断流状态。
- `packages/execution/orderRouter.ts`：提供限价/IOC/FOK、滑点守卫、PostOnly、`clientId` 去重及 STP 前置检查，输出基础执行指标。
- `packages/risk/RiskEngine.ts`：实现名义/库存/单笔限额校验、实时 PnL 汇总及 **增强 Kill-switch**：
  - 跨账户聚合 PnL 与权益
  - 多维度熔断触发器（PnL/Delta/对冲失败/数据断流）
  - 1 小时滑动窗口回撤计算

## 1.5. M1.5 网格策略 MVP（可选，+2-3 天）

**目标**：用最小代码量快速验证对冲架构是否可行

**前置条件**：M1 完成

**交付清单**：

- `packages/strategies/gridMaker.ts` **（新建，约 200 行）**：
  - `GridMaker` 类：核心网格逻辑
  - `initialize()`: 在当前 mid 周围布置双边网格
  - `onFill()`: 成交后挂对手单，更新 Delta，检查对冲阈值
  - `reset()`: 撤销所有旧订单，重新布网格
  - 批量对冲：Delta 累积到阈值（如 0.3 BTC）触发 HedgeEngine
  - 实现逻辑需与 `docs/SEQUENCE_FLOW.md` 中的网格流程保持一致，并使用 `docs/CONFIG_REFERENCE.md` 定义的参数字段。

- `packages/domain/src/types.ts` **（扩展）**：
  - 新增 `GridLevel` 接口定义

- `apps/runner/src/index.ts` **（修改）**：
  - 根据 `config.strategy_mode` 选择加载 GridMaker 或 Scalper
  - 监听 Fill 事件，回调 `gridMaker.onFill()`

- `config/config.yaml` **（扩展）**：
  ```yaml
  strategy_mode: grid  # grid | scalper | both

  grid:
    enabled: true
    symbol: BTC
    grid_step_bps: 100   # 1%
    grid_range_bps: 400  # 4%
    base_clip_usd: 500
    max_layers: 4
    hedge_threshold_base: 0.3
  ```

- `packages/strategies/__tests__/gridMaker.test.ts` **（新建）**：
  - 测试网格初始化
  - 测试 Fill 后挂对手单
  - 测试 Delta 累积与对冲触发
  - 用例覆盖与断言参照 `docs/TESTING_PLAN.md` 的单元测试要求。

**验收标准**：
- ✅ 网格初始化成功，双边各 N 层订单
- ✅ 买单成交后，自动挂卖单在更高价
- ✅ Delta 累积到阈值，触发对冲
- ✅ 对冲完成后，Delta 归零
- ✅ |Delta| 始终 < max_base_abs

**测试计划**：
- Day 1: 实现 GridMaker 核心逻辑 + Runner 集成
- Day 2: 单元测试 + 本地 mock 测试
- Day 3: 测试网小额测试 1-2 小时，观察：成交率、对冲延迟、Delta 控制

**成功判断**：
- 若测试网运行正常（Delta 控制有效、对冲成功率 >95%、月收益率 >0.5%）
  → 继续 M2.5（增强网格）或 M2（剥头皮）
- 若失败
  → 问题大概率在对冲架构，修复后再回到 M1.5

## 2. M2 策略闭环 + 增强对冲（第 2 周）
- `packages/strategies/coordinator.ts` **（新增）**：
  - 策略协调器：MM 和 Scalper 提交 intent，检测方向冲突
  - 冲突解决策略（优先级/合并/取消）
  - 净仓位变化输出，避免频繁触发对冲
  - 接口签名、异常类型与优先级规则需符合 `docs/MODULE_INTERFACES.md` 与 `docs/SEQUENCE_FLOW.md` 中的描述。
- `packages/strategies/MarketMaker.ts`：基于 mid±δ 的多层挂单逻辑，支持波动分层和定时重挂。
- `packages/strategies/MicroScalper.ts`：实现 Spread 扩张 + 成交流不平衡触发的微剥头皮策略，含多执行模式与冷却控制。
- `packages/portfolio/PositionManager.ts` & `packages/hedge/HedgeEngine.ts`：聚合多 venue 仓位，使用 PI 控制器触发跨账户对冲并记录成本。
  - **对冲延迟追踪（新增）**：记录 P50/P95/P99 延迟，暴露 Prometheus 指标
  - **对冲重试机制（新增）**：失败自动重试最多 2 次，每次增加滑点容忍度 +5bps
  - **超时强制平仓（新增）**：若 3 秒内未完成，触发市价平仓
  - PI 参数、重试与超时阈值应与 `docs/CONFIG_REFERENCE.md`、`docs/TESTING_PLAN.md` 和 `docs/OPERATIONS_PLAYBOOK.md` 对齐。
- `packages/hedge/fundingRateMonitor.ts` **（新增）**：
  - 抓取双 venue funding rate 历史
  - 计算 30 天滚动相关性
  - 检测同向支付频率，告警与减仓建议
- `packages/execution/degradationPolicy.ts` **（新增）**：
  - 降级策略状态机实现（数据断流/对冲失败/Delta 失控等核心场景）
  - 降级动作执行器（撤单/只平不开/HALT）
  - 降级状态持久化
- `packages/execution/TriggerEngine.ts`：管理 OCO 止盈止损、时间止损，与 RiskEngine/Router 共享校验链路。
- `apps/runner`：构建 `live-runner`、`canary-runner`，整合配置加载、策略注入、生命周期管理。
  - 启动、热更新、降级与恢复流程必须遵循 `docs/SEQUENCE_FLOW.md` 与 `docs/OPERATIONS_PLAYBOOK.md` 的时序和 SOP。

## 2.5. M2.5 增强版网格（可选，+1 周）

**目标**：在 M1.5 基础上，增加生产级功能，使网格策略可长期稳定运行

**前置条件**：M1.5 完成且验证成功

**交付清单**：

- `packages/strategies/gridMaker.ts` **（扩展，+150 行）**：
  - **自适应网格中心调整**：
    - `onTimer()`: 定期检查价格偏离网格中心的程度
    - 若偏离 >2%，撤旧单并以新 mid 为中心重新布网格
  - **暂停/恢复机制**：
    - `pause()`: 撤销所有挂单，停止策略
    - `resume()`: 重新初始化网格
  - **多标的支持**：
    - 每个标的独立管理 grids、currentDelta

- `packages/strategies/trendFilter.ts` **（新建，100 行）**：
  - `TrendFilter` 类：趋势检测器
  - `isTrending()`: 检测 1 小时涨跌是否 >0.5%
  - 维护价格历史队列（lookback_periods = 12 * 5min）

- `packages/strategies/volatilityMonitor.ts` **（新建，80 行）**：
  - `VolatilityMonitor` 类：低波动监控
  - `checkDailyRange()`: 计算 24h 价格范围
  - 若 <0.8%，触发告警或自动缩小 grid_step

- `packages/backtest/gridBacktest.ts` **（新建，300 行）**：
  - `GridBacktest` 类：网格策略回测框架
  - `run()`: 事件重放，驱动 GridMaker 逻辑
  - 输出：总收益、Sharpe、最大回撤、往返次数、对冲成本

- `apps/runner/src/index.ts` **（扩展）**：
  - 支持多标的并行运行
  - 集成 TrendFilter 和 VolatilityMonitor
  - 定时触发 `gridMaker.onTimer()`（检查重置）

- `config/config.yaml` **（扩展）**：
  ```yaml
  grid:
    symbols:  # 支持多标的
      - symbol: BTC
        grid_step_bps: 100
        grid_range_bps: 400
      - symbol: ETH
        grid_step_bps: 120
        grid_range_bps: 500

    adaptive_recenter:
      enabled: true
      recenter_threshold_bps: 200

    trend_filter:
      enabled: true
      lookback_periods: 12
      trend_threshold_bps: 50

    volatility_monitor:
      enabled: true
      min_daily_range_bps: 80
      action: notify  # notify | reduce_step | switch_strategy
  ```

- `config/grid_backtest.example.yaml` **（新建）**：
  - 回测专用配置模板

- `docs/GRID_BACKTEST_GUIDE.md` **（新建）**：
  - 回测使用指南
  - 参数优化建议

**验收标准**：
- ✅ 网格自动重置触发准确率 >90%
- ✅ 趋势检测准确率 >70%
- ✅ 低波动告警及时性 <30 分钟延迟
- ✅ 多标的（3 个）并行运行无冲突，CPU <30%, 内存 <500MB
- ✅ 回测月收益率 >0.8%（震荡市数据）
- ✅ Sharpe >2.5, 最大回撤 <-2%

**测试计划**：
- Day 1-2: 自适应网格中心 + 趋势过滤器
- Day 3-4: 低波动监控 + 多标的支持
- Day 5: 回测框架核心逻辑
- Day 6: 回测报告与参数优化
- Day 7: 集成测试 + 文档更新

## 3. M3 回测与参数化（第 3 周）
- `packages/backtest/Replay.ts`：搭建事件重放框架，复用生产策略接口驱动回测。
- `packages/backtest/latencyInjector.ts` **（新增）**：
  - 记录实盘"链上时间 vs 策略接收时间"的延迟分布
  - 回测时按真实延迟分布注入随机延迟
  - 验证：回测 Sharpe 应略低于实盘（前瞻偏差检测）
- 整合费用/资金费率/滑点模型，输出 Sharpe、EV、分桶等报表；撰写回测 CLI。
- 实现参数搜索器（Grid/Random），保存配置快照，更新审计日志与结果摘要。
- **配置热更新金丝雀流程（新增）**：
  - `packages/config/canaryDeployer.ts`：zod 校验 → 回测烟囱测试 → 单标的试运行
  - KPI 自动验证（EV/delta/cancel_rate），达标则全量发布，否则自动回滚
  - 审计日志记录（who/when/what/result）

## 4. M4 合规加固与多 venue 扩展（第 4 周）
- 新增第二 venue/子账户 Adapter，实现跨 venue STP 与一致性维护。
- **完善 Global Order Coordinator（增强）**：
  - 跨账户经济 STP 全流程集成（检测关联账户挂单交叉）
  - 订单冲突检测与自动化解（MM vs Scalper 方向冲突）
  - 降级策略触发器全面集成
- `packages/utils/liquidityMonitor.ts` **（新增）**：
  - top10_depth_usd 实时追踪
  - clip 动态调整（depth 下降 >30% 时自动降低 clip）
  - 实际滑点 vs 预期滑点监控与告警（差异 >2bps）
- **标的筛选器增强**：
  - `packages/registry/fundingRateScorer.ts`：评估双 venue funding rate 相关性
  - 自动拒绝相关性 <0.8 或同向支付频率 >20% 的 venue 对
  - 定期重新评估已上线标的，自动下线不合格标的
- 审计日志落地（append-only），全链路 trace id；补充断线恢复（快照+增量）流程。
- 自适应参数策略：根据实时 RV/OBI 调整 spread、层数、clip；完善金丝雀机制。

## 5. M5 运维与持续改进（持续迭代）
- **完整降级策略矩阵（新增）**：
  - 实现 ARCHITECTURE_DESIGN.md 5.5 节中的全部 9 种故障场景
  - 每种场景的检测器、降级动作执行器、恢复条件检查器
  - 降级状态持久化与审计日志
- **对冲效率监控面板（新增）**：
  - Grafana dashboard：hedge_success_rate, hedge_latency_p50/p95/p99, hedge_slippage_bps, cross_venue_basis
  - 告警规则：hedge_success_rate < 95%, hedge_latency_p99 > 2s, hedge_slippage_bps > 0.5
- **手动干预 API（新增）**：
  - `apps/runner/src/api/degradationOverride.ts`：`POST /api/override-degradation`（需 API key 认证）
  - 允许运维人员强制退出降级模式或触发特定降级动作
- Telemetry：完善 Prometheus 指标、Grafana 仪表盘、报警策略（delta_abs、hedge_cost、latency_p99、**funding_correlation**、**hedge_success_rate** 等）。
- SRE Playbook：脚本化常见操作（全部撤单、HALT、Kill-switch、自检、**funding rate 异常处理**），定期演练。
- 回测回归：建立周期性回测与 KPI 复盘机制，记录参数变更与风险审查结果。

## 协作与质量要求
- 每个阶段完成后提交代码、更新相关文档（`docs/`）、附带自测结果或回测报表。
- PR 必须通过 CI，并附上与当前阶段相关的 KPI 截图/日志；重要参数调整需记录在审计日志中。
- 与 `docs/IMPLEMENTATION_PLAN.md`、`docs/ARCHITECTURE_DESIGN.md` 保持一致性，重大架构变更需同步更新文档。
