# AITrading 基础设施 新增

本项目提供一个可直接在 Docker 中运行的量化交易基础设施，包含：

- Go 实时行情采集服务（Binance WebSocket K 线 + Redis Publisher 接口）
- Python 本地 K 线动态展示工具（pandas + mplfinance）
- Backtrader 回测框架（支持 Strategy Class 快速接入）
- Go 与 Python 之间统一 JSON 数据交换协议

## 目录结构

```text
.
├── docker-compose.yml
├── go-service
│   ├── Dockerfile
│   ├── go.mod
│   └── main.go
├── python-app
│   ├── Dockerfile
│   ├── requirements.txt
│   └── app
│       ├── data_protocol.py
│       ├── kline_viewer.py
│       ├── backtest_runner.py
│       ├── strategies
│       │   ├── __init__.py
│       │   └── sma_cross.py
│       └── sample_data
│           └── klines.jsonl
└── shared
    └── protocol.md
```

## 快速启动（Docker）

默认已使用国内 Docker Hub 镜像前缀（`m.daocloud.io/docker.io/library`）加速基础镜像拉取。  
如需切换其它镜像代理，可先设置：

```bash
export DOCKER_MIRROR_PREFIX=m.daocloud.io/docker.io/library
```

1. 构建并启动 Redis + Go 行情服务：

```bash
docker compose up --build redis go-service
```

2. 单独运行 Python 动态 K 线展示（实时订阅 Redis）：

```bash
docker compose run --rm python-app python app/kline_viewer.py \
  --redis-host redis \
  --redis-port 6379 \
  --channel kline.stream
```

3. 运行 Backtrader 回测（可指定自定义策略类）：

```bash
docker compose run --rm python-app python app/backtest_runner.py \
  --input app/sample_data/klines.jsonl \
  --strategy strategies.sma_cross.SmaCrossStrategy \
  --strategy-param fast=5 \
  --strategy-param slow=13
```

4. 股票速查入口（输入代码/名称）：

```bash
./start.sh local quote 600519
./start.sh local quote 贵州茅台
```

5. 启动简单前端页面（信息 + 曲线 + 买卖点）：

```bash
./start.sh local web
```

打开浏览器访问：`http://localhost:8000`

## 多通道数据接入（解耦）

当前已将上层业务与下游数据源解耦，上层统一走 `market` 服务层：

- `MARKET_CHANNEL=cn` + `MARKET_PROVIDER=akshare`（默认）
- `MARKET_CHANNEL=cn` + `MARKET_PROVIDER=cmesdata`（需 `CMES_TOKEN`）
- `MARKET_CHANNEL=cn|hk|us` + `MARKET_PROVIDER=futu`（需本地运行 Futu OpenD）

示例：

```bash
export MARKET_CHANNEL=cn
export MARKET_PROVIDER=akshare
# 或使用 cmesdata
# export MARKET_PROVIDER=cmesdata
# export CMES_TOKEN=你的token
# 或使用 futu（需先启动 OpenD）
# export MARKET_PROVIDER=futu
# export FUTU_HOST=127.0.0.1
# export FUTU_PORT=11111
# export FUTU_MARKET=cn   # 可选: cn/hk/us，默认跟随 MARKET_CHANNEL
# export FUTU_IS_ENCRYPT=0 # 可选: 1/0
```

说明：

- `web_app.py` 与 `stock_lookup.py` 不再直接依赖具体 SDK
- 新增市场（如 `us` / `hk`）时，只需新增 Provider 并在 `market/factory.py` 注册
- `futu` Provider 已接入：支持按代码/名称检索股票与日 K 线读取（通过 OpenD）

## Go 服务说明

- 默认订阅：`btcusdt` `1m` K 线
- 会将标准 JSON K 线数据打印到 stdout
- 预留 `RedisPublisher` 接口，默认实现为 `NoopPublisher`
- 若配置 Redis，将自动切换到 `RedisChannelPublisher`

可用环境变量：

- `BINANCE_SYMBOL`（默认 `btcusdt`）
- `BINANCE_INTERVAL`（默认 `1m`）
- `REDIS_ADDR`（例如 `redis:6379`）
- `REDIS_PASSWORD`（可选）
- `REDIS_DB`（默认 `0`）
- `REDIS_CHANNEL`（默认 `kline.stream`）

## Python 回测快速接入策略

你可以新增一个策略类并通过完整路径接入：

- 文件示例：`python-app/app/strategies/my_strategy.py`
- 类示例：`class MyStrategy(bt.Strategy): ...`
- 启动参数：`--strategy strategies.my_strategy.MyStrategy`
- 参数注入：`--strategy-param key=value`（可重复传入）
- 回测简报自动输出：`Final Value`、`Max Drawdown (%)`、`Sharpe Ratio`

## 协议定义

统一 JSON 格式位于 `shared/protocol.md`，Go 与 Python 都使用同一字段语义与时间戳单位（毫秒）。