## 需求文档（V2）— 多交易所对冲执行系统

### 1. 总体目标

- 统一 `exchanges` 接入层（抽象 + 实现），策略与领域层不感知底层差异。
- 降低净值回撤、减少误码（精度/保证金不足等），保持两侧灵活度与原子对称开平。
- 强化可观测性（中文日志、持久化、报表）与可运维性（PM2/健康检查）。

### 2. 分层与目录

- `src/exchanges/`：
  - 抽象：`ExchangeAdapter.ts`
  - 实现：`aster/*`、`binance/*`、`pacifica/*`
- `src/core/`：对冲执行抽象、市场聚合、策略接口

### 账户文档索引

- 统一方式：`docs/accounts/UNIFIED_MANAGEMENT.md`
- 生命周期：`docs/accounts/ACCOUNT_LIFECYCLE.md`
- 环境变量：`docs/accounts/ENV_VARS.md`
- Pacifica 账户：`docs/accounts/PACIFICA_ACCOUNT.md`
- Aster 账户：`docs/accounts/ASTER_ACCOUNT.md`
- `src/infrastructure/`：钱包、配置、数据库（当前仅钱包在用）
- `docs/`：架构、使用、变更日志与需求

### 3. 交易与执行需求

- 原子配对与对称开平：两侧同时下单，任一失败立即回滚/对冲，净敞口约束。
- 强制净零：周期性/每 tick 将净暴露打回阈值内。
- 入场价对齐：AUTO（ADD/REPLACE）自适应回归，参数范围（delta 8–15bps、chunk 20–30%、间隔 3–5s）。
- 混合 Maker/Taker 刷量：`takerRatio` 自适应，薄盘口限制 Taker，Maker join best/inside。
- 成本阈值过滤：若费用+滑点+价差超阈值则跳过。
- -2019 处理：双边多步减仓、失败侧冷却，Taker 爆发前撤限价释放保证金。
- 精度与步进：严格遵循 stepSize/tickSize/precision；数量与价格格式化统一。

### 4. 行情与订单簿

- 标准化 `depth(symbol, limit)` 与 WS 事件（depth/ticker/trade）。
- 薄盘口（如部分 DEX）启用 spread-aware，限制 Taker；聚合中位价用于触发逻辑。

### 5. 可观测性与持久化

- 中文日志：账户/仓位/入场价/PNL/净暴露/动作（重试/回退/对冲/净零/对齐）。
- 数据持久化：CSV/SQLite（账户净值、下单/成交量、PnL、错误码、回归动作）。
- 报表脚本：支持时间窗口聚合（胜率、回撤、手续费覆盖率、净度）。

### 6. 运维与测试

- PM2 管理，`--update-env` 热重载；健康检查。
- smoke：各交易所连通（time/symbols/depth/最小下单/撤单）。
- 单元：精度与步进边界、指令与账户解码一致性（适用 DEX）。

### 7. 参数（保守默认）

- 杠杆 25x；单侧最大名义 30u；`baseNotional=2u`；`gridStep=60bps`
- `takerRatio=0.4`；`minSpreadBps=35`；`takerCooldownMs=10000`
- 入场价对齐：`delta=8–15bps`，`chunk=20–30%`，`interval=3–5s`，`mode=AUTO`

### 8. 里程碑

- M1：三交易所 smoke 通，全局精度/步进校验通过
- M2：执行器面向 `ExchangeAdapter` 完整对接，原子配对>98%
- M3：日志/持久化/报表就绪、错误码自愈率>95%
- M4：长周期稳态试跑与复盘优化

### 9. 模块清单与职责（按分层）

- exchanges（接入层）

  - 抽象
    - `src/exchanges/ExchangeAdapter.ts`：统一接口（下单/撤单/账户/仓位/深度/WS）
  - Binance
    - `src/exchanges/binance/FutureConnector.ts`：USDS 合约 REST 封装
    - `src/exchanges/binance/BinanceAdapter.ts`：实现 `ExchangeAdapter`
  - Aster
    - `src/exchanges/aster/asterAdapter.ts`：签名封装/下单占位
    - `src/exchanges/aster/wsClient.ts`：WS 客户端（订阅/重连/心跳）
    - `src/exchanges/aster/orderBook.ts`：本地 OrderBook（快照+增量）
    - `src/exchanges/aster/orderBookManager.ts`：多符号管理与分发
    - `src/exchanges/aster/types.ts`：Aster 事件/配置类型
  - Pacifica
    - `src/exchanges/pacifica/PacificaClient.ts`：REST/WS 基础客户端（签名占位）
    - `src/exchanges/pacifica/PacificaAdapter.ts`：实现 `ExchangeAdapter`

