Files

T

yuqei 31ece2e99a Initialize AI Exchange closed-loop trading system repository.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-24 13:39:01 +08:00

16 KiB

Raw Blame History

AI ICT Codebase Skeleton Spec v1

1. 文档目标

本文档用于把 AI ICT 项目第一阶段的总体设计进一步落到“代码骨架”粒度，明确：

目录结构
模块职责
配置文件分工
服务边界
运行入口
第一轮实现顺序

目标不是一次把全部业务写完，而是先把后续开发要长期承载的工程骨架固定下来，确保数据库、规则引擎、信号、执行、回测和 AI 报告都能在同一套结构下持续推进。

2. 设计原则

代码骨架应遵循以下原则：

先支撑基础数据与基础规则，再支撑信号与执行
规则判定与 AI 解释分层，不混在一个模块里
数据入库、规则计算、信号生成、执行管理职责分离
所有核心输出都应能回写 PostgreSQL
第一阶段优先单体代码仓库，模块清晰即可，不急于微服务拆分

因此，第一版更适合采用：

单仓库
单进程多入口
共享 config / db / models / services / rules
后续再按实际负载拆服务

3. 推荐目录结构

建议第一版代码仓库采用以下结构：

ai-ict/
  src/
    app/
    config/
    db/
      migrations/
      seeds/
      repositories/
    domain/
      market/
      session/
      structure/
      signal/
      execution/
      backtest/
      report/
    services/
      market-data/
      rule-engine/
      signal/
      execution/
      report/
      backtest/
    rules/
      swings/
      ranges/
      liquidity/
      sweep/
      displacement/
      structure/
      fvg/
      bias/
    jobs/
    api/
    runtime/
    utils/
    types/
  scripts/
  tests/
    unit/
    integration/
    fixtures/
  docs/
  .env.example
  package.json
  tsconfig.json
  README.md

说明：

src/domain/ 放领域对象与核心数据结构，不放外部 API 细节
src/services/ 放跨模块编排逻辑
src/rules/ 放纯规则判定逻辑
src/db/ 放 migration、seed、repository 和数据库接入
src/runtime/ 放各类启动入口
src/jobs/ 放定时任务、重算任务、数据同步任务
src/api/ 放 HTTP 接口或内部管理接口

4. 目录职责拆分

4.1 `src/app/`

用于放应用装配层。

建议内容：

容器初始化
配置加载
日志初始化
数据库初始化
服务注册
runtime 共享启动辅助

这个目录不负责业务规则本身，只负责把系统拼起来。

4.2 `src/config/`

用于集中管理配置。

建议拆分：

src/config/
  env.ts
  database.ts
  market.ts
  sessions.ts
  timeframes.ts
  risk.ts
  models.ts

职责建议：

env.ts
- 读取环境变量
- 做最小边界校验
database.ts
- PostgreSQL 连接参数
- pool 配置
market.ts
- 交易所、品种、symbol 映射
sessions.ts
- ASIA / LONDON / NY_AM / NY_LUNCH / NY_PM 定义
timeframes.ts
- bias/setup/trigger 周期配置
risk.ts
- 单笔风险、日亏损、新闻窗口、会话限制
models.ts
- 各策略模型编码，例如 SWEEP_MSS_FVG

要求：

配置模块只负责提供配置值
不在配置模块里写业务查询或数据库逻辑

4.3 `src/db/`

用于统一管理数据库接入。

建议结构：

src/db/
  client.ts
  migrations/
  seeds/
  repositories/
    venues-repository.ts
    instruments-repository.ts
    candles-repository.ts
    market-sessions-repository.ts
    swings-repository.ts
    dealing-ranges-repository.ts
    liquidity-pools-repository.ts
    sweep-events-repository.ts
    displacement-events-repository.ts
    structure-events-repository.ts
    fvg-zones-repository.ts
    bias-snapshots-repository.ts
    trade-signals-repository.ts
    trade-executions-repository.ts
    backtest-runs-repository.ts
    backtest-results-repository.ts

职责：

client.ts 负责 PostgreSQL 连接与事务入口
migrations/ 放正式 migration 文件
seeds/ 放初始种子数据
repositories/ 只负责表读写，不负责业务判断

建议约束：

repository 不直接做规则识别
复杂业务编排交给 services/
规则计算交给 rules/

4.4 `src/domain/`

用于放领域模型与跨模块共享结构。

建议子目录：

src/domain/
  market/
  session/
  structure/
  signal/
  execution/
  backtest/
  report/

可承载内容：

