# X-Trader

**Repository Path**: ChaosDay/x-trader

## Basic Information

- **Project Name**: X-Trader
- **Description**: X-Trader 是一个基于C++ 的，适应全市场全品种交易的跨平台的极简量化交易框架，X-Trader 支持用户使用C++ 构建各种类型的日内量化交易策略, 并提供包含实时数据-开发调试-模拟交易-实盘交易-运行监控-风险管理的一站式解决方案。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 11
- **Created**: 2026-05-14
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# X-Trader

从零自研的量化交易系统（C++ / CTP），目标最终**实盘交易国内期货与期权**。仓库沿用旧名，历史上曾基于开源 X-Trader 改造，现 legacy 已全部移除（完整快照见 tag `v0.7.0-pre-cleanup`），仅作参考资料。

> **当前状态（2026-09）**：`src/lab` 试验田完成前四个里程碑，全部在 SimNow 模拟盘验证：
> - `lab` 环境冒烟（构建/日志/CTP/.so 自检）
> - `lab_md` 接通行情，打印 tick
> - `lab_login` 交易登录链走通（认证→登录→结算确认→查合约）
> - `lab_order` 行情+限价单+撤单 闭环
>
> 开发现状、问题清单、路线图以 **[开发备忘录](document/devRecords/C_aiDevDocs/C_备忘录A_从零开始开发量化交易系统.md)** 为唯一权威入口。

---

## 快速开始

```bash
# 0. 首次运行前：复制配置模板并填入自己的 SimNow 账号
#    （真实 *.ini 已被 .gitignore 排除，永远不会推送到远程仓库）
cp ini/simnow/0_skMimic_7x24.ini.example ini/simnow/0_skMimic_7x24.ini
#    然后编辑新文件，替换 <你的SimNow账号> / <你的SimNow密码>

# 1. 配置 + 编译（Debug，产物在 build/debug/bin/）
cmake --preset debug && cmake --build --preset debug -j

# 2. 环境冒烟（不联网，应打印 CTP 行情/交易 API 版本号：v6.7.2）
./build/debug/bin/lab

# 3. 连 SimNow 的三个程序（必须在仓库根目录运行，ini 是相对路径）
./build/debug/bin/lab_md            # 订阅 ini [lab].contracts 合约，打印 tick
./build/debug/bin/lab_login         # 交易登录链 + 合约表
./build/debug/bin/lab_order [合约]   # tick 触发限价买开 1 手 → 3 秒后撤单
```

VS Code：`Ctrl+Shift+B` 编译；任务列表可运行四个程序；`F5` 调试 lab_order / lab_md。

### 前置条件

| 工具 | 版本要求 | 实测环境 |
|------|---------|---------|
| CMake | ≥ 3.25（FetchContent SYSTEM） | 3.28.3 |
| GCC/G++ | ≥ 11 | 13.3.0 |
| SimNow 账号 | https://www.simnow.com.cn（免费注册） | 复制 ini/simnow/ 模板填入（真实配置不入库） |
| 网络 | 首次配置需访问 gitee（拉 spdlog） | 可切官方/本地，见灾备 |

---

## 目录结构

```
X-Trader/
├── CMakeLists.txt        # 唯一构建入口：全局设置 / spdlog / CTP / 警告 / 工具函数
├── CMakePresets.json     # debug / release 预设（build/debug、build/release 分目录）
├── api/ctp/v6.7.2/       # CTP 官方 SDK（头 + .so/.dll）—— 唯一 vendor 依赖，严禁修改
├── ini/simnow/           # 连接配置：仅 *.ini.example 模板入库，真实 *.ini 本地保存（已 gitignore）
├── yard/                 # 试验场（ADR-005/006）：tmp 临时区 / log 学习日志 / scripts 脚本 / flow CTP会话流
├── document/             # 文档（ABCZ 分级；备忘录在 devRecords/C_aiDevDocs/）
├── .vscode/              # tasks / launch / settings
└── src/
    ├── CMakeLists.txt    # 模块调度器（当前只挂 lab，新模块在此追加）
    └── lab/              # ★ 全部自研代码
        ├── core/         #   类型宇宙 + SPSC 无锁事件通道
        ├── utils/        #   INIReader 等通用工具
        ├── gateway/      #   CTP 行情/交易网关（my_md / my_td）
        └── apps/         #   可执行入口（每个里程碑一个）
```

---

## 架构与数据流（现状）

```
ini 配置 ──▶ my_md / my_td（gateway，各连各的 SimNow 前置）
                 │ CTP SDK 内部线程 = 生产者：只做"报文→本地结构体翻译 + 入队"
                 ▼
     SPSC 无锁队列（core/ringbuffer.hpp）
                 │ 主线程 = 消费者：process_event() 取事件 → bind_callback 的 lambda
                 ▼
     apps/*.cpp 主循环（状态机 + 事件消费）
```

铁律：CTP 回调线程严禁业务逻辑与阻塞（会断线丢包）；业务逻辑只活在主线程。

---

## 构建系统速览