- core（领域层）

  - `src/core/hedging/hedgingExecutor.ts`：对称/原子开平、净敞口约束（后续对接 exchanges）
  - `src/core/hedging/hedgeCalculator.ts`：数量/净暴露/回归计算
  - `src/core/hedging/router.ts`：路由到现货/合约执行（调用 AsterAdapter）
  - `src/core/strategy/positionStrategy.ts`：策略接口/信号定义
  - `src/core/market/*`：行情聚合/配置（深度/中位价）

- infrastructure（基础设施）

  - `src/infrastructure/wallet/walletManager.ts`：链上签名/地址管理（已用）
  - `src/infrastructure/config/configManager.ts`：统一配置读取（待接）
  - `src/infrastructure/database/`：持久化（CSV/SQLite/报表，待接）

- utils（通用）

  - `src/utils/logger.ts`：中文日志输出
  - `src/utils/math.ts`、`src/utils/events.ts`、`src/utils/web3.ts`

- examples / scripts（示例与脚本）

  - `examples/pacifica_smoke.ts`：Pacifica 连通性
  - （新增）`examples/adapter_symmetry_demo.ts`：基于 `ExchangeAdapter` 的最小对称下单
  - yarn 脚本：`smoke:pacifica`（已有）、（新增）`demo:adapter-symmetry`

- docs（文档）
  - `docs/requirements.md`（本文）、`docs/architecture.md`、`docs/CHANGELOG.md`

### 10. 生产就绪模块要求

#### 🔴 关键生产模块（P0 - 上线前必须）

**监控和可观测性**

- [ ] Prometheus 指标收集系统
- [ ] Grafana 监控仪表板
- [ ] 健康检查 API (`/health`)
- [ ] 关键指标告警规则 (延迟、错误率、连接状态)
- [ ] 结构化日志输出 (JSON格式、统一时间戳)

**故障恢复和容错**

- [ ] 自动重连机制 (指数退避策略)
- [ ] 订单执行失败回滚机制
- [ ] 网络分区场景处理
- [ ] 账户故障切换逻辑
- [ ] 数据不一致自动修复

**安全加固**

- [ ] API 密钥轮换机制
- [ ] IP 白名单和防火墙配置
- [ ] 详细审计日志记录
- [ ] 敏感数据加密存储
- [ ] 入侵检测和告警

#### 🟡 重要生产模块（P1 - 上线后优化）

**性能和扩展**

- [ ] 连接池管理优化
- [ ] 批量订单处理
- [ ] 内存缓存策略
- [ ] 数据库连接池
- [ ] WebSocket 消息压缩

**数据持久化**

- [ ] PostgreSQL 数据库集成
- [ ] 数据备份和恢复机制
- [ ] 实时分析引擎
- [ ] 交易报表系统
- [ ] 历史数据归档

**运维工具**

- [ ] PM2 生态配置文件
- [ ] Docker 容器化部署
- [ ] CI/CD 流水线
- [ ] 自动化部署脚本
- [ ] 环境配置管理

#### 🟢 增强功能模块（P2 - 长期规划）

**高级交易功能**

- [ ] 冰山订单和 TWAP 算法
- [ ] 动态风险管理系统
- [ ] 回测框架集成
- [ ] ML 模型集成接口
- [ ] 更多 DeFi 协议支持

### 11. 需新增/完善模块（任务清单）

- 执行器对接 exchanges：将 `hedgingExecutor` 改为仅依赖 `ExchangeAdapter`
- 精度/步进工具：数量/价格对齐（stepSize/tickSize/precision）通用化
- 审计与持久化：
  - CSV/SQLite 写入器（账户净值、下单/成交量、PNL、错误码、回归动作）
  - 报表脚本（时间窗口聚合）
- 对称下单示例与脚本（adapter_symmetry_demo）
- PM2 生态文件（ecosystem.config.js），含日志目录与自动重启

### 12. 生产就绪度评估

**当前状态**: 81.55/100 分
**目标状态**: 90+ 分 (企业级标准)

**关键指标要求**:

- 系统可用性 ≥ 99.9%
- API 响应时间 < 100ms (95th percentile)
- 故障恢复时间 < 5分钟
- 错误率 < 0.1%
- 支持并发账户数 ≥ 1000个