Candle
SessionWindow
Swing
DealingRange
LiquidityPool
SweepEvent
DisplacementEvent
StructureEvent
FvgZone
BiasSnapshot
TradeSignal
TradeExecution
BacktestRun
BacktestResult

要求：

领域层表达“数据是什么”
不表达“从哪个 API 拉来的”
不耦合具体数据库客户端

4.5 `src/rules/`

这是第一阶段最关键的纯规则层。

建议结构：

src/rules/
  swings/
    detect-swings.ts
  ranges/
    detect-dealing-range.ts
    classify-price-location.ts
  liquidity/
    detect-liquidity-pools.ts
  sweep/
    detect-sweeps.ts
  displacement/
    detect-displacement.ts
  structure/
    detect-msb.ts
    detect-mss.ts
  fvg/
    detect-fvg.ts
    update-fvg-status.ts
  bias/
    build-bias-snapshot.ts

职责：

输入标准化市场数据或上游结构对象
输出结构化判定结果
尽量保持纯函数、可回测、可重复执行

设计要求：

rules/ 不直接调用交易所 API
rules/ 不直接控制下单
rules/ 可以被实时运行和回测共用

这层是后续“规则口径与回测口径一致”的核心。

4.6 `src/services/`

服务层负责把 repository、rules、外部数据源串起来。

建议结构：

src/services/
  market-data/
    ingest-okx-candles.ts
    sync-instruments.ts
    generate-market-sessions.ts
  rule-engine/
    rebuild-market-structure.ts
    run-swing-pipeline.ts
    run-liquidity-pipeline.ts
    run-structure-pipeline.ts
  signal/
    build-bias.ts
    generate-trade-signals.ts
    update-signal-state.ts
  execution/
    run-risk-check.ts
    create-paper-order.ts
    create-semi-auto-order.ts
    manage-open-position.ts
  report/
    build-pre-market-report.ts
    build-intraday-report.ts
    build-post-trade-review.ts
  backtest/
    run-backtest.ts
    summarize-backtest.ts

服务层职责是：

组织调用顺序
控制事务边界
调用 repository 落库
调用 rules 计算
处理任务入口与失败恢复

要求：

service 可以依赖多个 repository 和 rule 模块
service 不应把 SQL 写得到处都是
service 不应承载底层公共工具函数

4.7 `src/jobs/`

用于放异步任务与定时任务入口。

建议首批任务：

sync-okx-candles-job.ts
generate-sessions-job.ts
rebuild-swings-job.ts
rebuild-liquidity-job.ts
generate-signals-job.ts
run-backtest-job.ts

职责：

作为 cron 或手动触发入口
调用 services/ 完成任务
记录任务执行日志

4.8 `src/api/`

第一阶段即使不做完整前端，也建议预留轻量 API 层。

建议提供：

health check
recent candles query
current sessions query
current structure query
candidate signals query
backtest summary query

作用：

供后续 Web 控制台使用
供人工验证与调试使用
避免所有数据检查都依赖直接查库

4.9 `src/runtime/`

用于放程序入口。

建议结构：

src/runtime/
  worker.ts
  api-server.ts
  market-data-runner.ts
  rule-engine-runner.ts
  signal-runner.ts
  backtest-runner.ts

每个入口只负责：

启动应用上下文
选择要跑的 service 或 job
处理进程级日志与退出码

不建议把核心业务直接堆在入口文件里。

4.10 `src/utils/`

只放通用工具。

例如：

时间处理
数值精度处理
时区转换
分页工具
幂等键生成

要求：

不把业务规则偷偷塞进 utils
与 ICT 规则直接相关的逻辑应留在 rules/

4.11 `src/types/`

用于放跨层共享类型。

例如：

DTO
job payload
service input/output
API response shape

如果某类型已经明显属于领域对象，应优先放回 domain/，不要全堆在 types/。

5. 服务边界

结合总体设计，第一阶段建议保留 5 条主要服务边界。

5.1 market-data-service

职责：

拉取 OKX / LMAX 行情
规范化 candles
维护 instruments 元数据
生成 market sessions
持续写入 PostgreSQL

核心输入：

交易所 API
品种配置
session 配置

核心输出：

venues
instruments
candles
market_sessions

5.2 rule-engine-service

职责：

基于 candles 和 sessions 识别结构
生成 swings、ranges、liquidity、sweep、displacement、MSS、FVG
维护结构对象的更新与重算

核心输入：

candles
market_sessions
参数配置

核心输出：

swings
dealing_ranges
liquidity_pools
sweep_events
displacement_events
structure_events
fvg_zones

