# trade — 数字货币量化交易系统

Python + TypeScript (Bun) 混合架构：数据层 TS 采集行情入库，业务层 Python 跑策略/回测/风控。

## 项目

- **`data/`**：TypeScript (Bun)，行情采集、K 线合成、数据写入 TimescaleDB。workdir 必须是 `data/`。
- **`engine/`**：Python 3.10+，策略引擎、回测、信号分发。workdir 必须是 `engine/`，导入用 `from common import ...`。
- 两模块通过 Redis Pub/Sub 通信（设计阶段，尚未实现）。
- 数据库：TimescaleDB（Docker Compose 启动，端口 5432）。配置在根 `env.yaml`。

## 命令

```bash
# 基础设施
docker compose up -d                              # 启动 TimescaleDB + Adminer(:8080)

# data/ (TS) — 必须先 cd data
cd data && bun install                            # 安装依赖
bun run data/run/exchange.ts --concurrency 2      # 拉取历史 K 线
bun run data/run/build_aggregates_sql.ts           # 连续聚合刷新 (dry-run)
bun run data/run/build_aggregates_sql.ts --execute # 实际执行聚合刷新
bun run lint                                      # eslint
bun run format                                    # prettier
bun run build                                     # tsc 类型检查
```

## 架构

```
data/                          engine/
  exchanges/rest.ts   Binance    common/base.py      策略基类
  types/base.ts       类型定义    common/models.py    Pydantic 数据模型
  types/kline.ts      K线类型     common/logger.py    日志
  entities/           TypeORM    backtest/           回测引擎
  run/exchange.ts     拉取入口    indicators/        技术指标
  run/build_aggregates_sql.ts    example/           策略示例+回测脚本
```

- **K 线复合主键**：`[exchange, symbol, interval, time]`，TimescaleDB 超表按 `time` 分区。
- **`synchronize: false`**：TypeORM 不自动 sync schema，改实体需手动迁移。
- **`@timescaledb/typeorm` 是 v0.0.1 实验版**，连续聚合用原生 SQL 视图（`klines_5m` / `klines_15m` 等）。
- TS 侧价格字段为 `string`（精度），Python 侧 Pydantic `field_validator` 转 float。
- `KLINE_INTERVAL_MS` 定义在 `data/exchanges/rest.ts` 和 `data/types/kline.ts` 两处，新增周期需同步。

## 约定

- **中文优先**：所有回答和推理用中文；代码、标识符、文件名、技术术语保持原文。
- **运行时是 Bun，不是 Node.js**：TS 执行用 `bun run <file>`，禁止 `node`/`npm`/`npx`。
- **workdir 严格分离**：TS 命令在 `data/`，Python 命令在 `engine/`。`package.json` 在 `data/` 中。
- **先确认再动手**：涉及多文件或架构决策时先出方案等用户点头。不做未要求的改动。
- **一次改一处**：逐步 edit_file，不批量 multi_edit。改完让用户看到再继续。
- **拒绝时先问原因**：操作被 declined 不要立即换方式重试。
- **配置单一源**：`env.yaml` 是 TS 和 Python 共享的唯一配置，含 API Key，禁止硬编码密钥。
- **Python 虚拟环境**：`engine/.venv/`，未安装依赖（pydantic 等）需先 `pip install`。

## 现状

- ✅ TS 数据模块：配置加载、TypeORM 实体、Binance REST K 线拉取+UPSERT、连续聚合刷新。
- ❌ 未实现：WebSocket 行情、K 线合成管道、Redis 发布、策略管理器、信号总线、回测引擎、参数优化器、风控、交易执行、API 网关。
- ❌ 无测试、无 CI。
- `data/run/main.ts` 不存在，`dev`/`start` 脚本指向未创建文件。

## 注意事项

- `env.yaml` 含明文密钥且被 git 追踪，不可提交到公开仓库。
- 数据库当前指向远程 `10.0.0.7`，本地开发改 `env.yaml` 中 host 为 `localhost`。
- `db/pgsql/` 是 Docker volume 数据目录，已在 `.gitignore`。