binance-api/docs/requirements.md

需求文档（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个