5.3 signal-service

职责：

汇总 higher timeframe context
生成 bias snapshot
把结构链路组合成 trade signal
维护 signal 状态流转

核心输出：

bias_snapshots
trade_signals

5.4 execution-service

职责：

风控检查
模拟盘执行
半自动下单编排
持仓与订单状态更新

核心输出：

trade_executions
风控结论
审计记录

5.5 report-service

职责：

盘前计划
盘中解释
盘后复盘
回测摘要
为 LLM 准备结构化输入

核心要求：

只解释规则层和执行层的结构化结果
不绕过规则直接生成裸建议

6. 配置文件与环境变量建议

第一阶段建议至少具备以下配置文件：

6.1 `.env.example`

建议包含：

DATABASE_URL=
OKX_API_KEY=
OKX_API_SECRET=
OKX_PASSPHRASE=
LMAX_BASE_URL=
APP_TIMEZONE=UTC
DEFAULT_SESSION_TIMEZONE=America/New_York
LOG_LEVEL=info

说明：

第一阶段至少把数据库和 OKX 接入所需变量明确下来
未实际接入的供应商变量也可以预留，但不要提前绑定太多无用项

6.2 `package.json`

建议承载：

dev 启动命令
migration 命令
seed 命令
ingest 命令
rule rebuild 命令
backtest 命令

6.3 `tsconfig.json`

建议固定：

路径别名
strict 模式
source map
测试目录纳入方式

6.4 日志与格式配置

若使用：

ESLint / Biome
Prettier
Vitest / Jest

应在项目启动初期固定，避免中期频繁改工程规范。

7. 数据库层与代码层映射建议

第一阶段建议先把数据库对象与代码模块稳定映射：

数据表	repository	主要服务	主要规则
`venues`	`venues-repository.ts`	`sync-instruments.ts`	-
`instruments`	`instruments-repository.ts`	`sync-instruments.ts`	-
`candles`	`candles-repository.ts`	`ingest-okx-candles.ts`	-
`market_sessions`	`market-sessions-repository.ts`	`generate-market-sessions.ts`	-
`swings`	`swings-repository.ts`	`run-swing-pipeline.ts`	`detect-swings.ts`
`dealing_ranges`	`dealing-ranges-repository.ts`	`run-structure-pipeline.ts`	`detect-dealing-range.ts`
`liquidity_pools`	`liquidity-pools-repository.ts`	`run-liquidity-pipeline.ts`	`detect-liquidity-pools.ts`
`displacement_events`	`displacement-events-repository.ts`	`run-structure-pipeline.ts`	`detect-displacement.ts`
`structure_events`	`structure-events-repository.ts`	`run-structure-pipeline.ts`	`detect-msb.ts` / `detect-mss.ts`
`fvg_zones`	`fvg-zones-repository.ts`	`run-structure-pipeline.ts`	`detect-fvg.ts`
`bias_snapshots`	`bias-snapshots-repository.ts`	`build-bias.ts`	`build-bias-snapshot.ts`
`trade_signals`	`trade-signals-repository.ts`	`generate-trade-signals.ts`	组合规则
`trade_executions`	`trade-executions-repository.ts`	`create-paper-order.ts`	风控规则
`backtest_runs`	`backtest-runs-repository.ts`	`run-backtest.ts`	-
`backtest_results`	`backtest-results-repository.ts`	`run-backtest.ts`	回放逻辑

这样可以避免后续代码增长后职责混乱。

8. 运行入口建议

第一阶段建议至少提供以下运行入口。

8.1 API server

用途：

健康检查
查询当前市场结构
查询候选信号
查询回测摘要

建议入口：

src/runtime/api-server.ts

8.2 market data runner

用途：

定时拉取 OKX candles
同步 instruments
驱动 session 生成

建议入口：

src/runtime/market-data-runner.ts

8.3 rule engine runner

用途：

重算 swings
重算 dealing range
重算 liquidity
重算 displacement / MSS / FVG

建议入口：

src/runtime/rule-engine-runner.ts

8.4 signal runner

用途：

生成 bias snapshot
生成 trade signal
更新 signal 状态

建议入口：

src/runtime/signal-runner.ts

8.5 backtest runner

用途：

执行指定模型、品种、周期范围的回测
输出 backtest summary

建议入口：

src/runtime/backtest-runner.ts

9. 第一轮实现顺序

结合路线图与总体设计，建议第一轮按以下顺序实现。

9.1 Step 1：项目骨架初始化

先完成：

src/config/
src/db/client.ts
src/runtime/
src/services/market-data/ 基础空壳
.env.example
日志模块

