# 数字货币量化交易系统开发计划

> 基于 Python + TypeScript 混合架构的数字货币量化交易系统 —— 核心模块划分与开发步骤

---

## 目录

1. [项目概述](#项目概述)
2. [技术栈选型](#技术栈选型)
3. [架构方案对比](#架构方案对比)
4. [核心模块划分](#核心模块划分)
5. [TypeScript 数据模块详解](#typescript-数据模块详解)
6. [开发步骤](#开发步骤)
7. [项目目录结构](#项目目录结构)
8. [部署与运维](#部署与运维)
9. [注意事项与风险提示](#注意事项与风险提示)

---

## 项目概述

本项目的目标是构建一套**可扩展、低延迟、稳定可靠**的数字货币量化交易系统，支持：

- 多交易所接入（Binance、OKX、Bybit 等）
- 多策略并行运行
- 实时行情数据采集与存储
- 策略回测与参数优化
- 实盘交易执行与风控管理
- 可视化监控与告警

### 架构策略

采用 **Python + TypeScript 混合架构**：

| 层 | 语言 | 职责 |
|---|------|------|
| **数据层** | TypeScript (Bun) | 行情采集、WebSocket 连接管理、K 线聚合、数据写入 |
| **业务层** | Python 3.10+ | 策略引擎、回测、风控、交易执行 |
| **接口层** | TypeScript / Python | FastAPI (Python) 或 NestJS (TS) 提供 REST/WS API |

---

## 技术栈选型

| 分类         | 技术 / 库                          | 说明                                   |
| ------------ | ---------------------------------- | -------------------------------------- |
| **数据层语言** | **TypeScript 5.x (Bun)**           | 行情采集、WebSocket 管理、数据管道     |
| **业务层语言** | **Python 3.10+**                  | 策略引擎、回测、风控逻辑               |
| **时序数据库** | **TimescaleDB**                   | K 线数据存储，连续聚合，基于 PostgreSQL 扩展 |
| 关系型数据库 | PostgreSQL 16+                     | 订单、策略配置等（与 TimescaleDB 共用实例）|
| 消息队列     | Redis                              | 跨语言数据流解耦，事件驱动（远期）     |
| 异步框架(TS) | Binance 官方 SDK + TypeORM        | REST/WS 客户端、ORM 映射               |
| 异步框架(Py) | `asyncio` + `aiohttp` / `httpx`    | 异步 I/O，高性能网络请求               |
| 数据分析     | `pandas` + `numpy` + `ta` / `talib` | 技术指标计算与数据分析                 |
| 策略回测     | `backtrader` / `vectorbt` / 自研   | 高性能回测引擎                         |
| Web 框架     | FastAPI + Uvicorn                  | REST API 与 WebSocket 服务            |
| 可视化       | Grafana + Streamlit                | 监控仪表盘与交互式分析                 |
| 任务调度     | Celery / APScheduler / Bull        | 定时任务与异步任务队列                 |
| 配置管理     | pydantic-settings + `.env`         | 类型安全的配置管理                     |
| 日志监控     | loguru + winston + sentry          | 结构化日志与异常追踪                    |
| **类型校验** | **Zod (TS) / Pydantic (Py)**       | 运行时数据校验，双端类型一致性保证      |

---

## 架构方案对比

### 方案 A：纯 Python（原方案）

```
[Python] 数据采集 → 策略引擎 → 交易执行 → 风控
```

| 优势 | 劣势 |
|------|------|
| 单一语言，维护简单 | WebSocket 大规模连接管理不如 Node.js |
| 数据分析生态无敌 | Python GIL 在 CPU 密集型场景受限 |
| 量化金融社区成熟 | 异步生态相对 Node.js 较新 |

### 方案 B：TypeScript 数据模块 + Python 业务引擎 ✅ **（推荐）**

```
[TypeScript] 数据采集 → Redis/消息队列 → [Python] 策略引擎 → 交易执行
```

| 优势 | 劣势 |
|------|------|
| Node.js WebSocket 性能优异，天然适合高并发连接 | 需要维护两套技术栈 |
| TypeScript 类型系统在数据管道中减少运行时错误 | 跨语言调试稍复杂 |
| **共享类型**：前后端可用同一套 TypeScript 类型定义 | 部署需要 Bun + Python 双运行时 |
| 事件驱动模型与行情数据流天然匹配 | 团队需要双语言能力 |
| npm 生态有成熟的交易 SDK（ccxt 等） | |

### 方案 C：全 TypeScript

```
[TypeScript] 数据采集 → 策略引擎 → 交易执行 → 风控
```

| 优势 | 劣势 |
|------|------|
| 单一语言 | 回测/量化分析生态远不如 Python |
| 类型安全 | 缺乏 pandas/numpy 级别的数据处理库 |
| 全栈一致性（前后端 + 数据层共用 TS） | 量化社区资源少，需要自研大量基础设施 |

---

## 核心模块划分

系统划分为 **7 大核心模块**，模块间通过消息队列或 API 解耦，整体架构如下：

```
┌─────────────────────────────────────────────────────────────┐
│                       Web UI / Dashboard                     │
│               (FastAPI / Streamlit / Grafana)                │
└──────────────┬──────────────────┬───────────────────────────┘
               │                  │
    ┌──────────▼──────────┐  ┌───▼────────────────────┐
    │    API Gateway       │  │   监控告警模块           │
    │  (REST + WebSocket)  │  │  (Prometheus + Alert)  │
    └──────────┬──────────┘  └────────────────────────┘
               │
    ┌──────────▼──────────────────────────────────────────┐
    │                    策略引擎  🐍 Python               │
    │         (策略加载 / 生命周期管理 / 信号分发)            │
    └────┬──────────────┬──────────────┬─────────────────┘
         │              │              │
    ┌────▼────┐   ┌─────▼─────┐   ┌───▼──────────┐
    │ 策略 A  │   │  策略 B   │   │   策略 C ...  │
    │(趋势)   │   │ (网格)    │   │              │
    └────┬────┘   └─────┬─────┘   └───┬──────────┘
         │              │              │
    ┌────▼──────────────▼──────────────▼─────────────────┐
    │                 交易执行模块  🐍 Python              │
    │    (订单管理 / 仓位管理 / 交易所适配器 / 重试机制)     │
    └────────────────────┬───────────────────────────────┘
                         │
    ┌────────────────────▼───────────────────────────────┐
    │         消息队列 (Redis / NATS)                      │
    │    ┌───────────── 数据管道 ─────────────┐           │
    └────────────────────┬───────────────────────────────┘
                         │
    ┌────────────────────▼───────────────────────────────┐
    │              数据模块  🟦 TypeScript                │
    │  (行情采集 / K线合成 / 数据存储 / 数据清洗 / 因子计算) │
    └────────────────────┬───────────────────────────────┘
                         │
    ┌────────────────────▼───────────────────────────────┐
    │                  风控模块  🐍 Python                │
    │ (资金管理 / 仓位限制 / 最大回撤 / 异常交易熔断 / 白名单)│
    └─────────────────────────────────────────────────────┘
```

---

### 1. 数据模块 (`data/`) — 🟦 TypeScript

负责从交易所获取和处理市场数据，是一切策略和决策的基础。

#### 为什么数据模块用 TypeScript？

| 原因 | 说明 |
|------|------|
| **WebSocket 性能** | Node.js 事件循环天然适合处理大量 WebSocket 连接（单进程万级连接） |
| **内存管理** | V8 引擎的垃圾回收机制在短生命周期对象场景表现优异 |
| **类型安全** | TypeScript 编译期检查确保数据管道中的类型正确性 |
| **流式处理** | Node.js Stream / Observable 模式与行情数据流完美匹配 |
| **生态优势** | 各交易所官方/社区 SDK 对 Node.js 支持最好 |

#### 子模块划分

| 子模块           | 职责                                                                 | 关键技术点                                      | 状态 |
| ---------------- | -------------------------------------------------------------------- | ----------------------------------------------- | :--: |
| **交易所适配器** | 封装不同交易所的 REST / WebSocket API，提供统一的 K 线拉取和订阅接口 | 适配器模式、`rest-registry` 自动路由、`ws-manager` 实例池 | ✅ |
| **数据回补**     | 启动时自动检测数据缺口，通过 REST API 逐交易对拉取历史 K 线补齐       | 增量回补、断点续传、并发控制、`lastBackfillTime` 追踪  | ✅ |
| **实时行情**     | WebSocket 订阅 1m K 线流，通过 EventBus 桥接到入库和聚合刷新          | Binance 官方 SDK、断线重连、超时检测、`kline:tick` 微回补 | ✅ |
| **数据存储**     | K 线数据持久化到 TimescaleDB，5 列复合主键 UPSERT                     | TypeORM + `@timescaledb/typeorm`、`synchronize: false`、DDL 由 SQL 脚本管理 | ✅ |
| **连续聚合**     | TimescaleDB 连续聚合视图自动从 1m K 线生成高周期（3m→1mon，共 12 层） | `FIRST(open, time)` / `LAST(close, time)` 保证 OHLC 语义 | ✅ |
| **事件总线**     | `node:events` 类型安全封装，解耦 WS 接收、入库、聚合刷新、策略消费    | `TypedEventBus`、`kline:update` → `kline:saved` → `aggregate:refreshed` | ✅ |
| **数据发布**     | 将处理后的数据通过 Redis Pub/Sub 推送给 Python 策略引擎               | `ioredis`、频道设计（设计阶段，尚未实现）          | ⏳ |
| **数据清洗**     | 去除异常数据、填充缺失值、处理停盘数据                                 | 统计异常检测、插值法（远期）                       | ❌ |

#### 关键接口

```typescript
// exchanges/rest-registry.ts — REST 客户端注册 + 自动路由
export function createRestClient(exchange: string, type: PairType): BaseRestClient;
export async function fetchKlines(params: FetchKlinesParams): Promise<Kline[]>;

// exchanges/ws-manager.ts — WS 订阅管理
export function watchKline(target: { exchange: string; type: PairType; symbol: string }): void;
export function watchKlines(targets: Array<{ exchange: string; type: PairType; symbol: string }>): void;
export function unWatchKline(symbol: string, type: PairType): void;

// service/backfill.ts — 历史数据回补
export async function backfillKline(pair: TradingPair): Promise<void>;
export async function backfillKlines(): Promise<void>;  // 遍历所有交易对

// service/kline.ts — K 线写入
export async function upsertOrUpdateKlines(klines: Kline[]): Promise<void>;

// service/aggregate.ts — 聚合刷新
export async function checkAndRefresh(openTime: number): Promise<void>; // 从 openTime 所在的分钟桶开始刷新
```

> 详细 API 参考见 [`data/ARCHITECTURE.md`](data/ARCHITECTURE.md)。

---

#### 数据采集与聚合策略

本模块**不自行合成 K 线**，而是采用"交易所原始 K 线 + TimescaleDB 连续聚合"方案：

1. **1m K 线**：通过交易所 REST API 回补历史数据 + WebSocket 订阅实时 1m K 线，直接 UPSERT 到 `klines` hypertable。K 线的 `time` 字段存储交易所原始 `openTime`（UTC），不做本地转换。
2. **高周期 K 线**：由 TimescaleDB 连续聚合视图（Continuous Aggregate）自动从 1m 表生成，`FIRST(open, time)` / `LAST(close, time)` 保证 OHLC 语义与交易所原生高周期 K 线一致。
3. **聚合刷新**：TS 侧 `checkAndRefresh()` 在每根 1m K 线入库后触发 TimescaleDB 刷新策略，确保连续聚合视图实时更新。

**K 线复合主键**：`[exchange, symbol, type, interval, time]`（5 列），其中 `type` 区分现货（spot）/ USDT-M 合约（um）/ Coin-M（cm）。

> 详细设计见 [`data/ARCHITECTURE.md`](data/ARCHITECTURE.md) §4.3、§5 和 [`data/db/init-db/03-continuous-aggregates.sql`](data/db/init-db/03-continuous-aggregates.sql)。

---

#### TimescaleDB 数据存储方案

K 线数据具有典型的时序特征：**持续写入、按时间范围查询、少有更新、数据量大**。TimescaleDB 作为 PostgreSQL 的时序扩展，相比 InfluxDB 有以下核心优势：

| 对比维度 | TimescaleDB | InfluxDB |
|---------|------------|----------|
| **基础数据库** | PostgreSQL 扩展 | 独立时序数据库 |
| **SQL 兼容** | 完整 SQL 支持（JOIN、子查询、窗口函数） | 类 SQL 但不完全兼容 |
| **与业务数据关联** | K 线表和订单表可以在同一个 PG 实例中 JOIN | 需要跨数据库查询 |
| **数据压缩** | 列式压缩，压缩比 90%+ | 压缩比约 85% |
| **连续聚合** | 内置自动刷新物化视图 | 需要外部工具 |
| **保留策略** | 内置自动删除（数据保留策略） | 内置 |
| **生态集成** | 可与 PostGIS、pgvector 等 PG 扩展共存 | 独立生态 |
| **运维成本** | 复用 PG 运维经验 | 需独立运维 |

**实际表结构**（5 列复合主键）：

```sql
CREATE TABLE klines (
  exchange    TEXT          NOT NULL,
  symbol      TEXT          NOT NULL,
  type        TEXT          NOT NULL,   -- spot / um / cm
  interval    TEXT          NOT NULL,   -- 1m / 5m / 15m / 1h / 4h / 1d …
  time        BIGINT        NOT NULL,   -- 交易所原始 openTime (ms)
  open        NUMERIC(20,8) NOT NULL,
  high        NUMERIC(20,8) NOT NULL,
  low         NUMERIC(20,8) NOT NULL,
  close       NUMERIC(20,8) NOT NULL,
  volume      NUMERIC(20,8) NOT NULL,
  -- ... 扩展字段
  PRIMARY KEY (exchange, symbol, type, interval, time)
);
SELECT create_hypertable('klines', 'time', chunk_time_interval => INTERVAL '1 day');
```

> **DDL 全部由 SQL 脚本管理**（`synchronize: false`），TypeORM 实体仅用于运行时映射。连续聚合视图共 **12 层**（3m → 5m → 15m → 30m → 1h → 2h → 4h → 6h → 8h → 12h → 1d → 1mon），使用 `FIRST(open, time)` / `LAST(close, time)` 保证 OHLC 语义。
>
> 详见 [`data/db/init-db/`](data/db/init-db/) 和 [`data/ARCHITECTURE.md`](data/ARCHITECTURE.md) §4.3。

**磁盘空间估算**：

| 数据量 | 未压缩 | 压缩后 (~92%) |
|--------|--------|-------------|
| 10 币种 / 1 年 | ~945 MB | ~75 MB |
| 50 币种 / 1 年 | ~4.7 GB | ~375 MB |
| 200 币种 / 1 年 | ~18.9 GB | ~1.5 GB |


---

#### 推荐的 npm 包（实际依赖）

| 包名 | 用途 | 状态 |
|------|------|:--:|
| `binance` | Binance 官方 SDK（MainClient + USDMClient + WebSocket） | ✅ |
| `typeorm` + `@timescaledb/typeorm` | ORM 框架 + TimescaleDB 装饰器映射 | ✅ |
| `pg` | PostgreSQL 原生驱动（TypeORM 底层） | ✅ |
| `pino` + `pino-pretty` + `pino-roll` | 高性能结构化日志 | ✅ |
| `yaml` | 解析 env.yaml 配置文件 | ✅ |
| `ioredis` | Redis 客户端（Pub/Sub 远期集成） | ⏳ |
| `ccxt` | 统一交易所 API（多交易所远期） | ⏳ |

---

### 2. 策略引擎 (`engine/`) — 🐍 Python

核心调度中心，负责策略的生命周期管理和信号分发。

#### 子模块划分

| 子模块         | 职责                                           | 关键技术点                             |
| -------------- | ---------------------------------------------- | -------------------------------------- |
| **通用模块**   | 策略基类、数据模型、日志、配置                   | `engine/common/` 目录，基础类型定义     |
| **策略管理器** | 策略注册、启动、停止、热加载                     | 插件化架构、动态导入、`importlib`      |
| **信号分发器** | 将策略产生的交易信号分发到交易执行模块            | 事件总线、消息队列                      |
| **回测引擎**   | 使用历史数据模拟策略执行，评估收益、回撤等指标     | `vectorbt` / `backtrader`、事件驱动    |
| **参数优化器** | 网格搜索 / 贝叶斯优化策略参数                     | `scipy.optimize`、`optuna`、并行计算    |

#### 策略基类设计

```python
from common import BaseStrategy, StrategyConfig, Signal
from common.models import Kline, Ticker, OrderBook

class MyStrategy(BaseStrategy):
    """策略示例 — 所有策略继承 BaseStrategy"""
    strategy_type = "my_strategy"

    async def on_kline(self, kline: Kline) -> Signal | None:
        ...
```

---

### 3. 交易执行模块 (`executor/`) — 🐍 Python

负责将策略信号转化为实际订单，管理交易所连接和仓位。虽然数据采集在 TypeScript 层完成，但下单操作仍需在 Python 侧执行，因为策略引擎和风控逻辑同在 Python 侧，减少跨语言通信延迟。

#### 子模块划分

| 子模块           | 职责                                                   | 关键技术点                               |
| ---------------- | ------------------------------------------------------ | ---------------------------------------- |
| **交易所适配器** | 封装不同交易所的 REST / WebSocket API，提供统一接口     | 适配器模式、限频控制、签名算法            |
| **订单管理器**   | 下单、撤单、查询订单状态；支持限价单、市价单、条件单    | 订单状态机、幂等性、超时处理              |
| **仓位管理器**   | 跟踪当前持仓、可用余额、未实现盈亏                      | 实时同步、增量更新                        |
| **执行算法**     | TWAP、VWAP、冰山订单等高级执行算法（降低滑点）          | 切片算法、时间加权                        |

#### 交易所适配器接口

```python
class ExchangeAdapter(ABC):
    """交易所统一适配器接口"""

    @abstractmethod
    async def create_order(self, order: Order) -> OrderResult:
        ...

    @abstractmethod
    async def cancel_order(self, order_id: str) -> bool:
        ...

    @abstractmethod
    async def get_balance(self) -> dict[str, float]:
        ...

    @abstractmethod
    async def get_position(self, symbol: str) -> Position:
        ...
```

---

### 4. 风控模块 (`risk/`) — 🐍 Python

系统的安全防线，在交易前、交易中、交易后全链路控制风险。

| 功能               | 说明                                                               |
| ------------------ | ------------------------------------------------------------------ |
| **资金管理**       | 单笔下单量限制、总仓位比例限制、逐仓/全仓模式支持                    |
| **最大回撤控制**   | 当日/累计回撤超过阈值时自动暂停策略                                  |
| **异常检测**       | 检测价格异常波动、交易所 API 异常、网络延迟过高                      |
| **熔断机制**       | 极端行情下自动停止所有交易，进入只平不开模式                         |
| **订单频率限制**   | 控制单位时间内的下单次数，防止过度交易                               |
| **白名单/黑名单**  | 限制可交易的币种和交易对                                             |

```python
class RiskManager:
    async def check_order(self, order: Order, context: TradingContext) -> RiskResult:
        """下单前风控检查"""
        checks = [
            self._check_max_position,
            self._check_order_value,
            self._check_order_frequency,
            self._check_drawdown_limit,
            self._check_price_deviation,
        ]
        for check in checks:
            result = await check(order, context)
            if not result.passed:
                return result
        return RiskResult(passed=True)
```

---

### 5. 监控告警模块 (`monitor/`)

保障系统运行的可观测性。

| 功能             | 说明                                               |
| ---------------- | -------------------------------------------------- |
| **指标收集**     | 收集策略收益、胜率、夏普比率、最大回撤等绩效指标       |
| **系统监控**     | CPU / 内存 / 网络延迟 / API 调用量                  |
| **告警通知**     | 通过钉钉、Telegram、飞书等发送告警                   |
| **日志管理**     | 结构化日志存储，支持按级别、模块检索                  |
| **Web 仪表盘**   | 实时展示资金曲线、持仓、交易记录、策略状态等           |

---

### 6. API 网关 (`api/`)

对外提供统一接口，支持浏览器端和移动端访问。

| 功能               | 说明                                |
| ------------------ | ----------------------------------- |
| **REST API**       | 策略管理、查询持仓、查看交易记录      |
| **WebSocket**      | 实时推送行情、交易信号和通知          |
| **用户认证**       | JWT 认证、API Key 管理               |
| **权限管理**       | 多用户角色（管理员 / 只读用户）       |

---

### 7. 配置与工具模块 (`common/`)

提供跨模块共享的基础设施。

| 模块     | 功能                                     |
| -------- | ---------------------------------------- |
| **配置** | 基于 `pydantic-settings` 的环境配置管理   |
| **日志** | 基于 `loguru` 的统一日志配置              |
| **工具** | 时间工具、重试装饰器、限流器、加解密工具   |
| **模型** | 共享的 Pydantic 数据模型（订单、K 线等）  |
| **常量** | 交易所枚举、订单类型、时间周期等定义       |

---

## TypeScript 数据模块详解

### 核心架构

```
┌──────────────────────────────────────────────────────────────────┐
│                    TypeScript 数据模块 (Bun)                       │
│                                                                   │
│  ┌──────────────────┐                    ┌──────────────────┐    │
│  │  Binance REST    │── backfill ──────→│  TimescaleDB     │    │
│  │  · MainClient    │                    │  Klines (1m)     │    │
│  │  · USDMClient    │                    └────────┬─────────┘    │
│  └──────────────────┘                             │              │
│                                                   │              │
│  ┌──────────────────┐    EventBus (node:events)   │              │
│  │  Binance WS      │── kline:update ────→ upsert─┘              │
│  │  (官方 SDK)      │         ↓                                   │
│  └────────┬─────────┘   kline:saved ────→ 连续聚合刷新            │
│           │                                                       │
│           │  pair:ready ← backfill 完成后触发                     │
│           │  ws:disconnected / ws:connected / ws:stale            │
│           │                                                       │
│  ┌────────┴──────────────────────────┐                           │
│  │  run/start.ts（编排层）             │                           │
│  │  注册 bus 监听 → backfillKlines()  │                           │
│  │  → WS 订阅 → 入库 → 聚合刷新        │                           │
│  └───────────────────────────────────┘                           │
│                                                                   │
│  ┌───────────────────────────────────┐                           │
│  │  TypeORM 实体（关系数据）            │                           │
│  │  Exchange / TradingPair           │                           │
│  └───────────────────────────────────┘                           │
└──────────────────────────────────────────────────────────────────┘
```

### 数据流生命周期

```
回补阶段                         实时阶段
────────                         ────────
REST API                       WebSocket
    │                               │
    ▼                               ▼
fetchKlines()                 kline:update (bus event)
    │                               │
    ▼                               ▼
upsertOrUpdateKlines()        upsertOrUpdateKlines()
    │                               │
    ▼                               ▼
pair:ready (bus event)        kline:saved (bus event)
    │                               │
    ▼                               ▼
watchKline()                  checkAndRefresh()
    │                          (连续聚合刷新)
    ▼
WS 实时订阅启动                aggregate:refreshed
                                     │
                                     ▼
                              Redis Pub/Sub (远期)
                                     │
                                     ▼
                              Python 策略引擎消费
```

### TypeScript 数据模块目录结构

```
data/
├── package.json
├── tsconfig.json
├── bun.lock
│
├── run/                           # 启动入口
│   ├── start.ts                   # 编排层：回补 → WS 订阅 → 入库 → 聚合刷新
│   ├── exchange.ts                # 独立回补入口
│   └── build_aggregates_sql.ts    # 聚合刷新（dry-run / --execute）
│
├── config/                        # 配置模块
│   ├── index.ts                   # 加载 env.yaml → 校验 → 分组导出
│   └── validators.ts              # 零依赖运行时校验
│
├── db/                            # 数据库层
│   ├── data-source.ts             # TypeORM DataSource（synchronize: false）
│   ├── entities/                  # ORM 实体
│   │   ├── kline.entity.ts        # TimescaleDB K 线 hypertable（5 列复合 PK）
│   │   ├── exchange.entity.ts     # 交易所
│   │   ├── trading-pair.entity.ts # 交易对（含 type 列）
│   │   └── common.entity.ts       # 公共基类
│   ├── init-db/                   # DDL SQL（容器首次启动自动执行）
│   │   ├── 01-timescaledb.sql
│   │   ├── 02-init-tables.sql
│   │   └── 03-continuous-aggregates.sql
│   └── migrations/                # TypeORM 迁移文件
│
├── exchanges/                     # 交易所适配器
│   ├── base.ts                    # BaseRestClient / BaseWsClient 抽象基类
│   ├── constants.ts               # KLINE_INTERVAL_MS 等常量
│   ├── rest-registry.ts           # REST 客户端注册 + fetchKlines() 自动路由
│   ├── ws-manager.ts              # WS 实例池 + watchKline/watchKlines
│   └── binance/
│       ├── rest.ts                # BinanceRestClient（现货）+ Futures（合约）
│       └── ws.ts                  # BinanceWsClient
│
├── service/                       # 业务服务层
│   ├── backfill.ts                # 回补编排
│   ├── kline.ts                   # upsertOrUpdateKlines（批量 UPSERT）
│   ├── pair.ts                    # 交易对查询/更新
│   └── aggregate.ts               # checkAndRefresh（聚合刷新触发）
│
├── types/                         # 共享类型
│   ├── base.ts                    # Kline / Ticker / Trade 等接口
│   └── kline.ts                   # PairType / KlineInterval 枚举
│
├── utils/                         # 工具
│   ├── bus.ts                     # TypedEventBus（node:events 类型安全封装）
│   ├── logger.ts                  # Pino 日志
│   └── index.ts                   # getNowMinuteMS / wait 等
│
└── tests/                         # 测试（4 个文件，覆盖率建设中）
```

> 详细架构说明见 [`data/ARCHITECTURE.md`](data/ARCHITECTURE.md)。

### Python ↔ TypeScript 跨语言通信

> ⚠️ **当前状态**：Redis Pub/Sub 尚未集成，TS 侧已安装 `ioredis` 依赖。当前 Python engine 通过直接读取 TimescaleDB 获取 K 线数据进行回测。

```
┌──────────────────┐         Redis/NATS          ┌──────────────────┐
│  🟦 TypeScript   │ ──────────────────────────►  │  🐍 Python       │
│  数据模块        │    Pub: "market:kline:1m"    │  策略引擎        │
│                  │    Pub: "market:trade"        │                  │
│                  │                              │  Sub: 消费行情   │
└──────────────────┘                              └──────────────────┘

---

## 开发步骤

### 第一阶段：基础建设 ✅ 数据模块已完成

**目标**：搭建项目骨架，完成 TypeScript 数据模块的基础能力和 Python 项目基础。

| 步骤 | 状态 | 任务 | 产出物 |
| ---- | :--: | ---- | ------ |
| 1.1 | ✅ | 初始化 TypeScript 数据项目（`data/`），配置 `package.json` | 项目结构，ESLint + Prettier 配置 |
| 1.2 | ✅ | 初始化 Python 项目，配置 `uv` 依赖管理 | `pyproject.toml`，项目目录结构 |
| 1.3 | ✅ | 定义共享类型：TypeScript `types/` + Python `engine/common/models.py` | 双端对齐的数据模型 |
| 1.4 | ✅ | 实现 TS 交易所适配器基类 + Binance 适配器（`data/exchanges/`） | 统一接口 + REST/WS 连接 |
| 1.5 | ✅ | 实现 TS 行情采集器，WebSocket 订阅实时 1m K 线 | 实时行情流入 |
| 1.6 | ✅ | 实现 TS 数据存储模块，TypeORM + TimescaleDB UPSERT | 数据持久化 |
| 1.7 | ✅ | TimescaleDB 连续聚合视图（12 层，3m→1mon） | 高周期 K 线自动生成 |
| 1.8 | ⏳ | 实现 TS → Redis 数据发布 | 实时行情推送到消息队列（远期） |
| 1.9 | ⏳ | Python 侧实现 Redis 订阅消费者 | 消费端就绪（远期） |
| 1.10 | ✅ | Docker Compose 编排基础服务（TimescaleDB） | `docker-compose.yml` |

> 实际 TS 路径为 `data/exchanges/`（非 `data/src/exchanges/`），未实现本地 K 线合成器，改为交易所原始 K 线 + TimescaleDB 连续聚合。详见 [`data/ARCHITECTURE.md`](data/ARCHITECTURE.md)。

### 第二阶段：策略与回测 🔄 进行中

**目标**：实现策略框架和回测引擎，能编写策略并进行回测验证。

| 步骤 | 状态 | 任务 | 产出物 |
| ---- | :--: | ---- | ------ |
| 2.1 | ✅ | 实现策略基类（`engine/common/base.py`） | `BaseStrategy` 抽象基类 |
| 2.2 | ❌ | 实现策略管理器，支持策略注册和生命周期 | 策略热加载、启动/停止控制 |
| 2.3 | ❌ | 实现信号分发器 | 事件总线，策略到执行器的信号传递 |
| 2.4 | ✅ | 实现回测引擎（`engine/backtest/`） | 历史数据回测，收益曲线、回撤等指标 |
| 2.5 | ✅ | 实现技术指标（`engine/indicators/`） | MA、ATR、RSI 等常用指标 |
| 2.6 | ✅ | 编写示例策略（`engine/example/`） | 多个可运行的策略示例 |
| 2.7 | ❌ | 实现参数优化器 | 基于 Optuna 的参数搜索 |

### 第三阶段：交易执行与风控（远期）

**目标**：连接实盘交易通道，实现完整的交易执行流程和风控体系。

| 步骤 | 状态 | 任务 | 产出物 |
| ---- | :--: | ---- | ------ |
| 3.1 | ❌ | 实现订单管理器 | 下单、撤单、订单状态更新 |
| 3.2 | ❌ | 实现仓位管理器 | 实时仓位跟踪 |
| 3.3 | ❌ | 实现交易状态机 | 订单生命周期管理 |
| 3.4 | ❌ | 实现重试与容错机制 | 网络异常自动重试 |
| 3.5 | ❌ | 实现风控管理器 | 资金管理、仓位限制、熔断 |
| 3.6 | ❌ | 实现风控规则引擎 | 可扩展的风控规则链 |
| 3.7 | ❌ | 整合 TS → Redis → Python 端到端流程 | 跨语言运行流水线 |

### 第四阶段：API 与监控（远期）

| 步骤 | 状态 | 任务 | 产出物 |
| ---- | :--: | ---- | ------ |
| 4.1 | ❌ | 搭建 FastAPI 项目 | REST API 服务 |
| 4.2 | ❌ | 实现 WebSocket 实时推送 | 行情和交易数据推送 |
| 4.3 | ❌ | 实现策略管理 API | 策略启停、参数修改 |
| 4.4 | ❌ | 实现交易记录查询 API | 交易历史查询 |
| 4.5 | ❌ | 集成 Prometheus 指标 | 关键业务指标暴露 |
| 4.6 | ❌ | 配置 Grafana 仪表盘 | 可视化仪表盘 |
| 4.7 | ❌ | 实现告警通知集成 | Telegram / 钉钉通知 |

### 第五阶段：优化与生产化（远期）

| 步骤 | 状态 | 任务 |
| ---- | :--: | ---- |
| 5.1 | ❌ | 性能优化与压测 |
| 5.2 | ❌ | 测试覆盖率 > 80% |
| 5.3 | ❌ | CI/CD 流水线 |

---

## 项目目录结构

```
trade/
├── env.yaml                     # 统一环境配置源（TS/Python 共享）
├── docker-compose.yml           # 基础服务编排（TimescaleDB + Adminer）
├── .gitignore
├── README.md
│
├── data/                        # 🟦 TypeScript 数据模块 ✅ MVP 就绪
│   ├── ARCHITECTURE.md          # 模块技术架构说明
│   ├── package.json
│   ├── tsconfig.json
│   ├── run/                     # 启动入口（start.ts / exchange.ts / build_aggregates_sql.ts）
│   ├── config/                  # 配置（加载 env.yaml）
│   ├── db/                      # TypeORM DataSource + 实体 + init-db SQL
│   ├── exchanges/               # 交易所适配器（base / binance / rest-registry / ws-manager）
│   ├── service/                 # 业务层（backfill / kline / pair / aggregate）
│   ├── types/                   # 共享类型（Kline / PairType / KlineInterval）
│   ├── utils/                   # EventBus / Logger / 工具函数
│   └── tests/                   # 测试（覆盖率建设中）
│
├── engine/                      # 🐍 Python 策略引擎 🔄 进行中
│   ├── common/                  # 策略基类 + 数据模型 + 日志
│   ├── backtest/                # 回测引擎
│   ├── indicators/              # 技术指标（ATR / MA / RSI …）
│   └── example/                 # 示例策略（ma_cross / atr_band …）
│
├── executor/                    # 🐍 Python 交易执行 ❌ 远期
├── risk/                        # 🐍 Python 风控 ❌ 远期
├── monitor/                     # 监控告警 ❌ 远期
├── api/                         # API 网关 ❌ 远期
├── strategies/                  # 策略目录 ❌ 远期
└── docs/                        # 文档
```

---

## 部署与运维

### 服务组件依赖

```
┌──────────────────┐   ┌──────────────┐   ┌─────────────┐
│  TS 数据模块     │   │  PostgreSQL  │   │   Grafana    │
│  (Bun 进程)      │   │  (业务数据)   │   │  (可视化)    │
└──────┬───────────┘   └──────────────┘   └──────┬──────┘
       │                                         │
       │            ┌──────────────┐             │
       ├────────────▶  TimescaleDB │◀────────────┤
       │            │  (时序存储)   │             │
       │            └──────────────┘             │
       │                                         │
       │            ┌──────────────┐             │
       ├────────────▶    Redis     ├─────────────┤
       │            │ (队列/缓存)  │             │
       │            └──────┬───────┘             │
       │                   │                     │
       │            ┌──────▼───────┐             │
       └────────────▶ Python 引擎  │             │
                    │ (策略+执行)  │             │
                    └──────────────┘             │
```

### 容器化方案

```dockerfile
# Dockerfile.data — TypeScript 数据模块
FROM node:20-alpine AS builder
WORKDIR /app
COPY data/package*.json ./
RUN npm ci
COPY data/ .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]
```

```dockerfile
# Dockerfile.engine — Python 业务引擎
FROM python:3.11-slim
WORKDIR /app
COPY pyproject.toml poetry.lock ./
RUN pip install poetry && poetry install --no-dev
COPY . .
CMD ["poetry", "run", "python", "-m", "engine.main"]
```

### 关键运维指标

- **API 延迟**：单次下单 < 500ms（网络延迟不计）
- **数据延迟**：行情从交易所到 Redis < 500ms（TypeScript 采集）
- **系统可用性**：核心交易链路 > 99.9%
- **策略执行周期**：秒级 tick 策略 < 100ms / 次
- **跨语言通信延迟**：Redis Pub/Sub < 1ms（同机部署）

---

## 注意事项与风险提示

> ⚠️ **风险声明**：数字货币交易具有高风险，本系统仅为技术实现，不构成任何投资建议。使用前请充分了解风险。

### 技术注意事项

1. **API 限频**：各交易所均有严格 API 限频，需实现本地限流器
2. **WebSocket 重连**：网络波动导致断线，需实现心跳检测和自动重连（指数退避策略）
3. **数据一致性**：订单状态需轮询确认，避免因异步回调丢失状态
4. **时间同步**：服务器需 NTP 同步，防止时间偏差导致下单失败
5. **日志安全**：避免记录 API Secret 等敏感信息到日志
6. **灰度发布**：新策略先在模拟盘运行，验证通过后方可接入实盘
7. **资金隔离**：不同策略的资金账户严格隔离，防止交叉影响
8. **跨语言类型一致性**：TypeScript 的 `zod` schema 和 Python 的 `Pydantic` model 需保持同步，建议用自动化脚本生成或共享 schema 文件

### 开发建议

1. **模块化开发**：各模块独立开发、独立测试，通过接口契约协作
2. **代码质量**：TS 用 `ESLint` + `Prettier`，Python 用 `ruff` + `mypy`
3. **版本控制**：配置文件和策略参数不应硬编码，使用 `.env` 或配置文件
4. **日志先行**：先写好日志，再写业务逻辑，便于调试
5. **单元测试**：核心逻辑（风控、订单状态机、K 线合成器）必须有单元测试覆盖
6. **模拟盘先行**：实盘前至少 2 周模拟盘验证策略稳定性
7. **本地开发**：Python 和 TS 模块分别 `npm run dev` / `poetry run dev` 独立开发调试
8. **schema 驱动**：考虑使用 Protocol Buffers 的 `.proto` 文件同时生成 TS 和 Python 代码，保证类型完全一致

---

## 许可证

MIT License