# AI ICT Codebase Skeleton Spec v1

## 1. 文档目标

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

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

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

---

## 2. 设计原则

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

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

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

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

---

## 3. 推荐目录结构

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

```text
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/`

用于集中管理配置。

建议拆分：

```text
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/`

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

建议结构：

```text
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/`

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

建议子目录：

```text
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/`

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

建议结构：

```text
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、外部数据源串起来。

建议结构：

```text
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/`

用于放程序入口。

建议结构：

```text
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`

建议包含：

```text
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 数据接入

优先接通：

- BTC
- ETH

完成内容：

- candles 拉取
- 标准化
- 入库
- 去重

---

## 9.4 Step 4：session generator

完成内容：

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

---

## 9.5 Step 5：基础规则层

优先实现：

1. swings
2. dealing_ranges
3. 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. 第一阶段最小启动文件清单

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

```text
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 都可以在同一套结构下稳定扩展。