完成标准：

项目可启动
配置可加载
PostgreSQL 可连接

9.2 Step 2：基础 migration 落地

先建：

venues
instruments
candles
market_sessions
swings
dealing_ranges
liquidity_pools

说明：

这是第一阶段共享底座
后续所有规则与信号都依赖这些表

9.3 Step 3：OKX 数据接入

优先接通：

完成内容：

candles 拉取
标准化
入库
去重

9.4 Step 4：session generator

完成内容：

ASIA / LONDON / NY_AM / NY_LUNCH / NY_PM 切分
session high / low / midpoint 生成
状态更新

9.5 Step 5：基础规则层

优先实现：

swings
dealing_ranges
liquidity_pools

原因：

它们是 sweep / MSS / FVG 的共同前提

9.6 Step 6：核心信号链

按链路推进：

sweep
displacement
MSB / MSS
FVG
bias snapshot
trade signal

主链路保持为：

Sweep -> MSS -> FVG Retrace -> IRL/ERL

9.7 Step 7：回测与执行

在信号链稳定后，再进入：

backtest
paper trading
semi-auto execution
report generation

不建议跳过回测直接做执行自动化。

10. 第一阶段最小启动文件清单

若现在要直接开始建项目，建议先落以下最小文件：

src/config/env.ts
src/config/database.ts
src/config/sessions.ts
src/db/client.ts
src/db/migrations/001_create_venues.sql
src/db/migrations/002_create_instruments.sql
src/db/migrations/003_create_candles.sql
src/db/migrations/004_create_candles_partitions_and_indexes.sql
src/db/migrations/005_create_market_sessions.sql
src/services/market-data/ingest-okx-candles.ts
src/services/market-data/generate-market-sessions.ts
src/runtime/market-data-runner.ts
src/runtime/api-server.ts
.env.example

若以上文件稳定，再继续进入 swing / dealing range 实现。

11. 验证与关闭标准

根据执行检查清单，代码骨架文档完成至少应满足：

文档已写入本地 .md
路径存在
已读取前部内容检查格式正常
标题、章节结构、核心内容完整

后续代码真正开始落地时，每个骨架模块也应满足：

有目标文件
有最小启动或导入验证
与当前阶段目标直接相关

12. 当前结论

AI ICT 项目第一阶段最合适的代码组织方式，不是上来拆成很多独立服务，而是：

先建立单仓库、清晰分层、可多入口运行的工程骨架，再按 数据 -> 基础规则 -> 核心信号 -> 回测 -> 执行 -> 报告 顺序推进。

只要骨架按本文档固定下来，后续 migration、OKX 接入、session generator、swings、dealing range、liquidity、MSS、FVG 和 signal 都可以在同一套结构下稳定扩展。

16 KiB Raw Blame History Unescape Escape

AI ICT Codebase Skeleton Spec v1

1. 文档目标

2. 设计原则

3. 推荐目录结构

4. 目录职责拆分

4.1 src/app/

4.2 src/config/

4.3 src/db/

4.4 src/domain/

4.5 src/rules/

4.6 src/services/

4.7 src/jobs/

4.8 src/api/

4.9 src/runtime/

4.10 src/utils/

4.11 src/types/

5. 服务边界

5.1 market-data-service

5.2 rule-engine-service

5.3 signal-service

5.4 execution-service

5.5 report-service

6. 配置文件与环境变量建议

6.1 .env.example

6.2 package.json

6.3 tsconfig.json

6.4 日志与格式配置

7. 数据库层与代码层映射建议

8. 运行入口建议

8.1 API server

8.2 market data runner

8.3 rule engine runner

8.4 signal runner

8.5 backtest runner

9. 第一轮实现顺序

9.1 Step 1：项目骨架初始化

9.2 Step 2：基础 migration 落地

9.3 Step 3：OKX 数据接入

9.4 Step 4：session generator

9.5 Step 5：基础规则层

9.6 Step 6：核心信号链

9.7 Step 7：回测与执行

10. 第一阶段最小启动文件清单

11. 验证与关闭标准

12. 当前结论

16 KiB

Raw Blame History

4.1 `src/app/`

4.2 `src/config/`

4.3 `src/db/`

4.4 `src/domain/`

4.5 `src/rules/`

4.6 `src/services/`

4.7 `src/jobs/`

4.8 `src/api/`

4.9 `src/runtime/`

4.10 `src/utils/`

4.11 `src/types/`

6.1 `.env.example`

6.2 `package.json`

6.3 `tsconfig.json`