| 主题 | 说明 |
|------|------|
| 构建目录 | debug 与 release 分目录（`build/debug`、`build/release`），互不覆盖 |
| spdlog | FetchContent 拉取 v1.14.1（gitee 镜像，`-DXTRADER_SPDLOG_REPOSITORY` 可切）；`SYSTEM` 包含，警告不刷屏 |
| CTP | 预编译 `.so`/`.dll` 以 `ctp::md` / `ctp::trader` IMPORTED 目标接入；头文件路径只暴露给链接它的目标 |
| 运行期自包含 | 编译后 CTP 动态库自动拷到 exe 旁 + 写入 `$ORIGIN` RUNPATH → 不需要 LD_LIBRARY_PATH |
| 警告 | 全项目 `-Wall -Wextra`，仅 `-Wno-unused-parameter`（CTP 回调签名所致）定点静音 |
| 编译命令数据库 | `build/<配置>/compile_commands.json`（clangd / VS Code IntelliSense 用） |

---

## 常用命令速查

| 目的 | 命令 |
|---|---|
| 配置 Debug | `cmake --preset debug` |
| 编译 Debug | `cmake --build --preset debug -j` |
| 配置+编译 Release | `cmake --preset release && cmake --build --preset release -j` |
| 运行四个程序 | 见"快速开始" |
| 彻底清理 | `rm -rf build` |
| 查某文件真实编译命令 | `cat build/debug/compile_commands.json` |

---

## 文档导航

| 文档 | 用途 |
|---|---|
| [开发备忘录（指南针）](document/devRecords/C_aiDevDocs/C_备忘录A_从零开始开发量化交易系统.md) | **当前状态 / 架构 / 决策记录 / 问题登记 / 路线图 / 陷阱速查** —— 开发必读 |
| document/devRecords/D_referenceDocs/A_guideLine.md | AI 协作开发总章程 |
| document/devRecords/D_referenceDocs/A_discussionNoticeAndcaveat.md | "暗礁图"：CTP 陷阱与已确认的工程方案 |
| document/introduce/reference/A_x-trader-简单复制粗糙版.md | CTP 从零教科书 |
| document/ 下其余 A_/B_/C_/Z_ 文档 | 按前缀分级（A 最有价值 → Z 仅考古） |

---

## 常见问题

1. **报"无法读取配置文件"**：未按"快速开始"第 0 步复制模板——`cp ini/simnow/0_skMimic_7x24.ini.example ini/simnow/0_skMimic_7x24.ini` 并填入自己的 SimNow 账号。
2. **连不上 SimNow**：7x24 测试前置（:40011/:40001）全天可连但偶有维护窗口；正式前置（:30011/:30001 等）跟随交易时段（11:30-13:30 午休无 tick）。交易时段内 SimNow 对"查合约"这类重查询常限流（表现为登录成功但查合约无回报），重查询类验证建议安排在午休或夜盘时段；`yard/scripts/linux/simnow_session.sh` 可自动判断时段并在两套前置间切换。
3. **CTP 4097 断线**：网络抖动或前置拥堵；`lab` 打印的版本号可与柜台核对（本机 API v6.7.2）。
4. **运行后 /tmp 下多出 `.hash-00000000.so` 文件**：CTP 穿透式库（`*_se.so`）运行时自解包的产物，每次运行会重新生成，可随时安全清理。
5. **运行时找不到 CTP .so**：正常不会发生（自动拷贝 + `$ORIGIN`）；应急 `LD_LIBRARY_PATH=build/debug/bin ./build/debug/bin/lab_md`。
6. **IntelliSense 红线**：先跑一次 `cmake --preset debug`；必要时手动 `cp build/debug/compile_commands.json build/`。
7. **首次配置 spdlog 拉取失败**：`cmake --preset debug -DXTRADER_SPDLOG_REPOSITORY=https://github.com/gabime/spdlog.git`，或 `-DFETCHCONTENT_SOURCE_DIR_SPDLOG=/path/to/spdlog` 指向本地源码。
8. **Clock skew 警告**：WSL 挂载盘（/mnt/*）时间戳精度问题，无害；介意可把仓库迁到 WSL 原生文件系统（编译 I/O 也会快数倍）。

---

## 灾备手册（改错了怎么办）

**关键锚点**：

| tag | 含义 |
|---|---|
| `v0.7.0-pre-cleanup` | 大扫除前完整快照（含全部 legacy 源码、旧 ini、双轨制 CMake） |
| `v0.8.0-clean-restart` | 删除 legacy 后的从零新起点（当前基线） |

| 场景 | 恢复命令 |
|---|---|
| 查旧实现某文件 | `git show v0.7.0-pre-cleanup:src/trade-core/trader/ctp_trader.cpp` |
| 恢复某文件到旧版 | `git checkout v0.7.0-pre-cleanup -- <路径>` |
| 回到新起点 | `git reset --hard v0.8.0-clean-restart`（⚠️ 丢弃全部未提交改动） |
| 构建坏了 | `rm -rf build && cmake --preset debug && cmake --build --preset debug -j` |

---

## 维护约定

1. **代码归属**：自研代码一律进 `src/lab/`（core=类型/队列，utils=工具，gateway=CTP 接入，apps=入口）；模块长大后升级为 `src/` 平级模块并在 `src/CMakeLists.txt` 挂载。
2. **文档纪律**：开发现状/决策/问题以备忘录为准，每次开发会话按其 §0 协议更新。
3. **提交纪律**：改任何 CMakeLists 后完整重编译 + `lab` 冒烟通过再提交；提交信息 `类型: 摘要`。
4. **双远程同步**：master 与 tag 必须同时推送 origin（gitee）与 backup（gitcode）。

---

## License

Apache-2.0