From 31ece2e99a2e990815046491997fb0b49dba1064 Mon Sep 17 00:00:00 2001
From: yuqei <cyuqei@gmail.com>
Date: Fri, 24 Apr 2026 13:39:01 +0800
Subject: [PATCH] Initialize AI Exchange closed-loop trading system repository.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .dockerignore                                 |   12 +
 .env.example                                  |    6 +
 .gitignore                                    |   23 +
 Dockerfile                                    |   28 +
 ICT Concepts.md                               | 2477 +++++++++++++++++
 ...ts [TFO]_,_ICT Killzones & Pivots [TFO].md | 1673 +++++++++++
 README.md                                     |   51 +
 docker-compose.yml                            |   11 +
 docs/AI_ICT_Codebase_Skeleton_Spec_v1.md      |  872 ++++++
 docs/AI_ICT_Dealing_Range_Spec_v1.md          |  584 ++++
 docs/AI_ICT_Dealing_Range_规格书_v1.md        |  410 +++
 docs/AI_ICT_Displacement_规格书_v1.md         |  494 ++++
 docs/AI_ICT_FVG_规格书_v1.md                  |  466 ++++
 docs/AI_ICT_Liquidity_Pool_规格书_v1.md       |  429 +++
 docs/AI_ICT_MSS_判定规格书_v1.md              |  472 ++++
 docs/AI_ICT_MVP_规则规格书_v1.md              |  761 +++++
 docs/AI_ICT_Migration_拆分计划_v1.md          |  493 ++++
 docs/AI_ICT_OKX_数据接入规格书_v1.md          |  433 +++
 ..._ICT_PostgreSQL_Migration_SQL_Drafts_v1.md |  549 ++++
 ..._ICT_PostgreSQL_Migration_Split_Plan_v1.md |  711 +++++
 docs/AI_ICT_PostgreSQL_Schema_v1.md           |  806 ++++++
 docs/AI_ICT_Session_Generator_Spec_v1.md      |  518 ++++
 docs/AI_ICT_Session_生成器规格书_v1.md        |  421 +++
 docs/AI_ICT_Sweep_Identification_Spec_v1.md   |  590 ++++
 docs/AI_ICT_Sweep_识别规格书_v1.md            |  479 ++++
 docs/AI_ICT_Swing_Identification_Spec_v1.md   |  491 ++++
 docs/AI_ICT_Swing_识别规格书_v1.md            |  494 ++++
 docs/AI_ICT_主线开发检查点_v1.md              |  455 +++
 docs/AI_ICT_主线进度摘要_v1.md                |   66 +
 docs/AI_ICT_开发路线图_v1.md                  |  592 ++++
 docs/AI_ICT_总体设计文档_v1.md                |  516 ++++
 docs/AI_ICT_执行检查清单_v1.md                |  327 +++
 docs/AI_ICT_数据库_Migration_SQL_草案_v1.md   |  454 +++
 docs/AI_ICT_文档索引与命名规范_v1.md          |  291 ++
 ...AI_ICT_第一批正式_Migration_文件草案_v1.md |  489 ++++
 ...AI_ICT_第二批正式_Migration_文件草案_v1.md |  462 +++
 docs/AI_ICT_重复文档清理计划_v1.md            |  217 ++
 docs/AI_ICT_项目代码骨架规范_v1.md            |  492 ++++
 docs/AI_ICT_项目启动清单_v1.md                |  250 ++
 docs/AI_协作自动化工作规程_v1.md              |  338 +++
 docs/AI_自动化协作迁移清单_v1.md              |  239 ++
 docs/CLAUDE_template_autonomy_first.md        |  225 ++
 ...automation_workflow_migration_checklist.md |  182 ++
 docs/标准_CLAUDE_md_模板_v1.md                |  166 ++
 migrations/.gitkeep                           |    1 +
 migrations/001_create_venues.sql              |    9 +
 migrations/002_create_instruments.sql         |   20 +
 migrations/003_create_candles.sql             |   16 +
 ..._create_candles_partitions_and_indexes.sql |   13 +
 migrations/005_create_market_sessions.sql     |   23 +
 migrations/006_create_swings.sql              |   23 +
 migrations/007_create_dealing_ranges.sql      |   22 +
 migrations/008_create_liquidity_pools.sql     |   21 +
 migrations/009_seed_venues.sql                |    5 +
 migrations/010_seed_instruments.sql           |   57 +
 migrations/011_create_displacement_events.sql |   20 +
 migrations/012_create_structure_events.sql    |   21 +
 migrations/013_create_fvg_zones.sql           |   22 +
 migrations/014_create_bias_snapshots.sql      |   23 +
 migrations/015_create_trade_signals.sql       |   33 +
 migrations/016_create_trade_executions.sql    |   29 +
 migrations/017_create_backtest_runs.sql       |   17 +
 migrations/018_create_backtest_results.sql    |   20 +
 migrations/019_create_sweep_events.sql        |   22 +
 pyproject.toml                                |   16 +
 scripts/apply_migrations.py                   |   36 +
 scripts/check_db.py                           |   21 +
 scripts/check_db_connection.py                |   21 +
 scripts/deploy_server.exp                     |   25 +
 scripts/deploy_with_expect.exp                |   28 +
 scripts/fix_pg_hba.exp                        |   24 +
 scripts/run_api_server.py                     |   19 +
 scripts/run_backtest.py                       |   18 +
 scripts/run_dev.py                            |   12 +
 scripts/run_displacement.py                   |   19 +
 scripts/run_execution.py                      |   26 +
 scripts/run_fvg.py                            |   19 +
 scripts/run_liquidity.py                      |   19 +
 scripts/run_migrations.py                     |   35 +
 scripts/run_mss.py                            |   19 +
 scripts/run_okx_backfill.py                   |   54 +
 scripts/run_pipeline.py                       |   18 +
 scripts/run_ranges.py                         |   19 +
 scripts/run_reports.py                        |   48 +
 scripts/run_session_generator.py              |   20 +
 scripts/run_signals.py                        |   25 +
 scripts/run_sweeps.py                         |   19 +
 scripts/run_swings.py                         |   19 +
 scripts/show_models.py                        |   23 +
 scripts/ssh_diagnose.exp                      |    9 +
 seeds/.gitkeep                                |    1 +
 src/__init__.py                               |    1 +
 src/api/__init__.py                           |   18 +
 src/api/backtest.py                           |   24 +
 src/api/candles.py                            |   19 +
 src/api/health.py                             |    9 +
 src/api/server.py                             |  108 +
 src/api/sessions.py                           |   18 +
 src/api/signals.py                            |   19 +
 src/config/__init__.py                        |    1 +
 src/config/constants.py                       |    9 +
 src/config/sessions.py                        |   17 +
 src/config/settings.py                        |   15 +
 src/db/__init__.py                            |    1 +
 src/db/base.py                                |    5 +
 src/db/config.py                              |    5 +
 src/db/engine.py                              |    6 +
 src/db/session.py                             |    6 +
 src/domain/__init__.py                        |    1 +
 src/main.py                                   |  201 ++
 src/models/__init__.py                        |   37 +
 src/models/backtest_result.py                 |   22 +
 src/models/backtest_run.py                    |   19 +
 src/models/bias_snapshot.py                   |   25 +
 src/models/candle.py                          |   22 +
 src/models/dealing_range.py                   |   23 +
 src/models/displacement_event.py              |   22 +
 src/models/fvg_zone.py                        |   23 +
 src/models/instrument.py                      |   26 +
 src/models/liquidity_pool.py                  |   22 +
 src/models/market_session.py                  |   26 +
 src/models/structure_event.py                 |   23 +
 src/models/sweep_event.py                     |   25 +
 src/models/swing.py                           |   21 +
 src/models/trade_execution.py                 |   27 +
 src/models/trade_signal.py                    |   31 +
 src/models/venue.py                           |   16 +
 src/repositories/__init__.py                  |   31 +
 src/repositories/backtest_repository.py       |  176 ++
 src/repositories/bias_repository.py           |  135 +
 src/repositories/candle_repository.py         |   81 +
 src/repositories/dealing_range_repository.py  |   95 +
 src/repositories/displacement_repository.py   |   83 +
 src/repositories/execution_repository.py      |  135 +
 src/repositories/fvg_repository.py            |  165 ++
 src/repositories/liquidity_pool_repository.py |   99 +
 src/repositories/market_session_repository.py |  103 +
 src/repositories/signal_repository.py         |  189 ++
 src/repositories/structure_repository.py      |  119 +
 src/repositories/sweep_repository.py          |  140 +
 src/repositories/swing_repository.py          |   84 +
 src/services/__init__.py                      |    1 +
 src/services/backtest/__init__.py             |   11 +
 src/services/backtest/backtest_service.py     |  303 ++
 src/services/bias/__init__.py                 |    5 +
 src/services/bias/bias_service.py             |   88 +
 src/services/displacement/__init__.py         |    5 +
 .../displacement/displacement_service.py      |   72 +
 src/services/execution/__init__.py            |   17 +
 src/services/execution/execution_service.py   |  172 ++
 src/services/fvg/__init__.py                  |    5 +
 src/services/fvg/fvg_service.py               |  182 ++
 src/services/liquidity/__init__.py            |   10 +
 .../liquidity/liquidity_pool_service.py       |  271 ++
 src/services/market_data/__init__.py          |    6 +
 src/services/market_data/normalizer.py        |   39 +
 src/services/market_data/okx_client.py        |   72 +
 src/services/ranges/__init__.py               |    5 +
 src/services/ranges/dealing_range_service.py  |   60 +
 src/services/reports/__init__.py              |   13 +
 .../reports/backtest_report_service.py        |    6 +
 .../reports/intraday_report_service.py        |   45 +
 .../reports/post_trade_review_service.py      |   50 +
 .../reports/pre_market_report_service.py      |   39 +
 src/services/sessions/__init__.py             |    5 +
 src/services/sessions/session_generator.py    |   71 +
 src/services/signals/__init__.py              |   17 +
 src/services/signals/signal_service.py        |  188 ++
 src/services/structure/__init__.py            |    5 +
 src/services/structure/mss_service.py         |  191 ++
 src/services/sweeps/__init__.py               |    5 +
 src/services/sweeps/sweep_service.py          |  109 +
 src/services/swings/__init__.py               |    5 +
 src/services/swings/swing_service.py          |   80 +
 src/utils/__init__.py                         |    1 +
 tests/__init__.py                             |    1 +
 tests/fixtures/__init__.py                    |    1 +
 tests/integration/__init__.py                 |    1 +
 tests/unit/__init__.py                        |    1 +
 tests/unit/test_api_and_main.py               |  206 ++
 tests/unit/test_api_server.py                 |   90 +
 tests/unit/test_backtest_report_service.py    |   98 +
 tests/unit/test_backtest_service.py           |  127 +
 tests/unit/test_execution_service.py          |  140 +
 tests/unit/test_fvg_service.py                |   62 +
 tests/unit/test_liquidity_pool_service.py     |  126 +
 tests/unit/test_mss_service.py                |   66 +
 tests/unit/test_report_services.py            |   61 +
 tests/unit/test_signal_service.py             |  112 +
 189 files changed, 27318 insertions(+)
 create mode 100644 .dockerignore
 create mode 100644 .env.example
 create mode 100644 .gitignore
 create mode 100644 Dockerfile
 create mode 100644 ICT Concepts.md
 create mode 100644 ICT Killzones & Pivots [TFO]_,_ICT Killzones & Pivots [TFO].md
 create mode 100644 README.md
 create mode 100644 docker-compose.yml
 create mode 100644 docs/AI_ICT_Codebase_Skeleton_Spec_v1.md
 create mode 100644 docs/AI_ICT_Dealing_Range_Spec_v1.md
 create mode 100644 docs/AI_ICT_Dealing_Range_规格书_v1.md
 create mode 100644 docs/AI_ICT_Displacement_规格书_v1.md
 create mode 100644 docs/AI_ICT_FVG_规格书_v1.md
 create mode 100644 docs/AI_ICT_Liquidity_Pool_规格书_v1.md
 create mode 100644 docs/AI_ICT_MSS_判定规格书_v1.md
 create mode 100644 docs/AI_ICT_MVP_规则规格书_v1.md
 create mode 100644 docs/AI_ICT_Migration_拆分计划_v1.md
 create mode 100644 docs/AI_ICT_OKX_数据接入规格书_v1.md
 create mode 100644 docs/AI_ICT_PostgreSQL_Migration_SQL_Drafts_v1.md
 create mode 100644 docs/AI_ICT_PostgreSQL_Migration_Split_Plan_v1.md
 create mode 100644 docs/AI_ICT_PostgreSQL_Schema_v1.md
 create mode 100644 docs/AI_ICT_Session_Generator_Spec_v1.md
 create mode 100644 docs/AI_ICT_Session_生成器规格书_v1.md
 create mode 100644 docs/AI_ICT_Sweep_Identification_Spec_v1.md
 create mode 100644 docs/AI_ICT_Sweep_识别规格书_v1.md
 create mode 100644 docs/AI_ICT_Swing_Identification_Spec_v1.md
 create mode 100644 docs/AI_ICT_Swing_识别规格书_v1.md
 create mode 100644 docs/AI_ICT_主线开发检查点_v1.md
 create mode 100644 docs/AI_ICT_主线进度摘要_v1.md
 create mode 100644 docs/AI_ICT_开发路线图_v1.md
 create mode 100644 docs/AI_ICT_总体设计文档_v1.md
 create mode 100644 docs/AI_ICT_执行检查清单_v1.md
 create mode 100644 docs/AI_ICT_数据库_Migration_SQL_草案_v1.md
 create mode 100644 docs/AI_ICT_文档索引与命名规范_v1.md
 create mode 100644 docs/AI_ICT_第一批正式_Migration_文件草案_v1.md
 create mode 100644 docs/AI_ICT_第二批正式_Migration_文件草案_v1.md
 create mode 100644 docs/AI_ICT_重复文档清理计划_v1.md
 create mode 100644 docs/AI_ICT_项目代码骨架规范_v1.md
 create mode 100644 docs/AI_ICT_项目启动清单_v1.md
 create mode 100644 docs/AI_协作自动化工作规程_v1.md
 create mode 100644 docs/AI_自动化协作迁移清单_v1.md
 create mode 100644 docs/CLAUDE_template_autonomy_first.md
 create mode 100644 docs/automation_workflow_migration_checklist.md
 create mode 100644 docs/标准_CLAUDE_md_模板_v1.md
 create mode 100644 migrations/.gitkeep
 create mode 100644 migrations/001_create_venues.sql
 create mode 100644 migrations/002_create_instruments.sql
 create mode 100644 migrations/003_create_candles.sql
 create mode 100644 migrations/004_create_candles_partitions_and_indexes.sql
 create mode 100644 migrations/005_create_market_sessions.sql
 create mode 100644 migrations/006_create_swings.sql
 create mode 100644 migrations/007_create_dealing_ranges.sql
 create mode 100644 migrations/008_create_liquidity_pools.sql
 create mode 100644 migrations/009_seed_venues.sql
 create mode 100644 migrations/010_seed_instruments.sql
 create mode 100644 migrations/011_create_displacement_events.sql
 create mode 100644 migrations/012_create_structure_events.sql
 create mode 100644 migrations/013_create_fvg_zones.sql
 create mode 100644 migrations/014_create_bias_snapshots.sql
 create mode 100644 migrations/015_create_trade_signals.sql
 create mode 100644 migrations/016_create_trade_executions.sql
 create mode 100644 migrations/017_create_backtest_runs.sql
 create mode 100644 migrations/018_create_backtest_results.sql
 create mode 100644 migrations/019_create_sweep_events.sql
 create mode 100644 pyproject.toml
 create mode 100644 scripts/apply_migrations.py
 create mode 100644 scripts/check_db.py
 create mode 100644 scripts/check_db_connection.py
 create mode 100755 scripts/deploy_server.exp
 create mode 100755 scripts/deploy_with_expect.exp
 create mode 100755 scripts/fix_pg_hba.exp
 create mode 100644 scripts/run_api_server.py
 create mode 100644 scripts/run_backtest.py
 create mode 100644 scripts/run_dev.py
 create mode 100644 scripts/run_displacement.py
 create mode 100644 scripts/run_execution.py
 create mode 100644 scripts/run_fvg.py
 create mode 100644 scripts/run_liquidity.py
 create mode 100644 scripts/run_migrations.py
 create mode 100644 scripts/run_mss.py
 create mode 100644 scripts/run_okx_backfill.py
 create mode 100644 scripts/run_pipeline.py
 create mode 100644 scripts/run_ranges.py
 create mode 100644 scripts/run_reports.py
 create mode 100644 scripts/run_session_generator.py
 create mode 100644 scripts/run_signals.py
 create mode 100644 scripts/run_sweeps.py
 create mode 100644 scripts/run_swings.py
 create mode 100644 scripts/show_models.py
 create mode 100755 scripts/ssh_diagnose.exp
 create mode 100644 seeds/.gitkeep
 create mode 100644 src/__init__.py
 create mode 100644 src/api/__init__.py
 create mode 100644 src/api/backtest.py
 create mode 100644 src/api/candles.py
 create mode 100644 src/api/health.py
 create mode 100644 src/api/server.py
 create mode 100644 src/api/sessions.py
 create mode 100644 src/api/signals.py
 create mode 100644 src/config/__init__.py
 create mode 100644 src/config/constants.py
 create mode 100644 src/config/sessions.py
 create mode 100644 src/config/settings.py
 create mode 100644 src/db/__init__.py
 create mode 100644 src/db/base.py
 create mode 100644 src/db/config.py
 create mode 100644 src/db/engine.py
 create mode 100644 src/db/session.py
 create mode 100644 src/domain/__init__.py
 create mode 100644 src/main.py
 create mode 100644 src/models/__init__.py
 create mode 100644 src/models/backtest_result.py
 create mode 100644 src/models/backtest_run.py
 create mode 100644 src/models/bias_snapshot.py
 create mode 100644 src/models/candle.py
 create mode 100644 src/models/dealing_range.py
 create mode 100644 src/models/displacement_event.py
 create mode 100644 src/models/fvg_zone.py
 create mode 100644 src/models/instrument.py
 create mode 100644 src/models/liquidity_pool.py
 create mode 100644 src/models/market_session.py
 create mode 100644 src/models/structure_event.py
 create mode 100644 src/models/sweep_event.py
 create mode 100644 src/models/swing.py
 create mode 100644 src/models/trade_execution.py
 create mode 100644 src/models/trade_signal.py
 create mode 100644 src/models/venue.py
 create mode 100644 src/repositories/__init__.py
 create mode 100644 src/repositories/backtest_repository.py
 create mode 100644 src/repositories/bias_repository.py
 create mode 100644 src/repositories/candle_repository.py
 create mode 100644 src/repositories/dealing_range_repository.py
 create mode 100644 src/repositories/displacement_repository.py
 create mode 100644 src/repositories/execution_repository.py
 create mode 100644 src/repositories/fvg_repository.py
 create mode 100644 src/repositories/liquidity_pool_repository.py
 create mode 100644 src/repositories/market_session_repository.py
 create mode 100644 src/repositories/signal_repository.py
 create mode 100644 src/repositories/structure_repository.py
 create mode 100644 src/repositories/sweep_repository.py
 create mode 100644 src/repositories/swing_repository.py
 create mode 100644 src/services/__init__.py
 create mode 100644 src/services/backtest/__init__.py
 create mode 100644 src/services/backtest/backtest_service.py
 create mode 100644 src/services/bias/__init__.py
 create mode 100644 src/services/bias/bias_service.py
 create mode 100644 src/services/displacement/__init__.py
 create mode 100644 src/services/displacement/displacement_service.py
 create mode 100644 src/services/execution/__init__.py
 create mode 100644 src/services/execution/execution_service.py
 create mode 100644 src/services/fvg/__init__.py
 create mode 100644 src/services/fvg/fvg_service.py
 create mode 100644 src/services/liquidity/__init__.py
 create mode 100644 src/services/liquidity/liquidity_pool_service.py
 create mode 100644 src/services/market_data/__init__.py
 create mode 100644 src/services/market_data/normalizer.py
 create mode 100644 src/services/market_data/okx_client.py
 create mode 100644 src/services/ranges/__init__.py
 create mode 100644 src/services/ranges/dealing_range_service.py
 create mode 100644 src/services/reports/__init__.py
 create mode 100644 src/services/reports/backtest_report_service.py
 create mode 100644 src/services/reports/intraday_report_service.py
 create mode 100644 src/services/reports/post_trade_review_service.py
 create mode 100644 src/services/reports/pre_market_report_service.py
 create mode 100644 src/services/sessions/__init__.py
 create mode 100644 src/services/sessions/session_generator.py
 create mode 100644 src/services/signals/__init__.py
 create mode 100644 src/services/signals/signal_service.py
 create mode 100644 src/services/structure/__init__.py
 create mode 100644 src/services/structure/mss_service.py
 create mode 100644 src/services/sweeps/__init__.py
 create mode 100644 src/services/sweeps/sweep_service.py
 create mode 100644 src/services/swings/__init__.py
 create mode 100644 src/services/swings/swing_service.py
 create mode 100644 src/utils/__init__.py
 create mode 100644 tests/__init__.py
 create mode 100644 tests/fixtures/__init__.py
 create mode 100644 tests/integration/__init__.py
 create mode 100644 tests/unit/__init__.py
 create mode 100644 tests/unit/test_api_and_main.py
 create mode 100644 tests/unit/test_api_server.py
 create mode 100644 tests/unit/test_backtest_report_service.py
 create mode 100644 tests/unit/test_backtest_service.py
 create mode 100644 tests/unit/test_execution_service.py
 create mode 100644 tests/unit/test_fvg_service.py
 create mode 100644 tests/unit/test_liquidity_pool_service.py
 create mode 100644 tests/unit/test_mss_service.py
 create mode 100644 tests/unit/test_report_services.py
 create mode 100644 tests/unit/test_signal_service.py

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..60635a9
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+.venv/
+venv/
+tests/
+docs/
+*.pdf
+memory/
+.DS_Store
diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..1875322
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,6 @@
+DATABASE_URL=postgresql+psycopg://postgres:postgres@localhost:5432/ai_ict
+OKX_BASE_URL=https://www.okx.com
+OKX_TIMEOUT=30
+DEFAULT_TIMEZONE=UTC
+SESSION_TIMEZONE=America/New_York
+LOG_LEVEL=INFO
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..289812f
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+venv/
+
+# Environment and secrets
+.env
+*.pem
+*.key
+
+# OS/editor
+.DS_Store
+.idea/
+.vscode/
+
+# Claude local state
+.claude/
+memory/
+
+# Large artifacts and local docs copies
+*.pdf
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..fff21ca
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,28 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONPATH=/app
+
+WORKDIR /app
+
+COPY pyproject.toml /app/pyproject.toml
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir \
+      "sqlalchemy>=2.0" \
+      "psycopg[binary]>=3.1" \
+      "pydantic>=2.7" \
+      "pydantic-settings>=2.2" \
+      "httpx>=0.27"
+
+COPY src /app/src
+COPY scripts /app/scripts
+COPY migrations /app/migrations
+COPY .env.example /app/.env.example
+COPY README.md /app/README.md
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 CMD python -c "from urllib.request import urlopen; import sys; sys.exit(0 if urlopen('http://127.0.0.1:8000/health').status == 200 else 1)"
+
+CMD ["python", "scripts/run_api_server.py"]
diff --git a/ICT Concepts.md b/ICT Concepts.md
new file mode 100644
index 0000000..b5e65bc
--- /dev/null
+++ b/ICT Concepts.md	
@@ -0,0 +1,2477 @@
+# ICT Concepts
+
+// This work is licensed under a Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) https://creativecommons.org/licenses/by-nc-sa/4.0/
+
+// © LuxAlgo
+
+
+
+
+
+//@version=5
+
+indicator("ICT Concepts \[LuxAlgo]",max\_lines\_count=500,max\_boxes\_count=500,max\_labels\_count=500,max\_bars\_back=3000,overlay=true)
+
+//-----------------------------------------------------------------------------}
+
+//Strings
+
+//-----------------------------------------------------------------------------{
+
+o='Options'
+
+sp1=' '
+
+sp2=' '
+
+hl='High / Low '+sp1
+
+ny\_='New York'+sp1
+
+lo\_='London Open'
+
+lc\_='London Close'
+
+as\_='Asian'
+
+
+
+
+
+//-----------------------------------------------------------------------------}
+
+//Settings
+
+//-----------------------------------------------------------------------------{
+
+i\_mode=input.string( 'Present',title='Mode',options=\['Present','Historical'] )
+
+
+
+
+
+//Market Structure Shift
+
+showMS=input.bool ( true,title='',group='Market Structures',inline='MS' )
+
+len=input.int ( 5,title=' Length '+sp2,group='Market Structures',inline='MS',minval=3,maxval=10 )
+
+
+
+
+
+iMSS=input.bool ( true,title=' MSS'+sp1,group='Market Structures',inline='M1' )
+
+cMSSbl=input.color (color.new(#00e6a1,0),title='bullish',group='Market Structures',inline='M1' )
+
+cMSSbr=input.color (color.new(#e60400,0),title='bearish',group='Market Structures',inline='M1' )
+
+
+
+
+
+iBOS=input.bool ( true,title=' BOS'+sp1,group='Market Structures',inline='BS' )
+
+cBOSbl=input.color (color.new(#00e6a1,0),title='bullish',group='Market Structures',inline='BS' )
+
+cBOSbr=input.color (color.new(#e60400,0),title='bearish',group='Market Structures',inline='BS' )
+
+
+
+
+
+//Displacement
+
+sDispl=input.bool ( false,title='Show Displacement',group='Displacement' )
+
+
+
+
+
+perc\_Body=0.36// input.int( 36, minval=1, maxval=36) / 100
+
+bxBack=10// input.int( 10, minval=0, maxval=10)
+
+
+
+
+
+sVimbl=input.bool ( true,title='',group='Volume Imbalance',inline='VI' )
+
+visVim=input.int ( 2,title=" # Visible VI's "+sp1,group='Volume Imbalance',inline='VI',minval=2,maxval=100 ) 
+
+cVimbl=input.color (color.new(#06b2d0,0),title='',group='Volume Imbalance',inline='VI' )
+
+
+
+
+
+//Order Blocks 
+
+showOB=input.bool ( true,title='Show Order Blocks',group='Order Blocks' )
+
+length=input.int ( 10,title='Swing Lookback',group='Order Blocks',minval=3 )
+
+showBull=input.int ( 1,title='Show Last Bullish OB',group='Order Blocks',minval=0 )
+
+showBear=input.int ( 1,title='Show Last Bearish OB',group='Order Blocks',minval=0 )
+
+useBody=input.bool ( true,title='Use Candle Body' )
+
+
+
+
+
+//OB Style
+
+bullCss=input.color (color.new(#3e89fa,0),title='Bullish OB ',group='Order Blocks',inline='bullcss' )
+
+bullBrkCss=input.color (color.new(#4785f9,85),title='Bullish Break ',group='Order Blocks',inline='bullcss' )
+
+
+
+
+
+bearCss=input.color (color.new(#FF3131,0),title='Bearish OB',group='Order Blocks',inline='bearcss' )
+
+bearBrkCss=input.color (color.new(#f9ff57,85),title='Bearish Break',group='Order Blocks',inline='bearcss' )
+
+
+
+
+
+showLabels=input.bool ( false,title='Show Historical Polarity Changes',group='Order Blocks' )
+
+
+
+
+
+//Liquidity 
+
+showLq=input.bool ( true,title='Show Liquidity',group='Liquidity' )
+
+a=10/input.float ( 4,title='margin',group='Liquidity',step=0.1,minval=2,maxval=7 )
+
+visLiq=input.int ( 2,title='# Visible Liq. boxes',group='Liquidity'
+
+,minval=1,maxval=50,tooltip='In the same direction' )
+
+cLIQ\_B=input.color (color.new(#fa451c,0),title='Buyside Liquidity ',group='Liquidity' )
+
+cLIQ\_S=input.color (color.new(#1ce4fa,0),title='Sellside Liquidity',group='Liquidity' )
+
+
+
+
+
+//FVG 
+
+shwFVG=input.bool ( true,title='Show FVGs',group='Fair Value Gaps' )
+
+i\_BPR=input.bool ( false,title='Balance Price Range',group='Fair Value Gaps' )
+
+i\_FVG=input.string( 'FVG',title=o,group='Fair Value Gaps',options=\['FVG','IFVG'] 
+
+,tooltip='Fair Value Gaps\nor\nImplied Fair Value Gaps' )
+
+visBxs=input.int ( 2,title='# Visible FVG\\'s',group='Fair Value Gaps'
+
+,minval=1,maxval=20,tooltip='In the same direction' )
+
+
+
+
+
+//FVG Style
+
+cFVGbl=input.color (color.new(#00e676,0),title='Bullish FVG ',group='Fair Value Gaps',inline='FVGbl' )
+
+cFVGblBR=input.color (color.new(#808000,0),title='Break',group='Fair Value Gaps',inline='FVGbl' )
+
+cFVGbr=input.color (color.new(#ff5252,0),title='Bearish FVG ',group='Fair Value Gaps',inline='FVGbr' )
+
+cFVGbrBR=input.color (color.new(#FF0000,0),title='Break',group='Fair Value Gaps',inline='FVGbr' )
+
+
+
+
+
+//NWOG/NDOG 
+
+iNWOG=input.bool ( true,title='',inline='NWOG',group='NWOG/NDOG' )
+
+cNWOG1=input.color (color.new(#ff5252,28),title='NWOG ',inline='NWOG',group='NWOG/NDOG' )
+
+cNWOG2=input.color (color.new(#b2b5be,50),title='',inline='NWOG',group='NWOG/NDOG' )
+
+maxNWOG=input.int ( 3,title='Show max',inline='NWOG',group='NWOG/NDOG',minval=0,maxval=50 )
+
+
+
+
+
+iNDOG=input.bool ( false,title='',inline='NDOG',group='NWOG/NDOG' )
+
+cNDOG1=input.color (color.new(#ff9800,20),title='NDOG ',inline='NDOG',group='NWOG/NDOG' )
+
+cNDOG2=input.color (color.new(#4dd0e1,65),title='',inline='NDOG',group='NWOG/NDOG' )
+
+maxNDOG=input.int ( 1,title='Show max',inline='NDOG',group='NWOG/NDOG',minval=0,maxval=50 )
+
+
+
+
+
+//Fibonacci 
+
+iFib=input.string( 'NONE',title='Fibonacci between last: ',group='Fibonacci',options=\['FVG','BPR','OB','Liq','VI','NWOG','NONE'])
+
+iExt=input.bool ( false,title='Extend lines',group='Fibonacci' )
+
+
+
+
+
+//Killzones 
+
+showKZ=input.bool ( false,title='Show Killzones',group='Killzones' )
+
+//New York
+
+showNy=input.bool ( true,title=ny\_,inline='ny',group='Killzones' ) andshowKZ
+
+nyCss=input.color (color.new(#ff5d00,93),title='',inline='ny',group='Killzones' )
+
+//London Open
+
+showLdno=input.bool ( true,title=lo\_,inline='lo',group='Killzones' ) andshowKZ
+
+ldnoCss=input.color (color.new(#00bcd4,93),title='',inline='lo',group='Killzones' )
+
+//London Close
+
+showLdnc=input.bool ( true,title=lc\_,inline='lc',group='Killzones' ) andshowKZ
+
+ldncCss=input.color (color.new(#2157f3,93),title='',inline='lc',group='Killzones' )
+
+//Asian
+
+showAsia=input.bool ( true,title=as\_+sp2,inline='as',group='Killzones' ) andshowKZ
+
+asiaCss=input.color (color.new(#e91e63,93),title='',inline='as',group='Killzones' )
+
+
+
+
+
+//-----------------------------------------------------------------------------}
+
+//General Calculations
+
+//-----------------------------------------------------------------------------{
+
+n=bar\_index
+
+hi=high
+
+lo=low
+
+tf\_msec=timeframe.in\_seconds(timeframe.period) \*1000
+
+maxSize=50
+
+atr=ta.atr(10)
+
+per=i\_mode=='Present'?last\_bar\_index-bar\_index<=500:true
+
+perB=last\_bar\_index-bar\_index<=1000?true:false
+
+xloc=iFib=='OB'?xloc.bar\_time:xloc.bar\_index
+
+ext=iExt?extend.right:extend.none
+
+plus=iFib=='OB'?tf\_msec\*50:50
+
+mx=math.max(close,open)
+
+mn=math.min(close,open)
+
+body=math.abs(close-open)
+
+meanBody=ta.sma (body,len)
+
+max=useBody?mx:high
+
+min=useBody?mn:low
+
+blBrkConf=0
+
+brBrkConf=0
+
+r=color.r(chart.bg\_color)
+
+g=color.g(chart.bg\_color)
+
+b=color.b(chart.bg\_color)
+
+isDark=r<80andg<80andb<80
+
+
+
+
+
+//-----------------------------------------------------------------------------}
+
+//User Defined Types
+
+//-----------------------------------------------------------------------------{
+
+typeZZ
+
+int \[] d
+
+int \[] x
+
+float \[] y
+
+bool \[] b
+
+
+
+
+
+typeln\_d
+
+linel
+
+intd
+
+
+
+
+
+type\_2ln\_lb
+
+linel1
+
+linel2
+
+labellb
+
+
+
+
+
+typebx\_ln
+
+boxb
+
+linel
+
+
+
+
+
+typebx\_ln\_lb
+
+boxbx
+
+lineln
+
+labellb
+
+
+
+
+
+typemss
+
+intdir
+
+line \[] l\_mssBl
+
+line \[] l\_mssBr
+
+line \[] l\_bosBl
+
+line \[] l\_bosBr
+
+label\[] lbMssBl
+
+label\[] lbMssBr
+
+label\[] lbBosBl
+
+label\[] lbBosBr
+
+
+
+
+
+typeliq
+
+boxbx
+
+boolbroken
+
+boolbrokenTop
+
+boolbrokenBtm
+
+lineln
+
+
+
+
+
+typeob
+
+floattop=na
+
+floatbtm=na
+
+intloc=bar\_index
+
+boolbreaker=false
+
+intbreak\_loc=na
+
+
+
+
+
+typeswing
+
+floaty=na
+
+intx=na
+
+boolcrossed=false
+
+
+
+
+
+typeFVG
+
+boxbox
+
+boolactive
+
+intpos
+
+
+
+
+
+varmssMSS=mss.new(
+
+0
+
+,array.new\<line>()
+
+,array.new\<line>() 
+
+,array.new\<line>()
+
+,array.new\<line>()
+
+,array.new\<label>() 
+
+,array.new\<label>()
+
+,array.new\<label>()
+
+,array.new\<label>()
+
+&#x20;)
+
+
+
+
+
+//-----------------------------------------------------------------------------}
+
+//Variables
+
+//-----------------------------------------------------------------------------{
+
+maxVimb=2
+
+
+
+
+
+varfloatfriCp=na,varintfriCi=na// Friday Close price/index
+
+varfloatmonOp=na,varintmonOi=na// Monday Open price/index
+
+
+
+
+
+varfloatprDCp=na,varintprDCi=na// Previous Day Open price/index
+
+varfloatcuDOp=na,varintcuDOi=na// Current Day Open price/index
+
+
+
+
+
+var\_2ln\_lb \[] Vimbal=array.new< \_2ln\_lb>() 
+
+
+
+
+
+varliq \[] b\_liq\_B=array.new< liq>(1,liq.new(box(na),false,false,false,line(na)))
+
+varliq \[] b\_liq\_S=array.new< liq>(1,liq.new(box(na),false,false,false,line(na)))
+
+
+
+
+
+varob \[] bullish\_ob=array.new< ob>()
+
+varob \[] bearish\_ob=array.new< ob>()
+
+
+
+
+
+varbx\_ln \[] bl\_NWOG=array.new< bx\_ln>()
+
+varbx\_ln \[] bl\_NDOG=array.new< bx\_ln>()
+
+
+
+
+
+varbx\_ln\_lb\[] a\_bx\_ln\_lb=array.new< bx\_ln\_lb>()
+
+
+
+
+
+varFVG \[] bFVG\_UP=array.new< FVG>()
+
+varFVG \[] bFVG\_DN=array.new< FVG>()
+
+
+
+
+
+varFVG \[] bBPR\_UP=array.new< FVG>()
+
+varFVG \[] bBPR\_DN=array.new< FVG>()
+
+
+
+
+
+varZZaZZ=
+
+ZZ.new(
+
+array.new\<int>(maxSize,0),
+
+array.new\<int>(maxSize,0),
+
+array.new\<float>(maxSize,na),
+
+array.new\<bool>(maxSize,na))
+
+
+
+
+
+varline\_diag=line.new(na,na,na,na,color=color.new(color.silver,50),style=line.style\_dashed,xloc=xloc )
+
+varline\_vert=line.new(na,na,na,na,color=color.new(color.silver,50),style=line.style\_dotted,xloc=xloc )
+
+varline\_zero=line.new(na,na,na,na,color=color.new(color.silver,5),style=line.style\_solid,xloc=xloc,extend=ext)
+
+varline\_0236=line.new(na,na,na,na,color=color.new(color.orange,25),style=line.style\_solid,xloc=xloc,extend=ext)
+
+varline\_0382=line.new(na,na,na,na,color=color.new(color.yellow,25),style=line.style\_solid,xloc=xloc,extend=ext)
+
+varline\_0500=line.new(na,na,na,na,color=color.new(color.green,25),style=line.style\_solid,xloc=xloc,extend=ext)
+
+varline\_0618=line.new(na,na,na,na,color=color.new(color.yellow,25),style=line.style\_solid,xloc=xloc,extend=ext)
+
+varline\_0786=line.new(na,na,na,na,color=color.new(color.orange,25),style=line.style\_solid,xloc=xloc,extend=ext)
+
+varline\_one\_=line.new(na,na,na,na,color=color.new(color.silver,5),style=line.style\_solid,xloc=xloc,extend=ext)
+
+varline\_1618=line.new(na,na,na,na,color=color.new(color.yellow,25),style=line.style\_solid,xloc=xloc,extend=ext)
+
+
+
+//-----------------------------------------------------------------------------}
+
+//Functions/methods
+
+//-----------------------------------------------------------------------------{
+
+methodin\_out(ZZaZZ,intd,intx1,floaty1,intx2,floaty2,colorcol,boolb) =>
+
+aZZ.d.unshift(d),aZZ.x.unshift(x2),aZZ.y.unshift(y2),aZZ.b.unshift(b),aZZ.d.pop(),aZZ.x.pop(),aZZ.y.pop(),aZZ.b.pop()
+
+
+
+
+
+methodtimeinrange(stringres,stringsess) =>notna(time(timeframe.period,res,sess))
+
+
+
+
+
+methodsetLine(lineln,intx1,floaty1,intx2,floaty2) =>ln.set\_xy1(x1,y1),ln.set\_xy2(x2,y2)
+
+
+
+
+
+methodclear\_aLine(line\[] l) =>
+
+ifl.size() >0
+
+fori=l.size() -1to0
+
+l.pop().delete()
+
+
+
+
+
+methodclear\_aLabLin(label\[] l) =>
+
+ifl.size() >0
+
+fori=l.size() -1to0
+
+l.pop().delete()
+
+
+
+
+
+methodclear\_aLabLin(line\[] l) =>
+
+ifl.size() >0
+
+fori=l.size() -1to0
+
+l.pop().delete()
+
+
+
+
+
+methodnotransp(colorcss) =>color.rgb(color.r(css),color.g(css),color.b(css))
+
+
+
+
+
+methoddisplay(obid,css,break\_css,str)=>
+
+ifshowOB
+
+ifid.breaker
+
+a\_bx\_ln\_lb.unshift(
+
+bx\_ln\_lb.new(
+
+box.new(id.loc,id.top,timenow+ (tf\_msec\*10),id.btm,na
+
+,bgcolor=break\_css
+
+,extend=extend.none
+
+,xloc=xloc.bar\_time)
+
+,line (na)
+
+,label(na))
+
+&#x20;)
+
+else
+
+y=str=='bl'?id.btm:id.top
+
+s=str=='bl'?label.style\_label\_up:label.style\_label\_down
+
+a\_bx\_ln\_lb.unshift(
+
+bx\_ln\_lb.new(
+
+box(na)
+
+,line.new(id.loc,y,id.loc+ (tf\_msec\*10),y
+
+,xloc=xloc.bar\_time,color=css,width=2)
+
+,label.new( id.loc+ (tf\_msec\*10),y
+
+,text=str=='bl'?'+OB':'-OB'
+
+,xloc=xloc.bar\_time
+
+,style=s,color=color(na)
+
+,textcolor=css,size=size.small))
+
+&#x20;)
+
+
+
+
+
+swings(len)=>
+
+varos=0
+
+varswingtop=swing.new(na,na)
+
+varswingbtm=swing.new(na,na)
+
+
+
+upper=ta.highest(len)
+
+lower=ta.lowest(len)
+
+
+
+
+
+os:=high\[len] >upper?0
+
+:low \[len] \<lower?1:os
+
+
+
+
+
+ifos==0andos\[1] !=0
+
+top:=swing.new(high\[length],bar\_index\[length])
+
+
+
+ifos==1andos\[1] !=1
+
+btm:=swing.new(low\[length],bar\_index\[length])
+
+
+
+
+
+&#x20;\[top,btm]
+
+
+
+set\_lab(i,str) =>
+
+style=str=='Bl'?label.style\_label\_down:label.style\_label\_up
+
+txcol=str=='Bl'?color.lime:color.red
+
+label.new(math.round(math.avg(aZZ.x.get(i),n)),aZZ.y.get(i),text='BOS'
+
+,style=style,color=color(na),textcolor=txcol,size=size.tiny)
+
+set\_lin(i,str) =>
+
+color=str=='Bl'?color.lime:color.red
+
+line.new(aZZ.x.get(i),aZZ.y.get(i),n,aZZ.y.get(i),color=color,style=line.style\_dotted)
+
+
+
+
+
+draw(left,col) =>
+
+//
+
+max\_bars\_back(time,1000)
+
+varintdir=na,varintx1=na,varfloaty1=na,varintx2=na,varfloaty2=na
+
+//
+
+sz=aZZ.d.size( )
+
+x2:=bar\_index-1
+
+ph=ta.pivothigh(hi,left,1)
+
+pl=ta.pivotlow (lo,left,1)
+
+ifph
+
+dir:=aZZ.d.get (0) 
+
+x1:=aZZ.x.get (0) 
+
+y1:=aZZ.y.get (0) 
+
+y2:=nz(hi\[1])
+
+//
+
+ifdir<1// if previous point was a pl, add, and change direction ( 1)
+
+aZZ.in\_out( 1,x1,y1,x2,y2,col,true)
+
+else
+
+ifdir==1andph>y1
+
+aZZ.x.set(0,x2),aZZ.y.set(0,y2)
+
+//
+
+// liquidity
+
+ifshowLqandperandsz>0
+
+count=0
+
+st\_P=0.
+
+st\_B=0
+
+minP=0.
+
+maxP=10e6
+
+fori=0tomath.min(sz,50) -1
+
+ifaZZ.d.get(i) ==1
+
+ifaZZ.y.get(i) >ph+ (atr/a)
+
+break
+
+else
+
+ifaZZ.y.get(i) >ph- (atr/a) andaZZ.y.get(i) \<ph+ (atr/a)
+
+count+=1
+
+st\_B:=aZZ.x.get(i)
+
+st\_P:=aZZ.y.get(i)
+
+ifaZZ.y.get(i) >minP
+
+minP:=aZZ.y.get(i)
+
+ifaZZ.y.get(i) \<maxP
+
+maxP:=aZZ.y.get(i)
+
+ifcount>2
+
+getB=b\_liq\_B.get(0)
+
+ifst\_B==getB.bx.get\_left()
+
+getB.bx.set\_top(math.avg(minP,maxP) + (atr/a))
+
+getB.bx.set\_rightbottom(n+10,math.avg(minP,maxP) - (atr/a))
+
+else
+
+b\_liq\_B.unshift(liq.new(
+
+box.new(
+
+st\_B,math.avg(minP,maxP) + (atr/a),n+10,math.avg(minP,maxP) - (atr/a)
+
+,text='Buyside liquidity',text\_size=size.tiny,text\_halign=text.align\_left
+
+,text\_valign=text.align\_bottom,text\_color=color.new(cLIQ\_B,25)
+
+,bgcolor=color(na),border\_color=color(na)
+
+&#x20;)
+
+,false
+
+,false
+
+,false
+
+,line.new(st\_B,st\_P,n-1,st\_P,color=color.new(cLIQ\_B,0))
+
+&#x20;)
+
+&#x20;) 
+
+ifb\_liq\_B.size() >visLiq
+
+getLast=b\_liq\_B.pop()
+
+getLast.bx.delete()
+
+getLast.ln.delete() 
+
+//
+
+ifpl
+
+dir:=aZZ.d.get (0) 
+
+x1:=aZZ.x.get (0) 
+
+y1:=aZZ.y.get (0) 
+
+y2:=nz(lo\[1])
+
+//
+
+ifdir>-1// if previous point was a ph, add, and change direction (-1)
+
+aZZ.in\_out(-1,x1,y1,x2,y2,col,true)
+
+else
+
+ifdir==-1andpl\<y1
+
+aZZ.x.set(0,x2),aZZ.y.set(0,y2)
+
+//
+
+//Liquidity
+
+ifshowLqandperandsz>0
+
+count=0
+
+st\_P=0.
+
+st\_B=0
+
+minP=0.
+
+maxP=10e6
+
+fori=0tomath.min(sz,50) -1
+
+ifaZZ.d.get(i) ==-1
+
+ifaZZ.y.get(i) \<pl- (atr/a)
+
+break
+
+else
+
+ifaZZ.y.get(i) >pl- (atr/a) andaZZ.y.get(i) \<pl+ (atr/a)
+
+count+=1
+
+st\_B:=aZZ.x.get(i)
+
+st\_P:=aZZ.y.get(i)
+
+ifaZZ.y.get(i) >minP
+
+minP:=aZZ.y.get(i)
+
+ifaZZ.y.get(i) \<maxP
+
+maxP:=aZZ.y.get(i)
+
+ifcount>2
+
+getB=b\_liq\_S.get(0)
+
+ifst\_B==getB.bx.get\_left()
+
+getB.bx.set\_top(math.avg(minP,maxP) + (atr/a))
+
+getB.bx.set\_rightbottom(n+10,math.avg(minP,maxP) - (atr/a))
+
+else
+
+b\_liq\_S.unshift(liq.new(
+
+box.new(
+
+st\_B,math.avg(minP,maxP) + (atr/a),n+10,math.avg(minP,maxP) - (atr/a)
+
+,text='Sellside liquidity',text\_size=size.tiny,text\_halign=text.align\_left
+
+,text\_valign=text.align\_bottom,text\_color=color.new(cLIQ\_S,25)
+
+,bgcolor=color(na),border\_color=color(na)
+
+&#x20;)
+
+,false
+
+,false
+
+,false
+
+,line.new(st\_B,st\_P,n-1,st\_P,color=color.new(cLIQ\_S,0))
+
+&#x20;)
+
+&#x20;) 
+
+ifb\_liq\_S.size() >visLiq
+
+getLast=b\_liq\_S.pop()
+
+getLast.bx.delete()
+
+getLast.ln.delete() 
+
+//
+
+//Market Structure Shift 
+
+ifshowMS
+
+//
+
+iH=aZZ.d.get(2) ==1?2:1
+
+iL=aZZ.d.get(2) ==-1?2:1
+
+//
+
+switch
+
+// MSS Bullish
+
+close>aZZ.y.get(iH) andaZZ.d.get(iH) ==1andMSS.dir<1=>
+
+MSS.dir:=1
+
+ifi\_mode=='Present'
+
+MSS.l\_bosBl.clear\_aLabLin(),MSS.l\_bosBr.clear\_aLabLin() 
+
+MSS.lbBosBl.clear\_aLabLin(),MSS.lbBosBr.clear\_aLabLin() 
+
+MSS.l\_mssBl.clear\_aLabLin(),MSS.l\_mssBr.clear\_aLabLin() 
+
+MSS.lbMssBl.clear\_aLabLin(),MSS.lbMssBr.clear\_aLabLin() 
+
+// 
+
+MSS.l\_mssBl.unshift(line.new (
+
+aZZ.x.get(iH),aZZ.y.get(iH),n,aZZ.y.get(iH),color=cMSSbl))
+
+MSS.lbMssBl.unshift(label.new(
+
+math.round(math.avg(aZZ.x.get(iH),n)),aZZ.y.get(iH),text='MSS'
+
+,style=label.style\_label\_down,size=size.tiny,color=color(na),textcolor=cMSSbl))
+
+// MSS Bearish
+
+close\<aZZ.y.get(iL) andaZZ.d.get(iL) ==-1andMSS.dir>-1=>
+
+MSS.dir:=-1
+
+ifi\_mode=='Present'
+
+MSS.l\_bosBl.clear\_aLabLin(),MSS.l\_bosBr.clear\_aLabLin() 
+
+MSS.lbBosBl.clear\_aLabLin(),MSS.lbBosBr.clear\_aLabLin() 
+
+MSS.l\_mssBl.clear\_aLabLin(),MSS.l\_mssBr.clear\_aLabLin() 
+
+MSS.lbMssBl.clear\_aLabLin(),MSS.lbMssBr.clear\_aLabLin()
+
+// 
+
+MSS.l\_mssBr.unshift(line.new (
+
+aZZ.x.get(iL),aZZ.y.get(iL),n,aZZ.y.get(iL),color=cMSSbr))
+
+MSS.lbMssBr.unshift(label.new(
+
+math.round(math.avg(aZZ.x.get(iL),n)),aZZ.y.get(iL),text='MSS'
+
+,style=label.style\_label\_up,size=size.tiny,color=color(na),textcolor=cMSSbr))
+
+// BOS Bullish
+
+MSS.dir==1andclose>aZZ.y.get(iH) andiBOS=>
+
+ifMSS.l\_bosBl.size() >0
+
+ifaZZ.y.get(iH) !=MSS.l\_bosBl.get(0).get\_y2() and
+
+aZZ.y.get(iH) !=MSS.l\_mssBl.get(0).get\_y2()
+
+MSS.l\_bosBl.unshift(set\_lin(iH,'Bl')),MSS.lbBosBl.unshift(set\_lab(iH,'Bl'))
+
+else
+
+ifaZZ.y.get(iH) !=MSS.l\_mssBl.get(0).get\_y2() 
+
+MSS.l\_bosBl.unshift(set\_lin(iH,'Bl')),MSS.lbBosBl.unshift(set\_lab(iH,'Bl'))
+
+// BOS Bearish
+
+MSS.dir==-1andclose\<aZZ.y.get(iL) andiBOS=>
+
+ifMSS.l\_bosBr.size() >0
+
+ifaZZ.y.get(iL) !=MSS.l\_bosBr.get(0).get\_y2() and
+
+aZZ.y.get(iL) !=MSS.l\_mssBr.get(0).get\_y2()
+
+MSS.l\_bosBr.unshift(set\_lin(iL,'Br')),MSS.lbBosBr.unshift(set\_lab(iL,'Br'))
+
+else
+
+ifaZZ.y.get(iL) !=MSS.l\_mssBr.get(0).get\_y2() 
+
+MSS.l\_bosBr.unshift(set\_lin(iL,'Br')),MSS.lbBosBr.unshift(set\_lab(iL,'Br'))
+
+ifnotiMSS
+
+MSS.l\_mssBl.get(0).set\_color(color(na)),MSS.lbMssBl.get(0).set\_textcolor(color(na))
+
+MSS.l\_mssBr.get(0).set\_color(color(na)),MSS.lbMssBr.get(0).set\_textcolor(color(na))
+
+
+
+
+
+
+
+
+
+//-----------------------------------------------------------------------------}
+
+//Calculations
+
+//-----------------------------------------------------------------------------{
+
+draw(len,color.yellow) 
+
+
+
+
+
+ifMSS.l\_bosBl.size() >200
+
+MSS.l\_bosBl.pop().delete()
+
+MSS.lbBosBl.pop().delete()
+
+
+
+
+
+ifMSS.l\_bosBr.size() >200
+
+MSS.l\_bosBr.pop().delete()
+
+MSS.lbBosBr.pop().delete()
+
+
+
+
+
+//Killzones 
+
+ny=time(timeframe.period,input.session('0700-0900','',inline='ny',group='Killzones'),'America/New\_York') andshowNy
+
+ldn\_open=time(timeframe.period,input.session('0700-1000','',inline='lo',group='Killzones'),'Europe/London' ) andshowLdno// 0200-0500 UTC-5
+
+ldn\_close=time(timeframe.period,input.session('1500-1700','',inline='lc',group='Killzones'),'Europe/London' ) andshowLdnc// 1000-1200 UTC-5
+
+asian=time(timeframe.period,input.session('1000-1400','',inline='as',group='Killzones'),'Asia/Tokyo' ) andshowAsia// 2000-0000 UTC-5
+
+
+
+
+
+//Pivotpoints 
+
+ph=ta.pivothigh(3,1),lPh=fixnan(ph)
+
+pl=ta.pivotlow (3,1),lPl=fixnan(pl)
+
+
+
+
+
+//Candles 
+
+L\_body=
+
+high-mx\<body\*perc\_Bodyand
+
+mn-low\<body\*perc\_Body
+
+
+
+
+
+L\_bodyUP=body>meanBodyandL\_bodyandclose>open
+
+L\_bodyDN=body>meanBodyandL\_bodyandclose\<open
+
+
+
+
+
+bsNOTbodyUP=ta.barssince(notL\_bodyUP)
+
+bsNOTbodyDN=ta.barssince(notL\_bodyDN)
+
+
+
+
+
+bsIs\_bodyUP=ta.barssince( L\_bodyUP)
+
+bsIs\_bodyDN=ta.barssince( L\_bodyDN)
+
+
+
+
+
+lwst=math.min(lPh \[bsNOTbodyUP\[1]],low\[bsNOTbodyUP\[1]])
+
+hgst=math.max(high\[bsNOTbodyDN\[1]],lPl\[bsNOTbodyDN\[1]])
+
+
+
+
+
+//Imbalance
+
+imbalanceUP=L\_bodyUP\[1] and (i\_FVG=='FVG'?low>high\[2] :low\<high\[2])
+
+imbalanceDN=L\_bodyDN\[1] and (i\_FVG=='FVG'?high\<low \[2] :high>low \[2])
+
+
+
+
+
+//Volume Imbalance
+
+vImb\_Bl=open>close\[1] andhigh\[1] >lowandclose>close\[1] andopen>open\[1] andhigh\[1] \<mn
+
+vImb\_Br=open\<close\[1] andlow \[1] \<highandclose\<close\[1] andopen\<open\[1] andlow \[1] >mx
+
+
+
+
+
+ifsVimbl
+
+ifvImb\_Bl
+
+Vimbal.unshift(
+
+\_2ln\_lb.new(
+
+line.new (n-1,mx\[1],n+3,mx\[1],color=cVimbl)
+
+,line.new (n,mn,n+3,mn,color=cVimbl)
+
+,label.new(n+3,math.avg (mx\[1],mn),text='VI'
+
+,color=color(na) ,textcolor=cVimbl,style=label.style\_label\_left)
+
+&#x20;)
+
+&#x20;)
+
+ifvImb\_Br
+
+Vimbal.unshift(
+
+\_2ln\_lb.new(
+
+line.new (n-1,mn\[1],n+3,mn\[1],color=cVimbl)
+
+,line.new (n,mx,n+3,mx,color=cVimbl)
+
+,label.new(n+3,math.avg (mn\[1],mx),text='VI'
+
+,color=color(na) ,textcolor=cVimbl,style=label.style\_label\_left)
+
+&#x20;)
+
+&#x20;)
+
+ifVimbal.size() >visVim
+
+pop=Vimbal.pop()
+
+pop.l1.delete()
+
+pop.l2.delete()
+
+pop.lb.delete()
+
+
+
+
+
+//Fair Value Gap 
+
+ifbarstate.isfirst
+
+fori=0tovisBxs-1
+
+bFVG\_UP.unshift(FVG.new(box(na),false))
+
+bFVG\_DN.unshift(FVG.new(box(na),false))
+
+ifi\_BPR
+
+bBPR\_UP.unshift(FVG.new(box(na),false))
+
+bBPR\_DN.unshift(FVG.new(box(na),false))
+
+
+
+
+
+ifimbalanceUPandperandshwFVG
+
+ifimbalanceUP\[1]
+
+bFVG\_UP.get(0).box.set\_lefttop (n-2,low )
+
+bFVG\_UP.get(0).box.set\_rightbottom(n+8,high\[2])
+
+else
+
+bFVG\_UP.unshift(FVG.new(
+
+box.new(
+
+n-2
+
+,i\_FVG=='FVG'?low:high\[2]
+
+,n,i\_FVG=='FVG'?high\[2] :low
+
+,bgcolor=i\_BPR?color(na) :color.new(cFVGbl,90)
+
+,border\_color=i\_BPR?color(na) :color.new(cFVGbl,65)
+
+,text\_color=i\_BPR?color(na) :color.new(cFVGbl,65)
+
+,text\_size=size.small
+
+,text=i\_FVG
+
+&#x20;)
+
+,true)
+
+&#x20;)
+
+bFVG\_UP.pop().box.delete()
+
+
+
+
+
+ifimbalanceDNandperandshwFVG
+
+ifimbalanceDN\[1]
+
+bFVG\_DN.get(0).box.set\_lefttop (n-2,low\[2])
+
+bFVG\_DN.get(0).box.set\_rightbottom(n+8,high )
+
+else
+
+bFVG\_DN.unshift(FVG.new(
+
+box.new(
+
+n-2
+
+,i\_FVG=='FVG'?low\[2] :high
+
+,n,i\_FVG=='FVG'?high:low\[2]
+
+,bgcolor=i\_BPR?color(na) :color.new(cFVGbr,90)
+
+,border\_color=i\_BPR?color(na) :color.new(cFVGbr,65)
+
+,text\_color=i\_BPR?color(na) :color.new(cFVGbr,65)
+
+,text\_size=size.small
+
+,text=i\_FVG
+
+&#x20;)
+
+,true)
+
+&#x20;)
+
+bFVG\_DN.pop().box.delete()
+
+
+
+
+
+//Balance Price Range (overlap of 2 latest FVG bull/bear)
+
+ifi\_BPRandbFVG\_UP.size() >0andbFVG\_DN.size() >0
+
+bxUP=bFVG\_UP.get(0)
+
+bxDN=bFVG\_DN.get(0)
+
+bxUPbtm=bxUP.box.get\_bottom()
+
+bxDNbtm=bxDN.box.get\_bottom()
+
+bxUPtop=bxUP.box.get\_top()
+
+bxDNtop=bxDN.box.get\_top()
+
+left=math.min(bxUP.box.get\_left (),bxDN.box.get\_left ())
+
+right=math.max(bxUP.box.get\_right(),bxDN.box.get\_right())
+
+//
+
+ifbxUPbtm\<bxDNtopand
+
+bxDNbtm\<bxUPbtm
+
+ifleft==bBPR\_UP.get(0).box.get\_left() 
+
+ifbBPR\_UP.get(0).active
+
+bBPR\_UP.get(0).box.set\_right(right)
+
+else
+
+bBPR\_UP.unshift(FVG.new(
+
+box.new(
+
+left,bxDNtop,right,bxUPbtm
+
+,bgcolor=i\_BPR?color.new(cFVGbl,90) :color(na)
+
+,border\_color=i\_BPR?color.new(cFVGbl,65) :color(na)
+
+,text\_color=i\_BPR?color.new(cFVGbl,65) :color(na)
+
+,text\_size=size.small
+
+,text='BPR'
+
+&#x20;) 
+
+,true
+
+,close>bxUPbtm?1:close\<bxDNtop?-1:0
+
+&#x20;)
+
+&#x20;)
+
+bBPR\_UP.pop().box.delete()
+
+//
+
+ifbxDNbtm\<bxUPtopand
+
+bxUPbtm\<bxDNbtm
+
+ifleft==bBPR\_DN.get(0).box.get\_left() 
+
+ifbBPR\_DN.get(0).active
+
+bBPR\_DN.get(0).box.set\_right(right)
+
+else
+
+bBPR\_DN.unshift(FVG.new(
+
+box.new(
+
+left,bxUPtop,right,bxDNbtm
+
+,bgcolor=i\_BPR?color.new(cFVGbr,90) :color(na)
+
+,border\_color=i\_BPR?color.new(cFVGbr,65) :color(na)
+
+,text\_color=i\_BPR?color.new(cFVGbr,65) :color(na)
+
+,text\_size=size.small
+
+,text='BPR'
+
+&#x20;) 
+
+,true
+
+,close>bxDNbtm?1:close\<bxUPtop?-1:0
+
+&#x20;)
+
+&#x20;)
+
+bBPR\_DN.pop().box.delete()
+
+
+
+
+
+//FVG's breaks
+
+fori=0tomath.min(bxBack,bFVG\_UP.size() -1)
+
+getUPi=bFVG\_UP.get(i)
+
+ifgetUPi.active
+
+getUPi.box.set\_right(bar\_index+8)
+
+iflow\<getUPi.box.get\_top() andnoti\_BPR
+
+getUPi.box.set\_border\_style(line.style\_dashed)
+
+iflow\<getUPi.box.get\_bottom()
+
+ifnoti\_BPR
+
+getUPi.box.set\_bgcolor(color.new(cFVGblBR,95))
+
+getUPi.box.set\_border\_style(line.style\_dotted)
+
+getUPi.box.set\_right(bar\_index)
+
+getUPi.active:=false
+
+
+
+
+
+fori=0tomath.min(bxBack,bFVG\_DN.size() -1)
+
+getDNi=bFVG\_DN.get(i)
+
+ifgetDNi.active
+
+getDNi.box.set\_right(bar\_index+8)
+
+ifhigh>getDNi.box.get\_bottom() andnoti\_BPR
+
+getDNi.box.set\_border\_style(line.style\_dashed)
+
+ifhigh>getDNi.box.get\_top()
+
+ifnoti\_BPR
+
+getDNi.box.set\_bgcolor(color.new(cFVGbrBR,95))
+
+getDNi.box.set\_border\_style(line.style\_dotted)
+
+getDNi.box.set\_right(bar\_index)
+
+getDNi.active:=false
+
+
+
+
+
+ifi\_BPR
+
+fori=0tomath.min(bxBack,bBPR\_UP.size() -1)
+
+getUPi=bBPR\_UP.get(i)
+
+ifgetUPi.active
+
+getUPi.box.set\_right(bar\_index+8)
+
+switchgetUPi.pos
+
+-1=>
+
+ifhigh>getUPi.box.get\_bottom()
+
+getUPi.box.set\_border\_style(line.style\_dashed)
+
+ifhigh>getUPi.box.get\_top ()
+
+getUPi.box.set\_bgcolor(color.new(cFVGblBR,95))
+
+getUPi.box.set\_border\_style(line.style\_dotted)
+
+getUPi.box.set\_right(bar\_index)
+
+getUPi.active:=false
+
+1=>
+
+iflow\<getUPi.box.get\_top ()
+
+getUPi.box.set\_border\_style(line.style\_dashed)
+
+iflow\<getUPi.box.get\_bottom()
+
+getUPi.box.set\_bgcolor(color.new(cFVGblBR,95))
+
+getUPi.box.set\_border\_style(line.style\_dotted)
+
+getUPi.box.set\_right(bar\_index)
+
+getUPi.active:=false
+
+
+
+fori=0tomath.min(bxBack,bBPR\_DN.size() -1)
+
+getDNi=bBPR\_DN.get(i)
+
+ifgetDNi.active
+
+getDNi.box.set\_right(bar\_index+8)
+
+switchgetDNi.pos
+
+-1=>
+
+ifhigh>getDNi.box.get\_bottom()
+
+getDNi.box.set\_border\_style(line.style\_dashed)
+
+ifhigh>getDNi.box.get\_top ()
+
+getDNi.box.set\_bgcolor(color.new(cFVGbrBR,95))
+
+getDNi.box.set\_border\_style(line.style\_dotted)
+
+getDNi.box.set\_right(bar\_index)
+
+getDNi.active:=false
+
+1=>
+
+iflow\<getDNi.box.get\_top ()
+
+getDNi.box.set\_border\_style(line.style\_dashed)
+
+iflow\<getDNi.box.get\_bottom()
+
+getDNi.box.set\_bgcolor(color.new(cFVGbrBR,95))
+
+getDNi.box.set\_border\_style(line.style\_dotted)
+
+getDNi.box.set\_right(bar\_index)
+
+getDNi.active:=false
+
+
+
+
+
+//NWOG/NDOG 
+
+ifbarstate.isfirst
+
+fori=0tomaxNWOG-1
+
+bl\_NWOG.unshift(bx\_ln.new(box(na),line(na)))
+
+fori=0tomaxNDOG-1
+
+bl\_NDOG.unshift(bx\_ln.new(box(na),line(na)))
+
+
+
+
+
+ifdayofweek==dayofweek.friday
+
+friCp:=close,friCi:=n
+
+
+
+
+
+ifta.change(dayofweek) 
+
+ifdayofweek==dayofweek.mondayandiNWOG
+
+monOp:=open,monOi:=n
+
+bl\_NWOG.unshift(bx\_ln.new( 
+
+box.new(
+
+friCi,math.max (friCp,monOp )
+
+,monOi,math.min (friCp,monOp )
+
+,bgcolor=color ( na )
+
+,border\_color=cNWOG2
+
+,extend=extend.right )
+
+,
+
+line.new(
+
+monOi,math.avg (friCp,monOp ) 
+
+,monOi+1,math.avg (friCp,monOp )
+
+,color=cNWOG1
+
+,style=line.style\_dotted
+
+,extend=extend.right ) 
+
+&#x20;))
+
+bl=bl\_NWOG.pop(),bl.b.delete(),bl.l.delete()
+
+ifiNDOG
+
+cuDOp:=open,cuDOi:=n
+
+prDCp:=close\[1],prDCi:=n-1
+
+//
+
+bl\_NDOG.unshift(bx\_ln.new( 
+
+box.new(
+
+prDCi,math.max (prDCp,cuDOp )
+
+,cuDOi,math.min (prDCp,cuDOp )
+
+,bgcolor=color ( na )
+
+,border\_color=cNDOG2
+
+,extend=extend.right )
+
+,
+
+line.new(
+
+cuDOi,math.avg (prDCp,cuDOp ) 
+
+,cuDOi+1,math.avg (prDCp,cuDOp )
+
+,color=cNDOG1
+
+,style=line.style\_dotted
+
+,extend=extend.right ) 
+
+&#x20;))
+
+bl=bl\_NDOG.pop(),bl.b.delete(),bl.l.delete()
+
+
+
+
+
+//Liquidity 
+
+fori=0tob\_liq\_B.size() -1
+
+x=b\_liq\_B.get(i)
+
+ifnotx.broken
+
+x.bx.set\_right(n+3)
+
+x.ln.set\_x2 (n+3)
+
+ifnotx.brokenTop
+
+ifclose>x.bx.get\_top ()
+
+x.brokenTop:=true
+
+ifnotx.brokenBtm
+
+ifclose>x.bx.get\_bottom()
+
+x.brokenBtm:=true
+
+ifx.brokenBtm
+
+x.bx.set\_bgcolor(color.new(cLIQ\_B,90))
+
+x.ln.delete()
+
+ifx.brokenTop
+
+x.broken:=true
+
+x.bx.set\_right(n)
+
+
+
+
+
+fori=0tob\_liq\_S.size() -1
+
+x=b\_liq\_S.get(i)
+
+ifnotx.broken
+
+x.bx.set\_right(n+3)
+
+x.ln.set\_x2 (n+3)
+
+ifnotx.brokenTop
+
+ifclose\<x.bx.get\_top ()
+
+x.brokenTop:=true
+
+ifnotx.brokenBtm
+
+ifclose\<x.bx.get\_bottom()
+
+x.brokenBtm:=true
+
+ifx.brokenTop
+
+x.bx.set\_bgcolor(color.new(cLIQ\_S,90))
+
+x.ln.delete()
+
+ifx.brokenBtm
+
+x.broken:=true
+
+x.bx.set\_right(n)
+
+
+
+
+
+//Order Blocks 
+
+\[top,btm] =swings(length)
+
+
+
+
+
+ifshowOBandper
+
+ifclose>top.yandnottop.crossed
+
+top.crossed:=true
+
+
+
+minima=max\[1]
+
+maxima=min\[1]
+
+loc=time\[1]
+
+
+
+fori=1to (n-top.x)-1
+
+minima:=math.min(min\[i],minima)
+
+maxima:=minima==min\[i] ?max\[i] :maxima
+
+loc:=minima==min\[i] ?time\[i] :loc
+
+bullish\_ob.unshift(ob.new(maxima,minima,loc))
+
+
+
+ifbullish\_ob.size() >0
+
+fori=bullish\_ob.size()-1to0
+
+element=bullish\_ob.get(i)
+
+
+
+ifnotelement.breaker
+
+ifmath.min(close,open) \<element.btm
+
+element.breaker:=true
+
+element.break\_loc:=time
+
+else
+
+ifclose>element.top
+
+bullish\_ob.remove(i)
+
+elseifi\<showBullandtop.y\<element.topandtop.y>element.btm
+
+blBrkConf:=1
+
+
+
+
+
+//Set label
+
+ifblBrkConf>blBrkConf\[1] andshowLabels
+
+label.new(top.x,top.y,'▼',color=na
+
+,textcolor=bearCss.notransp()
+
+,style=label.style\_label\_down
+
+,size=size.tiny)
+
+
+
+
+
+ifshowOBandper
+
+ifclose\<btm.yandnotbtm.crossed
+
+btm.crossed:=true
+
+
+
+
+
+minima=min\[1]
+
+maxima=max\[1]
+
+loc=time\[1]
+
+
+
+
+
+fori=1to (n-btm.x)-1
+
+maxima:=math.max(max\[i],maxima)
+
+minima:=maxima==max\[i] ?min\[i] :minima
+
+loc:=maxima==max\[i] ?time\[i] :loc
+
+bearish\_ob.unshift(ob.new(maxima,minima,loc))
+
+
+
+
+
+ifbearish\_ob.size() >0
+
+fori=bearish\_ob.size()-1to0
+
+element=bearish\_ob.get(i)
+
+
+
+
+
+ifnotelement.breaker
+
+ifmath.max(close,open) >element.top
+
+element.breaker:=true
+
+element.break\_loc:=time
+
+else
+
+ifclose\<element.btm
+
+bearish\_ob.remove(i)
+
+elseifi\<showBearandbtm.y>element.btmandbtm.y\<element.top
+
+brBrkConf:=1
+
+
+
+
+
+//Set label
+
+ifbrBrkConf>brBrkConf\[1] andshowLabels
+
+label.new(btm.x,btm.y,'▲',color=na
+
+,textcolor=bullCss.notransp()
+
+,style=label.style\_label\_up
+
+,size=size.tiny)
+
+
+
+
+
+//-----------------------------------------------------------------------------}
+
+//Set Order Blocks
+
+//-----------------------------------------------------------------------------{
+
+ifbarstate.islastandshowOB
+
+ifa\_bx\_ln\_lb.size() >0
+
+fori=a\_bx\_ln\_lb.size() -1to0
+
+item=a\_bx\_ln\_lb.remove(i)
+
+item.bx.delete()
+
+item.ln.delete()
+
+item.lb.delete()
+
+//Bullish
+
+ifshowBull>0
+
+blSz=bullish\_ob.size()
+
+ifblSz>0
+
+fori=0tomath.min(showBull,bullish\_ob.size()) -1
+
+get\_ob=bullish\_ob.get(i)
+
+get\_ob.display(bullCss,bullBrkCss,'bl')
+
+//Bearish
+
+ifshowBear>0
+
+brSz=bearish\_ob.size()
+
+ifbrSz>0
+
+fori=0tomath.min(showBear,bearish\_ob.size()) -1
+
+get\_ob=bearish\_ob.get(i)
+
+get\_ob.display(bearCss,bearBrkCss,'br')
+
+
+
+
+
+//-----------------------------------------------------------------------------}
+
+//Fibonacci
+
+//-----------------------------------------------------------------------------{
+
+ifbarstate.islast
+
+x1=0,y1=0.,x2=0,y2=0.,boxup=na,boxdn=na
+
+switchiFib
+
+'FVG'=>
+
+ifbFVG\_UP.size() >0andbFVG\_DN.size() >0
+
+up:=bFVG\_UP.get(0).box
+
+dn:=bFVG\_DN.get(0).box
+
+dnFirst=up.get\_left() >dn.get\_left()
+
+dnBottm=up.get\_top () >dn.get\_top ()
+
+x1:=dnFirst?dn.get\_left () :up.get\_left ()
+
+x2:=dnFirst?up.get\_right () :dn.get\_right ()
+
+y1:=dnFirst?
+
+dnBottm?dn.get\_bottom() :dn.get\_top () :
+
+dnBottm?up.get\_top () :up.get\_bottom()
+
+y2:=dnFirst?
+
+dnBottm?up.get\_top () :up.get\_bottom() :
+
+dnBottm?dn.get\_bottom() :dn.get\_top ()
+
+'BPR'=>
+
+ifbBPR\_UP.size() >0andbBPR\_DN.size() >0
+
+up:=bBPR\_UP.get(0).box
+
+dn:=bBPR\_DN.get(0).box
+
+dnFirst=up.get\_left() >dn.get\_left()
+
+dnBottm=up.get\_top () >dn.get\_top ()
+
+x1:=dnFirst?dn.get\_left () :up.get\_left ()
+
+x2:=dnFirst?up.get\_right () :dn.get\_right ()
+
+y1:=dnFirst?
+
+dnBottm?dn.get\_bottom() :dn.get\_top () :
+
+dnBottm?up.get\_top () :up.get\_bottom()
+
+y2:=dnFirst?
+
+dnBottm?up.get\_top () :up.get\_bottom() :
+
+dnBottm?dn.get\_bottom() :dn.get\_top ()
+
+'OB'=>
+
+oSz=a\_bx\_ln\_lb.size()
+
+ifoSz>1
+
+xA=nz(
+
+a\_bx\_ln\_lb.get(oSz-1).ln.get\_x1 () 
+
+,a\_bx\_ln\_lb.get(oSz-1).bx.get\_left ()
+
+&#x20;)
+
+xB=nz(
+
+a\_bx\_ln\_lb.get(oSz-2).ln.get\_x1 () 
+
+,a\_bx\_ln\_lb.get(oSz-2).bx.get\_left ()
+
+&#x20;) 
+
+AFirst=xB>xA
+
+//
+
+yAT=nz(
+
+a\_bx\_ln\_lb.get(oSz-1).ln.get\_y1 () 
+
+,a\_bx\_ln\_lb.get(oSz-1).bx.get\_top ()
+
+&#x20;)
+
+yAB=nz(
+
+a\_bx\_ln\_lb.get(oSz-1).ln.get\_y1 () 
+
+,a\_bx\_ln\_lb.get(oSz-1).bx.get\_bottom()
+
+&#x20;) 
+
+yBT=nz(
+
+a\_bx\_ln\_lb.get(oSz-2).ln.get\_y1 () 
+
+,a\_bx\_ln\_lb.get(oSz-2).bx.get\_top ()
+
+&#x20;)
+
+yBB=nz(
+
+a\_bx\_ln\_lb.get(oSz-2).ln.get\_y1 () 
+
+,a\_bx\_ln\_lb.get(oSz-2).bx.get\_bottom()
+
+&#x20;) 
+
+ABottom=yAB\<yBB
+
+//
+
+x1:=AFirst?xA:xB
+
+x2:=AFirst?xB:xA
+
+y1:=AFirst?
+
+ABottom?yAB:yAT:
+
+ABottom?yBT:yBB
+
+y2:=AFirst?
+
+ABottom?yBT:yBB:
+
+ABottom?yAB:yAT
+
+'Liq'=>
+
+ifb\_liq\_B.size() >0andb\_liq\_S.size() >0
+
+xA=nz(
+
+b\_liq\_B.get(0).ln.get\_x1 () 
+
+,b\_liq\_B.get(0).bx.get\_left ()
+
+&#x20;)
+
+xB=nz(
+
+b\_liq\_S.get(0).ln.get\_x1 () 
+
+,b\_liq\_S.get(0).bx.get\_left ()
+
+&#x20;) 
+
+AFirst=xB>xA
+
+//
+
+yAT=nz(
+
+b\_liq\_B.get(0).ln.get\_y1 () 
+
+,b\_liq\_B.get(0).bx.get\_top ()
+
+&#x20;)
+
+yAB=nz(
+
+b\_liq\_B.get(0).ln.get\_y1 () 
+
+,b\_liq\_B.get(0).bx.get\_bottom()
+
+&#x20;) 
+
+yBT=nz(
+
+b\_liq\_S.get(0).ln.get\_y1 () 
+
+,b\_liq\_S.get(0).bx.get\_top ()
+
+&#x20;)
+
+yBB=nz(
+
+b\_liq\_S.get(0).ln.get\_y1 () 
+
+,b\_liq\_S.get(0).bx.get\_bottom()
+
+&#x20;) 
+
+ABottom=yAB\<yBB
+
+//
+
+x1:=AFirst?xA:xB
+
+x2:=AFirst?xB:xA
+
+y1:=AFirst?
+
+ABottom?yAB:yAT:
+
+ABottom?yBT:yBB
+
+y2:=AFirst?
+
+ABottom?yBT:yBB:
+
+ABottom?yAB:yAT
+
+'VI'=>
+
+ifVimbal.size() >1
+
+AxA=Vimbal.get(1).l2.get\_x1(),AxB=Vimbal.get(1).l1.get\_x1()
+
+BxA=Vimbal.get(0).l2.get\_x1(),BxB=Vimbal.get(0).l1.get\_x1()
+
+AyA=Vimbal.get(1).l2.get\_y1(),AyB=Vimbal.get(1).l1.get\_y1()
+
+ByA=Vimbal.get(0).l2.get\_y1(),ByB=Vimbal.get(0).l1.get\_y1()
+
+ABt=math.min(ByA,ByB) >math.min(AyA,AyB) 
+
+x1:=math.max(AxA,AxB) 
+
+x2:=math.max(BxA,BxB) 
+
+y1:=ABt?math.min(AyA,AyB) :math.max(AyA,AyB) 
+
+y2:=ABt?math.max(ByA,ByB) :math.min(ByA,ByB) 
+
+'NWOG'=>
+
+ifbl\_NWOG.size() >1
+
+up:=bl\_NWOG.get(0).b
+
+dn:=bl\_NWOG.get(1).b
+
+dnFirst=up.get\_left() >dn.get\_left()
+
+dnBottm=up.get\_top () >dn.get\_top ()
+
+x1:=dnFirst?dn.get\_left () :up.get\_left ()
+
+x2:=dnFirst?up.get\_right() :dn.get\_right()
+
+y1:=dnFirst?
+
+dnBottm?dn.get\_bottom() :dn.get\_top () :
+
+dnBottm?up.get\_top () :up.get\_bottom()
+
+y2:=dnFirst?
+
+dnBottm?up.get\_top () :up.get\_bottom() :
+
+dnBottm?dn.get\_bottom() :dn.get\_top ()
+
+//
+
+ifiFib!='NONE'
+
+rt=math.max(x1,x2)
+
+lt=math.min(x1,x2)
+
+tp=math.max(y1,y2)
+
+bt=math.min(y1,y2)
+
+\_0=rt==x1?y1:y2
+
+\_1=rt==x1?y2:y1
+
+//
+
+df=\_1-\_0
+
+m0236=df\*0.236
+
+m0382=df\*0.382
+
+m0500=df\*0.500
+
+m0618=df\*0.618
+
+m0786=df\*0.786
+
+m1618=df\*1.618
+
+//
+
+\_diag.setLine(x1,y1,x2,y2 )
+
+\_vert.setLine(rt,\_0,rt,\_0+m1618)
+
+\_zero.setLine(rt,\_0,rt+plus,\_0 )
+
+\_0236.setLine(rt,\_0+m0236,rt+plus,\_0+m0236)
+
+\_0382.setLine(rt,\_0+m0382,rt+plus,\_0+m0382)
+
+\_0500.setLine(rt,\_0+m0500,rt+plus,\_0+m0500)
+
+\_0618.setLine(rt,\_0+m0618,rt+plus,\_0+m0618)
+
+\_0786.setLine(rt,\_0+m0786,rt+plus,\_0+m0786)
+
+\_one\_.setLine(rt,\_1,rt+plus,\_1 )
+
+\_1618.setLine(rt,\_0+m1618,rt+plus,\_0+m1618)
+
+
+
+
+
+//-----------------------------------------------------------------------------}
+
+//Displacement
+
+//-----------------------------------------------------------------------------{
+
+plotshape(sDispl?per?
+
+L\_bodyUP?low:na:na:na
+
+,title='Displacement UP'
+
+,style=shape.labelup
+
+,color=color.lime
+
+,location=location.belowbar)
+
+plotshape(sDispl?per?
+
+L\_bodyDN?high:na:na:na
+
+,title='Displacement DN'
+
+,style=shape.labeldown
+
+,color=color.red
+
+,location=location.abovebar)
+
+
+
+
+
+//-----------------------------------------------------------------------------}
+
+//background - Killzones
+
+//-----------------------------------------------------------------------------{
+
+bgcolor (per?ny?nyCss:na:na,editable=false)
+
+bgcolor (per?ldn\_open?ldnoCss:na:na,editable=false)
+
+bgcolor (per?ldn\_close?ldncCss:na:na,editable=false)
+
+bgcolor (per?asian?asiaCss:na:na,editable=false)
+
+
+
+
+
+//-----------------------------------------------------------------------------}
diff --git a/ICT Killzones & Pivots [TFO]_,_ICT Killzones & Pivots [TFO].md b/ICT Killzones & Pivots [TFO]_,_ICT Killzones & Pivots [TFO].md
new file mode 100644
index 0000000..817575d
--- /dev/null
+++ b/ICT Killzones & Pivots [TFO]_,_ICT Killzones & Pivots [TFO].md	
@@ -0,0 +1,1673 @@
+# ICT Killzones & Pivots \[TFO]","ICT Killzones & Pivots \[TFO]
+
+// This source code is subject to the terms of the Mozilla Public License 2.0 at https://mozilla.org/MPL/2.0/
+
+// © tradeforopp
+
+
+
+
+
+//@version=6
+
+indicator("ICT Killzones & Pivots \[TFO]","ICT Killzones & Pivots \[TFO]",true,max\_labels\_count=500,max\_lines\_count=500,max\_boxes\_count=500) 
+
+
+
+
+
+
+
+// ---------------------------------------- Constant Functions --------------------------------------------------
+
+get\_line\_type(\_style) =>
+
+switch\_style
+
+"Solid"=>line.style\_solid
+
+"Dotted"=>line.style\_dotted
+
+"Dashed"=>line.style\_dashed
+
+
+
+
+
+get\_size(x) =>
+
+switchx
+
+"Auto"=>size.auto
+
+"Tiny"=>size.tiny
+
+"Small"=>size.small
+
+"Normal"=>size.normal
+
+"Large"=>size.large
+
+"Huge"=>size.huge
+
+
+
+
+
+get\_table\_pos(pos) =>
+
+switchpos
+
+"Bottom Center"=>position.bottom\_center
+
+"Bottom Left"=>position.bottom\_left
+
+"Bottom Right"=>position.bottom\_right
+
+"Middle Center"=>position.middle\_center
+
+"Middle Left"=>position.middle\_left
+
+"Middle Right"=>position.middle\_right
+
+"Top Center"=>position.top\_center
+
+"Top Left"=>position.top\_left
+
+"Top Right"=>position.top\_right
+
+// ---------------------------------------- Constant Functions --------------------------------------------------
+
+
+
+
+
+
+
+// ---------------------------------------- Inputs --------------------------------------------------
+
+varg\_SETTINGS="Settings"
+
+max\_days=input.int(3,"Session Drawing Limit",1,tooltip="Only this many drawings will be kept on the chart, for each selected drawing type (killzone boxes, pivot lines, open lines, etc.)",group=g\_SETTINGS)
+
+tf\_limit=input.timeframe("30","Timeframe Limit",tooltip="Drawings will not appear on timeframes greater than or equal to this",group=g\_SETTINGS)
+
+gmt\_tz=input.string('America/New\_York',"Timezone",options= \['America/New\_York','GMT-12','GMT-11','GMT-10','GMT-9','GMT-8','GMT-7','GMT-6','GMT-5','GMT-4','GMT-3','GMT-2','GMT-1','GMT+0','GMT+1','GMT+2','GMT+3','GMT+4','GMT+5','GMT+6','GMT+7','GMT+8','GMT+9','GMT+10','GMT+11','GMT+12','GMT+13','GMT+14'],tooltip="Note GMT is not adjusted to reflect Daylight Saving Time changes",group=g\_SETTINGS)
+
+lbl\_size=get\_size(input.string('Normal',"Label Size",options= \['Auto','Tiny','Small','Normal','Large','Huge'],tooltip="The size of all labels",group=g\_SETTINGS))
+
+txt\_color=input.color(color.black,"Text Color",tooltip="The color of all label and table text",group=g\_SETTINGS)
+
+use\_cutoff=input.bool(false,"Drawing Cutoff Time",inline="CO",tooltip="When enabled, all pivots and open price lines will stop extending at this time",group=g\_SETTINGS)
+
+cutoff=input.session("1800-1801","",inline="CO",group=g\_SETTINGS)
+
+
+
+
+
+vartf\_limit\_is\_equal\_or\_more\_chart\_tf=timeframe.in\_seconds('') <=timeframe.in\_seconds(tf\_limit)
+
+
+
+
+
+varg\_KZ="Killzones"
+
+show\_kz=input.bool(true,"Show Killzone Boxes",inline="KZ",group=g\_KZ)
+
+show\_kz\_text=input.bool(true,"Display Text",inline="KZ",group=g\_KZ)
+
+
+
+
+
+use\_asia=input.bool(true,"",inline="ASIA",group=g\_KZ)
+
+as\_txt=input.string("Asia","",inline="ASIA",group=g\_KZ)
+
+asia=input.session("2000-0000","",inline="ASIA",group=g\_KZ)
+
+as\_color=input.color(color.blue,"",inline="ASIA",group=g\_KZ)
+
+
+
+
+
+use\_london=input.bool(true,"",inline="LONDON",group=g\_KZ)
+
+lo\_txt=input.string("London","",inline="LONDON",group=g\_KZ)
+
+london=input.session("0200-0500","",inline="LONDON",group=g\_KZ)
+
+lo\_color=input.color(color.red,"",inline="LONDON",group=g\_KZ)
+
+
+
+
+
+use\_nyam=input.bool(true,"",inline="NYAM",group=g\_KZ)
+
+na\_txt=input.string("NY AM","",inline="NYAM",group=g\_KZ)
+
+nyam=input.session("0930-1100","",inline="NYAM",group=g\_KZ)
+
+na\_color=input.color(#089981,"",inline="NYAM",group=g\_KZ)
+
+
+
+
+
+use\_nylu=input.bool(true,"",inline="NYLU",group=g\_KZ)
+
+nl\_txt=input.string("NY Lunch","",inline="NYLU",group=g\_KZ)
+
+nylu=input.session("1200-1300","",inline="NYLU",group=g\_KZ)
+
+nl\_color=input.color(color.yellow,"",inline="NYLU",group=g\_KZ)
+
+
+
+
+
+use\_nypm=input.bool(true,"",inline="NYPM",group=g\_KZ)
+
+np\_txt=input.string("NY PM","",inline="NYPM",group=g\_KZ)
+
+nypm=input.session("1330-1600","",inline="NYPM",group=g\_KZ)
+
+np\_color=input.color(color.purple,"",inline="NYPM",group=g\_KZ)
+
+
+
+
+
+box\_transparency=input.int(70,"Box Transparency",0,100,group=g\_KZ)
+
+text\_transparency=input.int(50,"Text Transparency",0,100,group=g\_KZ)
+
+
+
+
+
+
+
+varg\_LABELS="Killzone Pivots"
+
+show\_pivots=input.bool(true,"Show Pivots",inline="PV",group=g\_LABELS)
+
+use\_alerts=input.bool(true,"Alert Broken Pivots",inline="PV",tooltip="The desired killzones must be enabled at the time that an alert is created, along with the show pivots option, in order for alerts to work",group=g\_LABELS)
+
+show\_midpoints=input.bool(false,"Show Pivot Midpoints",inline="mp",group=g\_LABELS)
+
+stop\_midpoints=input.bool(true,"Stop Once Mitigated",inline="mp",group=g\_LABELS) 
+
+show\_labels=input.bool(true,"Show Pivot Labels",inline="LB",tooltip="Show labels denoting each killzone's high and low. Optionally choose to show the price of each level. Right side will show labels on the right-hand side of the chart until they are reached",group=g\_LABELS)
+
+label\_price=input.bool(false,"Display Price",inline="LB",group=g\_LABELS)
+
+label\_right=input.bool(false,"Right Side",inline="LB",group=g\_LABELS)
+
+ext\_pivots=input.string("Until Mitigated","Extend Pivots...",options= \['Until Mitigated','Past Mitigation'],group=g\_LABELS)
+
+ext\_which=input.string("Most Recent","...From Which Sessions",options= \['Most Recent','All'],group=g\_LABELS)
+
+
+
+
+
+ash\_str=input.string("AS.H","Killzone 1 Labels",inline="L\_AS",group=g\_LABELS)
+
+asl\_str=input.string("AS.L","",inline="L\_AS",group=g\_LABELS)
+
+
+
+
+
+loh\_str=input.string("LO.H","Killzone 2 Labels",inline="L\_LO",group=g\_LABELS)
+
+lol\_str=input.string("LO.L","",inline="L\_LO",group=g\_LABELS)
+
+
+
+
+
+nah\_str=input.string("NYAM.H","Killzone 3 Labels",inline="L\_NA",group=g\_LABELS)
+
+nal\_str=input.string("NYAM.L","",inline="L\_NA",group=g\_LABELS)
+
+
+
+
+
+nlh\_str=input.string("NYL.H","Killzone 4 Labels",inline="L\_NL",group=g\_LABELS)
+
+nll\_str=input.string("NYL.L","",inline="L\_NL",group=g\_LABELS)
+
+
+
+
+
+nph\_str=input.string("NYPM.H","Killzone 5 Labels",inline="L\_NP",group=g\_LABELS)
+
+npl\_str=input.string("NYPM.L","",inline="L\_NP",group=g\_LABELS)
+
+
+
+
+
+kzp\_style=get\_line\_type(input.string(defval='Solid',title="Pivot Style",options= \['Solid','Dotted','Dashed'],inline="KZP",group=g\_LABELS))
+
+kzp\_width=input.int(1,"",inline="KZP",group=g\_LABELS)
+
+kzm\_style=get\_line\_type(input.string(defval='Dotted',title="Midpoint Style",options= \['Solid','Dotted','Dashed'],inline="KZM",group=g\_LABELS))
+
+kzm\_width=input.int(1,"",inline="KZM",group=g\_LABELS)
+
+
+
+
+
+
+
+varg\_RNG="Killzone Range"
+
+show\_range=input.bool(false,"Show Killzone Range",tooltip="Show the most recent ranges of each selected killzone, from high to low",group=g\_RNG)
+
+show\_range\_avg=input.bool(true,"Show Average",tooltip="Show the average range of each selected killzone",group=g\_RNG)
+
+range\_avg=input.int(5,"Average Length",0,tooltip="This many previous sessions will be used to calculate the average. If there isn't enough data on the current chart, it will use as many sessions as possible",group=g\_RNG)
+
+range\_pos=get\_table\_pos(input.string('Top Right',"Table Position",options= \['Bottom Center','Bottom Left','Bottom Right','Middle Center','Middle Left','Middle Right','Top Center','Top Left','Top Right'],group=g\_RNG))
+
+range\_size=get\_size(input.string('Normal',"Table Size",options= \['Auto','Tiny','Small','Normal','Large','Huge'],group=g\_RNG))
+
+
+
+
+
+
+
+varg\_DWM="Day - Week - Month"
+
+sep\_unlimited=input.bool(false,"Unlimited",tooltip="Unlimited will show as many of the selected lines as possible. Otherwise, the session drawing limit will be used",group=g\_DWM)
+
+alert\_HL=input.bool(false,"Alert High/Low Break",tooltip="Alert when any selected highs and lows are traded through. The desired timeframe's high/low option must be enabled at the time that an alert is created",group=g\_DWM)
+
+
+
+
+
+show\_d\_open=input.bool(false,"D Open",inline="DO",group=g\_DWM)
+
+dhl=input.bool(false,"High/Low",inline="DO",tooltip="",group=g\_DWM)
+
+ds=input.bool(false,"Separators",inline="DO",tooltip="Mark where a new day begins",group=g\_DWM)
+
+d\_color=input.color(color.blue,"",inline="DO",group=g\_DWM)
+
+
+
+
+
+show\_w\_open=input.bool(false,"W Open",inline="WO",group=g\_DWM)
+
+whl=input.bool(false,"High/Low",inline="WO",tooltip="",group=g\_DWM)
+
+ws=input.bool(false,"Separators",inline="WO",tooltip="Mark where a new week begins",group=g\_DWM)
+
+w\_color=input.color(#089981,"",inline="WO",group=g\_DWM)
+
+
+
+
+
+show\_m\_open=input.bool(false,"M Open",inline="MO",group=g\_DWM)
+
+mhl=input.bool(false,"High/Low",inline="MO",tooltip="",group=g\_DWM)
+
+ms=input.bool(false,"Separators",inline="MO",tooltip="Mark where a new month begins",group=g\_DWM)
+
+m\_color=input.color(color.red,"",inline="MO",group=g\_DWM)
+
+
+
+
+
+htf\_style=get\_line\_type(input.string(defval='Solid',title="Style",options= \['Solid','Dotted','Dashed'],inline="D0",group=g\_DWM))
+
+htf\_width=input.int(1,"",inline="D0",group=g\_DWM)
+
+
+
+
+
+dow\_labels=input.bool(true,"Day of Week Labels",inline="DOW",group=g\_DWM)
+
+dow\_yloc=input.string('Bottom',"",options= \['Top','Bottom'],inline="DOW",group=g\_DWM)
+
+dow\_xloc=input.string('Midnight',"",options= \['Midnight','Midday'],inline="DOW",group=g\_DWM)
+
+dow\_hide\_wknd=input.bool(true,"Hide Weekend Labels",group=g\_DWM)
+
+
+
+
+
+
+
+varg\_OPEN="Opening Prices"
+
+open\_unlimited=input.bool(false,"Unlimited",tooltip="Unlimited will show as many of the selected lines as possible. Otherwise, the session drawing limit will be used",group=g\_OPEN)
+
+
+
+
+
+use\_h1=input.bool(false,"",inline="H1",group=g\_OPEN)
+
+h1\_text=input.string("True Day Open","",inline="H1",group=g\_OPEN)
+
+h1=input.session("0000-0001","",inline="H1",group=g\_OPEN)
+
+h1\_color=input.color(color.black,"",inline="H1",group=g\_OPEN)
+
+
+
+
+
+use\_h2=input.bool(false,"",inline="H2",group=g\_OPEN)
+
+h2\_text=input.string("06:00","",inline="H2",group=g\_OPEN)
+
+h2=input.session("0600-0601","",inline="H2",group=g\_OPEN)
+
+h2\_color=input.color(color.black,"",inline="H2",group=g\_OPEN)
+
+
+
+
+
+use\_h3=input.bool(false,"",inline="H3",group=g\_OPEN)
+
+h3\_text=input.string("10:00","",inline="H3",group=g\_OPEN)
+
+h3=input.session("1000-1001","",inline="H3",group=g\_OPEN)
+
+h3\_color=input.color(color.black,"",inline="H3",group=g\_OPEN)
+
+
+
+
+
+use\_h4=input.bool(false,"",inline="H4",group=g\_OPEN)
+
+h4\_text=input.string("14:00","",inline="H4",group=g\_OPEN)
+
+h4=input.session("1400-1401","",inline="H4",group=g\_OPEN)
+
+h4\_color=input.color(color.black,"",inline="H4",group=g\_OPEN)
+
+
+
+
+
+use\_h5=input.bool(false,"",inline="H5",group=g\_OPEN)
+
+h5\_text=input.string("00:00","",inline="H5",group=g\_OPEN)
+
+h5=input.session("0000-0001","",inline="H5",group=g\_OPEN)
+
+h5\_color=input.color(color.black,"",inline="H5",group=g\_OPEN)
+
+
+
+
+
+use\_h6=input.bool(false,"",inline="H6",group=g\_OPEN)
+
+h6\_text=input.string("00:00","",inline="H6",group=g\_OPEN)
+
+h6=input.session("0000-0001","",inline="H6",group=g\_OPEN)
+
+h6\_color=input.color(color.black,"",inline="H6",group=g\_OPEN)
+
+
+
+
+
+use\_h7=input.bool(false,"",inline="H7",group=g\_OPEN)
+
+h7\_text=input.string("00:00","",inline="H7",group=g\_OPEN)
+
+h7=input.session("0000-0001","",inline="H7",group=g\_OPEN)
+
+h7\_color=input.color(color.black,"",inline="H7",group=g\_OPEN)
+
+
+
+
+
+use\_h8=input.bool(false,"",inline="H8",group=g\_OPEN)
+
+h8\_text=input.string("00:00","",inline="H8",group=g\_OPEN)
+
+h8=input.session("0000-0001","",inline="H8",group=g\_OPEN)
+
+h8\_color=input.color(color.black,"",inline="H8",group=g\_OPEN)
+
+
+
+
+
+hz\_style=get\_line\_type(input.string(defval='Dotted',title="Style",options= \['Solid','Dotted','Dashed'],inline="H0",group=g\_OPEN))
+
+hz\_width=input.int(1,"",inline="H0",group=g\_OPEN)
+
+
+
+
+
+
+
+varg\_VERTICAL="Timestamps"
+
+v\_unlimited=input.bool(false,"Unlimited",tooltip="Unlimited will show as many of the selected lines as possible. Otherwise, the session drawing limit will be used",group=g\_VERTICAL)
+
+
+
+
+
+use\_v1=input.bool(false,"",inline="V1",group=g\_VERTICAL)
+
+v1=input.session("0000-0001","",inline="V1",group=g\_VERTICAL)
+
+v1\_color=input.color(color.black,"",inline="V1",group=g\_VERTICAL)
+
+
+
+
+
+use\_v2=input.bool(false,"",inline="V2",group=g\_VERTICAL)
+
+v2=input.session("0800-0801","",inline="V2",group=g\_VERTICAL)
+
+v2\_color=input.color(color.black,"",inline="V2",group=g\_VERTICAL)
+
+
+
+
+
+use\_v3=input.bool(false,"",inline="V3",group=g\_VERTICAL)
+
+v3=input.session("1000-1001","",inline="V3",group=g\_VERTICAL)
+
+v3\_color=input.color(color.black,"",inline="V3",group=g\_VERTICAL)
+
+
+
+
+
+use\_v4=input.bool(false,"",inline="V4",group=g\_VERTICAL)
+
+v4=input.session("1200-1201","",inline="V4",group=g\_VERTICAL)
+
+v4\_color=input.color(color.black,"",inline="V4",group=g\_VERTICAL)
+
+
+
+
+
+vl\_style=get\_line\_type(input.string(defval='Dotted',title="Style",options= \['Solid','Dotted','Dashed'],inline="V0",group=g\_VERTICAL))
+
+vl\_width=input.int(1,"",inline="V0",group=g\_VERTICAL)
+
+// ---------------------------------------- Inputs --------------------------------------------------
+
+
+
+
+
+
+
+// ---------------------------------------- Variables & Constants --------------------------------------------------
+
+typekz
+
+string\_title
+
+
+
+
+
+array\<box> \_box
+
+
+
+
+
+array\<line> \_hi\_line
+
+array\<line> \_md\_line
+
+array\<line> \_lo\_line
+
+
+
+
+
+array\<label> \_hi\_label
+
+array\<label> \_lo\_label
+
+
+
+
+
+array\<bool> \_hi\_valid
+
+array\<bool> \_md\_valid
+
+array\<bool> \_lo\_valid
+
+
+
+
+
+array\<float> \_range\_store
+
+float\_range\_current
+
+
+
+
+
+typehz
+
+array\<line> LN
+
+array\<label> LB
+
+array\<bool> CO
+
+
+
+
+
+typedwm\_hl
+
+array\<line> hi\_line
+
+array\<line> lo\_line
+
+array\<label> hi\_label
+
+array\<label> lo\_label
+
+boolhit\_high=false
+
+boolhit\_low=false
+
+
+
+
+
+typedwm\_info
+
+stringtf
+
+floato=na
+
+floath=na
+
+floatl=na
+
+floatph=na
+
+floatpl=na
+
+
+
+
+
+typelines\_helper
+
+hz\_hz
+
+stringh
+
+stringh\_text
+
+colorh\_color
+
+
+
+
+
+initLines() =>
+
+array\<lines\_helper> res=array.new\<lines\_helper>()
+
+ifuse\_h1
+
+res.push(lines\_helper.new(hz.new(array.new\_line(),array.new\_label(),array.new\_bool()),h1,h1\_text,h1\_color))
+
+ifuse\_h2
+
+res.push(lines\_helper.new(hz.new(array.new\_line(),array.new\_label(),array.new\_bool()),h2,h2\_text,h2\_color))
+
+ifuse\_h3
+
+res.push(lines\_helper.new(hz.new(array.new\_line(),array.new\_label(),array.new\_bool()),h3,h3\_text,h3\_color))
+
+ifuse\_h4
+
+res.push(lines\_helper.new(hz.new(array.new\_line(),array.new\_label(),array.new\_bool()),h4,h4\_text,h4\_color))
+
+ifuse\_h5
+
+res.push(lines\_helper.new(hz.new(array.new\_line(),array.new\_label(),array.new\_bool()),h5,h5\_text,h5\_color))
+
+ifuse\_h6
+
+res.push(lines\_helper.new(hz.new(array.new\_line(),array.new\_label(),array.new\_bool()),h6,h6\_text,h6\_color))
+
+ifuse\_h7
+
+res.push(lines\_helper.new(hz.new(array.new\_line(),array.new\_label(),array.new\_bool()),h7,h7\_text,h7\_color))
+
+ifuse\_h8
+
+res.push(lines\_helper.new(hz.new(array.new\_line(),array.new\_label(),array.new\_bool()),h8,h8\_text,h8\_color))
+
+res
+
+
+
+
+
+vararray\<lines\_helper> lines=initLines()
+
+
+
+
+
+typekz\_helper
+
+kz\_kz
+
+stringsession
+
+colorc
+
+stringbox\_txt
+
+stringhi\_txt
+
+stringlo\_txt
+
+
+
+
+
+initKZ() =>
+
+array\<kz\_helper> res=array.new\<kz\_helper>()
+
+ifuse\_asia
+
+res.push(kz\_helper.new(
+
+kz.new(as\_txt,array.new\_box(),array.new\_line(),array.new\_line(),array.new\_line(),array.new\_label(),array.new\_label(),array.new\_bool(),array.new\_bool(),array.new\_bool(),array.new\_float()),
+
+asia,as\_color,as\_txt,ash\_str,asl\_str
+
+&#x20;))
+
+ifuse\_london
+
+res.push(kz\_helper.new(
+
+kz.new(lo\_txt,array.new\_box(),array.new\_line(),array.new\_line(),array.new\_line(),array.new\_label(),array.new\_label(),array.new\_bool(),array.new\_bool(),array.new\_bool(),array.new\_float()),
+
+london,lo\_color,lo\_txt,loh\_str,lol\_str
+
+&#x20;))
+
+ifuse\_nyam
+
+res.push(kz\_helper.new(
+
+kz.new(na\_txt,array.new\_box(),array.new\_line(),array.new\_line(),array.new\_line(),array.new\_label(),array.new\_label(),array.new\_bool(),array.new\_bool(),array.new\_bool(),array.new\_float()),
+
+nyam,na\_color,na\_txt,nah\_str,nal\_str
+
+&#x20;))
+
+ifuse\_nylu
+
+res.push(kz\_helper.new(
+
+kz.new(nl\_txt,array.new\_box(),array.new\_line(),array.new\_line(),array.new\_line(),array.new\_label(),array.new\_label(),array.new\_bool(),array.new\_bool(),array.new\_bool(),array.new\_float()),
+
+nylu,nl\_color,nl\_txt,nlh\_str,nll\_str
+
+&#x20;))
+
+ifuse\_nypm
+
+res.push(kz\_helper.new(
+
+kz.new(np\_txt,array.new\_box(),array.new\_line(),array.new\_line(),array.new\_line(),array.new\_label(),array.new\_label(),array.new\_bool(),array.new\_bool(),array.new\_bool(),array.new\_float()),
+
+nypm,np\_color,np\_txt,nph\_str,npl\_str
+
+&#x20;))
+
+res
+
+
+
+
+
+vararray\<kz\_helper> \_kz=initKZ()
+
+
+
+
+
+
+
+vard\_hl=dwm\_hl.new(array.new\_line(),array.new\_line(),array.new\_label(),array.new\_label())
+
+varw\_hl=dwm\_hl.new(array.new\_line(),array.new\_line(),array.new\_label(),array.new\_label())
+
+varm\_hl=dwm\_hl.new(array.new\_line(),array.new\_line(),array.new\_label(),array.new\_label())
+
+
+
+
+
+vard\_info=dwm\_info.new("D")
+
+varw\_info=dwm\_info.new("W")
+
+varm\_info=dwm\_info.new("M")
+
+
+
+
+
+t\_co=notna(time("",cutoff,gmt\_tz))
+
+
+
+
+
+typets\_helper
+
+stringsession
+
+array\<line> lines
+
+colorc
+
+
+
+
+
+initTS() =>
+
+array\<ts\_helper> res=array.new\<ts\_helper>()
+
+ifuse\_v1
+
+res.push(ts\_helper.new(v1,array.new\_line(),v1\_color))
+
+ifuse\_v2
+
+res.push(ts\_helper.new(v2,array.new\_line(),v2\_color))
+
+ifuse\_v3
+
+res.push(ts\_helper.new(v3,array.new\_line(),v3\_color))
+
+ifuse\_v4
+
+res.push(ts\_helper.new(v4,array.new\_line(),v4\_color))
+
+res
+
+
+
+
+
+vararray\<ts\_helper> ts\_data=initTS()
+
+
+
+
+
+vard\_sep\_line=array.new\_line()
+
+varw\_sep\_line=array.new\_line()
+
+varm\_sep\_line=array.new\_line()
+
+
+
+
+
+vard\_line=array.new\_line()
+
+varw\_line=array.new\_line()
+
+varm\_line=array.new\_line()
+
+
+
+
+
+vard\_label=array.new\_label()
+
+varw\_label=array.new\_label()
+
+varm\_label=array.new\_label()
+
+
+
+
+
+vartransparent=#ffffff00
+
+varext\_current=ext\_which=='Most Recent'
+
+varext\_past=ext\_pivots=='Past Mitigation'
+
+
+
+
+
+update\_dwm\_info(dwm\_infon) =>
+
+iftimeframe.change(n.tf)
+
+n.ph:=n.h
+
+n.pl:=n.l
+
+n.o:=open
+
+n.h:=high
+
+n.l:=low
+
+else
+
+n.h:=math.max(high,n.h)
+
+n.l:=math.min(low,n.l)
+
+
+
+
+
+ifdhlorshow\_d\_open
+
+update\_dwm\_info(d\_info)
+
+ifwhlorshow\_w\_open
+
+update\_dwm\_info(w\_info)
+
+ifmhlorshow\_m\_open
+
+update\_dwm\_info(m\_info)
+
+// ---------------------------------------- Variables & Constants --------------------------------------------------
+
+
+
+
+
+
+
+// ---------------------------------------- Functions --------------------------------------------------
+
+get\_box\_color(colorc) =>
+
+color.new(c,box\_transparency)
+
+
+
+
+
+get\_text\_color(colorc) =>
+
+color.new(c,text\_transparency)
+
+// ---------------------------------------- Functions --------------------------------------------------
+
+
+
+
+
+
+
+// ---------------------------------------- Core Logic --------------------------------------------------
+
+dwm\_sep(stringtf,booluse,array\<line> arr,colorcol) =>
+
+ifuse
+
+iftimeframe.change(tf)
+
+arr.unshift(line.new(bar\_index,high\*1.0001,bar\_index,low,style=htf\_style,width=htf\_width,extend=extend.both,color=col))
+
+ifnotsep\_unlimitedandarr.size() >max\_days
+
+arr.pop().delete()
+
+
+
+
+
+
+
+dwm\_open(stringtf,booluse,array\<line> lns,array\<label> lbls,dwm\_infon,colorcol) =>
+
+ifuse
+
+iflns.size() >0
+
+lns.get(0).set\_x2(time)
+
+lbls.get(0).set\_x(time)
+
+iftimeframe.change(tf)
+
+lns.unshift(line.new(time,n.o,time,n.o,xloc=xloc.bar\_time,style=htf\_style,width=htf\_width,color=col))
+
+lbls.unshift(label.new(time,n.o,tf+" OPEN",xloc=xloc.bar\_time,style=label.style\_label\_left,color=transparent,textcolor=txt\_color,size=lbl\_size))
+
+ifnotsep\_unlimitedandlns.size() >max\_days
+
+lns.pop().delete()
+
+lbls.pop().delete()
+
+
+
+
+
+
+
+dwm\_hl(stringtf,booluse,dwm\_hlhl,dwm\_infon,colorcol) =>
+
+ifuse
+
+ifhl.hi\_line.size() >0
+
+hl.hi\_line.get(0).set\_x2(time)
+
+hl.lo\_line.get(0).set\_x2(time)
+
+hl.hi\_label.get(0).set\_x(time)
+
+hl.lo\_label.get(0).set\_x(time)
+
+iftimeframe.change(tf)
+
+hl.hi\_line.unshift(line.new(time,n.ph,time,n.ph,xloc=xloc.bar\_time,style=htf\_style,width=htf\_width,color=col))
+
+hl.lo\_line.unshift(line.new(time,n.pl,time,n.pl,xloc=xloc.bar\_time,style=htf\_style,width=htf\_width,color=col))
+
+hl.hi\_label.unshift(label.new(time,n.ph,"P"+tf+"H",xloc=xloc.bar\_time,style=label.style\_label\_left,color=transparent,textcolor=txt\_color,size=lbl\_size))
+
+hl.lo\_label.unshift(label.new(time,n.pl,"P"+tf+"L",xloc=xloc.bar\_time,style=label.style\_label\_left,color=transparent,textcolor=txt\_color,size=lbl\_size))
+
+hl.hit\_high:=false
+
+hl.hit\_low:=false
+
+ifnotsep\_unlimitedandhl.hi\_line.size() >max\_days
+
+hl.hi\_line.pop().delete()
+
+hl.lo\_line.pop().delete()
+
+hl.hi\_label.pop().delete()
+
+hl.lo\_label.pop().delete()
+
+ifhl.hi\_line.size() >0andalert\_HL
+
+ifnothl.hit\_highandhigh>hl.hi\_line.get(0).get\_y1()
+
+hl.hit\_high:=true
+
+alert(str.format("Hit P{0}H",tf))
+
+ifnothl.hit\_lowandlow\<hl.lo\_line.get(0).get\_y1()
+
+hl.hit\_low:=true
+
+alert(str.format("Hit P{0}L",tf))
+
+
+
+
+
+
+
+dwm() =>
+
+iftf\_limit\_is\_equal\_or\_more\_chart\_tf
+
+// DWM - Separators
+
+dwm\_sep("D",ds,d\_sep\_line,d\_color)
+
+dwm\_sep("W",ws,w\_sep\_line,w\_color)
+
+dwm\_sep("M",ms,m\_sep\_line,m\_color)
+
+
+
+
+
+// DWM - Open Lines
+
+dwm\_open("D",show\_d\_open,d\_line,d\_label,d\_info,d\_color)
+
+dwm\_open("W",show\_w\_open,w\_line,w\_label,w\_info,w\_color)
+
+dwm\_open("M",show\_m\_open,m\_line,m\_label,m\_info,m\_color)
+
+
+
+
+
+// DWM - Highs and Lows
+
+dwm\_hl("D",dhl,d\_hl,d\_info,d\_color)
+
+dwm\_hl("W",whl,w\_hl,w\_info,w\_color)
+
+dwm\_hl("M",mhl,m\_hl,m\_info,m\_color)
+
+
+
+
+
+
+
+methodvline(ts\_helperthis) =>
+
+boolt=notna(time("",this.session,gmt\_tz))
+
+boolt\_prev=notna(time("",this.session,gmt\_tz,bars\_back=1))
+
+array\<line> arr=this.lines
+
+colorcol=this.c
+
+iftandnott\_prev
+
+arr.unshift(line.new(bar\_index,high\*1.0001,bar\_index,low,style=vl\_style,width=vl\_width,extend=extend.both,color=col))
+
+ifnotv\_unlimited
+
+ifarr.size() >max\_days
+
+arr.pop().delete()
+
+
+
+
+
+
+
+vlines() =>
+
+iftf\_limit\_is\_equal\_or\_more\_chart\_tf
+
+for \[\_,value] ints\_data
+
+vline(value)
+
+
+
+
+
+methodhz\_line(lines\_helperthis) =>
+
+boolt=notna(time("",this.h,gmt\_tz))
+
+boolt\_prev=notna(time("",this.h,gmt\_tz,bars\_back=1))
+
+hzhz=this.\_hz
+
+stringtxt=this.h\_text
+
+colorcol=this.h\_color
+
+
+
+
+
+iftandnott\_prev
+
+hz.LN.unshift(line.new(bar\_index,open,bar\_index,open,style=hz\_style,width=hz\_width,color=col))
+
+hz.LB.unshift(label.new(bar\_index,open,txt,style=label.style\_label\_left,color=transparent,textcolor=txt\_color,size=lbl\_size))
+
+array.unshift(hz.CO,false)
+
+ifnotopen\_unlimitedandhz.LN.size() >max\_days
+
+hz.LN.pop().delete()
+
+hz.LB.pop().delete()
+
+hz.CO.pop()
+
+ifnottandhz.CO.size() >0
+
+ifnothz.CO.get(0)
+
+hz.LN.get(0).set\_x2(bar\_index)
+
+hz.LB.get(0).set\_x(bar\_index)
+
+if (use\_cutoff?t\_co:false)
+
+hz.CO.set(0,true)
+
+
+
+
+
+
+
+hz\_lines() =>
+
+iftf\_limit\_is\_equal\_or\_more\_chart\_tf
+
+for \[\_,value] inlines
+
+hz\_line(value)
+
+
+
+
+
+
+
+del\_kz(kzk) =>
+
+ifk.\_box.size() >max\_days
+
+k.\_box.pop().delete()
+
+ifk.\_hi\_line.size() >max\_days
+
+k.\_hi\_line.pop().delete()
+
+k.\_lo\_line.pop().delete()
+
+k.\_hi\_valid.pop()
+
+k.\_lo\_valid.pop()
+
+ifshow\_midpoints
+
+k.\_md\_line.pop().delete()
+
+k.\_md\_valid.pop()
+
+ifk.\_hi\_label.size() >max\_days
+
+k.\_hi\_label.pop().delete()
+
+k.\_lo\_label.pop().delete()
+
+
+
+
+
+update\_price\_string(labelL,floatP) =>
+
+S=L.get\_text()
+
+pre=str.substring(S,0,str.pos(S," ")) 
+
+str.trim(pre)
+
+L.set\_text(str.format("{0} ({1})",pre,P))
+
+
+
+
+
+adjust\_in\_kz(kzkz,boolt) =>
+
+ift
+
+kzBox0=kz.\_box.get(0)
+
+kzBox0.set\_right(time)
+
+newTop=math.max(kzBox0.get\_top(),high)
+
+kzBox0.set\_top(newTop)
+
+newBottom=math.min(kzBox0.get\_bottom(),low)
+
+kzBox0.set\_bottom(newBottom)
+
+
+
+
+
+kz.\_range\_current:=newTop-newBottom
+
+
+
+
+
+ifshow\_pivotsandkz.\_hi\_line.size() >0
+
+kzHiLine0=kz.\_hi\_line.get(0)
+
+kzHiLine0.set\_x2(time)
+
+ifhigh>kzHiLine0.get\_y1()
+
+kzHiLine0.set\_xy1(time,high)
+
+kzHiLine0.set\_xy2(time,high)
+
+
+
+
+
+kzLoLine0=kz.\_lo\_line.get(0)
+
+kzLoLine0.set\_x2(time)
+
+iflow\<kzLoLine0.get\_y1()
+
+kzLoLine0.set\_xy1(time,low)
+
+kzLoLine0.set\_xy2(time,low)
+
+
+
+
+
+ifshow\_midpoints
+
+kzMidLine0=kz.\_md\_line.get(0)
+
+kzMidLine0.set\_x2(time)
+
+kzMidLine0.set\_xy1(time,math.avg(kzHiLine0.get\_y2(),kzLoLine0.get\_y2()))
+
+kzMidLine0.set\_xy2(time,math.avg(kzHiLine0.get\_y2(),kzLoLine0.get\_y2()))
+
+
+
+
+
+ifshow\_labelsandkz.\_hi\_label.size() >0
+
+iflabel\_right
+
+kz.\_hi\_label.get(0).set\_x(time)
+
+kz.\_lo\_label.get(0).set\_x(time)
+
+ifhigh>kz.\_hi\_label.get(0).get\_y()
+
+kz.\_hi\_label.get(0).set\_xy(time,high)
+
+iflabel\_price
+
+update\_price\_string(kz.\_hi\_label.get(0),high)
+
+iflow\<kz.\_lo\_label.get(0).get\_y()
+
+kz.\_lo\_label.get(0).set\_xy(time,low)
+
+iflabel\_price
+
+update\_price\_string(kz.\_lo\_label.get(0),low)
+
+
+
+
+
+
+
+adjust\_out\_kz(kzkz,boolt,boolt\_prev) =>
+
+boxCount=kz.\_box.size()
+
+ifnottandboxCount>0
+
+ift\_prev
+
+array.unshift(kz.\_range\_store,kz.\_range\_current)
+
+ifkz.\_range\_store.size() >range\_avg
+
+kz.\_range\_store.pop()
+
+
+
+
+
+ifshow\_pivotsandboxCount>0
+
+fori=0toboxCount-1by1
+
+ifnotext\_currentori==0
+
+kzHiValid=kz.\_hi\_valid.get(i)
+
+ifext\_pastorkzHiValid
+
+kz.\_hi\_line.get(i).set\_x2(time)
+
+ifshow\_labelsandlabel\_right
+
+kz.\_hi\_label.get(i).set\_x(time)
+
+ifkzHiValidandhigh>kz.\_hi\_line.get(i).get\_y1()
+
+ifuse\_alertsandi==0
+
+alert('Broke '+kz.\_title+' High',alert.freq\_once\_per\_bar)
+
+kz.\_hi\_valid.set(i,false)
+
+ifshow\_labelsandlabel\_right
+
+kz.\_hi\_label.get(i).set\_style(label.style\_label\_down)
+
+elseifuse\_cutoff?t\_co:false
+
+kz.\_hi\_valid.set(i,false)
+
+
+
+
+
+kzLoValid=kz.\_lo\_valid.get(i)
+
+ifext\_pastorkzLoValid
+
+kz.\_lo\_line.get(i).set\_x2(time)
+
+ifshow\_labelsandlabel\_right
+
+kz.\_lo\_label.get(i).set\_x(time)
+
+ifkzLoValidandlow\<kz.\_lo\_line.get(i).get\_y1()
+
+ifuse\_alertsandi==0
+
+alert("Broke "+kz.\_title+" Low",alert.freq\_once\_per\_bar)
+
+kz.\_lo\_valid.set(i,false)
+
+ifshow\_labelsandlabel\_right
+
+kz.\_lo\_label.get(i).set\_style(label.style\_label\_up)
+
+elseifuse\_cutoff?t\_co:false
+
+kz.\_lo\_valid.set(i,false)
+
+
+
+
+
+ifshow\_midpointsandnott
+
+ifstop\_midpoints?kz.\_md\_valid.get(i) :true
+
+kz.\_md\_line.get(i).set\_x2(time)
+
+ifkz.\_md\_valid.get(i) andlow<=kz.\_md\_line.get(i).get\_y1() andhigh>=kz.\_md\_line.get(i).get\_y1()
+
+kz.\_md\_valid.set(i,false)
+
+
+
+
+
+else
+
+break
+
+
+
+
+
+methodmanage\_kz(kz\_helperthis) =>
+
+kzkz=this.\_kz
+
+c=this.c
+
+stringbox\_txt=this.box\_txt
+
+stringhi\_txt=this.hi\_txt
+
+stringlo\_txt=this.lo\_txt
+
+
+
+
+
+iftf\_limit\_is\_equal\_or\_more\_chart\_tf
+
+t=notna(time("",this.session,gmt\_tz))
+
+t\_prev=notna(time("",this.session,gmt\_tz,bars\_back=1))
+
+iftandnott\_prev
+
+\_c=get\_box\_color(c)
+
+\_t=get\_text\_color(c)
+
+kz.\_box.unshift(box.new(time,high,time,low,xloc=xloc.bar\_time,border\_color=show\_kz?\_c:na,bgcolor=show\_kz?\_c:na,text=show\_kzandshow\_kz\_text?box\_txt:na,text\_color=\_t))
+
+
+
+
+
+ifshow\_pivots
+
+kz.\_hi\_line.unshift(line.new(time,high,time,high,xloc=xloc.bar\_time,style=kzp\_style,color=c,width=kzp\_width))
+
+kz.\_lo\_line.unshift(line.new(time,low,time,low,xloc=xloc.bar\_time,style=kzp\_style,color=c,width=kzp\_width))
+
+ifshow\_midpoints
+
+kz.\_md\_line.unshift(line.new(time,math.avg(high,low),time,math.avg(high,low),xloc=xloc.bar\_time,style=kzm\_style,color=c,width=kzm\_width))
+
+array.unshift(kz.\_md\_valid,true)
+
+
+
+
+
+array.unshift(kz.\_hi\_valid,true)
+
+array.unshift(kz.\_lo\_valid,true)
+
+
+
+
+
+ifshow\_labels
+
+\_hi\_txt=label\_price?str.format('{0} ({1})',hi\_txt,high) :hi\_txt
+
+\_lo\_txt=label\_price?str.format('{0} ({1})',lo\_txt,low) :lo\_txt
+
+iflabel\_right
+
+kz.\_hi\_label.unshift(label.new(time,high,\_hi\_txt,xloc=xloc.bar\_time,color=transparent,textcolor=txt\_color,style=label.style\_label\_left,size=lbl\_size))
+
+kz.\_lo\_label.unshift(label.new(time,low,\_lo\_txt,xloc=xloc.bar\_time,color=transparent,textcolor=txt\_color,style=label.style\_label\_left,size=lbl\_size))
+
+else
+
+kz.\_hi\_label.unshift(label.new(time,high,\_hi\_txt,xloc=xloc.bar\_time,color=transparent,textcolor=txt\_color,style=label.style\_label\_down,size=lbl\_size))
+
+kz.\_lo\_label.unshift(label.new(time,low,\_lo\_txt,xloc=xloc.bar\_time,color=transparent,textcolor=txt\_color,style=label.style\_label\_up,size=lbl\_size))
+
+
+
+
+
+del\_kz(kz)
+
+adjust\_in\_kz(kz,t)
+
+adjust\_out\_kz(kz,t,t\_prev)
+
+
+
+
+
+for \[\_,value] in\_kz
+
+manage\_kz(value)
+
+
+
+
+
+dwm()
+
+vlines()
+
+hz\_lines()
+
+
+
+
+
+new\_dow\_time=dow\_xloc=='Midday'?time-timeframe.in\_seconds("D") /2\*1000:time
+
+new\_day=dayofweek(new\_dow\_time,gmt\_tz) !=dayofweek(new\_dow\_time,gmt\_tz)\[1]
+
+
+
+
+
+vardow\_top=dow\_yloc=='Top'
+
+
+
+
+
+varsaturday="SATURDAY"
+
+varsunday="SUNDAY"
+
+varmonday="MONDAY"
+
+vartuesday="TUESDAY"
+
+varwednesday="WEDNESDAY"
+
+varthursday="THURSDAY"
+
+varfriday="FRIDAY"
+
+
+
+
+
+plotchar(dow\_labelsandtimeframe.isintradayanddayofweek(new\_dow\_time,gmt\_tz) ==1andnew\_dayandnotdow\_hide\_wknd,location=dow\_top?location.top:location.bottom,char='',textcolor=txt\_color,text=sunday)
+
+plotchar(dow\_labelsandtimeframe.isintradayanddayofweek(new\_dow\_time,gmt\_tz) ==2andnew\_day,location=dow\_top?location.top:location.bottom,char='',textcolor=txt\_color,text=monday)
+
+plotchar(dow\_labelsandtimeframe.isintradayanddayofweek(new\_dow\_time,gmt\_tz) ==3andnew\_day,location=dow\_top?location.top:location.bottom,char='',textcolor=txt\_color,text=tuesday)
+
+plotchar(dow\_labelsandtimeframe.isintradayanddayofweek(new\_dow\_time,gmt\_tz) ==4andnew\_day,location=dow\_top?location.top:location.bottom,char='',textcolor=txt\_color,text=wednesday)
+
+plotchar(dow\_labelsandtimeframe.isintradayanddayofweek(new\_dow\_time,gmt\_tz) ==5andnew\_day,location=dow\_top?location.top:location.bottom,char='',textcolor=txt\_color,text=thursday)
+
+plotchar(dow\_labelsandtimeframe.isintradayanddayofweek(new\_dow\_time,gmt\_tz) ==6andnew\_day,location=dow\_top?location.top:location.bottom,char='',textcolor=txt\_color,text=friday)
+
+plotchar(dow\_labelsandtimeframe.isintradayanddayofweek(new\_dow\_time,gmt\_tz) ==7andnew\_dayandnotdow\_hide\_wknd,location=dow\_top?location.top:location.bottom,char='',textcolor=txt\_color,text=saturday)
+
+
+
+
+
+get\_min\_days\_stored() =>
+
+store=array.new\_int()
+
+for \[\_,value] in\_kz
+
+inttmpStoreSize=value.\_kz.\_range\_store.size()
+
+iftmpStoreSize>0
+
+store.push(tmpStoreSize) 
+
+store.min()
+
+
+
+
+
+methodset\_table(tabletbl,kzkz,introw,stringtxt,boolt,colorcol) =>
+
+table.cell(tbl,0,row,txt,text\_size=range\_size,bgcolor=get\_box\_color(col),text\_color=txt\_color)
+
+table.cell(tbl,1,row,str.tostring(kz.\_range\_current),text\_size=range\_size,bgcolor=t?get\_box\_color(col) :na,text\_color=txt\_color)
+
+ifshow\_range\_avg
+
+table.cell(tbl,2,row,str.tostring(kz.\_range\_store.avg()),text\_size=range\_size,text\_color=txt\_color)
+
+
+
+
+
+ifshow\_rangeandbarstate.islast
+
+vartbl=table.new(range\_pos,10,10,chart.bg\_color,chart.fg\_color,2,chart.fg\_color,1)
+
+
+
+
+
+table.cell(tbl,0,0,"Killzone",text\_size=range\_size,text\_color=txt\_color)
+
+table.cell(tbl,1,0,"Range",text\_size=range\_size,text\_color=txt\_color)
+
+ifshow\_range\_avg
+
+table.cell(tbl,2,0,"Avg ("+str.tostring(get\_min\_days\_stored()) +")",text\_size=range\_size,text\_color=txt\_color)
+
+
+
+
+
+for \[index,value] in\_kz
+
+set\_table(tbl,value.\_kz,index+1,value.box\_txt,notna(time("",value.session,gmt\_tz)),value.c)
+
+// ---------------------------------------- Core Logic --------------------------------------------------
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8cfc962
--- /dev/null
+++ b/README.md
@@ -0,0 +1,51 @@
+# AI ICT
+
+AI ICT 交易辅助系统第一阶段工程实现。
+
+当前项目已经具备从数据、结构、信号、执行、回测到报告的最小闭环，并提供轻量查询 API、HTTP 调试服务与一键编排入口。
+
+See `docs/` for architecture, database, rule, and migration references.
+
+## Current closed loop
+
+当前主线可运行链路：
+
+`OKX -> candles -> market_sessions -> swings -> dealing_ranges -> liquidity_pools -> sweep_events -> displacement_events -> MSS -> FVG -> bias_snapshots -> trade_signals -> trade_executions -> backtest_runs -> backtest_results -> reports`
+
+## Runtime utility scripts
+
+- `python3 scripts/run_dev.py` - run the scaffold entrypoint
+- `python3 scripts/show_models.py` - list exported ORM model names
+- `python3 scripts/check_db.py` - run a simple database connectivity check
+- `python3 scripts/run_migrations.py` - apply SQL files in `migrations/` order
+- `python3 scripts/run_okx_backfill.py` - fetch and write sample OKX candles
+- `python3 scripts/run_session_generator.py` - generate market sessions
+- `python3 scripts/run_swings.py` - rebuild swings
+- `python3 scripts/run_ranges.py` - rebuild dealing ranges
+- `python3 scripts/run_liquidity.py` - rebuild liquidity pools
+- `python3 scripts/run_sweeps.py` - rebuild sweep events
+- `python3 scripts/run_displacement.py` - rebuild displacement events
+- `python3 scripts/run_mss.py` - rebuild MSS structure events
+- `python3 scripts/run_fvg.py` - rebuild FVG zones
+- `python3 scripts/run_signals.py` - generate bias and signals
+- `python3 scripts/run_execution.py` - run paper execution gating and create an execution record
+- `python3 scripts/run_backtest.py` - run backtest and write results
+- `python3 scripts/run_reports.py` - build sample reports from current services
+- `python3 scripts/run_api_server.py` - start a lightweight HTTP API server on `127.0.0.1:8000`
+- `python3 scripts/run_pipeline.py` - run the current end-to-end closed loop and print a structured summary
+
+## Lightweight API helpers
+
+The `src/api/` package exposes internal query helpers and HTTP routes for:
+
+- `GET /health`
+- `GET /candles?instrument_id=1&timeframe=1m&limit=100`
+- `GET /sessions?instrument_id=1&limit=20`
+- `GET /signals?instrument_id=1&limit=20`
+- `GET /backtests?instrument_id=1&limit=10`
+
+## Validation
+
+Unit tests:
+
+- `python3 -m unittest discover -s tests/unit -p "test_*.py"`
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..b1d9bb7
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,11 @@
+services:
+  ai-ict:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: ai-ict
+    env_file:
+      - .env
+    ports:
+      - "8000:8000"
+    restart: unless-stopped
diff --git a/docs/AI_ICT_Codebase_Skeleton_Spec_v1.md b/docs/AI_ICT_Codebase_Skeleton_Spec_v1.md
new file mode 100644
index 0000000..458459d
--- /dev/null
+++ b/docs/AI_ICT_Codebase_Skeleton_Spec_v1.md
@@ -0,0 +1,872 @@
+# 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 都可以在同一套结构下稳定扩展。
diff --git a/docs/AI_ICT_Dealing_Range_Spec_v1.md b/docs/AI_ICT_Dealing_Range_Spec_v1.md
new file mode 100644
index 0000000..f09538a
--- /dev/null
+++ b/docs/AI_ICT_Dealing_Range_Spec_v1.md
@@ -0,0 +1,584 @@
+# AI ICT Dealing Range 识别规格书 v1
+
+## 1. 文档目标
+
+本文档定义 AI ICT 项目第一阶段 MVP 的 dealing range identification 规则，用于指导：
+
+- `dealing_ranges` 表设计与落库
+- premium / discount / equilibrium 位置判定
+- bias、liquidity、signal 等下游模块引用
+- 本地验证、抽样复盘与后续回测
+
+本文档只覆盖 dealing range 的识别与维护，不覆盖 MSS、FVG、signal 组装等后续规则。
+
+关联文档：
+
+1. `AI_ICT_MVP_规则规格书_v1.md`
+2. `AI_ICT_PostgreSQL_Schema_v1.md`
+3. `AI_ICT_开发路线图_v1.md`
+4. `AI_ICT_执行检查清单_v1.md`
+5. `AI_ICT_Swing_Identification_Spec_v1.md`
+
+---
+
+## 2. 设计目标
+
+ dealing range 模块需要满足以下目标：
+
+1. 输出稳定，可重复生成
+2. range 锚点来源清晰，可审计
+3. 能稳定计算 equilibrium
+4. 能对当前价格给出 premium / discount / equilibrium 标注
+5. 能在同一 timeframe 历史上保留多个 range 记录
+6. 能明确当前 active range 的选择逻辑
+7. 具备可控的重算与失效规则
+
+---
+
+## 3. 核心定义
+
+## 3.1 Dealing Range
+
+Dealing range 是由一组有效结构高低点定义出的当前工作区间，用于建立价格所处位置坐标。
+
+第一版中，一个 dealing range 由：
+
+- 一个有效高点锚 `high_swing`
+- 一个有效低点锚 `low_swing`
+- 基于两者计算的 `equilibrium`
+
+共同组成。
+
+## 3.2 Range Anchor
+
+range anchor 指用于定义当前 range 边界的 swing 锚点：
+
+- `high_swing_id`
+- `low_swing_id`
+
+锚点必须来自已确认的 swing，且默认优先使用与当前 timeframe 对齐的 confirmed swing。
+
+## 3.3 Equilibrium
+
+`equilibrium` 是 dealing range 中点，计算方式为：
+
+```text
+equilibrium = (high + low) / 2
+```
+
+第一版使用简单中点，不引入成交量、时间权重或 VWAP 修正。
+
+## 3.4 Premium / Discount / Equilibrium Zone
+
+给定当前价格 `p`：
+
+- 若 `p > equilibrium`，则价格位于 `premium`
+- 若 `p < equilibrium`，则价格位于 `discount`
+- 若 `p == equilibrium` 或落在定义的中点容忍带内，则位于 `equilibrium`
+
+---
+
+## 4. range 锚点规则
+
+## 4.1 第一版锚点来源
+
+第一版 dealing range 的锚点只来源于 confirmed swing，不直接来源于 candle、session high/low 或 liquidity pool。
+
+原因：
+
+- 与结构识别链路一致
+- 易于审计与复现
+- 可直接复用 `swings.id`
+
+## 4.2 锚点类型
+
+一个有效 range 必须由：
+
+- 1 个 `swing_high`
+- 1 个 `swing_low`
+
+组成。
+
+不允许：
+
+- high/high 组成 range
+- low/low 组成 range
+- 未确认 swing 组成正式 range
+
+## 4.3 锚点确认要求
+
+用于正式 range 的锚点必须满足：
+
+- `confirmed = true`
+- 与 range 相同 `instrument_id`
+- 与 range 相同 `timeframe`
+- `strength` 符合当前 timeframe 的默认使用层级
+
+## 4.4 默认层级选择
+
+第一版建议：
+
+- `trigger_tf` / `setup_tf` 上优先使用 ST swing 生成工作 range
+- `range_tf` 上可优先使用 IT swing 生成更稳定 range
+- `bias_tf` 若需要生成背景 range，可优先使用 IT 或 LT swing
+
+但在 MVP 第一阶段，为了降低复杂度：
+
+- dealing range 模块默认先支持“单一 timeframe 内的 confirmed ST swing 组合”
+- IT / LT range 作为增强项，在基础 ST range 稳定后再扩展
+
+## 4.5 时间顺序要求
+
+锚点必须满足以下条件：
+
+- `high_swing_id != low_swing_id`
+- 两个锚点都已有明确 `ts`
+- 两个锚点共同界定的区间必须覆盖当前工作段
+
+第一版允许 high swing 早于 low swing，也允许 low swing 早于 high swing，不强制某个方向先出现。
+
+原因：
+
+- dealing range 本质是区间坐标，不是方向判断本身
+- 方向与叙事由 bias / structure 模块补充
+
+---
+
+## 5. range 构建规则
+
+## 5.1 基础构建公式
+
+给定一组有效锚点：
+
+- `high = high_swing.price`
+- `low = low_swing.price`
+- `equilibrium = (high + low) / 2`
+
+则生成一条 dealing range。
+
+## 5.2 合法性要求
+
+有效 range 必须满足：
+
+- `high > low`
+- `equilibrium > low`
+- `equilibrium < high`
+
+若不满足，说明锚点或输入数据异常，不得落为正式 range。
+
+## 5.3 ts_start 与 ts_end
+
+第一版建议：
+
+- `ts_start = min(high_swing.ts, low_swing.ts)`
+- `ts_end` 在 range 仍 active 时为空
+- 当 range 失效或被新 range 替代时，写入 `ts_end`
+
+## 5.4 价格突破处理
+
+价格突破 range 的高低边界，不立即删除历史 range。
+
+处理方式：
+
+- 原 range 保留历史记录
+- 根据 active-range 规则决定是否失效
+- 若产生新锚点组合，则新建一条 range 记录
+
+---
+
+## 6. equilibrium 与位置标注规则
+
+## 6.1 equilibrium 计算
+
+第一版固定为：
+
+```text
+equilibrium = (high + low) / 2
+```
+
+不做：
+
+- Fibonacci 0.5 以外的扩展坐标
+- 基于成交量的权重均值
+- 动态 session 调整
+
+## 6.2 位置标注
+
+给定价格 `p`：
+
+- `p > equilibrium` => `premium`
+- `p < equilibrium` => `discount`
+- `p == equilibrium` => `equilibrium`
+
+## 6.3 equilibrium 容忍带
+
+由于实际价格精度与不同品种 tick size 不同，第一版建议加入容忍带：
+
+```text
+equilibrium_band = max(tick_size, (high - low) * 0.001)
+```
+
+位置判定：
+
+- 若 `abs(p - equilibrium) <= equilibrium_band`，标记为 `equilibrium`
+- 否则按 premium / discount 判定
+
+说明：
+
+- 这是工程容忍带，不是交易策略本身
+- 主要用于减少价格刚好贴近中点时的标签抖动
+
+## 6.4 输出内容
+
+dealing range 模块至少应输出：
+
+- `high`
+- `low`
+- `equilibrium`
+- `location_label`：premium / discount / equilibrium
+- `distance_to_eq`
+- `distance_to_range_high`
+- `distance_to_range_low`
+
+其中距离字段可先作为运行时输出，不强制第一版全部落库。
+
+---
+
+## 7. active range 选择规则
+
+## 7.1 为什么需要 active range
+
+同一 instrument + timeframe 历史上可能存在多条 range 记录，因此需要明确当前哪一条才是正式工作区间。
+
+## 7.2 第一版 active range 原则
+
+第一版在同一 `instrument_id + timeframe` 下，最多只认一条 `state = 'valid'` 的当前主 range。
+
+其余历史 range：
+
+- 保留为历史记录
+- `state` 改为非当前状态
+
+## 7.3 默认选取规则
+
+若存在多个候选 range，按以下优先级选择 active range：
+
+1. 锚点均为 confirmed swing
+2. 锚点时间较新
+3. 覆盖当前价格结构更完整
+4. 最近一次被结构事件引用的 range 优先
+5. 若仍冲突，则取 `ts_start` 更晚者
+
+第一版最小实现建议：
+
+- 直接选择最近生成且状态为 `valid` 的一条
+- 同时保证旧 range 被置为非 active
+
+## 7.4 状态建议
+
+第一版建议 `state` 取值：
+
+- `valid`：当前 active range
+- `superseded`：已被新 range 替代
+- `invalidated`：因结构失效而不再有效
+- `archived`：历史保留，不参与当前选择
+
+若暂时不做完整状态机，至少要支持：
+
+- `valid`
+- `superseded`
+
+## 7.5 多 timeframe 并存
+
+允许多个 timeframe 同时各自拥有 active range。
+
+例如：
+
+- H1 有一条 active range
+- M15 也有一条 active range
+
+这不冲突，因为它们服务于不同层级判断。
+
+---
+
+## 8. 重算与更新规则
+
+## 8.1 重算触发条件
+
+当出现以下情况时，应触发 dealing range 重算：
+
+1. 新 confirmed swing 写入
+2. 既有 provisional swing 转为 confirmed
+3. 历史数据补齐导致 swing 结果变化
+4. 参数变更导致 swing 识别结果变化
+5. 手动触发全量或分段重算
+
+## 8.2 重算范围
+
+第一版建议按 `instrument_id + timeframe` 做局部重算，而不是全市场全量重算。
+
+如需更保守，可按时间窗口重算：
+
+- 受影响 swing 附近 N 根 candle 对应区间
+- 再向后重建 active range
+
+## 8.3 更新策略
+
+建议：
+
+- 不直接覆盖历史 dealing range 记录
+- 旧 range 改 `state`
+- 新 range 新增一条记录
+- `updated_at` 仅用于状态变更或元数据更新
+
+这样做的好处：
+
+- 历史轨迹清晰
+- 回测更易复现
+- 审计更容易
+
+## 8.4 何时 superseded
+
+若出现更新、更合理的锚点组合，且新 range 被判定为当前主 range，则旧 range 设为 `superseded`。
+
+## 8.5 何时 invalidated
+
+以下情况可将 range 标记为 `invalidated`：
+
+- 锚点 swing 后续被证明无效
+- 数据缺口导致锚点可靠性丧失
+- 结构上下文已切换，旧 range 不再适合作为坐标参考
+
+第一版如不实现 `invalidated`，可先统一用 `superseded` 处理。
+
+---
+
+## 9. 边界与异常情况
+
+## 9.1 锚点价格相等
+
+若 `high_swing.price == low_swing.price`，不得生成 range。
+
+处理：
+
+- 标记异常
+- 跳过写入
+- `meta.error = 'flat_range_anchor'`
+
+## 9.2 锚点顺序反转
+
+若 low swing 的时间晚于 high swing，或 high swing 的时间晚于 low swing，不构成错误。
+
+第一版只要价格边界合法即可。
+
+## 9.3 锚点过旧
+
+若锚点距离当前时间过远，可能导致 range 与当前结构脱节。
+
+第一版不强制设置最大年龄限制，但建议在 `meta` 中记录：
+
+- `anchor_age_bars`
+- `anchor_age_minutes`
+
+后续可用于优化 active-range 选择。
+
+## 9.4 多组锚点同时成立
+
+若同一时刻存在多组合法锚点：
+
+- 第一版按 active-range 默认选取规则择一
+- 其余记录可写为历史候选或不落库
+
+为了降低复杂度，MVP 第一版建议只落库最终被选中的主 range。
+
+## 9.5 数据缺口
+
+若两个锚点之间存在明显缺口：
+
+- 可暂不生成正式 range
+- 或写入但 `meta.data_gap = true`
+- 下游默认不消费含 `data_gap` 的 range
+
+第一版更建议：缺口存在时不生成 active range。
+
+## 9.6 极端宽 range
+
+若 `high - low` 远大于当前 timeframe 的正常波动，可能说明锚点选取过粗。
+
+第一版不直接拒绝，但建议记录：
+
+- `meta.range_width`
+- `meta.range_width_pct`
+
+供后续过滤与回测分析使用。
+
+---
+
+## 10. 存储模型
+
+## 10.1 对应表
+
+`dealing range` 结果落到 `dealing_ranges` 表。
+
+建议字段：
+
+- `instrument_id`
+- `timeframe`
+- `high`
+- `low`
+- `equilibrium`
+- `high_swing_id`
+- `low_swing_id`
+- `state`
+- `ts_start`
+- `ts_end`
+- `meta`
+- `created_at`
+- `updated_at`
+
+## 10.2 字段语义
+
+- `high`：range 上边界
+- `low`：range 下边界
+- `equilibrium`：中点
+- `high_swing_id`：上边界来源 swing
+- `low_swing_id`：下边界来源 swing
+- `state`：当前有效性状态
+- `ts_start`：range 起始时间
+- `ts_end`：range 结束时间
+
+## 10.3 meta 建议内容
+
+适合写入 `meta` 的字段：
+
+- `anchor_strength_high`
+- `anchor_strength_low`
+- `anchor_high_ts`
+- `anchor_low_ts`
+- `location_label`
+- `equilibrium_band`
+- `data_gap`
+- `selection_reason`
+- `recalc_batch_id`
+- `range_width`
+- `range_width_pct`
+
+不应只放在 `meta` 的字段：
+
+- `high`
+- `low`
+- `equilibrium`
+- `high_swing_id`
+- `low_swing_id`
+- `state`
+- `ts_start`
+
+## 10.4 更新策略
+
+建议：
+
+- 新主 range 产生时新增记录
+- 旧记录更新 `state` 和 `ts_end`
+- 不静默覆盖历史 high / low / equilibrium
+
+---
+
+## 11. 处理流程建议
+
+## 11.1 基础计算流程
+
+1. 读取指定 instrument + timeframe 的 confirmed swings
+2. 筛选当前可用的 swing_high 与 swing_low
+3. 按规则组合候选锚点
+4. 计算 `high / low / equilibrium`
+5. 校验合法性
+6. 选出当前 active range
+7. 落库并更新旧 range 状态
+
+## 11.2 最小 MVP 实现
+
+建议先做：
+
+1. confirmed ST swings 驱动的单 timeframe range
+2. equilibrium 计算
+3. premium / discount / equilibrium 标注
+4. 单一 active range 管理
+5. superseded 历史保留
+
+之后再增强：
+
+- IT / LT range
+- 更复杂的 active-range 选择
+- 数据缺口与异常过滤
+- 更精细的状态机
+
+---
+
+## 12. 验证检查点
+
+## 12.1 功能验证
+
+- [ ] 能按 timeframe 产出当前主 range
+- [ ] 同一批输入重复运行结果一致
+- [ ] active range 可稳定查询
+- [ ] premium / discount / equilibrium 输出稳定
+
+## 12.2 规则验证
+
+- [ ] range 必须由 1 个 confirmed high swing + 1 个 confirmed low swing 组成
+- [ ] `high > low` 才允许落库
+- [ ] `equilibrium = (high + low) / 2` 计算正确
+- [ ] 旧 range 被替代时会正确转为非 active
+- [ ] 当前价格位置标签与手工计算一致
+
+## 12.3 存储验证
+
+- [ ] `high_swing_id` / `low_swing_id` 可正确关联 `swings`
+- [ ] `state` 可区分当前与历史 range
+- [ ] `ts_start / ts_end` 逻辑正确
+- [ ] `meta` 可记录 selection reason 和异常信息
+
+## 12.4 人工抽样验证
+
+每个核心 timeframe 至少抽查：
+
+- 1 个标准 bullish range 样例
+- 1 个标准 bearish range 样例
+- 1 个当前价格位于 premium 的样例
+- 1 个当前价格位于 discount 的样例
+- 1 个旧 range 被 superseded 的样例
+- 1 个锚点异常未落库的反例
+
+## 12.5 与路线图对齐的完成标准
+
+满足以下条件才算完成：
+
+- 当前主 range 可查询
+- 可输出当前价格所处分区
+- 结果可重复生成
+- 可作为 bias / liquidity / signal 的上游输入
+
+---
+
+## 13. MVP 范围内不做的事
+
+第一版暂不包含：
+
+- 多 session 拼接式 range
+- AI 自由解释生成 range 锚点
+- 基于外部订单流的 range 加权
+- 自动合并多个候选 range
+- Fibonacci 多层分区扩展
+- 不同品种联动生成共享 range
+
+---
+
+## 14. 推荐的最小实现顺序
+
+1. 先实现 confirmed ST swing 驱动的 range 构建
+2. 再实现 equilibrium 与位置标签
+3. 再实现 active range 的单一选择
+4. 再实现 superseded 历史保留
+5. 最后补充异常标记、重算批次和增强状态机
+
+这样可以先满足阶段 2 的最小可用目标，再逐步增强。
\ No newline at end of file
diff --git a/docs/AI_ICT_Dealing_Range_规格书_v1.md b/docs/AI_ICT_Dealing_Range_规格书_v1.md
new file mode 100644
index 0000000..58801b4
--- /dev/null
+++ b/docs/AI_ICT_Dealing_Range_规格书_v1.md
@@ -0,0 +1,410 @@
+# AI ICT Dealing Range 规格书 v1
+
+## 1. 文档目标
+
+本文档定义 AI ICT 项目第一阶段的 Dealing Range 识别规则，用于从结构高低点中建立当前工作区间，并为后续位置、目标和执行质量判断提供空间坐标。
+
+Dealing Range 位于以下链路中：
+
+`Candles -> Sessions -> Swings -> Dealing Range -> Liquidity -> Bias -> Signal`
+
+本模块的输出将直接影响：
+
+- 当前价格位置判断
+- Premium / Discount / Equilibrium 标签
+- IRL / ERL 目标分层
+- Bias 强度判断
+- 追价 / 等回补 / 放弃交易的执行判断
+
+因此，Dealing Range 是基础规则中的“位置坐标模块”。
+
+---
+
+## 2. 模块职责
+
+### 2.1 本模块负责
+
+1. 选取当前工作区间的上边界和下边界
+2. 计算 equilibrium
+3. 输出 premium / discount / equilibrium 位置标签
+4. 维护当前 timeframe 的 active range
+5. 写入 `dealing_ranges`
+
+### 2.2 本模块不负责
+
+- swing 识别
+- liquidity pool 识别
+- draw on liquidity
+- bias 判定
+- 目标是否可执行
+
+这些都属于下游模块。
+
+---
+
+## 3. 输入与输出
+
+## 3.1 输入
+
+本模块依赖：
+
+- `swings`
+- 当前价格
+- timeframe
+
+至少需要：
+
+- swing high
+- swing low
+- ts
+- strength
+- confirmed 状态
+
+---
+
+## 3.2 输出
+
+输出写入 `dealing_ranges` 表，字段包括：
+
+- instrument_id
+- timeframe
+- high
+- low
+- equilibrium
+- high_swing_id
+- low_swing_id
+- state
+- ts_start
+- ts_end
+- meta
+
+并输出运行时标签：
+
+- location = premium | discount | equilibrium
+
+---
+
+## 4. 基础定义
+
+## 4.1 Dealing Range
+
+Dealing Range 指当前分析层级下，价格活动的工作区间，至少由一个有效高点和一个有效低点界定。
+
+它不是装饰线，而是后续位置判断、目标判断和执行质量判断的统一坐标系。
+
+---
+
+## 4.2 Key High / Key Low
+
+- Key High：当前工作区间上边界锚点
+- Key Low：当前工作区间下边界锚点
+
+这两个锚点一般来自已确认的 swing。
+
+---
+
+## 4.3 Equilibrium
+
+Equilibrium 为当前 range 的中值，第一阶段采用：
+
+`equilibrium = (high + low) / 2`
+
+说明：
+
+- 第一阶段不做复杂加权平衡
+- 统一使用简单中值，避免口径漂移
+
+---
+
+## 4.4 Premium / Discount
+
+以 equilibrium 为中轴：
+
+- 当前价格 > equilibrium -> premium
+- 当前价格 < equilibrium -> discount
+- 当前价格接近 equilibrium -> equilibrium 区
+
+说明：
+
+- Premium / Discount 是位置概念，不是方向概念
+- 方向由上游结构和 narrative 决定
+- 位置只决定“值不值得在这里做”
+
+---
+
+## 5. 当前 active range 选择规则
+
+Dealing Range 最核心的问题不是“能不能画 range”，而是“当前应使用哪个 range 作为工作区间”。
+
+---
+
+## 5.1 第一阶段选择原则
+
+MVP 先采用简化规则：
+
+1. 每个 timeframe 同时只保留一个 active range
+2. active range 必须由已确认 swing high / swing low 组成
+3. 优先选最近一组仍具执行意义的 confirmed anchors
+
+---
+
+## 5.2 推荐选取逻辑
+
+对于某个 timeframe：
+
+1. 获取最近 confirmed swing highs
+2. 获取最近 confirmed swing lows
+3. 从中选出最近有效的一组上边界和下边界
+4. 形成当前 active range
+
+要求：
+
+- high 必须大于 low
+- 两个锚点时间顺序可不同，但必须逻辑上构成同一工作区间
+
+---
+
+## 5.3 不采用的做法
+
+第一阶段不建议：
+
+- 在同一 timeframe 同时输出多个 competing active ranges
+- 引入过于复杂的 fractal priority engine
+- 让 range 频繁抖动
+
+原因：
+
+- 会导致下游 bias 和 signal 口径不稳定
+- 第一阶段目标是先打稳基础坐标，不追求极致复杂表达
+
+---
+
+## 6. 位置判定规则
+
+## 6.1 基础规则
+
+给定当前价格 `p`：
+
+- `p > equilibrium` -> premium
+- `p < equilibrium` -> discount
+
+---
+
+## 6.2 equilibrium 区间处理
+
+为了避免价格刚好围绕中值来回抖动，建议设置一个中值缓冲带。
+
+例如：
+
+- 若价格在 equilibrium 附近阈值范围内，则标记为 `equilibrium`
+
+建议阈值：
+
+- 按百分比
+- 或按 tick / ATR 的极小比例
+
+第一阶段建议：
+
+- 配置项形式实现
+- 但默认值保持简单
+
+---
+
+## 7. 重绘与更新规则
+
+## 7.1 何时重算 range
+
+以下情况应触发重算：
+
+1. 新 confirmed swing 出现
+2. 当前 active range 的边界失去代表性
+3. 下游明确要求重排上下文
+
+---
+
+## 7.2 何时结束旧 range
+
+当 active range 被新结构替代时：
+
+- 旧 range 设置 `state = inactive` 或 `closed`
+- 写入 `ts_end`
+- 新 range 成为 `state = valid`
+
+---
+
+## 7.3 更新频率建议
+
+- 增量运行时，只重算最近窗口
+- 历史回测时，可按 timeframe 全量重算
+
+---
+
+## 8. 边界与异常处理
+
+## 8.1 swing 不足
+
+若当前 timeframe 缺少足够 confirmed swing：
+
+- 不生成 dealing range
+- 或输出 `state = invalid`
+
+---
+
+## 8.2 high <= low
+
+若选出的边界不满足 `high > low`：
+
+- 立即判定为异常
+- 不允许写入有效 dealing range
+
+---
+
+## 8.3 数据缺口
+
+若关键 swing 来源区间存在数据缺口：
+
+- 可生成 range，但应在 `meta` 中标记不完整
+- 若缺口严重，建议拒绝输出 valid range
+
+---
+
+## 8.4 多层级冲突
+
+同一价格在不同 timeframe 可能同时是：
+
+- H4 discount
+- H1 equilibrium
+- M15 premium
+
+这是正常现象。
+
+处理原则：
+
+- 每个 timeframe 独立存储 range
+- 下游模块按职责读取对应 timeframe
+- 不在本模块中处理跨 timeframe 冲突
+
+---
+
+## 9. 写入策略
+
+## 9.1 幂等要求
+
+相同 timeframe、相同 anchor 组合重复计算时：
+
+- 不应产生重复 dealing range 记录
+- 已存在的 active range 应更新而不是复制
+
+---
+
+## 9.2 状态建议
+
+第一阶段建议支持：
+
+- valid
+- inactive
+- invalid
+
+说明：
+
+- valid：当前 active range
+- inactive：已被新 range 替代
+- invalid：输入异常或条件不足
+
+---
+
+## 10. 下游依赖约定
+
+Dealing Range 输出将被下游这样使用：
+
+### Liquidity
+- 边界外目标识别
+- IRL / ERL 层级参考
+
+### Bias
+- 当前位置在 premium / discount / equilibrium
+- 是否允许追价
+
+### Signal
+- 判断 entry 是否处于合理位置
+- 决定是否等待回补
+
+因此，Dealing Range 模块必须稳定输出：
+
+- current active range
+- equilibrium
+- location label
+
+---
+
+## 11. 推荐任务拆分
+
+### T1. active range anchor 选取
+- 从 swings 中选 high / low
+
+### T2. equilibrium 计算
+- high / low -> equilibrium
+
+### T3. location 判定
+- premium / discount / equilibrium
+
+### T4. dealing_ranges 入库
+- valid / inactive / invalid
+
+### T5. 增量更新逻辑
+- 新 swing 出现后的 range 重算
+
+---
+
+## 12. 验证检查点
+
+## 12.1 最低验证
+
+至少验证：
+
+- [ ] H1 能生成 active range
+- [ ] M15 能生成 active range
+- [ ] current location 可输出
+- [ ] equilibrium 计算正确
+
+---
+
+## 12.2 数值验证
+
+- [ ] high > low
+- [ ] equilibrium = (high + low) / 2
+- [ ] valid range 同时存在 high_swing_id / low_swing_id
+- [ ] location 与当前价格关系一致
+
+---
+
+## 12.3 人工抽查
+
+随机抽取图表样本检查：
+
+- [ ] 选取的 high / low 符合肉眼结构
+- [ ] premium / discount 判断合理
+- [ ] range 未频繁无意义抖动
+
+---
+
+## 13. 完成标准
+
+只有满足以下全部条件，Dealing Range 模块才算完成：
+
+1. 能从 swings 生成当前 active range
+2. 能稳定计算 equilibrium
+3. 能输出 premium / discount / equilibrium 标签
+4. 能幂等写入 `dealing_ranges`
+5. 能在新结构出现时更新 active range
+6. 可直接供 bias 与 signal 模块使用
+
+---
+
+## 14. 当前结论
+
+Dealing Range 模块是执行系统的空间坐标层。
+
+如果 Swing 是结构锚点，那么 Dealing Range 就是把这些锚点组织成“当前位置是否值得出手”的空间判断系统。
+
+在真实开发中，它应被视为基础规则层中的核心模块之一。
\ No newline at end of file
diff --git a/docs/AI_ICT_Displacement_规格书_v1.md b/docs/AI_ICT_Displacement_规格书_v1.md
new file mode 100644
index 0000000..414b1f2
--- /dev/null
+++ b/docs/AI_ICT_Displacement_规格书_v1.md
@@ -0,0 +1,494 @@
+# AI ICT Displacement 规格书 v1
+
+## 1. 文档目标
+
+本文档定义 AI ICT 项目第一阶段的 Displacement 识别规则，用于从价格行为中识别“有效位移”事件，并为后续 MSS、Bias、Signal 生成提供结构强度依据。
+
+Displacement 模块位于以下链路中：
+
+`Candles -> Liquidity -> Sweep -> Displacement -> MSS -> Signal`
+
+本模块输出将直接影响：
+
+- 是否出现真正有意义的方向表达
+- Sweep 后是否出现足够强的反向承接
+- MSS 是否具备更高可信度
+- FVG 是否具有更高解释力
+- Signal 是否达到执行门槛
+
+因此，Displacement 是“结构强度确认层”。
+
+---
+
+## 2. 模块职责
+
+### 2.1 本模块负责
+
+1. 检测价格是否出现明显位移
+2. 判断位移方向
+3. 给出位移强度评分
+4. 记录位移与 FVG 的联动关系
+5. 为后续 MSS 和 Signal 提供结构强度证据
+
+### 2.2 本模块不负责
+
+- MSS 最终判定
+- Bias 最终判定
+- Signal 最终生成
+- FVG 本体识别
+
+这些都属于下游或相邻模块。
+
+---
+
+## 3. 输入与输出
+
+## 3.1 输入
+
+本模块依赖：
+
+- `candles`
+- 可选：`sweep_events`
+- 可选：`fvg_zones`
+- timeframe
+
+至少需要：
+
+- open
+- high
+- low
+- close
+- ts
+
+---
+
+## 3.2 输出
+
+输出写入 `displacement_events`，字段建议包括：
+
+- instrument_id
+- timeframe
+- direction
+- start_ts
+- end_ts
+- strength_score
+- body_ratio
+- has_fvg
+- is_valid
+- meta
+
+其中：
+
+- `direction = bullish | bearish`
+- `strength_score` 为归一化强度评分
+- `body_ratio` 表示相对实体扩张程度
+- `has_fvg = true | false`
+
+---
+
+## 4. 基础定义
+
+## 4.1 Displacement
+
+Displacement 指价格在短时间内以明显的方向性、实体性和推进性脱离原平衡状态的行为。
+
+它不是普通波动，而是：
+
+1. 有明确方向
+2. 有明显实体扩张
+3. 有推进性而非来回噪音
+4. 往往伴随低效率定价或 FVG
+
+---
+
+## 4.2 为什么 Displacement 重要
+
+在 ICT 结构语境中，Displacement 是“控制权表达”的关键线索。
+
+例如：
+
+- Sweep 之后若没有 Displacement，则后续 reversal 解释力较弱
+- MSB 之后若没有 Displacement，则 MSS 可信度较低
+
+因此，Displacement 不能只是“涨得快”或“跌得快”，而应是结构上有意义的位移事件。
+
+---
+
+## 5. 识别维度
+
+第一阶段建议至少从以下 4 个维度综合判断：
+
+1. 实体扩张
+2. 方向推进
+3. 脱离平衡
+4. FVG / 低效率联动
+
+---
+
+## 5.1 实体扩张
+
+若某根或连续几根 candle 的实体显著大于近期平均实体，则位移解释力增强。
+
+建议指标：
+
+- 当前实体 / 最近 N 根平均实体 = `body_ratio`
+
+其中：
+
+`body_size = abs(close - open)`
+
+第一阶段建议：
+
+- 不使用特别复杂的波动模型
+- 先用滚动平均实体做相对比较
+
+---
+
+## 5.2 方向推进
+
+位移不应只是单根大 K，而应体现短时段方向推进能力。
+
+例如：
+
+- bullish displacement：连续向上推进、回撤弱、收盘位置强
+- bearish displacement：连续向下推进、反弹弱、收盘位置弱
+
+说明：
+
+- 单根异常长影线不一定代表 displacement
+- 更关键的是方向推进的连续性
+
+---
+
+## 5.3 脱离平衡
+
+位移通常表现为价格快速脱离原有平衡区、中值区或短期整理区。
+
+第一阶段建议：
+
+- 可通过短期整理区脱离来增强 displacement 解释
+- 但不要一开始把平衡定义复杂化
+
+---
+
+## 5.4 FVG 联动
+
+若位移同时产生 FVG / imbalance，则说明：
+
+- 市场在快速再定价
+- 位移并非普通来回振荡
+
+因此：
+
+- `has_fvg = true` 应显著提升位移可信度
+
+---
+
+## 6. 方向判定
+
+## 6.1 bullish displacement
+
+若价格表现出以下特征：
+
+1. 实体向上扩张
+2. 向上推进明显
+3. close 位置强
+4. 可伴随 bullish FVG
+
+则判定为 bullish displacement。
+
+---
+
+## 6.2 bearish displacement
+
+若价格表现出以下特征：
+
+1. 实体向下扩张
+2. 向下推进明显
+3. close 位置弱
+4. 可伴随 bearish FVG
+
+则判定为 bearish displacement。
+
+---
+
+## 7. 评分建议
+
+第一阶段建议保留一个简单强度评分：
+
+- `strength_score` 范围可设为 0 ~ 1
+
+评分可综合以下因素：
+
+1. body_ratio
+2. 连续推进程度
+3. close 强弱位置
+4. 是否伴随 FVG
+5. 是否发生在关键事件之后（如 sweep）
+
+说明：
+
+- 第一阶段不要求极致数学精确
+- 更重要的是评分口径一致
+
+---
+
+## 8. 最低成立条件
+
+为了避免把普通波动误判为 displacement，第一阶段建议要求至少满足以下两项：
+
+1. `body_ratio` 超过阈值
+2. 存在短时连续推进
+3. close 表现强 / 弱明显
+4. 同时出现 FVG
+
+只有单一条件成立，不建议直接记为强 displacement。
+
+---
+
+## 9. 与 Sweep 的联动
+
+## 9.1 sweep 后 displacement
+
+若某一侧 pool 被 sweep 后，在观察窗口内出现反向 displacement：
+
+- 该 displacement 的解释力显著增强
+- 可作为后续 MSS 的重要前提证据
+
+因此，建议在 `meta` 中保留：
+
+- related_sweep_id
+- sweep_after_bars
+
+---
+
+## 9.2 无 sweep 的 displacement
+
+没有前置 sweep 也可以存在 displacement，但解释语义不同：
+
+- 可能是普通趋势推进
+- 可能是整理区突破
+- 其结构意义不一定等于“先清理后递送”
+
+因此，下游模块应区分：
+
+- pure displacement
+- sweep-backed displacement
+
+---
+
+## 10. 与 FVG 的联动
+
+## 10.1 has_fvg
+
+若 displacement 同时生成 FVG：
+
+- `has_fvg = true`
+- 强度评分提升
+
+### 原因
+FVG 往往说明价格出现快速再定价，提升 displacement 的结构解释力。
+
+---
+
+## 10.2 无 FVG 情况
+
+无 FVG 并不代表一定不是 displacement，但可信度通常略低。
+
+第一阶段建议：
+
+- 无 FVG 可以保留为 displacement
+- 但评分较低
+- 若其他维度也不强，则不应升级为高质量 displacement
+
+---
+
+## 11. 时间窗口与确认
+
+## 11.1 观察窗口
+
+Displacement 识别建议在短窗口内完成，不应拖得过长。
+
+例如：
+
+- 观察最近 N 根 candle 的方向推进质量
+
+第一阶段建议：
+
+- N 按 timeframe 配置
+- 不同 timeframe 单独设定
+
+---
+
+## 11.2 confirmed displacement
+
+当观察窗口内多个条件已满足时，可记为 confirmed displacement。
+
+若条件不足：
+
+- 可忽略
+- 或作为低可信候选，不进入主链路
+
+第一阶段建议：
+
+- displacement 事件尽量只记录 confirmed 结果
+- 避免大量低质量候选污染数据库
+
+---
+
+## 12. 边界与异常处理
+
+## 12.1 单根长影线
+
+若只有很长影线，但实体不够、推进不连续：
+
+- 不应轻易判为 displacement
+
+---
+
+## 12.2 高波动但无方向
+
+若波动剧烈，但上下反复、close 无明显优势：
+
+- 视为高噪音，不应判为 displacement
+
+---
+
+## 12.3 数据缺口
+
+若窗口内 candles 不连续：
+
+- 不建议输出高可信 displacement
+- 若仍输出，必须在 `meta` 中标记不完整
+
+---
+
+## 13. 写入策略
+
+## 13.1 幂等要求
+
+同一主事件窗口重复计算时：
+
+- 不应重复生成多个 identical displacement 事件
+
+建议幂等参考：
+
+- instrument_id
+- timeframe
+- direction
+- start_ts
+- end_ts
+
+---
+
+## 13.2 有效性标记
+
+建议字段：
+
+- `is_valid = true | false`
+
+用于表示：
+
+- 是否达到最小成立条件
+- 是否可进入 MSS / signal 主链路
+
+---
+
+## 14. 下游依赖约定
+
+Displacement 输出将被下游这样使用：
+
+### MSS
+- 判断结构切换是否真的有控制权表达
+
+### Bias
+- 判断当前位置是否已经出现方向表达
+
+### Signal
+- 判断 setup 是否达到执行强度门槛
+
+因此，本模块必须稳定输出：
+
+- direction
+- strength_score
+- has_fvg
+- is_valid
+
+---
+
+## 15. 推荐任务拆分
+
+### T1. body_ratio 计算
+- 当前实体 vs 历史平均实体
+
+### T2. 推进性判断
+- 连续方向推进检测
+
+### T3. close 强弱检测
+- candle 收盘位置质量
+
+### T4. FVG 联动
+- has_fvg 标记
+
+### T5. displacement 评分
+- 生成 strength_score
+
+### T6. 入库与幂等控制
+- 写入 `displacement_events`
+
+---
+
+## 16. 验证检查点
+
+## 16.1 最低验证
+
+至少验证：
+
+- [ ] bullish displacement 可识别
+- [ ] bearish displacement 可识别
+- [ ] body_ratio 可计算
+- [ ] has_fvg 可联动标记
+
+---
+
+## 16.2 行为验证
+
+- [ ] 单根长影线不会轻易误判为高质量 displacement
+- [ ] 纯高波动噪音不会误判为 displacement
+- [ ] 有 sweep 背景的 displacement 评分更高
+
+---
+
+## 16.3 人工抽查
+
+至少抽样检查：
+
+- [ ] displacement 起止窗口合理
+- [ ] 方向判定合理
+- [ ] 与 FVG 联动合理
+- [ ] 评分排序大致符合肉眼感知
+
+---
+
+## 17. 完成标准
+
+只有满足以下全部条件，Displacement 模块才算完成：
+
+1. 能识别 bullish / bearish displacement
+2. 能计算基础强度评分
+3. 能与 FVG 联动
+4. 能与 sweep 事件联动
+5. 能幂等写入 `displacement_events`
+6. 可直接供 MSS 模块使用
+
+---
+
+## 18. 当前结论
+
+Displacement 模块不是单纯的“大阳线/大阴线识别器”，而是市场是否真正表达出一侧控制权的强度确认层。
+
+在真实开发中，它应作为 Sweep 和 MSS 之间的关键桥梁模块，优先保证：
+
+- 规则口径稳定
+- 评分一致
+- 不被噪音 K 线污染
diff --git a/docs/AI_ICT_FVG_规格书_v1.md b/docs/AI_ICT_FVG_规格书_v1.md
new file mode 100644
index 0000000..f90ac6e
--- /dev/null
+++ b/docs/AI_ICT_FVG_规格书_v1.md
@@ -0,0 +1,466 @@
+# AI ICT FVG 规格书 v1
+
+## 1. 文档目标
+
+本文档定义 AI ICT 项目第一阶段的 FVG（Fair Value Gap）识别与使用规则，用于把位移过程中形成的低效率定价区结构化存储，并为后续 retrace entry、目标管理与 signal 生成提供关键参考。
+
+FVG 模块位于以下链路中：
+
+`Sweep -> Displacement -> MSS -> FVG -> Retrace Entry -> Signal`
+
+本模块输出将直接影响：
+
+- 是否存在可回补的低效率定价区
+- Displacement 是否具备更强结构解释力
+- MSS 之后是否有可执行的 retrace 区域
+- Signal 是否能获得更清晰的 entry zone
+- 后续 fill / mitigation / invalidation 管理
+
+因此，FVG 是 MVP 主模型中最关键的入场区域模块之一。
+
+---
+
+## 2. 模块职责
+
+### 2.1 本模块负责
+
+1. 识别 bullish / bearish FVG
+2. 记录 FVG 的上下边界
+3. 跟踪 fill_pct 与 mitigation 状态
+4. 标记与 displacement 的联动关系
+5. 为 retrace entry 提供结构区间
+
+### 2.2 本模块不负责
+
+- Displacement 成立判定
+- MSS 成立判定
+- Signal 最终下单许可
+- 仓位管理
+
+这些由上下游模块分别负责。
+
+---
+
+## 3. 输入与输出
+
+## 3.1 输入
+
+本模块依赖：
+
+- `candles`
+- 可选：`displacement_events`
+- timeframe
+
+至少需要：
+
+- open
+- high
+- low
+- close
+- ts
+
+---
+
+## 3.2 输出
+
+输出写入 `fvg_zones`，字段建议包括：
+
+- instrument_id
+- timeframe
+- direction
+- upper
+- lower
+- start_ts
+- end_ts
+- fill_pct
+- status
+- related_displacement_id
+- meta
+
+其中：
+
+- `direction = bullish | bearish`
+- `status = open | touched | mitigated | invalidated`
+
+---
+
+## 4. 核心定义
+
+## 4.1 FVG（Fair Value Gap）
+
+FVG 指价格在快速位移过程中形成的低效率定价区，表现为三根 candle 之间出现未被充分交易覆盖的区间。
+
+在 ICT 语境中，FVG 往往具有两层含义：
+
+1. 位移强度的副产物
+2. 后续回补与承接的候选区域
+
+因此：
+
+- FVG 既是结构表达
+- 也是 retrace entry 的候选位置
+
+---
+
+## 4.2 为什么 FVG 重要
+
+对于 MVP 主模型：
+
+`Sweep -> MSS -> FVG Retrace`
+
+FVG 的作用是把“结构切换”转成一个更可执行的 entry zone。
+
+若只有 MSS，没有清晰 FVG：
+
+- 可以有结构解释
+- 但入场位置往往不够标准化
+
+因此，FVG 是把结构分析连接到执行区域的关键模块。
+
+---
+
+## 5. 识别逻辑
+
+第一阶段采用标准三根 candle 逻辑。
+
+## 5.1 bullish FVG
+
+对于连续三根 candle：
+
+- 若第 1 根的 high < 第 3 根的 low
+
+则认为存在 bullish FVG。
+
+区间定义：
+
+- lower = candle1.high
+- upper = candle3.low
+
+说明：
+
+- 这表示中间位移过程中价格上移过快，留下未充分交易覆盖区间
+
+---
+
+## 5.2 bearish FVG
+
+对于连续三根 candle：
+
+- 若第 1 根的 low > 第 3 根的 high
+
+则认为存在 bearish FVG。
+
+区间定义：
+
+- lower = candle3.high
+- upper = candle1.low
+
+说明：
+
+- 这表示中间位移过程中价格下移过快，留下未充分交易覆盖区间
+
+---
+
+## 6. FVG 与 Displacement 的联动
+
+第一阶段建议：
+
+- FVG 不单独脱离价格背景解释
+- 若 FVG 来自有效 displacement，其价值显著提高
+
+因此建议保留字段：
+
+- `related_displacement_id`
+- `meta.has_displacement_context`
+
+---
+
+## 6.1 有 displacement 背景的 FVG
+
+若 FVG 伴随 displacement 出现：
+
+- 其作为 retrace zone 的解释力更强
+- 更适合作为 signal 候选入场区
+
+---
+
+## 6.2 无 displacement 背景的 FVG
+
+无 displacement 背景的 FVG 仍可识别，但执行价值通常较弱。
+
+第一阶段建议：
+
+- 允许保留
+- 但优先级低于 displacement-backed FVG
+
+---
+
+## 7. 状态管理
+
+第一阶段建议支持以下状态：
+
+- open
+- touched
+- mitigated
+- invalidated
+
+---
+
+## 7.1 open
+
+FVG 刚形成，尚未被后续价格触达。
+
+---
+
+## 7.2 touched
+
+价格已进入 FVG 区间，但尚未完全回补。
+
+---
+
+## 7.3 mitigated
+
+价格已完成较充分回补，FVG 的执行价值显著下降。
+
+第一阶段建议：
+
+- 当 fill_pct 达到预设阈值，可标记为 mitigated
+
+---
+
+## 7.4 invalidated
+
+若后续价格行为表明该 FVG 不再具有结构价值，则标记 invalidated。
+
+例如：
+
+- 结构方向被彻底否定
+- 价格长时间在区间内无意义穿梭
+- FVG 对应的 MSS 已失效
+
+---
+
+## 8. fill_pct 计算
+
+为了追踪 FVG 被回补的程度，建议计算：
+
+- `fill_pct`
+
+其含义是：
+
+- 当前价格对 FVG 区间已回补的比例
+
+第一阶段不必追求复杂公式，但应固定统一口径。
+
+建议要求：
+
+- 0.0 表示完全未回补
+- 1.0 表示完全回补
+
+---
+
+## 9. retrace entry 使用规则
+
+FVG 最重要的用途之一，是作为 retrace entry zone。
+
+## 9.1 bullish FVG retrace
+
+若上游结构为 bullish：
+
+- 等待价格回补到 bullish FVG 区间
+- 结合 MSS、session、RR 再决定是否进入 signal 候选
+
+---
+
+## 9.2 bearish FVG retrace
+
+若上游结构为 bearish：
+
+- 等待价格回补到 bearish FVG 区间
+- 再结合下游模块决定是否进入执行候选
+
+---
+
+## 9.3 不建议直接用法
+
+第一阶段不建议：
+
+- 只看到 FVG 就直接做单
+- 脱离 MSS / sweep / displacement 背景使用 FVG
+
+因为 FVG 本身不是方向确认工具，它只是位置工具。
+
+---
+
+## 10. 多个 FVG 并存的处理
+
+同一时间窗口可能出现多个 FVG。
+
+第一阶段建议：
+
+1. 允许多个 FVG 并存
+2. 优先考虑最近的、与当前 displacement 直接相关的 FVG
+3. 若多个 FVG 高度重叠，可由下游模块再做优先级筛选
+
+本模块不负责最终优先级排序，只负责正确识别和状态追踪。
+
+---
+
+## 11. 边界与异常处理
+
+## 11.1 极窄 gap
+
+若 gap 极小，可能是噪音，不一定有执行价值。
+
+第一阶段建议：
+
+- 仍可识别
+- 但可在 `meta` 中记录 width
+- 下游再决定是否过滤过窄 FVG
+
+---
+
+## 11.2 已完全回补后再次识别
+
+若同一 FVG 已被充分回补并 mitigation 完成：
+
+- 不应反复当作新鲜主执行区
+
+---
+
+## 11.3 数据缺口
+
+若 candles 本身存在数据缺口：
+
+- 可能误判为假 FVG
+- 此时应在 `meta` 中记录数据质量异常
+- 不建议进入高质量执行链路
+
+---
+
+## 12. 写入策略
+
+## 12.1 幂等要求
+
+同一组三根 candle 重复计算时：
+
+- 不应重复生成 identical FVG
+
+建议幂等参考：
+
+- instrument_id
+- timeframe
+- direction
+- start_ts
+- end_ts
+- upper
+- lower
+
+---
+
+## 12.2 更新策略
+
+后续运行时：
+
+- 更新 fill_pct
+- 更新 status
+- 更新 related_displacement 信息（若后补识别）
+
+---
+
+## 13. 下游依赖约定
+
+FVG 输出将被下游这样使用：
+
+### Signal 模块
+- 作为 retrace entry zone
+
+### Bias / Context 模块
+- 作为结构解释增强项
+
+### Risk 模块
+- 可辅助 stop 位置思考（但不是本模块职责）
+
+因此，本模块至少应稳定输出：
+
+- direction
+- price zone
+- fill_pct
+- status
+- displacement 关联
+
+---
+
+## 14. 推荐任务拆分
+
+### T1. 三根 candle FVG 识别
+- bullish / bearish 基础规则
+
+### T2. FVG 入库
+- 写入 `fvg_zones`
+- 做幂等控制
+
+### T3. fill_pct 追踪
+- 跟踪后续价格回补程度
+
+### T4. status 更新
+- open / touched / mitigated / invalidated
+
+### T5. displacement 关联
+- 标记 related_displacement_id
+
+---
+
+## 15. 验证检查点
+
+## 15.1 最低验证
+
+至少验证：
+
+- [ ] bullish FVG 可识别
+- [ ] bearish FVG 可识别
+- [ ] upper / lower 边界正确
+- [ ] fill_pct 可更新
+- [ ] status 可变化
+
+---
+
+## 15.2 行为验证
+
+- [ ] 有 displacement 背景的 FVG 可正确关联
+- [ ] 已完全回补的 FVG 会进入 mitigated
+- [ ] 无结构背景的 FVG 不会自动变成高质量执行区
+
+---
+
+## 15.3 人工抽查
+
+至少抽取图表样本：
+
+- [ ] FVG 边界与肉眼观察一致
+- [ ] fill 过程合理
+- [ ] retrace zone 解释符合走势
+- [ ] mitigated / invalidated 状态切换合理
+
+---
+
+## 16. 完成标准
+
+只有满足以下全部条件，FVG 模块才算完成：
+
+1. 能识别 bullish / bearish FVG
+2. 能稳定输出 price zone
+3. 能追踪 fill_pct
+4. 能维护 status
+5. 能与 displacement 关联
+6. 可直接供 retrace signal 模块使用
+
+---
+
+## 17. 当前结论
+
+FVG 模块是把“结构变化”转成“可回补入场区域”的关键执行桥梁。
+
+在 MVP 主模型里，它不是附属概念，而是：
+
+> 从 MSS 走向可执行 retrace entry 的核心位置模块。
diff --git a/docs/AI_ICT_Liquidity_Pool_规格书_v1.md b/docs/AI_ICT_Liquidity_Pool_规格书_v1.md
new file mode 100644
index 0000000..94d4ee6
--- /dev/null
+++ b/docs/AI_ICT_Liquidity_Pool_规格书_v1.md
@@ -0,0 +1,429 @@
+# AI ICT Liquidity Pool 规格书 v1
+
+## 1. 文档目标
+
+本文档定义 AI ICT 项目第一阶段的 Liquidity Pool 识别规则，用于结构化标记市场中可能被优先处理的流动性区域，并写入 `liquidity_pools` 表。
+
+Liquidity Pool 模块位于以下链路中：
+
+`Candles -> Sessions -> Swings -> Dealing Range -> Liquidity Pools -> Sweep -> MSS`
+
+本模块的输出会直接影响：
+
+- buy-side / sell-side liquidity 识别
+- prior highs / lows 标记
+- equal highs / lows 标记
+- session high / low 标记
+- sweep 检测
+- draw on liquidity 候选目标
+
+因此，Liquidity Pool 是后续 sweep 与目标判断的直接前置模块。
+
+---
+
+## 2. 模块职责
+
+### 2.1 本模块负责
+
+1. 识别 prior high / prior low
+2. 识别 equal highs / equal lows
+3. 识别 session highs / lows
+4. 给出 pool 的 side、type 和价格区间
+5. 维护 pool 状态变化
+6. 写入 `liquidity_pools`
+
+### 2.2 本模块不负责
+
+- sweep 是否成立
+- draw 优先级排序
+- MSS 判定
+- bias 方向
+
+这些属于下游模块。
+
+---
+
+## 3. 输入与输出
+
+## 3.1 输入
+
+本模块依赖：
+
+- `swings`
+- `market_sessions`
+- 当前 timeframe
+- equal-high/equal-low 阈值配置
+
+至少需要：
+
+- swing high / low
+- price
+- ts
+- session high / low
+
+---
+
+## 3.2 输出
+
+输出写入 `liquidity_pools` 表，字段包括：
+
+- instrument_id
+- timeframe
+- side
+- pool_type
+- price_low
+- price_high
+- reference_ids
+- status
+- created_ts
+- updated_ts
+- meta
+
+其中：
+
+- `side` = `buy_side | sell_side`
+- `pool_type` = `prior_high | prior_low | equal_highs | equal_lows | session_high | session_low`
+
+---
+
+## 4. 基础定义
+
+## 4.1 Buy-Side Liquidity
+
+通常指位于价格上方、容易吸引向上处理的流动性区域。
+
+第一阶段主要来自：
+
+- prior high
+- equal highs
+- session high
+
+---
+
+## 4.2 Sell-Side Liquidity
+
+通常指位于价格下方、容易吸引向下处理的流动性区域。
+
+第一阶段主要来自：
+
+- prior low
+- equal lows
+- session low
+
+---
+
+## 4.3 Pool 的本质
+
+Pool 不是“一个点”，而是一个可能被处理的价格区间。
+
+因此：
+
+- 对于单一 prior high / low，可允许 price_low = price_high
+- 对于 equal highs / lows，应允许一个窄区间
+
+---
+
+## 5. prior high / prior low 识别规则
+
+## 5.1 prior high
+
+来源：
+
+- 已确认 swing high
+
+输出：
+
+- `side = buy_side`
+- `pool_type = prior_high`
+- `price_low = swing price`
+- `price_high = swing price`
+
+---
+
+## 5.2 prior low
+
+来源：
+
+- 已确认 swing low
+
+输出：
+
+- `side = sell_side`
+- `pool_type = prior_low`
+- `price_low = swing price`
+- `price_high = swing price`
+
+---
+
+## 6. equal highs / equal lows 识别规则
+
+这是第一阶段最需要参数化的部分。
+
+## 6.1 equal highs
+
+若多个 swing highs 的价格足够接近，且落在定义阈值内，则可合并标记为 equal highs pool。
+
+输出：
+
+- `side = buy_side`
+- `pool_type = equal_highs`
+- `price_low = min(high prices)`
+- `price_high = max(high prices)`
+
+---
+
+## 6.2 equal lows
+
+若多个 swing lows 的价格足够接近，且落在定义阈值内，则可合并标记为 equal lows pool。
+
+输出：
+
+- `side = sell_side`
+- `pool_type = equal_lows`
+- `price_low = min(low prices)`
+- `price_high = max(low prices)`
+
+---
+
+## 6.3 阈值建议
+
+阈值必须配置化。
+
+第一阶段建议：
+
+### BTC / ETH
+- 可使用百分比阈值，例如极小百分比
+
+### XAU
+- 可使用固定 tick 阈值
+
+原则：
+
+- 不同品种不能硬套同一个固定数值
+- 第一阶段可以先设保守阈值
+
+---
+
+## 7. session high / low 识别规则
+
+Session-based liquidity 来源于 `market_sessions` 表。
+
+## 7.1 session high
+
+来源：
+
+- ASIA high
+- LONDON high
+- NY_AM high
+- NY_LUNCH high
+- NY_PM high
+
+输出：
+
+- `side = buy_side`
+- `pool_type = session_high`
+- `price_low = session high`
+- `price_high = session high`
+
+---
+
+## 7.2 session low
+
+来源：
+
+- ASIA low
+- LONDON low
+- NY_AM low
+- NY_LUNCH low
+- NY_PM low
+
+输出：
+
+- `side = sell_side`
+- `pool_type = session_low`
+- `price_low = session low`
+- `price_high = session low`
+
+---
+
+## 8. Pool 状态机
+
+第一阶段建议支持以下状态：
+
+- untouched
+- swept
+- consumed
+- invalid
+
+含义：
+
+- untouched：尚未被价格处理
+- swept：已被刺穿 / 处理
+- consumed：后续不再作为主要 pool 使用
+- invalid：来源异常或数据不完整
+
+---
+
+## 8.1 touched 与 swept 的处理
+
+第一阶段不单独引入 `touched`，统一收敛为：
+
+- 若已明确被价格刺穿，则标记 `swept`
+
+更细粒度状态可在后续引入。
+
+---
+
+## 9. 幂等与合并规则
+
+## 9.1 同来源重复识别
+
+若同一来源对象重复计算：
+
+- 不应重复生成多个 pool
+- 应按 `reference_ids + type + timeframe` 做幂等更新
+
+---
+
+## 9.2 合并规则
+
+对于 equal highs / equal lows：
+
+- 相同 cluster 中的多个点应合并成一个 pool
+- 不建议每个近似价格点各生成一条 pool
+
+否则下游 sweep 识别会混乱。
+
+---
+
+## 10. 边界与异常处理
+
+## 10.1 不完整 session
+
+若 session 状态为 `incomplete` 或 `invalid`：
+
+- 第一阶段建议不生成正式 session pool
+- 或在 `meta` 中显式标记风险
+
+---
+
+## 10.2 未确认 swing
+n
+第一阶段建议：
+
+- prior high / prior low 只使用 confirmed swings
+- provisional swings 不进入正式 liquidity pool
+
+这样可避免未来数据偏差污染。
+
+---
+
+## 10.3 重复 cluster
+
+若 equal highs / lows cluster 高度重叠：
+
+- 应优先合并为一个 pool
+- 不允许生成多个高度重复 pool
+
+---
+
+## 11. 下游依赖约定
+
+Liquidity Pool 输出将被下游这样使用：
+
+### Sweep 模块
+- 判断某一侧 pool 是否被刺穿
+
+### Draw 模块
+- 判断当前未处理目标
+
+### Signal 模块
+- 判断当前路径是否具备先清理后递送特征
+
+因此，本模块输出至少要稳定提供：
+
+- side
+- pool_type
+- price range
+- status
+- reference_ids
+
+---
+
+## 12. 推荐任务拆分
+
+### T1. prior high / low 识别
+- 从 confirmed swings 生成 pool
+
+### T2. equal highs / lows cluster
+- 按阈值聚类
+- 生成区间型 pool
+
+### T3. session high / low pool
+- 从 `market_sessions` 生成 session pool
+
+### T4. pool 入库与幂等更新
+- 写入 `liquidity_pools`
+- 更新 status
+
+### T5. 合并与去重
+- 处理重叠 cluster
+- 避免重复 pool
+
+---
+
+## 13. 验证检查点
+
+## 13.1 最低验证
+
+至少验证：
+
+- [ ] prior high 可生成 buy-side pool
+- [ ] prior low 可生成 sell-side pool
+- [ ] equal highs 可生成区间型 pool
+- [ ] equal lows 可生成区间型 pool
+- [ ] session high / low 可生成 pool
+
+---
+
+## 13.2 数据验证
+
+- [ ] buy_side pool 位于上方目标语义
+- [ ] sell_side pool 位于下方目标语义
+- [ ] equal-highs pool 的 `price_low <= price_high`
+- [ ] status 初始为 untouched
+- [ ] reference_ids 可追溯来源
+
+---
+
+## 13.3 人工抽查
+
+随机抽样检查：
+
+- [ ] prior highs / lows 与 swing 来源一致
+- [ ] equal highs / lows 聚类合理
+- [ ] session pools 与 session high/low 一致
+- [ ] 没有明显重复 pool 污染
+
+---
+
+## 14. 完成标准
+
+只有满足以下全部条件，Liquidity Pool 模块才算完成：
+
+1. 支持 prior highs / lows
+2. 支持 equal highs / lows
+3. 支持 session highs / lows
+4. 支持 status 管理
+5. 支持幂等写入 `liquidity_pools`
+6. 可直接供 sweep 模块使用
+
+---
+
+## 15. 当前结论
+
+Liquidity Pool 模块是市场“待处理目标”的结构化表达层。
+
+如果 Swing 提供锚点、Dealing Range 提供空间坐标，那么 Liquidity Pool 就提供“价格下一步可能优先处理哪里”的候选目标集合。
+
+在真实开发中，它应被视为进入 sweep 和 draw 模块之前必须稳定完成的关键基础模块。
\ No newline at end of file
diff --git a/docs/AI_ICT_MSS_判定规格书_v1.md b/docs/AI_ICT_MSS_判定规格书_v1.md
new file mode 100644
index 0000000..3304386
--- /dev/null
+++ b/docs/AI_ICT_MSS_判定规格书_v1.md
@@ -0,0 +1,472 @@
+# AI ICT MSS 判定规格书 v1
+
+## 1. 文档目标
+
+本文档定义 AI ICT 项目第一阶段的 MSS（Market Structure Shift）判定规则，用于把结构破坏、位移、承接和路径重排组合成一个可执行的“控制权切换”事件。
+
+MSS 模块位于以下链路中：
+
+`Swing -> Liquidity -> Sweep -> Displacement -> MSB -> MSS -> Signal`
+
+本模块的输出将直接影响：
+
+- 旧路径是否只是不稳，还是已经发生控制权切换
+- reversal / continuation 叙事是否成立
+- FVG retrace 是否值得进入候选执行链路
+- Daily Bias 是否可被增强或重排
+- trade signal 是否有资格进入 awaiting_confirmation
+
+因此，MSS 是基础结构链中最关键的“控制权确认模块”。
+
+---
+
+## 2. 模块职责
+
+### 2.1 本模块负责
+
+1. 区分 MSB 与 MSS
+2. 识别结构是否发生控制权切换
+3. 要求位移与承接证据闭合
+4. 输出 bullish / bearish MSS 事件
+5. 为下游 signal 提供结构确认依据
+
+### 2.2 本模块不负责
+
+- Bias 最终生成
+- Signal 最终下单许可
+- FVG 本体识别
+- 账户风控判断
+
+这些都由下游模块处理。
+
+---
+
+## 3. 输入与输出
+
+## 3.1 输入
+
+本模块依赖：
+
+- `swings`
+- `displacement_events`
+- 可选：`sweep_events`
+- 当前价格与后续 retest 行为
+
+至少需要：
+
+- 被破坏的 swing
+- 破坏方向
+- displacement 方向与强度
+- retest / acceptance 信息
+
+---
+
+## 3.2 输出
+
+输出建议写入 `structure_events`，字段包括：
+
+- instrument_id
+- timeframe
+- event_type
+- direction
+- broken_level
+- reference_swing_id
+- displacement_event_id
+- accepted
+- ts
+- meta
+
+其中：
+
+- `event_type = MSS`
+- `direction = bullish | bearish`
+- `accepted = true | false`
+
+---
+
+## 4. 核心定义
+
+## 4.1 MSB（Market Structure Break）
+
+MSB 表示：
+
+- 旧路径被破坏
+- 但新路径未必已经成立
+
+它解决的是：
+
+> 原结构还能不能继续稳定维持？
+
+MSB 不是最终交易结论。
+
+---
+
+## 4.2 MSS（Market Structure Shift）
+
+MSS 表示：
+
+- 旧路径已被破坏
+- 且反向控制权已经通过位移与承接被确认
+
+它解决的是：
+
+> 新的主导权是否已经开始接管？
+
+因此：
+
+- 不是每个 MSB 都能升级成 MSS
+- MSS 必须是“证据链闭合”后的结果
+
+---
+
+## 5. MSS 的证据链
+
+第一阶段建议把 MSS 定义为以下 4 个环节组成：
+
+1. 结构破坏（MSB）
+2. 有效位移（Displacement）
+3. 回补后的承接（Retest / Acceptance）
+4. 主路径重排（New Draw becomes meaningful）
+
+只有这 4 个环节基本闭合，才进入 MSS。
+
+---
+
+## 5.1 环节 1：结构破坏
+
+必须先出现关键 swing 被有效破坏。
+
+例如：
+
+- bearish 环境下，某关键高点被向上破坏 -> 候选 bullish MSB
+- bullish 环境下，某关键低点被向下破坏 -> 候选 bearish MSB
+
+要求：
+
+- 破坏对象必须来自有效 swing
+- 不能用随机局部波动当关键结构点
+
+---
+
+## 5.2 环节 2：有效位移
+
+MSB 之后必须出现与候选新方向一致的 displacement。
+
+要求：
+
+- displacement 方向必须与 MSS 方向一致
+- displacement 不能只是噪音波动
+- 若伴随 FVG，则解释力更强
+
+说明：
+
+- 没有 displacement 的 MSB，通常不应升级为 MSS
+
+---
+
+## 5.3 环节 3：承接 / Acceptance
+
+新方向不能只靠一次冲击成立，还需要后续承接。
+
+常见表现：
+
+- 回补后未失守关键接管边界
+- 回测后继续保持新方向控制权
+- 未被快速重新夺回原区间
+
+第一阶段建议用布尔标记：
+
+- `accepted = true | false`
+
+---
+
+## 5.4 环节 4：路径重排
+
+若 MSS 成立，下游应能看到：
+
+- 原来的主 Draw 不再占优
+- 新的目标方向开始具备解释力
+
+说明：
+
+- 路径重排不一定在本模块里完全算完
+- 但 MSS 至少应在 `meta` 中保留足够信息，供下游确认“新路径已具备可叙述性”
+
+---
+
+## 6. bullish MSS 判定
+
+第一阶段建议：
+
+若满足以下条件，则可判为 bullish MSS：
+
+1. 先出现候选 bullish MSB
+2. 后续出现 bullish displacement
+3. 回补后未重新跌回关键失效边界下方
+4. 新的上方递送路径开始具备解释力
+
+输出：
+
+- `event_type = MSS`
+- `direction = bullish`
+- `accepted = true`
+
+---
+
+## 7. bearish MSS 判定
+
+若满足以下条件，则可判为 bearish MSS：
+
+1. 先出现候选 bearish MSB
+2. 后续出现 bearish displacement
+3. 回补后未重新站回关键失效边界上方
+4. 新的下方递送路径开始具备解释力
+
+输出：
+
+- `event_type = MSS`
+- `direction = bearish`
+- `accepted = true`
+
+---
+
+## 8. 不成立情况
+
+以下情况第一阶段不应升级为 MSS：
+
+### 8.1 只有 MSB，没有 displacement
+
+- 旧结构虽然不稳
+- 但没有新方向控制权表达
+
+结论：
+- 保留为 MSB
+- 不升级 MSS
+
+---
+
+### 8.2 有 displacement，但没有承接
+
+- 价格冲击后又被快速夺回
+- 回补后无法守住新方向边界
+
+结论：
+- 可视为 failed shift
+- 不升级 MSS
+
+---
+
+### 8.3 假突破 / 流动性清理后立即反夺回
+
+- 刺穿看似结构破坏
+- 但后续并未形成真正接管
+
+结论：
+- 更接近 liquidity event
+- 不应升级 MSS
+
+---
+
+### 8.4 时间框架错位
+
+若低周期破坏试图越权改写高周期主结构：
+
+- 在本周期可记为局部 MSS 候选
+- 但不能自动等于更高周期结构切换
+
+说明：
+- MSS 必须绑定 timeframe
+
+---
+
+## 9. 与 Sweep 的联动
+
+若 MSS 前存在相关 sweep：
+
+- 该 MSS 的解释力更强
+- 更符合“先清理，后位移，再切换”的链路
+
+建议在 `meta` 中记录：
+
+- related_sweep_id
+- sweep_side
+- bars_between_sweep_and_mss
+
+说明：
+
+- 没有 sweep 也可能出现 MSS
+- 但存在 sweep 背景时，更符合 ICT 核心路径
+
+---
+
+## 10. 与 FVG 的联动
+
+若 displacement 同时产生 FVG：
+
+- 后续可作为 retrace entry zone
+- MSS 的可执行意义增强
+
+因此建议在 `meta` 中记录：
+
+- related_fvg_id
+- has_related_fvg
+
+说明：
+
+- FVG 不是 MSS 必须条件
+- 但它会显著增强下游执行价值
+
+---
+
+## 11. 时间确认与窗口
+
+## 11.1 观察窗口
+
+MSS 不应无限期挂起等待。
+
+第一阶段建议：
+
+- 在 MSB 与 displacement 出现后，给一个有限 retest / acceptance 观察窗口
+
+若窗口结束仍未形成 acceptance：
+
+- 不应继续保留 MSS 候选
+
+---
+
+## 11.2 confirmed MSS
+
+第一阶段建议只把 confirmed MSS 写入主结构事件表。
+
+原因：
+
+- 如果把大量候选 shift 都写入数据库，会污染下游 signal 逻辑
+
+因此：
+
+- 候选状态可以在运行时内存中存在
+- 最终落库尽量只保留 confirmed MSS
+
+---
+
+## 12. 写入策略
+
+## 12.1 幂等要求
+
+相同结构切换重复计算时：
+
+- 不应产生多个 identical MSS 记录
+
+建议幂等参考：
+
+- instrument_id
+- timeframe
+- direction
+- reference_swing_id
+- displacement_event_id
+- ts 所在主事件窗口
+
+---
+
+## 12.2 `accepted` 字段
+
+第一阶段建议：
+
+- `accepted = true` 才进入高可信 MSS
+- 若后续验证失败，可更新为 false 或不写入主表
+
+---
+
+## 13. 下游依赖约定
+
+MSS 输出将被下游这样使用：
+
+### Bias
+- 判断控制权是否已切换
+
+### Signal
+- 判断结构确认是否已经足够进入候选执行链路
+
+### FVG Retrace Model
+- 只有在 MSS 成立后，FVG retrace 才更具执行意义
+
+因此 MSS 至少必须稳定输出：
+
+- direction
+- broken_level
+- accepted
+- displacement 关联
+- timeframe
+
+---
+
+## 14. 推荐任务拆分
+
+### T1. MSB 识别
+- 判断关键 swing 是否被有效破坏
+
+### T2. displacement 关联
+- 检查候选方向是否存在有效位移
+
+### T3. acceptance 检测
+- 回补后是否守住新方向边界
+
+### T4. MSS 事件入库
+- 写入 `structure_events`
+- 标记 `event_type = MSS`
+
+### T5. sweep / FVG 关联
+- 增强下游执行语义
+
+---
+
+## 15. 验证检查点
+
+## 15.1 最低验证
+
+至少验证：
+
+- [ ] bullish MSS 可识别
+- [ ] bearish MSS 可识别
+- [ ] 只有 MSB 不会误升为 MSS
+- [ ] displacement 缺失时不会误判 MSS
+
+---
+
+## 15.2 行为验证
+
+- [ ] acceptance 失败时不会保留 confirmed MSS
+- [ ] 低周期 MSS 不会越权改写高周期结构
+- [ ] 有 sweep 背景的 MSS 更易进入高质量链路
+
+---
+
+## 15.3 人工抽查
+
+至少抽查样本图表：
+
+- [ ] 被破坏 swing 选取合理
+- [ ] displacement 方向匹配
+- [ ] retest / acceptance 解释合理
+- [ ] confirmed MSS 与图表主观结构变化一致
+
+---
+
+## 16. 完成标准
+
+只有满足以下全部条件，MSS 模块才算完成：
+
+1. 能稳定区分 MSB 与 MSS
+2. 能要求 displacement 作为必要证据
+3. 能要求 retest / acceptance 作为确认条件
+4. 能输出 bullish / bearish MSS
+5. 能幂等写入 `structure_events`
+6. 可直接供 signal 模块使用
+
+---
+
+## 17. 当前结论
+
+MSS 模块不是“突破后换个名字”，而是把“旧结构失效 + 新方向接管”闭合为一个可执行事件。
+
+在真实开发中，它是从结构观察进入执行许可之前最关键的一道结构确认门。
\ No newline at end of file
diff --git a/docs/AI_ICT_MVP_规则规格书_v1.md b/docs/AI_ICT_MVP_规则规格书_v1.md
new file mode 100644
index 0000000..24f3ff2
--- /dev/null
+++ b/docs/AI_ICT_MVP_规则规格书_v1.md
@@ -0,0 +1,761 @@
+# AI ICT MVP 规则规格书 v1
+
+## 1. 文档目标
+
+本文档定义 AI ICT 项目第一阶段 MVP 的规则规格，用于指导后续规则引擎、信号生成、回测、报告与执行模块开发。
+
+第一阶段只围绕一个核心模型：
+
+`Sweep -> MSS -> FVG Retrace -> IRL/ERL`
+
+支持资产：
+
+- BTC
+- ETH
+- XAU
+
+支持目标：
+
+- 规则识别
+- 候选信号生成
+- 回测验证
+- 半自动执行
+- 复盘归因
+
+---
+
+## 2. 规则设计原则
+
+1. 规则引擎主判定，AI 不主判单
+2. 所有判断尽量结构化、可存储、可回测
+3. 高周期定向，低周期触发
+4. 先条件、再触发、再确认、再执行、再退出
+5. 会话过滤和风控过滤属于硬规则
+6. 不在 MVP 阶段同时推进过多模型
+
+---
+
+## 3. 时间框架职责
+
+### 3.1 默认职责
+
+- bias_tf：方向与背景
+- range_tf：工作区间与位置
+- setup_tf：结构与路径
+- trigger_tf：触发与执行
+
+### 3.2 MVP 默认配置
+
+#### BTC / ETH
+
+- bias_tf: H4
+- range_tf: H1
+- setup_tf: M15
+- trigger_tf: M5
+
+#### XAU
+
+- bias_tf: H1
+- range_tf: M15
+- setup_tf: M5
+- trigger_tf: M1
+
+原则：低周期不能越权改写高周期方向，只能优化执行。
+
+---
+
+## 4. 核心对象
+
+## 4.1 Candle
+
+标准 K 线对象，作为全部规则输入基础。
+
+关键字段：
+
+- symbol
+- venue
+- timeframe
+- ts_open
+- ts_close
+- open
+- high
+- low
+- close
+- volume
+
+---
+
+## 4.2 SwingPoint
+
+用途：标记结构高低点。
+
+关键字段：
+
+- kind: swing_high / swing_low
+- strength: ST / IT / LT
+- price
+- ts
+- left_bars
+- right_bars
+- confirmed
+
+---
+
+## 4.3 DealingRange
+
+用途：建立当前工作区间与位置坐标。
+
+关键字段：
+
+- high
+- low
+- equilibrium
+- timeframe
+- high_swing_id
+- low_swing_id
+- state
+
+输出位置：
+
+- premium
+- discount
+- equilibrium
+
+---
+
+## 4.4 MarketSession
+
+用途：建立会话边界和会话 pivot。
+
+关键字段：
+
+- session_code
+- start_ts
+- end_ts
+- high
+- low
+- midpoint
+- status
+
+默认会话：
+
+- ASIA
+- LONDON
+- NY_AM
+- NY_LUNCH
+- NY_PM
+
+---
+
+## 4.5 LiquidityPool
+
+用途：标记待处理流动性区域。
+
+关键字段：
+
+- side: buy_side / sell_side
+- pool_type
+- price_low
+- price_high
+- reference_ids
+- status
+
+第一版 pool_type：
+
+- prior_high
+- prior_low
+- equal_highs
+- equal_lows
+- session_high
+- session_low
+
+---
+
+## 4.6 SweepEvent
+
+用途：标记一侧流动性被清理。
+
+关键字段：
+
+- side_swept
+- pool_id
+- sweep_high
+- sweep_low
+- close_back_inside
+- displacement_after
+- ts
+
+---
+
+## 4.7 DisplacementEvent
+
+用途：标记有效位移。
+
+关键字段：
+
+- direction
+- start_ts
+- end_ts
+- strength_score
+- body_ratio
+- has_fvg
+- is_valid
+
+---
+
+## 4.8 StructureEvent
+
+用途：保存 MSB / MSS。
+
+关键字段：
+
+- event_type: MSB / MSS
+- direction
+- broken_level
+- reference_swing_id
+- displacement_event_id
+- accepted
+- ts
+
+---
+
+## 4.9 FVGZone
+
+用途：作为 retrace entry zone。
+
+关键字段：
+
+- direction
+- upper
+- lower
+- start_ts
+- end_ts
+- fill_pct
+- status
+
+状态：
+
+- open
+- touched
+- mitigated
+- invalidated
+
+---
+
+## 4.10 BiasSnapshot
+
+用途：保存某一时刻的偏向判断。
+
+关键字段：
+
+- daily_bias
+- confidence
+- execution_intensity
+- narrative_code
+- draw_side
+- range_id
+- reason_codes
+
+---
+
+## 4.11 TradeSignal
+
+用途：保存候选交易信号。
+
+关键字段：
+
+- model_code
+- side
+- status
+- entry_low / entry_high
+- stop_loss
+- tp1
+- tp2
+- rr_tp1
+- rr_tp2
+- invalidations
+- evidence
+
+---
+
+## 5. 规则清单
+
+## R1. Swing 识别规则
+
+### 目标
+识别结构锚点，供 range、liquidity、MSB/MSS 使用。
+
+### 输入
+- 连续 candles
+- 参数：left_bars, right_bars
+
+### 判定
+#### swing high
+当前 K 线高点高于左右指定数量 K 线高点。
+
+#### swing low
+当前 K 线低点低于左右指定数量 K 线低点。
+
+### 默认参数
+- M1/M5: 2 / 2
+- M15/H1: 3 / 3
+- H4/D: 3 / 3
+
+### 输出
+- SwingPoint[]
+
+### 注意
+- 未完成右侧确认前，可仅标 provisional
+- 最终回测时只以 confirmed swing 为准
+
+---
+
+## R2. Dealing Range 识别规则
+
+### 目标
+建立工作区间和位置坐标。
+
+### 输入
+- 指定周期 swings
+
+### 判定
+1. 选取最近有效 swing high / swing low
+2. high = range 上边界
+3. low = range 下边界
+4. equilibrium = (high + low) / 2
+
+### 输出
+- DealingRange
+- 当前价格位置：premium / discount / equilibrium
+
+### MVP 简化
+- 每个 timeframe 同时只保留一个主工作区间
+
+---
+
+## R3. Liquidity Pool 识别规则
+
+### 目标
+标记可能被优先处理的流动性区域。
+
+### 输入
+- swings
+- session pivots
+- equal highs/lows 检测结果
+
+### 判定对象
+1. prior high / prior low
+2. equal highs / equal lows
+3. Asia high / low
+4. London high / low
+
+### 输出
+- LiquidityPool[]
+
+### 等高等低阈值
+应配置化，不同品种分开：
+
+- BTC / ETH：建议按百分比阈值
+- XAU：建议按固定 tick 阈值
+
+---
+
+## R4. Sweep 识别规则
+
+### 目标
+识别“先清理，再递送”。
+
+### 输入
+- candles
+- liquidity pools
+
+### 判定
+#### buy-side sweep
+1. 价格刺穿 buy-side pool
+2. 随后回落或重新收回池内
+3. 后续出现反向 displacement 更优
+
+#### sell-side sweep
+反向。
+
+### 分类
+- weak_sweep
+- validated_sweep
+
+### validated_sweep 要求
+- sweep 后 N 根内出现反向 displacement
+
+### 输出
+- SweepEvent
+
+---
+
+## R5. Displacement 识别规则
+
+### 目标
+识别有效位移，避免把普通波动当趋势接管。
+
+### 输入
+- candles
+- ATR / 平均实体参考
+- FVG 检测结果
+
+### 建议判定
+满足以下至少两条：
+
+1. 实体明显大于过去 N 根平均实体
+2. 单向推进明显
+3. 同时产生 FVG / imbalance
+4. 快速脱离平衡区
+
+### 输出
+- DisplacementEvent
+
+---
+
+## R6. MSB 规则
+
+### 目标
+判断旧路径被破坏。
+
+### 输入
+- swings
+- displacement
+- current price
+
+### 判定
+1. 关键结构位被有效破坏
+2. 不只是 wick 穿越
+3. 最好伴随位移
+
+### 输出
+- StructureEvent(event_type = MSB)
+
+### 说明
+- MSB 只代表旧路径稳定性下降
+- 不自动等于反转机会
+
+---
+
+## R7. MSS 规则
+
+### 目标
+确认控制权切换。
+
+### 输入
+- MSB
+- displacement
+- retest / acceptance
+- updated draw
+
+### 判定
+必须满足：
+
+1. 已出现反向 MSB
+2. 出现有效 displacement
+3. 回补后未重新夺回原控制权
+4. 主 Draw 已重排
+
+### MVP 简化版
+- MSB = true
+- has_displacement = true
+- retest 后未破失效边界
+- 新目标已可定义
+
+### 输出
+- StructureEvent(event_type = MSS)
+
+---
+
+## R8. FVG 识别规则
+
+### 目标
+生成 retrace entry zone。
+
+### 输入
+- 三根连续 candles
+
+### 判定
+#### bullish FVG
+第一根高点 < 第三根低点
+
+#### bearish FVG
+第一根低点 > 第三根高点
+
+### 输出
+- FVGZone
+
+### 附加属性
+- fill_pct
+- first_touch_ts
+- is_mitigated
+
+---
+
+## R9. Bias 规则
+
+### 目标
+输出可执行偏向，而不是自由观点。
+
+### 输入
+- higher timeframe range
+- liquidity state
+- narrative inputs
+- current location
+- session
+
+### 输出字段
+- daily_bias: bullish / bearish / neutral
+- confidence
+- execution_intensity: low / medium / high
+- reason_codes[]
+
+### 降级条件
+满足任一则降级：
+
+1. 价格回到 equilibrium 附近
+2. 明显 consolidation hurdles
+3. 主 Draw 不清晰
+4. 当前 session 不支持当前路径
+
+---
+
+## R10. Session Filter 规则
+
+### 目标
+把会话作为硬过滤器。
+
+### 默认规则
+- ASIA：默认观察，不主动追单
+- LONDON：允许主触发
+- NY_AM：允许主触发 / 延续
+- NY_LUNCH：默认降频，只做管理或等待
+- NY_PM：允许延续或重构
+- OFF_HOURS：默认禁开新仓
+
+### 输出
+- session_code
+- execution_permission
+
+---
+
+## R11. Entry Zone 规则
+
+### 目标
+把结构链路转换为可执行信号。
+
+### 做空链路
+1. higher timeframe bias 偏空
+2. buy-side liquidity 被 sweep
+3. 出现 bearish displacement
+4. 形成 bearish MSS
+5. 出现 bearish FVG
+6. 回补进入 FVG
+7. stop 可定义
+8. RR 达标
+9. session 允许执行
+
+### 做多链路
+反向。
+
+### 输出
+- TradeSignal
+
+---
+
+## R12. Invalidation 规则
+
+### 目标
+定义否定叙事的硬边界。
+
+### 空单默认失效条件
+任一满足即失效：
+
+1. trigger_tf 收盘重新站上 sweep high
+2. 回补后出现反向强 displacement
+3. 上游 range 重绘并否定原 narrative
+4. 超过有效会话仍未触发
+
+### 多单
+反向。
+
+---
+
+## R13. TP 规则
+
+### 目标
+用 IRL / ERL 管理退出。
+
+### 定义
+- TP1 = IRL
+- TP2 = ERL
+
+### 默认执行逻辑
+- TP1 平部分仓位
+- TP2 留余仓争取延伸
+- 若到 TP1 后结构退化，可提前平余仓
+
+---
+
+## 6. MVP 主模型
+
+## 模型名
+`SWEEP_MSS_FVG`
+
+## 做空链路
+1. 高周期偏空
+2. 当前价格不在明显 discount 追空
+3. buy-side liquidity 被 sweep
+4. 出现 bearish displacement
+5. 形成 bearish MSS
+6. 出现 bearish FVG
+7. 回补进入 FVG
+8. stop 可定义
+9. TP1 / TP2 可定义
+10. RR >= 阈值
+
+## 做多链路
+完全反向。
+
+## 最低 RR
+- tp2_rr >= 2.0
+- 若 tp1_rr < 1.0，拒绝信号
+
+---
+
+## 7. Signal 状态机
+
+```text
+draft
+-> awaiting_context
+-> awaiting_confirmation
+-> active
+-> tp1_hit
+-> tp2_hit
+-> invalidated
+-> expired
+-> cancelled
+```
+
+---
+
+## 8. 回测标签定义
+
+## 8.1 结果标签
+
+- win
+- loss
+- breakeven
+- missed
+
+## 8.2 过程指标
+
+- mfe
+- mae
+- tp1_hit
+- tp2_hit
+- invalidated_before_entry
+- session_code
+- entry_triggered
+- same_candle_priority
+- same_candle_ambiguous
+
+## 8.3 错误归因标签
+
+- late_entry
+- poor_location
+- no_displacement
+- fake_mss
+- session_mismatch
+- range_redefined
+- rr_too_low
+- no_future_candles
+- entry_not_triggered
+- stopped_out
+- same_candle_entry_exit_ambiguous
+
+## 8.4 回测成交语义
+
+第一版回测只使用 OHLC K 线，无法知道同一根 K 线内部的真实触价顺序。因此必须采用保守、可追溯的假设：
+
+1. 若 entry、stop、TP 在同一根 K 线内同时可能发生，默认按 `stop_first` 处理
+2. 发生同根歧义时，结果仍按配置输出，但必须在 meta 中记录 `same_candle_ambiguous = true`
+3. `invalidated_before_entry` 只表示入场前信号已经失效，不表示入场后的普通止损
+4. 入场后的止损使用 `outcome = loss` 与 `stopped_out` 标签表达
+5. session 覆盖结果必须写入 meta，便于后续按 session 统计与排错
+
+## 8.5 统计维度
+
+至少按以下维度分析：
+
+- symbol
+- venue
+- session
+- weekday
+- setup_tf
+- trigger_tf
+- side
+- bias
+- range location
+
+---
+
+## 9. AI 报告接口边界
+
+AI 不直接判单，只解释规则结果。
+
+### 输入给 AI 的内容
+- higher timeframe context
+- session
+- sweep event
+- structure event
+- fvg zone
+- trade signal
+
+### 输出给用户的内容
+- 简要结构说明
+- 当前动作建议
+- 关键失效边界
+
+原则：
+
+- 规则层负责真值
+- AI 负责自然语言表达
+
+---
+
+## 10. 第一阶段开发顺序
+
+### 阶段 1：基础数据
+- candles
+- market_sessions
+
+### 阶段 2：结构基础
+- swings
+- dealing_ranges
+- liquidity_pools
+
+### 阶段 3：核心触发
+- sweep_events
+- displacement_events
+- structure_events
+- fvg_zones
+
+### 阶段 4：决策与信号
+- bias_snapshots
+- trade_signals
+
+### 阶段 5：验证与执行
+- backtest labels
+- trade_executions
+- reports
+
+---
+
+## 11. 当前结论
+
+MVP 的关键不是把 ICT 所有术语一次性实现完，而是稳定打通这一条最小闭环：
+
+`Candles -> Sessions -> Swings -> Range -> Liquidity -> Sweep -> MSS -> FVG -> Signal -> Execution -> Backtest`
+
+后续所有复杂模型都应建立在这条主链路稳定可验证的前提上。
diff --git a/docs/AI_ICT_Migration_拆分计划_v1.md b/docs/AI_ICT_Migration_拆分计划_v1.md
new file mode 100644
index 0000000..d6cbac6
--- /dev/null
+++ b/docs/AI_ICT_Migration_拆分计划_v1.md
@@ -0,0 +1,493 @@
+# AI ICT PostgreSQL Migration 拆分计划 v1
+
+## 1. 文档目标
+
+本文档把 `AI_ICT_PostgreSQL_Schema_v1.md` 中定义的数据库结构拆分成可实际执行的 migration 批次，明确建表顺序、依赖关系、验证点和回滚注意事项。
+
+目标：
+
+- 避免一次性建全部表导致排查困难
+- 确保基础共享表优先落地
+- 让后续开发可以按 migration 批次推进
+- 每一批 migration 都具备可验证完成标准
+
+---
+
+## 2. 拆分原则
+
+1. 按依赖顺序拆分，而不是按功能名堆叠
+2. 先基础字典表，再时间序列表，再结构事件表，再信号执行表
+3. 每批 migration 最好能独立验证
+4. 每批 migration 结束都要有回滚边界
+5. candles 分区单独处理，不混在其他逻辑里
+
+---
+
+## 3. 总体批次划分
+
+建议拆成 6 批 migration：
+
+1. 基础字典层
+2. 时间序列与会话层
+3. 基础结构层
+4. 核心事件层
+5. 决策与执行层
+6. 回测与分析层
+
+---
+
+## 4. Migration Batch 1：基础字典层
+
+## 4.1 包含表
+
+- `venues`
+- `instruments`
+
+## 4.2 依赖关系
+
+- 无上游依赖
+- 所有后续表都依赖 `instruments`
+
+## 4.3 建议拆分
+
+### migration_001_create_venues
+建立：
+- venues 主键
+- code 唯一键
+- timezone
+- status
+- created_at / updated_at
+
+### migration_002_create_instruments
+建立：
+- instruments 主键
+- venue_id 外键
+- symbol
+- asset_class
+- tick_size
+- lot_size
+- price_scale
+- qty_scale
+- meta jsonb
+- unique (venue_id, symbol)
+
+## 4.4 验证点
+
+- [ ] 可插入 OKX / LMAX
+- [ ] 可插入 BTC / ETH / XAU instrument
+- [ ] 重复 symbol + venue 被唯一键阻止
+
+## 4.5 回滚边界
+
+- 该批可整体回滚
+- 若已被下游表依赖，不应单独删除 `venues`
+
+---
+
+## 5. Migration Batch 2：时间序列与会话层
+
+## 5.1 包含表
+
+- `candles`
+- `market_sessions`
+
+## 5.2 依赖关系
+
+- 依赖 `instruments`
+
+## 5.3 建议拆分
+
+### migration_003_create_candles
+建立：
+- candles 主表
+- instrument_id 外键
+- timeframe
+- ts_open / ts_close
+- OHLCV
+- source
+- created_at
+- unique (instrument_id, timeframe, ts_open)
+
+### migration_004_create_candles_indexes
+建立：
+- candles 查询索引
+- instrument + timeframe + ts_open desc
+- instrument + timeframe + ts_close desc
+
+### migration_005_create_market_sessions
+建立：
+- market_sessions
+- session_date
+- session_code
+- timezone
+- start_ts / end_ts
+- high / low / midpoint
+- status
+- meta jsonb
+- unique (instrument_id, session_date, session_code, timezone)
+
+## 5.4 candles 分区说明
+
+建议：
+- candles 主表创建后立即加入月分区策略
+- 第一版先建立当前月和下个月分区
+
+示例命名：
+- candles_2026_04
+- candles_2026_05
+
+## 5.5 验证点
+
+- [ ] candles 可插入样本数据
+- [ ] 相同 `instrument_id + timeframe + ts_open` 无法重复插入
+- [ ] market_sessions 可插入单日会话样本
+- [ ] session 唯一键有效
+
+## 5.6 回滚边界
+
+- 可先删除 `market_sessions`
+- candles 若已有大量数据，不应轻易整体回滚
+
+---
+
+## 6. Migration Batch 3：基础结构层
+
+## 6.1 包含表
+
+- `swings`
+- `dealing_ranges`
+- `liquidity_pools`
+
+## 6.2 依赖关系
+
+- 依赖 `instruments`
+- `dealing_ranges` 依赖 `swings`
+
+## 6.3 建议拆分
+
+### migration_006_create_swings
+建立：
+- swings
+- kind
+- strength
+- price
+- ts
+- left_bars / right_bars
+- confirmed
+- meta jsonb
+
+### migration_007_create_dealing_ranges
+建立：
+- dealing_ranges
+- high / low / equilibrium
+- high_swing_id / low_swing_id
+- state
+- ts_start / ts_end
+- meta jsonb
+
+### migration_008_create_liquidity_pools
+建立：
+- liquidity_pools
+- side
+- pool_type
+- price_low / price_high
+- reference_ids jsonb
+- status
+- created_ts / updated_ts
+- meta jsonb
+
+## 6.4 验证点
+
+- [ ] swings 可写入样本数据
+- [ ] dealing_ranges 可引用 swings
+- [ ] liquidity_pools 可写入 prior/session pool 样本
+- [ ] 索引查询有效
+
+## 6.5 回滚边界
+
+- 若 `dealing_ranges` 已引用 `swings`，回滚顺序必须反向
+- 推荐回滚顺序：
+  1. liquidity_pools
+  2. dealing_ranges
+  3. swings
+
+---
+
+## 7. Migration Batch 4：核心事件层
+
+## 7.1 包含表
+
+- `displacement_events`
+- `structure_events`
+- `fvg_zones`
+
+## 7.2 依赖关系
+
+- 依赖 `instruments`
+- `structure_events` 可依赖 `swings` 与 `displacement_events`
+- `fvg_zones` 可依赖 `displacement_events`
+
+## 7.3 建议拆分
+
+### migration_009_create_displacement_events
+建立：
+- direction
+- start_ts / end_ts
+- strength_score
+- body_ratio
+- has_fvg
+- is_valid
+- meta jsonb
+
+### migration_010_create_structure_events
+建立：
+- event_type
+- direction
+- broken_level
+- reference_swing_id
+- displacement_event_id
+- accepted
+- signal_relevant
+- ts
+- meta jsonb
+
+### migration_011_create_fvg_zones
+建立：
+- direction
+- upper / lower
+- start_ts / end_ts
+- fill_pct
+- status
+- related_displacement_id
+- meta jsonb
+
+## 7.4 验证点
+
+- [ ] displacement_events 可写入正例样本
+- [ ] structure_events 可关联 swings / displacement
+- [ ] fvg_zones 可关联 displacement
+- [ ] 事件查询按 timeframe 和时间排序正常
+
+## 7.5 回滚边界
+
+- 推荐反向删除：
+  1. fvg_zones
+  2. structure_events
+  3. displacement_events
+
+---
+
+## 8. Migration Batch 5：决策与执行层
+
+## 8.1 包含表
+
+- `bias_snapshots`
+- `trade_signals`
+- `trade_executions`
+
+## 8.2 依赖关系
+
+- `bias_snapshots` 依赖 `dealing_ranges`
+- `trade_signals` 依赖 `bias_snapshots`
+- `trade_executions` 依赖 `trade_signals`
+
+## 8.3 建议拆分
+
+### migration_012_create_bias_snapshots
+建立：
+- bias_tf / setup_tf / trigger_tf
+- snapshot_ts
+- daily_bias
+- confidence
+- execution_intensity
+- narrative_code
+- draw_side
+- range_id
+- reason_codes jsonb
+- meta jsonb
+
+### migration_013_create_trade_signals
+建立：
+- model_code
+- side
+- status
+- bias_snapshot_id
+- entry_low / entry_high
+- stop_loss
+- tp1 / tp2
+- rr_tp1 / rr_tp2
+- session_code
+- created_ts / expires_ts
+- invalidations jsonb
+- evidence jsonb
+- meta jsonb
+
+### migration_014_create_trade_executions
+建立：
+- signal_id
+- venue_order_id
+- execution_mode
+- side
+- entry_price
+- stop_loss
+- take_profit_1 / take_profit_2
+- size
+- risk_pct
+- status
+- opened_ts / closed_ts
+- pnl
+- meta jsonb
+
+## 8.4 验证点
+
+- [ ] bias snapshot 可插入样本
+- [ ] trade_signals 可引用 bias snapshot
+- [ ] trade_executions 可引用 trade_signals
+- [ ] 信号和执行链路主外键正常
+
+## 8.5 回滚边界
+
+- 推荐反向回滚：
+  1. trade_executions
+  2. trade_signals
+  3. bias_snapshots
+
+---
+
+## 9. Migration Batch 6：回测与分析层
+
+## 9.1 包含表
+
+- `backtest_runs`
+- `backtest_results`
+
+## 9.2 依赖关系
+
+- `backtest_results` 依赖 `backtest_runs`
+- 可选关联 `trade_signals`
+
+## 9.3 建议拆分
+
+### migration_015_create_backtest_runs
+建立：
+- model_code
+- instrument_id
+- timeframe_set jsonb
+- started_ts / ended_ts
+- config jsonb
+- summary jsonb
+
+### migration_016_create_backtest_results
+建立：
+- backtest_run_id
+- signal_id
+- outcome
+- mfe / mae
+- tp1_hit / tp2_hit
+- invalidated_before_entry
+- error_tags jsonb
+- meta jsonb
+
+## 9.4 验证点
+
+- [ ] 可创建一次 backtest run
+- [ ] 可写入多条 result
+- [ ] 可按 backtest_run_id 查询完整结果
+
+## 9.5 回滚边界
+
+- 推荐反向回滚：
+  1. backtest_results
+  2. backtest_runs
+
+---
+
+## 10. 索引拆分建议
+
+为了避免 migration 过重，建议表创建和重索引拆开。
+
+### 10.1 表创建时保留
+- 主键
+- 唯一键
+- 必要外键
+
+### 10.2 批量追加索引时处理
+- 高频查询索引
+- 多列排序索引
+- 状态查询索引
+
+### 10.3 特别建议
+对 `candles` 的索引和分区单独处理，不要与业务事件表混在同一 migration 中。
+
+---
+
+## 11. 数据初始化建议
+
+基础 migration 完成后，立即执行一批 seed：
+
+### seed_001_venues
+- OKX
+- LMAX
+
+### seed_002_instruments
+- OKX BTC
+- OKX ETH
+- LMAX XAU
+
+说明：
+- XAU 若真实合约代码尚未最终确定，可先留占位 instrument，但要明确标记 `active=false` 或在 meta 标出待确认状态。
+
+---
+
+## 12. 推荐执行顺序
+
+实际落地时建议严格按以下顺序：
+
+1. migration_001_create_venues
+2. migration_002_create_instruments
+3. migration_003_create_candles
+4. migration_004_create_candles_indexes
+5. migration_005_create_market_sessions
+6. migration_006_create_swings
+7. migration_007_create_dealing_ranges
+8. migration_008_create_liquidity_pools
+9. migration_009_create_displacement_events
+10. migration_010_create_structure_events
+11. migration_011_create_fvg_zones
+12. migration_012_create_bias_snapshots
+13. migration_013_create_trade_signals
+14. migration_014_create_trade_executions
+15. migration_015_create_backtest_runs
+16. migration_016_create_backtest_results
+
+---
+
+## 13. 第一轮最小落地目标
+
+如果要最快进入真实开发，第一轮只需先完成以下 migration：
+
+- 001 venues
+- 002 instruments
+- 003 candles
+- 004 candles indexes
+- 005 market_sessions
+- 006 swings
+- 007 dealing_ranges
+
+这 7 个 migration 完成后，就能开始搭建：
+
+`Candles -> Sessions -> Swings -> Ranges`
+
+这也是全系统第一条必须打通的基础链路。
+
+---
+
+## 14. 当前结论
+
+Migration 拆分的关键不是数量，而是让每一批都具备：
+
+- 明确依赖
+- 明确验证点
+- 明确回滚顺序
+
+后续真实开发时，应以本文件作为 migration 执行顺序的标准参考，不建议跳批次直接建后面的表。
\ No newline at end of file
diff --git a/docs/AI_ICT_OKX_数据接入规格书_v1.md b/docs/AI_ICT_OKX_数据接入规格书_v1.md
new file mode 100644
index 0000000..4a4dd43
--- /dev/null
+++ b/docs/AI_ICT_OKX_数据接入规格书_v1.md
@@ -0,0 +1,433 @@
+# AI ICT OKX 数据接入规格书 v1
+
+## 1. 文档目标
+
+本文档定义 AI ICT 项目第一阶段的 OKX 数据接入方案，用于指导市场数据层的真实实现。
+
+本规格书聚焦：
+
+1. BTC / ETH 行情接入
+2. K 线标准化
+3. 历史补数与增量同步
+4. PostgreSQL 入库
+5. 可验证的数据质量控制
+
+第一阶段只把 OKX 作为主数据源，用于先打通：
+
+`OKX -> Candles -> Sessions -> Swings -> Ranges`
+
+---
+
+## 2. 接入目标
+
+第一阶段只处理最小必需数据。
+
+### 2.1 支持品种
+
+- BTC-USDT-SWAP 或你最终选定的 BTC 交易标的
+- ETH-USDT-SWAP 或你最终选定的 ETH 交易标的
+
+说明：
+
+- 最终采用现货、永续、期货中的哪一种，需要在启动开发前固定
+- 如果目标是日内交易模型，优先建议统一用流动性更稳定的一类合约，不要混用多个产品类型
+
+### 2.2 支持周期
+
+第一阶段建议：
+
+- 1m
+- 5m
+- 15m
+- 1H
+- 4H
+
+### 2.3 第一阶段不接入
+
+- 深度订单簿
+- 逐笔成交
+- 账户资产信息
+- 下单接口
+- WebSocket 实时执行流
+
+这些可留到后续阶段。
+
+---
+
+## 3. 数据对象定义
+
+## 3.1 原始对象
+
+OKX 返回的原始 K 线数据需要先保存在抓取层对象中。
+
+建议原始对象字段：
+
+- instId
+- bar
+- ts
+- o
+- h
+- l
+- c
+- vol
+- volCcy
+- volCcyQuote
+- confirm
+
+说明：
+
+- 原始对象仅用于抓取与排障
+- 不建议原样直接写入业务主表
+
+---
+
+## 3.2 标准化 Candle 对象
+
+写入业务层前统一转换为：
+
+- symbol
+- venue
+- timeframe
+- ts_open
+- ts_close
+- open
+- high
+- low
+- close
+- volume
+- source
+
+对应数据库表：`candles`
+
+---
+
+## 4. 品种映射规则
+
+## 4.1 instrument mapping 原则
+
+必须建立 OKX 原始标的与系统内部 instrument 的映射表，不允许在业务代码中硬编码散落的 instId。
+
+建议至少维护：
+
+- venue_code = OKX
+- raw_inst_id
+- internal_symbol
+- asset_class
+- product_type
+- active
+
+---
+
+## 4.2 建议做法
+
+统一在配置层维护，例如：
+
+```yaml
+okx:
+  instruments:
+    - raw_inst_id: BTC-USDT-SWAP
+      symbol: BTC-USDT
+      product_type: swap
+      active: true
+    - raw_inst_id: ETH-USDT-SWAP
+      symbol: ETH-USDT
+      product_type: swap
+      active: true
+```
+
+说明：
+
+- 若后续切成现货或期货，只改映射配置，不改抓取主流程
+- 内部 symbol 命名要固定，避免后续信号和回测口径混乱
+
+---
+
+## 5. 时间框架映射规则
+
+OKX 周期值需要统一映射为系统内部 timeframe。
+
+建议映射：
+
+- OKX 1m -> 1m
+- OKX 5m -> 5m
+- OKX 15m -> 15m
+- OKX 1H -> 1h
+- OKX 4H -> 4h
+
+要求：
+
+- 系统内部统一使用小写：`1m`, `5m`, `15m`, `1h`, `4h`
+- 所有数据库写入和规则引擎都只识别内部格式
+
+---
+
+## 6. 抓取模式设计
+
+第一阶段建议同时支持两种模式：
+
+1. 历史补数
+2. 增量同步
+
+---
+
+## 6.1 历史补数模式
+
+### 目标
+把某个品种某个 timeframe 的历史 K 线补齐到本地数据库。
+
+### 输入
+- symbol
+- timeframe
+- from_ts
+- to_ts
+
+### 输出
+- 分页抓取后的 candles
+- 去重写入数据库
+
+### 要求
+- 允许断点续传
+- 允许分段回补
+- 每批抓取后立即落库
+- 不应先全放内存再统一写入
+
+---
+
+## 6.2 增量同步模式
+
+### 目标
+持续更新最新 K 线。
+
+### 方式
+第一阶段先用轮询，不强依赖 WebSocket。
+
+### 输入
+- symbol
+- timeframe
+- last_ts_open
+
+### 输出
+- 自上次已入库时间后的新增 candles
+
+### 要求
+- 支持幂等执行
+- 支持重复轮询不重复写入
+- 遇到单次接口失败可重试
+- 重试失败要记录日志，不静默吞掉
+
+---
+
+## 7. 数据标准化规则
+
+## 7.1 数值字段
+
+抓取层统一转换：
+
+- open -> numeric
+- high -> numeric
+- low -> numeric
+- close -> numeric
+- volume -> numeric
+
+要求：
+
+- 不在业务层保留字符串数字
+- 所有价格字段统一用高精度 decimal / numeric
+
+---
+
+## 7.2 时间字段
+
+### 原则
+所有数据库字段统一转成 `timestamptz` 语义处理。
+
+### 要求
+- `ts_open` 必须是 candle 起始时间
+- `ts_close` 必须能由 timeframe 推导或明确计算
+- 所有入库时间统一使用 UTC 存储
+- session 层再按 `America/New_York` 做切分
+
+---
+
+## 7.3 confirm 字段处理
+
+若 OKX 原始数据带 `confirm`：
+
+- confirm = 1：已完成 candle，可直接进入稳定数据链路
+- confirm = 0：未完成 candle，仅用于实时观察，不作为正式规则输入
+
+第一阶段建议：
+
+- 历史补数只写 confirmed candles
+- 增量同步默认只将 confirmed candle 写入规则主表
+- 若需要观察未闭合 K，可另建缓存逻辑，不写正式主表
+
+---
+
+## 8. 数据入库规则
+
+## 8.1 写入目标表
+
+- `candles`
+
+### 唯一键
+
+`(instrument_id, timeframe, ts_open)`
+
+### 写入策略
+
+- 存在则跳过或更新（按最终策略固定）
+- 第一阶段建议使用幂等 upsert
+
+---
+
+## 8.2 幂等策略
+
+要求：
+
+- 同一批历史补数重复执行，不得产生重复数据
+- 同一轮增量同步重复执行，不得产生重复数据
+- 数据库唯一键必须作为最后防线
+
+建议：
+
+- 应用层先去重
+- 数据库层再唯一键兜底
+
+---
+
+## 9. 错误处理规范
+
+## 9.1 可重试错误
+
+- 网络超时
+- 临时 5xx
+- 限频返回
+- 短暂连接失败
+
+处理要求：
+
+- 有限次重试
+- 指数退避或固定退避
+- 每次重试记录日志
+
+## 9.2 不可重试错误
+
+- 无效 instId
+- 无效 timeframe
+- 配置缺失
+- 映射错误
+
+处理要求：
+
+- 立即失败
+- 输出清晰错误信息
+- 标记为配置问题，而不是抓取异常
+
+---
+
+## 9.3 限频处理
+
+必须考虑 OKX 接口限频。
+
+要求：
+
+- 同一时间不要无节制并发多个 timeframe + symbol 请求
+- 增加抓取节流
+- 错误日志中要能区分：
+  - 网络失败
+  - 限频失败
+  - 配置失败
+
+---
+
+## 10. 推荐任务拆分
+
+实现时建议拆成以下小任务：
+
+### T1. OKX 配置模块
+- 定义 base URL
+- 定义 instrument mapping
+- 定义 timeframe mapping
+
+### T2. 原始 API client
+- 单次请求能力
+- 参数校验
+- 错误处理
+
+### T3. 历史补数任务
+- 分页抓取
+- 批量标准化
+- 入库
+
+### T4. 增量同步任务
+- 读取 last_ts_open
+- 拉新增数据
+- 幂等入库
+
+### T5. 数据验证任务
+- 查询 DB 样本
+- 检查连续性
+- 检查重复
+
+---
+
+## 11. 验证检查点
+
+## 11.1 最低验证要求
+
+实现后至少验证以下内容：
+
+- [ ] BTC 1m 数据可入库
+- [ ] BTC 5m 数据可入库
+- [ ] ETH 1m 数据可入库
+- [ ] ETH 5m 数据可入库
+- [ ] 指定时间范围查询结果连续
+- [ ] 无重复 candle
+- [ ] timeframe 映射正确
+
+---
+
+## 11.2 样本验证
+
+至少对一段时间窗口做以下核查：
+
+- [ ] `open <= high`
+- [ ] `low <= close <= high`
+- [ ] `low <= open <= high`
+- [ ] ts_open 连续性正确
+- [ ] 同一 instrument/timeframe 无重复 ts_open
+
+---
+
+## 11.3 session 前置验证
+
+在进入 session generator 前，必须保证：
+
+- [ ] 目标交易日 candles 已完整
+- [ ] 时区转换无误
+- [ ] 缺口已识别
+
+否则 session high / low 可能失真。
+
+---
+
+## 12. 第一阶段交付标准
+
+只有满足以下全部条件，OKX 数据接入模块才算完成：
+
+1. BTC / ETH 至少两个 timeframe 可稳定入库
+2. 历史补数可重复执行且不重复写入
+3. 增量同步可重复执行且不重复写入
+4. candles 查询样本通过完整性检查
+5. 下游 session 生成器可直接消费数据
+
+---
+
+## 13. 当前结论
+
+第一阶段的 OKX 数据接入不是“能拉到数据就算完成”，而是必须满足：
+
+> 可映射、可标准化、可幂等入库、可重复验证、可直接供下游规则使用
+
+后续真实实现时，应优先按本规格书完成 BTC / ETH candles 数据链路，再进入 session、swing 和 range 模块。
\ No newline at end of file
diff --git a/docs/AI_ICT_PostgreSQL_Migration_SQL_Drafts_v1.md b/docs/AI_ICT_PostgreSQL_Migration_SQL_Drafts_v1.md
new file mode 100644
index 0000000..c1dfa6d
--- /dev/null
+++ b/docs/AI_ICT_PostgreSQL_Migration_SQL_Drafts_v1.md
@@ -0,0 +1,549 @@
+# AI ICT PostgreSQL Migration SQL Drafts v1
+
+## 1. 文档目标
+
+本文档提供 AI ICT 项目第一波 PostgreSQL migration 的 SQL 草案，用于直接指导：
+
+- 基础表初版建表
+- 主键 / 外键 / 唯一约束落地
+- 核心查询索引落地
+- `candles` 月分区初始化
+- 后续正式 migration 文件编写
+
+本文档聚焦第一实现波次，不覆盖全部事件表，只覆盖：
+
+1. `venues`
+2. `instruments`
+3. `candles`
+4. `market_sessions`
+5. `swings`
+
+关联文档：
+
+1. `AI_ICT_PostgreSQL_Schema_v1.md`
+2. `AI_ICT_PostgreSQL_Migration_Split_Plan_v1.md`
+3. `AI_ICT_开发路线图_v1.md`
+4. `AI_ICT_执行检查清单_v1.md`
+
+---
+
+## 2. 设计边界与约定
+
+第一波 migration 草案遵循以下原则：
+
+1. 优先让基础数据层可落地
+2. 使用 `text + check constraint`，不先引入数据库 enum
+3. 高增长表优先做好唯一键与索引
+4. 只有 `candles` 先做分区，其他表先普通表
+5. SQL 草案以 PostgreSQL 15+ 常见写法为基准
+
+统一约定：
+
+- 主键使用 `bigserial`
+- 时间字段统一使用 `timestamptz`
+- 默认 schema 先按 `public` 处理
+- 金额/价格统一使用 `numeric(20,10)` 或更高精度
+- JSON 扩展字段使用 `jsonb not null default '{}'::jsonb`
+
+---
+
+## 3. 建议 migration 文件顺序
+
+```text
+001_base_conventions.sql
+002_create_venues.sql
+003_create_instruments.sql
+004_create_candles.sql
+005_create_candles_partitions.sql
+006_create_market_sessions.sql
+007_create_swings.sql
+```
+
+说明：
+
+- `candles` 主表和分区单独拆文件，便于验证与回滚
+- 若团队偏向更细粒度，也可把索引拆到各自 `*_indexes.sql`
+- 第一波先不把 seed 数据硬编码进 DDL migration，可单独写 `seed_base_data.sql`
+
+---
+
+## 4. 基础公共 SQL 草案
+
+## 4.1 `001_base_conventions.sql`
+
+建议先放公共 trigger function：
+
+```sql
+create or replace function set_updated_at()
+returns trigger
+language plpgsql
+as $$
+begin
+  new.updated_at = now();
+  return new;
+end;
+$$;
+```
+
+用途：
+
+- 给存在 `updated_at` 的基础表复用
+- 减少每张表单独手写更新时间逻辑的重复
+
+说明：
+
+- `candles` 第一版没有 `updated_at`，通常不需要该 trigger
+- 若团队想保持 migration 最小化，也可先不加 trigger，改由应用层更新
+
+---
+
+## 5. `venues` SQL 草案
+
+## 5.1 建表 SQL
+
+```sql
+create table if not exists venues (
+  id bigserial primary key,
+  code text not null,
+  name text not null,
+  timezone text not null,
+  status text not null default 'active',
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  constraint venues_code_key unique (code),
+  constraint venues_status_check check (status in ('active', 'inactive'))
+);
+```
+
+## 5.2 索引与 trigger
+
+```sql
+create index if not exists idx_venues_status
+  on venues (status);
+
+create trigger trg_venues_set_updated_at
+before update on venues
+for each row
+execute function set_updated_at();
+```
+
+## 5.3 说明
+
+- `code` 用于业务稳定引用，如 `OKX`
+- `timezone` 保留交易所默认时区配置
+- `status` 先保留最小集合：`active | inactive`
+
+---
+
+## 6. `instruments` SQL 草案
+
+## 6.1 建表 SQL
+
+```sql
+create table if not exists instruments (
+  id bigserial primary key,
+  venue_id bigint not null references venues(id),
+  symbol text not null,
+  asset_class text not null,
+  base_asset text,
+  quote_asset text,
+  price_scale integer not null,
+  qty_scale integer not null,
+  tick_size numeric(20,10) not null,
+  lot_size numeric(20,10),
+  active boolean not null default true,
+  meta jsonb not null default '{}'::jsonb,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  constraint instruments_venue_symbol_key unique (venue_id, symbol),
+  constraint instruments_price_scale_check check (price_scale >= 0),
+  constraint instruments_qty_scale_check check (qty_scale >= 0),
+  constraint instruments_tick_size_check check (tick_size > 0),
+  constraint instruments_lot_size_check check (lot_size is null or lot_size > 0)
+);
+```
+
+## 6.2 索引与 trigger
+
+```sql
+create index if not exists idx_instruments_venue_id
+  on instruments (venue_id);
+
+create index if not exists idx_instruments_active
+  on instruments (active);
+
+create index if not exists idx_instruments_asset_class
+  on instruments (asset_class);
+
+create trigger trg_instruments_set_updated_at
+before update on instruments
+for each row
+execute function set_updated_at();
+```
+
+## 6.3 说明
+
+- 用 `unique (venue_id, symbol)` 保证交易所内品种唯一
+- `meta` 用于附加合约规则、别名、外部映射等
+- `asset_class` 暂时不强加 check，给现货、永续、CFD、贵金属留空间
+
+---
+
+## 7. `candles` SQL 草案
+
+## 7.1 主表建表 SQL
+
+第一版建议使用按 `ts_open` 的 range partition：
+
+```sql
+create table if not exists candles (
+  id bigserial,
+  instrument_id bigint not null references instruments(id),
+  timeframe text not null,
+  ts_open timestamptz not null,
+  ts_close timestamptz not null,
+  open numeric(20,10) not null,
+  high numeric(20,10) not null,
+  low numeric(20,10) not null,
+  close numeric(20,10) not null,
+  volume numeric(28,10),
+  source text not null default 'api',
+  created_at timestamptz not null default now(),
+  constraint candles_pk primary key (id, ts_open),
+  constraint candles_timeframe_check check (timeframe in ('1m', '5m', '15m', '1h', '4h', '1d')),
+  constraint candles_price_order_check check (high >= low),
+  constraint candles_open_range_check check (open <= high and open >= low),
+  constraint candles_close_range_check check (close <= high and close >= low),
+  constraint candles_time_order_check check (ts_close > ts_open),
+  constraint candles_unique_bar unique (instrument_id, timeframe, ts_open)
+) partition by range (ts_open);
+```
+
+## 7.2 为什么主键这样定义
+
+由于 PostgreSQL 分区表上的唯一约束/主键需要包含分区键，第一版草案建议：
+
+- 主键使用 `(id, ts_open)`
+- 真正业务幂等约束使用 `unique (instrument_id, timeframe, ts_open)`
+
+这样可以同时满足：
+
+- 保留自增主键
+- 兼容分区表限制
+- 保证单根 K 线不会重复写入
+
+## 7.3 主表索引 SQL
+
+```sql
+create index if not exists idx_candles_instrument_tf_ts_open_desc
+  on candles (instrument_id, timeframe, ts_open desc);
+
+create index if not exists idx_candles_instrument_tf_ts_close_desc
+  on candles (instrument_id, timeframe, ts_close desc);
+
+create index if not exists idx_candles_instrument_tf_source_ts_open_desc
+  on candles (instrument_id, timeframe, source, ts_open desc);
+```
+
+## 7.4 分区初始化 SQL 草案
+
+例如先建立 2026-04 与 2026-05 两个分区：
+
+```sql
+create table if not exists candles_2026_04
+partition of candles
+for values from ('2026-04-01 00:00:00+00') to ('2026-05-01 00:00:00+00');
+
+create table if not exists candles_2026_05
+partition of candles
+for values from ('2026-05-01 00:00:00+00') to ('2026-06-01 00:00:00+00');
+```
+
+## 7.5 分区级索引补充
+
+若实际运行中发现分区继承索引不足以覆盖主要查询，可显式补：
+
+```sql
+create index if not exists idx_candles_2026_04_instrument_tf_ts_open_desc
+  on candles_2026_04 (instrument_id, timeframe, ts_open desc);
+
+create index if not exists idx_candles_2026_05_instrument_tf_ts_open_desc
+  on candles_2026_05 (instrument_id, timeframe, ts_open desc);
+```
+
+## 7.6 后续自动建分区建议
+
+后续可以增加一个月度分区初始化脚本，例如：
+
+- 每月月底预建下两个月分区
+- 避免行情入库时因缺少分区而失败
+
+但这不属于第一波 migration DDL 主体，可放到运维脚本或 cron 任务中。
+
+---
+
+## 8. `market_sessions` SQL 草案
+
+## 8.1 建表 SQL
+
+```sql
+create table if not exists market_sessions (
+  id bigserial primary key,
+  instrument_id bigint not null references instruments(id),
+  session_date date not null,
+  timezone text not null,
+  session_code text not null,
+  start_ts timestamptz not null,
+  end_ts timestamptz not null,
+  high numeric(20,10),
+  low numeric(20,10),
+  midpoint numeric(20,10),
+  status text not null default 'closed',
+  meta jsonb not null default '{}'::jsonb,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  constraint market_sessions_unique_key unique (instrument_id, session_date, session_code, timezone),
+  constraint market_sessions_status_check check (status in ('open', 'closed', 'incomplete', 'invalid')),
+  constraint market_sessions_code_check check (session_code in ('ASIA', 'LONDON', 'NY_AM', 'NY_LUNCH', 'NY_PM')),
+  constraint market_sessions_time_order_check check (end_ts > start_ts),
+  constraint market_sessions_price_order_check check (
+    high is null or low is null or high >= low
+  )
+);
+```
+
+## 8.2 索引与 trigger
+
+```sql
+create index if not exists idx_market_sessions_instrument_date
+  on market_sessions (instrument_id, session_date desc);
+
+create index if not exists idx_market_sessions_instrument_code_date
+  on market_sessions (instrument_id, session_code, session_date desc);
+
+create index if not exists idx_market_sessions_status
+  on market_sessions (status);
+
+create trigger trg_market_sessions_set_updated_at
+before update on market_sessions
+for each row
+execute function set_updated_at();
+```
+
+## 8.3 说明
+
+- `session_date` 是业务会话所属日，不等同于 `start_ts::date`
+- `midpoint` 可存 session 中点，减少重复计算
+- `status` 预留不完整或异常会话标记
+
+---
+
+## 9. `swings` SQL 草案
+
+## 9.1 建表 SQL
+
+```sql
+create table if not exists swings (
+  id bigserial primary key,
+  instrument_id bigint not null references instruments(id),
+  timeframe text not null,
+  kind text not null,
+  strength text not null,
+  price numeric(20,10) not null,
+  ts timestamptz not null,
+  left_bars integer not null,
+  right_bars integer not null,
+  confirmed boolean not null default true,
+  meta jsonb not null default '{}'::jsonb,
+  created_at timestamptz not null default now(),
+  constraint swings_kind_check check (kind in ('swing_high', 'swing_low')),
+  constraint swings_strength_check check (strength in ('ST', 'IT', 'LT')),
+  constraint swings_left_bars_check check (left_bars > 0),
+  constraint swings_right_bars_check check (right_bars > 0)
+);
+```
+
+## 9.2 索引 SQL
+
+```sql
+create index if not exists idx_swings_instrument_tf_ts_desc
+  on swings (instrument_id, timeframe, ts desc);
+
+create index if not exists idx_swings_instrument_tf_kind_ts_desc
+  on swings (instrument_id, timeframe, kind, ts desc);
+
+create index if not exists idx_swings_instrument_tf_strength_ts_desc
+  on swings (instrument_id, timeframe, strength, ts desc);
+
+create index if not exists idx_swings_confirmed_ts_desc
+  on swings (instrument_id, timeframe, confirmed, ts desc);
+```
+
+## 9.3 可选幂等约束建议
+
+若后续想减少同一 swing 被重复写入，可考虑增加唯一约束：
+
+```sql
+unique (instrument_id, timeframe, kind, strength, ts, price)
+```
+
+但第一版建议先不急着加，原因：
+
+- 不同算法版本可能在同一时间点重建结构
+- 后续也可能需要靠 `meta.recalc_batch_id` 区分重算来源
+- 先观察真实数据再决定是否收紧
+
+---
+
+## 10. 推荐 seed SQL 草案
+
+## 10.1 `venues` seed
+
+```sql
+insert into venues (code, name, timezone)
+values
+  ('OKX', 'OKX', 'UTC'),
+  ('LMAX', 'LMAX', 'Europe/London')
+on conflict (code) do nothing;
+```
+
+## 10.2 `instruments` seed
+
+```sql
+insert into instruments (
+  venue_id,
+  symbol,
+  asset_class,
+  base_asset,
+  quote_asset,
+  price_scale,
+  qty_scale,
+  tick_size,
+  lot_size
+)
+select v.id, x.symbol, x.asset_class, x.base_asset, x.quote_asset, x.price_scale, x.qty_scale, x.tick_size, x.lot_size
+from venues v
+join (
+  values
+    ('OKX', 'BTC-USDT-SWAP', 'perpetual', 'BTC', 'USDT', 1, 3, 0.1::numeric, 0.001::numeric),
+    ('OKX', 'ETH-USDT-SWAP', 'perpetual', 'ETH', 'USDT', 2, 3, 0.01::numeric, 0.001::numeric),
+    ('LMAX', 'XAUUSD', 'spot', 'XAU', 'USD', 2, 2, 0.01::numeric, 0.01::numeric)
+) as x(venue_code, symbol, asset_class, base_asset, quote_asset, price_scale, qty_scale, tick_size, lot_size)
+  on v.code = x.venue_code
+on conflict (venue_id, symbol) do nothing;
+```
+
+---
+
+## 11. 第一波最小验证 SQL 草案
+
+## 11.1 唯一约束验证
+
+```sql
+-- candles 重复写入应失败
+insert into candles (
+  instrument_id, timeframe, ts_open, ts_close, open, high, low, close, volume
+) values (
+  1, '1m', '2026-04-01 00:00:00+00', '2026-04-01 00:01:00+00',
+  100, 101, 99, 100.5, 10
+);
+
+insert into candles (
+  instrument_id, timeframe, ts_open, ts_close, open, high, low, close, volume
+) values (
+  1, '1m', '2026-04-01 00:00:00+00', '2026-04-01 00:01:00+00',
+  100, 101, 99, 100.5, 10
+);
+```
+
+第二条应因 `candles_unique_bar` 失败。
+
+## 11.2 约束验证
+
+```sql
+-- 非法 timeframe 应失败
+insert into candles (
+  instrument_id, timeframe, ts_open, ts_close, open, high, low, close
+) values (
+  1, '2m', '2026-04-01 00:00:00+00', '2026-04-01 00:02:00+00',
+  100, 101, 99, 100
+);
+```
+
+```sql
+-- 非法 swing kind 应失败
+insert into swings (
+  instrument_id, timeframe, kind, strength, price, ts, left_bars, right_bars
+) values (
+  1, '1m', 'high', 'ST', 100, '2026-04-01 00:10:00+00', 2, 2
+);
+```
+
+## 11.3 分区验证
+
+```sql
+select tableoid::regclass, instrument_id, timeframe, ts_open
+from candles
+where ts_open = '2026-04-01 00:00:00+00';
+```
+
+应看到记录落到 `candles_2026_04`。
+
+---
+
+## 12. 回滚草案建议
+
+第一波回滚顺序建议：
+
+```text
+swings
+-> market_sessions
+-> candles partitions
+-> candles
+-> instruments
+-> venues
+-> set_updated_at function
+```
+
+回滚示例：
+
+```sql
+drop table if exists swings;
+drop table if exists market_sessions;
+drop table if exists candles_2026_05;
+drop table if exists candles_2026_04;
+drop table if exists candles;
+drop table if exists instruments;
+drop table if exists venues;
+drop function if exists set_updated_at();
+```
+
+说明：
+
+- 实际生产环境不应直接照抄物理删除
+- 先停写入任务，再确认无下游依赖，再执行回滚
+- 若已有真实数据，应先备份再处理
+
+---
+
+## 13. 第一波完成标准
+
+满足以下条件后，可认为 migration SQL draft 文档完成：
+
+- 已给出基础表的建表 SQL 草案
+- 已给出唯一约束和 check constraint 草案
+- 已给出核心索引草案
+- 已给出 `candles` 分区建表与初始化草案
+- 已给出最小 seed 与验证 SQL 草案
+- 已能直接作为正式 migration 编写参考
+
+---
+
+## 14. 推荐的下一步
+
+完成本文件后，建议立即继续：
+
+1. 把上述 SQL 草案拆成正式 migration 文件
+2. 单独补一份 `verify_base_tables.sql`
+3. 单独补一份 `rollback_base_tables.sql`
+4. 再进入 `dealing_ranges` / `liquidity_pools` 的第二波 migration 草案
diff --git a/docs/AI_ICT_PostgreSQL_Migration_Split_Plan_v1.md b/docs/AI_ICT_PostgreSQL_Migration_Split_Plan_v1.md
new file mode 100644
index 0000000..6ccf7f1
--- /dev/null
+++ b/docs/AI_ICT_PostgreSQL_Migration_Split_Plan_v1.md
@@ -0,0 +1,711 @@
+# AI ICT PostgreSQL Migration 拆分执行方案 v1
+
+## 1. 文档目标
+
+本文档把 `AI_ICT_PostgreSQL_Schema_v1.md` 中定义的数据库设计拆分为可执行的 migration 批次，确保：
+
+- 按依赖顺序落地
+- 每一批都可单独验证
+- 出问题时可以局部回滚
+- 不让 migration 任务停留在“已开始但不可执行”的状态
+
+适用范围：AI ICT 项目第一阶段 MVP。
+
+关联文档：
+
+1. `AI_ICT_总体设计文档_v1.md`
+2. `AI_ICT_PostgreSQL_Schema_v1.md`
+3. `AI_ICT_MVP_规则规格书_v1.md`
+4. `AI_ICT_开发路线图_v1.md`
+5. `AI_ICT_执行检查清单_v1.md`
+
+---
+
+## 2. 拆分原则
+
+1. 先基础字典，再时间序列，再结构事件，再信号执行，再回测分析
+2. 每个 batch 只处理一个明确依赖层级，避免一次 migration 混入过多对象
+3. 高数据量对象优先独立拆分，尤其是 `candles`
+4. 每个 batch 都要配套验证 SQL / 回滚说明 / 必要 seed 数据
+5. 第一版优先可落地，不对全部事件表过早分区
+
+---
+
+## 3. 总体依赖顺序
+
+```text
+B0 基础约定/公共函数
+  -> B1 venues
+  -> B2 instruments
+  -> B3 candles
+  -> B4 market_sessions
+  -> B5 swings
+  -> B6 dealing_ranges + liquidity_pools
+  -> B7 displacement_events
+  -> B8 structure_events + fvg_zones
+  -> B9 bias_snapshots
+  -> B10 trade_signals
+  -> B11 trade_executions
+  -> B12 backtest_runs
+  -> B13 backtest_results
+```
+
+依赖说明：
+
+- `instruments` 依赖 `venues`
+- `candles`、`market_sessions`、`swings` 依赖 `instruments`
+- `dealing_ranges` 依赖 `instruments`，并引用 `swings`
+- `structure_events` 引用 `swings` 与 `displacement_events`
+- `fvg_zones` 引用 `displacement_events`
+- `bias_snapshots` 引用 `dealing_ranges`
+- `trade_signals` 引用 `bias_snapshots`
+- `trade_executions` 引用 `trade_signals`
+- `backtest_runs` 依赖 `instruments`
+- `backtest_results` 依赖 `backtest_runs`，并可引用 `trade_signals`
+
+---
+
+## 4. migration 批次拆分
+
+## B0. 基础约定与公共函数
+
+### 目标
+
+建立后续所有 migration 共享的数据库前置条件。
+
+### 内容
+
+- 若项目决定使用非 `public`，先建立目标 schema
+- 建立 `updated_at` 自动更新时间的公共 trigger function（若采用）
+- 明确第一版统一使用 `text + check constraint` 替代数据库 enum
+- 明确所有时间字段使用 `timestamptz`
+
+### 验证检查点
+
+- 公共函数可创建成功
+- 后续表可以复用这些函数/约定
+- 时区约定已在 migration 注释中写明
+
+### 回滚说明
+
+- 删除本批次新增函数、trigger 模板和非业务 schema
+- 本批不涉及业务数据，回滚成本最低
+
+---
+
+## B1. `venues`
+
+### 目标
+
+建立交易所字典表。
+
+### 内容
+
+- 创建 `venues`
+- 主键 `id`
+- 唯一键 `code`
+- 默认状态 `status = 'active'`
+- 可插入初始 seed：`OKX`、`LMAX`
+
+### 依赖
+
+- B0
+
+### 验证检查点
+
+- 表可成功创建
+- `code` 唯一约束生效
+- 基础 seed 可查询
+
+### 回滚说明
+
+- 若无下游依赖，可先删 seed 再 drop 表
+- 若 `instruments` 已创建，必须先回退下游表
+
+---
+
+## B2. `instruments`
+
+### 目标
+
+建立统一交易品种表。
+
+### 内容
+
+- 创建 `instruments`
+- 外键 `venue_id references venues(id)`
+- 唯一键 `unique (venue_id, symbol)`
+- `meta jsonb default '{}'`
+- 插入 BTC / ETH / XAU 的基础 instrument seed
+
+### 依赖
+
+- B1
+
+### 验证检查点
+
+- `venue + symbol` 可唯一查询
+- 不存在的 `venue_id` 无法插入
+- `meta` 默认值生效
+
+### 回滚说明
+
+- 若无下游表，可删 seed 后 drop
+- 若已有 `candles`、`market_sessions`、`swings` 等表，需先逆序回滚下游
+
+---
+
+## B3. `candles`
+
+### 目标
+
+建立时间序列主表与首批月分区。
+
+### 内容
+
+- 创建 `candles` 主表
+- 唯一键 `unique (instrument_id, timeframe, ts_open)`
+- 索引：
+  - `(instrument_id, timeframe, ts_open desc)`
+  - `(instrument_id, timeframe, ts_close desc)`
+- 按 `ts_open` 建月分区
+- 至少预建当前月、下月分区
+
+### 为什么单独拆批
+
+- 数据量最大
+- 分区和唯一键策略最关键
+- 后续行情入库直接依赖这一批
+
+### 依赖
+
+- B2
+
+### 验证检查点
+
+- 可插入样例 K 线
+- 重复 `(instrument_id, timeframe, ts_open)` 会被拒绝
+- 数据能正确进入对应月分区
+- 关键查询能命中索引
+
+### 回滚说明
+
+- 先删测试数据
+- 先 drop 子分区，再 drop 主表
+- 若已有采集任务写入，生产环境不应直接回滚，应停写后重建
+
+---
+
+## B4. `market_sessions`
+
+### 目标
+
+建立 session 切分与 pivot 数据表。
+
+### 内容
+
+- 创建 `market_sessions`
+- 唯一键 `unique (instrument_id, session_date, session_code, timezone)`
+- `meta jsonb default '{}'`
+- 约定 session code：`ASIA`、`LONDON`、`NY_AM`、`NY_LUNCH`、`NY_PM`
+
+### 依赖
+
+- B2
+
+### 验证检查点
+
+- 同一 instrument/date/session/timezone 不能重复写入
+- 可查询 `high` / `low` / `midpoint`
+- 时区与会话区间表达一致
+
+### 回滚说明
+
+- 若未被上游程序依赖，可直接删测试数据并 drop
+- 若已有 session 生成器运行，先停任务再回滚
+
+---
+
+## B5. `swings`
+
+### 目标
+
+建立结构高低点表。
+
+### 内容
+
+- 创建 `swings`
+- check constraint：
+  - `kind in ('swing_high', 'swing_low')`
+  - `strength in ('ST', 'IT', 'LT')`
+- 索引：
+  - `(instrument_id, timeframe, ts desc)`
+  - `(instrument_id, timeframe, kind, ts desc)`
+  - `(instrument_id, timeframe, strength, ts desc)`
+
+### 依赖
+
+- B2
+
+### 验证检查点
+
+- `kind` / `strength` 约束生效
+- 能按 timeframe 查询最近 swing
+- 非法枚举值会被拒绝
+
+### 回滚说明
+
+- 若 `dealing_ranges` / `structure_events` 尚未创建，可直接回滚
+- 否则需先回滚依赖表
+
+---
+
+## B6. `dealing_ranges` + `liquidity_pools`
+
+### 目标
+
+建立基础规则层中最核心的两个结果表。
+
+### 合并原因
+
+- 同属基础规则层
+- 通常在同一轮规则计算中产出和消费
+- 依赖层级接近
+
+### 内容
+
+#### `dealing_ranges`
+- 创建表
+- 引用 `swings(id)`
+- 索引：
+  - `(instrument_id, timeframe, ts_start desc)`
+  - `(instrument_id, timeframe, state, ts_start desc)`
+
+#### `liquidity_pools`
+- 创建表
+- check constraint：
+  - `side in ('buy_side', 'sell_side')`
+  - `status in ('untouched', 'swept', 'consumed')`
+- 索引：
+  - `(instrument_id, timeframe, status, created_ts desc)`
+  - `(instrument_id, timeframe, side, created_ts desc)`
+
+### 依赖
+
+- B5
+
+### 验证检查点
+
+- `dealing_ranges.high_swing_id` / `low_swing_id` 能关联 `swings`
+- `liquidity_pools` 状态和方向约束生效
+- 可查询当前有效 range
+- 可查询当前流动性池
+
+### 回滚说明
+
+- 先停基础规则重算任务
+- 再按 `liquidity_pools -> dealing_ranges` 顺序回滚
+- 若 `bias_snapshots` 已存在，先回退下游
+
+---
+
+## B7. `displacement_events`
+
+### 目标
+
+建立有效位移事件表。
+
+### 内容
+
+- 创建 `displacement_events`
+- 添加 `direction`、`has_fvg`、`is_valid`
+- 索引：
+  - `(instrument_id, timeframe, end_ts desc)`
+  - `(instrument_id, timeframe, direction, end_ts desc)`
+
+### 依赖
+
+- B2
+
+### 验证检查点
+
+- 可查询最近 displacement
+- 默认值正常
+- 可被 `structure_events` 与 `fvg_zones` 引用
+
+### 回滚说明
+
+- 若 B8 尚未执行，可直接回滚
+- 否则先回滚 B8
+
+---
+
+## B8. `structure_events` + `fvg_zones`
+
+### 目标
+
+建立核心信号链路中的结构事件与 FVG 区域表。
+
+### 合并原因
+
+- 都属于信号上游对象
+- 都依赖 `displacement_events`
+- 一般同一轮规则识别会一起生成
+
+### 内容
+
+#### `structure_events`
+- 创建表
+- check constraint：
+  - `event_type in ('MSB', 'MSS')`
+  - `direction in ('bullish', 'bearish')`
+- 引用 `swings(id)` 与 `displacement_events(id)`
+
+#### `fvg_zones`
+- 创建表
+- check constraint：
+  - `direction in ('bullish', 'bearish')`
+  - `status in ('open', 'touched', 'mitigated', 'invalidated')`
+- 引用 `displacement_events(id)`
+
+### 依赖
+
+- B5、B7
+
+### 验证检查点
+
+- `structure_events` 能关联 swing 与 displacement
+- `fvg_zones` 能关联 displacement
+- 状态与方向约束生效
+- 可查询最近 MSS/MSB 与 open FVG
+
+### 回滚说明
+
+- 先删测试事件
+- 先回退信号层依赖，再回滚本批次
+
+---
+
+## B9. `bias_snapshots`
+
+### 目标
+
+建立 bias 快照表。
+
+### 内容
+
+- 创建 `bias_snapshots`
+- check constraint：
+  - `daily_bias in ('bullish', 'bearish', 'neutral')`
+  - `execution_intensity in ('low', 'medium', 'high')`
+- 引用 `dealing_ranges(id)`
+- 索引：
+  - `(instrument_id, snapshot_ts desc)`
+  - `(instrument_id, daily_bias, snapshot_ts desc)`
+
+### 依赖
+
+- B6
+
+### 验证检查点
+
+- 能关联有效 `range_id`
+- `reason_codes` / `meta` 默认值正常
+- 可按 instrument 查询最近 bias
+
+### 回滚说明
+
+- 若 `trade_signals` 尚未创建，可直接回滚
+- 否则先回滚 B10
+
+---
+
+## B10. `trade_signals`
+
+### 目标
+
+建立候选交易信号主表。
+
+### 内容
+
+- 创建 `trade_signals`
+- 引用 `bias_snapshots(id)`
+- 索引：
+  - `(instrument_id, created_ts desc)`
+  - `(instrument_id, status, created_ts desc)`
+  - `(instrument_id, model_code, created_ts desc)`
+- 保留 `invalidations jsonb`、`evidence jsonb`
+- 核心字段显式建列：entry/stop/tp/rr/status/side
+
+### 依赖
+
+- B9
+
+### 验证检查点
+
+- 信号可关联 bias snapshot
+- 能按 `status` 查询待确认/active 信号
+- `evidence` 可承载结构化引用
+
+### 回滚说明
+
+- 若 `trade_executions` 与 `backtest_results` 尚未创建，可直接回滚
+- 否则先回退下游依赖
+
+---
+
+## B11. `trade_executions`
+
+### 目标
+
+建立半自动执行记录表。
+
+### 内容
+
+- 创建 `trade_executions`
+- 引用 `trade_signals(id)`
+- check constraint：
+  - `execution_mode in ('paper', 'semi_auto', 'live')`
+  - `status in ('pending', 'open', 'partially_closed', 'closed', 'cancelled', 'rejected')`
+- 索引：
+  - `(signal_id)`
+  - `(status, created_at desc)`
+  - `(execution_mode, created_at desc)`
+
+### 依赖
+
+- B10
+
+### 验证检查点
+
+- execution 必须关联有效 signal
+- 可查询 open / closed / cancelled 状态
+- entry、stop、tp、size、risk_pct 可完整记录
+
+### 回滚说明
+
+- 先停执行写入流程
+- 删测试执行记录
+- 再回滚结构
+
+---
+
+## B12. `backtest_runs`
+
+### 目标
+
+建立回测任务元数据与结果摘要表。
+
+### 内容
+
+- 创建 `backtest_runs`
+- 引用 `instruments(id)`
+- 索引：
+  - `(model_code, started_ts desc)`
+  - `(instrument_id, started_ts desc)`
+- `config`、`summary` 使用 `jsonb`
+
+### 依赖
+
+- B2
+- 执行顺序上建议放在 B11 之后，以便阶段验收统一
+
+### 验证检查点
+
+- 可记录一次回测启动/结束
+- 可按 model 查询最近回测
+- `summary` 可保存聚合统计
+
+### 回滚说明
+
+- 若 `backtest_results` 尚未创建，可直接回滚
+- 否则先回滚 B13
+
+---
+
+## B13. `backtest_results`
+
+### 目标
+
+建立回测明细结果表。
+
+### 内容
+
+- 创建 `backtest_results`
+- 引用 `backtest_runs(id)`
+- 可空引用 `trade_signals(id)`
+- check constraint：
+  - `outcome in ('win', 'loss', 'breakeven', 'missed')`
+- 索引：
+  - `(backtest_run_id)`
+  - `(outcome)`
+
+### 依赖
+
+- B12
+- 若引用真实 signal，还依赖 B10
+
+### 验证检查点
+
+- 可按 `backtest_run_id` 查询所有结果
+- outcome 约束生效
+- `tp1_hit`、`tp2_hit`、`invalidated_before_entry` 可正确记录
+
+### 回滚说明
+
+- 先删除明细结果
+- 再回滚 `backtest_runs`
+- 生产环境优先逻辑废弃而非直接物理删除历史
+
+---
+
+## 5. 建议的 migration 文件命名
+
+```text
+001_base_conventions.sql
+002_create_venues.sql
+003_create_instruments.sql
+004_create_candles.sql
+005_create_candles_partitions.sql
+006_create_market_sessions.sql
+007_create_swings.sql
+008_create_dealing_ranges.sql
+009_create_liquidity_pools.sql
+010_create_displacement_events.sql
+011_create_structure_events.sql
+012_create_fvg_zones.sql
+013_create_bias_snapshots.sql
+014_create_trade_signals.sql
+015_create_trade_executions.sql
+016_create_backtest_runs.sql
+017_create_backtest_results.sql
+```
+
+说明：
+
+- 文档按 batch 归类
+- 实际文件可在同一 batch 内继续细拆
+- `candles` 主表和分区建议拆成两个 migration 文件
+
+---
+
+## 6. 每批次统一验证模板
+
+每个 batch 执行后至少完成以下检查：
+
+1. 表是否创建成功
+2. 主键/唯一键/外键是否生效
+3. check constraint 是否生效
+4. 默认值是否符合设计
+5. 一条合法样例插入是否成功
+6. 一条非法样例插入是否被拒绝
+7. 关键查询是否命中预期索引
+8. 验证结果是否记录到执行检查清单
+
+建议每批配套文件：
+
+- `verify_XXX.sql`
+- `rollback_XXX.sql`
+- `seed_XXX.sql`（如需要）
+
+---
+
+## 7. 回滚策略总则
+
+1. 严格按依赖逆序回滚
+2. 有真实业务数据后，先停写、备份、评估，再做物理回滚
+3. seed 与测试数据分开管理
+4. 分区表先回滚子分区，再回滚主表
+5. 代码已依赖该 migration 时，回滚前必须同步停用相关任务或服务
+
+推荐逆序：
+
+```text
+B13 -> B12 -> B11 -> B10 -> B9 -> B8 -> B7 -> B6 -> B5 -> B4 -> B3 -> B2 -> B1 -> B0
+```
+
+---
+
+## 8. 与开发阶段的对应关系
+
+### 阶段 0：项目基础设施初始化
+
+- B0
+- B1
+- B2
+
+### 阶段 1：基础数据层
+
+- B3
+- B4
+
+### 阶段 2：基础规则层
+
+- B5
+- B6
+
+### 阶段 3：核心信号层
+
+- B7
+- B8
+- B9
+- B10
+
+### 阶段 4：回测与验证层
+
+- B12
+- B13
+
+### 阶段 5：半自动执行层
+
+- B11
+
+说明：
+
+- 从纯数据库依赖上，`backtest_runs` 可更早建
+- 从交付节奏和验收上，按上面顺序更清晰
+
+---
+
+## 9. 最小可用落地顺序
+
+若当前目标是尽快启动 MVP，可先完成：
+
+1. B0
+2. B1
+3. B2
+4. B3
+5. B4
+6. B5
+7. B6
+
+完成后即可支撑：
+
+- 行情入库
+- session 生成
+- swing 识别
+- dealing range 识别
+- liquidity pool 识别
+
+之后继续：
+
+8. B7
+9. B8
+10. B9
+11. B10
+12. B11
+13. B12
+14. B13
+
+---
+
+## 10. 任务关闭标准
+
+本 migration 拆分文档完成后，应满足：
+
+- 已写入本地 `.md`
+- 路径存在且可读取
+- 批次顺序与 schema 依赖一致
+- 每个批次都包含验证检查点
+- 每个批次都包含回滚说明
+- 能直接作为后续 migration 编写参考
diff --git a/docs/AI_ICT_PostgreSQL_Schema_v1.md b/docs/AI_ICT_PostgreSQL_Schema_v1.md
new file mode 100644
index 0000000..1435caf
--- /dev/null
+++ b/docs/AI_ICT_PostgreSQL_Schema_v1.md
@@ -0,0 +1,806 @@
+# AI ICT PostgreSQL Schema 设计稿 v1
+
+## 1. 文档目标
+
+本文档定义 AI ICT 交易辅助系统第一阶段的 PostgreSQL 数据库设计方案，用于指导后续开发、建表、索引、分区和数据落库规范。
+
+目标：
+
+- 支撑 K 线与时间序列数据
+- 支撑 ICT 结构事件与信号建模
+- 支撑回测、复盘和审计
+- 支撑半结构化 evidence / narrative / labels 存储
+
+---
+
+## 2. 设计原则
+
+1. PostgreSQL 作为主库
+2. 时间序列主表优先做唯一键与分区设计
+3. 结构事件独立存表，不混入自由文本
+4. AI 相关说明使用 `jsonb`，但不替代核心字段
+5. 回测与实盘使用同一事件口径
+6. 先保守建模，预留扩展字段，不做过早复杂抽象
+
+---
+
+## 3. 命名规范
+
+- 表名：复数下划线风格，如 `trade_signals`
+- 主键：统一使用 `bigserial` 或 `uuid`
+- 时间字段：统一使用 `timestamptz`
+- 创建更新时间：`created_at`, `updated_at`
+- 逻辑状态：`status`
+- 配置或证据：`jsonb`
+
+建议：
+
+- 若系统由 Python / TypeScript 混合开发，业务主键可用 `uuid`
+- 若偏简洁开发，内部主键可用 `bigserial`，外部展示再加 `public_id`
+
+第一版建议：
+
+- 主表内部主键：`bigserial`
+- 对外引用可追加 `code` / `public_id`
+
+---
+
+## 4. 核心实体关系概览
+
+```text
+venues
+  -> instruments
+      -> candles
+      -> market_sessions
+      -> swings
+      -> dealing_ranges
+      -> liquidity_pools
+      -> displacement_events
+      -> structure_events
+      -> fvg_zones
+      -> bias_snapshots
+      -> trade_signals
+          -> trade_executions
+
+backtest_runs
+  -> backtest_results
+```
+
+---
+
+## 5. 基础表设计
+
+## 5.1 venues
+
+用途：交易所定义表。
+
+建议字段：
+
+```sql
+id              bigserial primary key
+code            text not null unique
+name            text not null
+timezone        text not null
+status          text not null default 'active'
+created_at      timestamptz not null default now()
+updated_at      timestamptz not null default now()
+```
+
+示例数据：
+
+- OKX
+- LMAX
+
+---
+
+## 5.2 instruments
+
+用途：交易品种定义表。
+
+建议字段：
+
+```sql
+id              bigserial primary key
+venue_id        bigint not null references venues(id)
+symbol          text not null
+asset_class     text not null
+base_asset      text
+quote_asset     text
+price_scale     integer not null
+qty_scale       integer not null
+tick_size       numeric(20,10) not null
+lot_size        numeric(20,10)
+active          boolean not null default true
+meta            jsonb not null default '{}'
+created_at      timestamptz not null default now()
+updated_at      timestamptz not null default now()
+```
+
+唯一约束：
+
+```sql
+unique (venue_id, symbol)
+```
+
+说明：
+
+- `meta` 存放交易所特定扩展信息
+- 如 XAU 在不同 venue 上合约不同，可通过 `meta` 补充合约属性
+
+---
+
+## 6. 行情与时间表设计
+
+## 6.1 candles
+
+用途：标准化 K 线主表。
+
+建议字段：
+
+```sql
+id              bigserial primary key
+instrument_id   bigint not null references instruments(id)
+timeframe       text not null
+ts_open         timestamptz not null
+ts_close        timestamptz not null
+open            numeric(20,10) not null
+high            numeric(20,10) not null
+low             numeric(20,10) not null
+close           numeric(20,10) not null
+volume          numeric(28,10)
+source          text not null default 'api'
+created_at      timestamptz not null default now()
+```
+
+唯一约束：
+
+```sql
+unique (instrument_id, timeframe, ts_open)
+```
+
+核心索引：
+
+```sql
+index on (instrument_id, timeframe, ts_open desc)
+index on (instrument_id, timeframe, ts_close desc)
+```
+
+分区建议：
+
+- 第一版按月范围分区
+- 分区键建议使用 `ts_open`
+
+例如：
+
+- `candles_2026_04`
+- `candles_2026_05`
+
+说明：
+
+- `timeframe` 先使用文本：`1m`, `5m`, `15m`, `1h`, `4h`, `1d`
+- 后期可引入枚举或维表
+
+---
+
+## 6.2 market_sessions
+
+用途：保存会话级别数据与 pivot。
+
+建议字段：
+
+```sql
+id              bigserial primary key
+instrument_id   bigint not null references instruments(id)
+session_date    date not null
+timezone        text not null
+session_code    text not null
+start_ts        timestamptz not null
+end_ts          timestamptz not null
+high            numeric(20,10)
+low             numeric(20,10)
+midpoint        numeric(20,10)
+status          text not null default 'closed'
+meta            jsonb not null default '{}'
+created_at      timestamptz not null default now()
+updated_at      timestamptz not null default now()
+```
+
+唯一约束：
+
+```sql
+unique (instrument_id, session_date, session_code, timezone)
+```
+
+建议的 `session_code`：
+
+- ASIA
+- LONDON
+- NY_AM
+- NY_LUNCH
+- NY_PM
+
+说明：
+
+- `meta` 可保存 broken / mitigated / extension 信息
+- 该表是会话 pivot、killzone 和执行许可的重要基础
+
+---
+
+## 7. 结构识别表设计
+
+## 7.1 swings
+
+用途：保存结构高低点。
+
+建议字段：
+
+```sql
+id              bigserial primary key
+instrument_id   bigint not null references instruments(id)
+timeframe       text not null
+kind            text not null
+strength        text not null
+price           numeric(20,10) not null
+ts              timestamptz not null
+left_bars       integer not null
+right_bars      integer not null
+confirmed       boolean not null default true
+meta            jsonb not null default '{}'
+created_at      timestamptz not null default now()
+```
+
+索引建议：
+
+```sql
+index on (instrument_id, timeframe, ts desc)
+index on (instrument_id, timeframe, kind, ts desc)
+index on (instrument_id, timeframe, strength, ts desc)
+```
+
+约束建议：
+
+- `kind in ('swing_high', 'swing_low')`
+- `strength in ('ST', 'IT', 'LT')`
+
+---
+
+## 7.2 dealing_ranges
+
+用途：保存当前工作区间。
+
+建议字段：
+
+```sql
+id                  bigserial primary key
+instrument_id       bigint not null references instruments(id)
+timeframe           text not null
+high                numeric(20,10) not null
+low                 numeric(20,10) not null
+equilibrium         numeric(20,10) not null
+high_swing_id       bigint references swings(id)
+low_swing_id        bigint references swings(id)
+state               text not null default 'valid'
+ts_start            timestamptz not null
+ts_end              timestamptz
+meta                jsonb not null default '{}'
+created_at          timestamptz not null default now()
+updated_at          timestamptz not null default now()
+```
+
+索引建议：
+
+```sql
+index on (instrument_id, timeframe, ts_start desc)
+index on (instrument_id, timeframe, state, ts_start desc)
+```
+
+说明：
+
+- 同一时刻可能存在多个 timeframe 的 range
+- 第一版允许一个 timeframe 存多条历史记录，由 `state` 标识当前有效项
+
+---
+
+## 7.3 liquidity_pools
+
+用途：保存流动性目标区域。
+
+建议字段：
+
+```sql
+id              bigserial primary key
+instrument_id   bigint not null references instruments(id)
+timeframe       text not null
+side            text not null
+pool_type       text not null
+price_low       numeric(20,10) not null
+price_high      numeric(20,10) not null
+reference_ids   jsonb not null default '[]'
+status          text not null default 'untouched'
+created_ts      timestamptz not null
+updated_ts      timestamptz not null default now()
+meta            jsonb not null default '{}'
+created_at      timestamptz not null default now()
+```
+
+建议约束：
+
+- `side in ('buy_side', 'sell_side')`
+- `status in ('untouched', 'swept', 'consumed')`
+
+`pool_type` 建议值：
+
+- prior_high
+- prior_low
+- equal_highs
+- equal_lows
+- session_high
+- session_low
+
+索引建议：
+
+```sql
+index on (instrument_id, timeframe, status, created_ts desc)
+index on (instrument_id, timeframe, side, created_ts desc)
+```
+
+---
+
+## 7.4 displacement_events
+
+用途：保存有效位移事件。
+
+建议字段：
+
+```sql
+id                  bigserial primary key
+instrument_id       bigint not null references instruments(id)
+timeframe           text not null
+direction           text not null
+start_ts            timestamptz not null
+end_ts              timestamptz not null
+strength_score      numeric(8,4)
+body_ratio          numeric(8,4)
+has_fvg             boolean not null default false
+is_valid            boolean not null default true
+meta                jsonb not null default '{}'
+created_at          timestamptz not null default now()
+```
+
+索引建议：
+
+```sql
+index on (instrument_id, timeframe, end_ts desc)
+index on (instrument_id, timeframe, direction, end_ts desc)
+```
+
+---
+
+## 7.5 structure_events
+
+用途：保存 MSB / MSS 等结构事件。
+
+建议字段：
+
+```sql
+id                      bigserial primary key
+instrument_id           bigint not null references instruments(id)
+timeframe               text not null
+event_type              text not null
+direction               text not null
+broken_level            numeric(20,10) not null
+reference_swing_id      bigint references swings(id)
+displacement_event_id   bigint references displacement_events(id)
+accepted                boolean
+signal_relevant         boolean not null default true
+ts                      timestamptz not null
+meta                    jsonb not null default '{}'
+created_at              timestamptz not null default now()
+```
+
+约束建议：
+
+- `event_type in ('MSB', 'MSS')`
+- `direction in ('bullish', 'bearish')`
+
+索引建议：
+
+```sql
+index on (instrument_id, timeframe, ts desc)
+index on (instrument_id, timeframe, event_type, ts desc)
+```
+
+---
+
+## 7.6 fvg_zones
+
+用途：保存 FVG / imbalance 区域。
+
+建议字段：
+
+```sql
+id                          bigserial primary key
+instrument_id               bigint not null references instruments(id)
+timeframe                   text not null
+direction                   text not null
+upper                       numeric(20,10) not null
+lower                       numeric(20,10) not null
+start_ts                    timestamptz not null
+end_ts                      timestamptz not null
+fill_pct                    numeric(8,4) not null default 0
+status                      text not null default 'open'
+related_displacement_id     bigint references displacement_events(id)
+meta                        jsonb not null default '{}'
+created_at                  timestamptz not null default now()
+updated_at                  timestamptz not null default now()
+```
+
+约束建议：
+
+- `direction in ('bullish', 'bearish')`
+- `status in ('open', 'touched', 'mitigated', 'invalidated')`
+
+索引建议：
+
+```sql
+index on (instrument_id, timeframe, start_ts desc)
+index on (instrument_id, timeframe, status, start_ts desc)
+```
+
+---
+
+## 8. 决策与执行表设计
+
+## 8.1 bias_snapshots
+
+用途：保存特定时刻的 bias 结果。
+
+建议字段：
+
+```sql
+id                  bigserial primary key
+instrument_id       bigint not null references instruments(id)
+bias_tf             text not null
+setup_tf            text not null
+trigger_tf          text not null
+snapshot_ts         timestamptz not null
+daily_bias          text not null
+confidence          numeric(8,4)
+execution_intensity text not null
+narrative_code      text
+draw_side           text
+range_id            bigint references dealing_ranges(id)
+reason_codes        jsonb not null default '[]'
+meta                jsonb not null default '{}'
+created_at          timestamptz not null default now()
+```
+
+约束建议：
+
+- `daily_bias in ('bullish', 'bearish', 'neutral')`
+- `execution_intensity in ('low', 'medium', 'high')`
+
+索引建议：
+
+```sql
+index on (instrument_id, snapshot_ts desc)
+index on (instrument_id, daily_bias, snapshot_ts desc)
+```
+
+---
+
+## 8.2 trade_signals
+
+用途：保存候选交易信号。
+
+建议字段：
+
+```sql
+id                  bigserial primary key
+instrument_id       bigint not null references instruments(id)
+model_code          text not null
+side                text not null
+status              text not null
+bias_snapshot_id    bigint references bias_snapshots(id)
+entry_type          text not null
+entry_low           numeric(20,10)
+entry_high          numeric(20,10)
+stop_loss           numeric(20,10)
+tp1                 numeric(20,10)
+tp2                 numeric(20,10)
+rr_tp1              numeric(8,4)
+rr_tp2              numeric(8,4)
+session_code        text
+created_ts          timestamptz not null
+expires_ts          timestamptz
+invalidations       jsonb not null default '[]'
+evidence            jsonb not null default '{}'
+meta                jsonb not null default '{}'
+created_at          timestamptz not null default now()
+updated_at          timestamptz not null default now()
+```
+
+建议状态值：
+
+- draft
+- awaiting_context
+- awaiting_confirmation
+- active
+- tp1_hit
+- tp2_hit
+- invalidated
+- expired
+- cancelled
+
+索引建议：
+
+```sql
+index on (instrument_id, created_ts desc)
+index on (instrument_id, status, created_ts desc)
+index on (instrument_id, model_code, created_ts desc)
+```
+
+说明：
+
+- `evidence` 保存 rule engine 引用对象，如 `range_id`, `sweep_event_id`, `structure_event_id`, `fvg_id`
+- 核心交易字段必须显式建列，不应只放进 JSON
+
+---
+
+## 8.3 trade_executions
+
+用途：保存实际执行记录。
+
+建议字段：
+
+```sql
+id                  bigserial primary key
+signal_id           bigint not null references trade_signals(id)
+venue_order_id      text
+execution_mode      text not null
+side                text not null
+entry_price         numeric(20,10)
+stop_loss           numeric(20,10)
+take_profit_1       numeric(20,10)
+take_profit_2       numeric(20,10)
+size                numeric(28,10)
+risk_pct            numeric(8,4)
+status              text not null
+opened_ts           timestamptz
+closed_ts           timestamptz
+pnl                 numeric(28,10)
+meta                jsonb not null default '{}'
+created_at          timestamptz not null default now()
+updated_at          timestamptz not null default now()
+```
+
+建议枚举：
+
+- `execution_mode in ('paper', 'semi_auto', 'live')`
+- `status in ('pending', 'open', 'partially_closed', 'closed', 'cancelled', 'rejected')`
+
+索引建议：
+
+```sql
+index on (signal_id)
+index on (status, created_at desc)
+index on (execution_mode, created_at desc)
+```
+
+---
+
+## 9. 回测与分析表设计
+
+## 9.1 backtest_runs
+
+用途：保存回测任务定义与结果摘要。
+
+建议字段：
+
+```sql
+id              bigserial primary key
+model_code      text not null
+instrument_id   bigint references instruments(id)
+timeframe_set    jsonb not null default '{}'
+started_ts      timestamptz not null
+ended_ts        timestamptz
+config          jsonb not null default '{}'
+summary         jsonb not null default '{}'
+created_at      timestamptz not null default now()
+```
+
+索引建议：
+
+```sql
+index on (model_code, started_ts desc)
+index on (instrument_id, started_ts desc)
+```
+
+---
+
+## 9.2 backtest_results
+
+用途：保存回测明细结果。
+
+建议字段：
+
+```sql
+id                      bigserial primary key
+backtest_run_id         bigint not null references backtest_runs(id)
+signal_id               bigint references trade_signals(id)
+outcome                 text not null
+mfe                     numeric(20,10)
+mae                     numeric(20,10)
+tp1_hit                 boolean
+tp2_hit                 boolean
+invalidated_before_entry boolean
+error_tags              jsonb not null default '[]'
+meta                    jsonb not null default '{}'
+created_at              timestamptz not null default now()
+```
+
+建议枚举：
+
+- `outcome in ('win', 'loss', 'breakeven', 'missed')`
+
+索引建议：
+
+```sql
+index on (backtest_run_id)
+index on (outcome)
+```
+
+---
+
+## 10. JSONB 边界建议
+
+适合放入 `jsonb` 的内容：
+
+- evidence 引用集合
+- narrative reason codes
+- 回测 error tags
+- 风控检查详情
+- 第三方交易所扩展字段
+- 会话扩展状态
+
+不应只存在于 `jsonb` 的内容：
+
+- side
+- status
+- timeframe
+- symbol / instrument_id
+- stop_loss
+- tp1 / tp2
+- bias
+- event_type
+- direction
+- ts
+
+原则：
+
+- 查询高频、过滤高频、排序高频字段必须单独建列
+- JSONB 仅用于补充与扩展
+
+---
+
+## 11. 索引策略建议
+
+### 11.1 时间序列表
+
+优先索引：
+
+- `(instrument_id, timeframe, ts_open desc)`
+- `(instrument_id, timeframe, ts desc)`
+- `(instrument_id, status, created_ts desc)`
+
+### 11.2 事件表
+
+优先索引：
+
+- 按 `instrument_id + timeframe + time`
+- 按 `event_type`
+- 按 `status`
+
+### 11.3 回测表
+
+优先索引：
+
+- `backtest_run_id`
+- `outcome`
+- `instrument_id + started_ts`
+
+---
+
+## 12. 分区建议
+
+### 12.1 必须优先分区的表
+
+1. `candles`
+2. 后期若数据量变大，可考虑：
+   - `trade_signals`
+   - `trade_executions`
+   - `backtest_results`
+
+### 12.2 第一版建议
+
+- `candles` 采用月分区
+- 其他表先普通表 + 合理索引
+- 不要一开始对所有事件表做过度分区
+
+原因：
+
+- candles 数据量增长最快
+- 其余表前期量可控
+- 先简化迁移和开发成本
+
+---
+
+## 13. 当前优先落地的 5 张基础表
+
+按照基础模块优先，建议先建：
+
+1. `venues`
+2. `instruments`
+3. `candles`
+4. `market_sessions`
+5. `swings`
+
+然后再建：
+
+6. `dealing_ranges`
+7. `liquidity_pools`
+
+之后进入：
+
+8. `displacement_events`
+9. `structure_events`
+10. `fvg_zones`
+11. `bias_snapshots`
+12. `trade_signals`
+13. `trade_executions`
+14. `backtest_runs`
+15. `backtest_results`
+
+---
+
+## 14. 建表顺序建议
+
+### 第一阶段
+
+- venues
+- instruments
+- candles
+- market_sessions
+
+### 第二阶段
+
+- swings
+- dealing_ranges
+- liquidity_pools
+
+### 第三阶段
+
+- displacement_events
+- structure_events
+- fvg_zones
+
+### 第四阶段
+
+- bias_snapshots
+- trade_signals
+- trade_executions
+
+### 第五阶段
+
+- backtest_runs
+- backtest_results
+
+---
+
+## 15. 当前结论
+
+Schema v1 的目标不是一次性穷尽全部 ICT 概念，而是先稳定支撑以下主链路：
+
+`Candles -> Sessions -> Swings -> Ranges -> Liquidity -> Sweep -> MSS -> FVG -> Signal -> Execution -> Backtest`
+
+后续开发中，所有新增字段和表都应优先服从这条主链路的一致性，不要为了术语完整性提前引入过多复杂实体。
diff --git a/docs/AI_ICT_Session_Generator_Spec_v1.md b/docs/AI_ICT_Session_Generator_Spec_v1.md
new file mode 100644
index 0000000..a481553
--- /dev/null
+++ b/docs/AI_ICT_Session_Generator_Spec_v1.md
@@ -0,0 +1,518 @@
+# AI ICT Session Generator 规格说明 v1
+
+## 1. 文档目标
+
+本文档定义 market session generator 的输入、时间规则、切分逻辑、计算方法、完整性检查和落库输出，用于指导 `market_sessions` 相关开发实现。
+
+目标：
+
+- 统一时区与交易日边界
+- 生成稳定、可重复的 session segmentation
+- 计算 session high / low / midpoint
+- 识别数据缺失与异常情况
+- 结果结构化输出到 `market_sessions`
+
+适用范围：AI ICT 项目第一阶段 MVP。
+
+关联文档：
+
+1. `AI_ICT_总体设计文档_v1.md`
+2. `AI_ICT_PostgreSQL_Schema_v1.md`
+3. `AI_ICT_MVP_规则规格书_v1.md`
+4. `AI_ICT_开发路线图_v1.md`
+5. `AI_ICT_执行检查清单_v1.md`
+
+---
+
+## 2. 设计目标与边界
+
+### 2.1 目标
+
+session generator 负责把标准化 candles 按固定会话切分，生成后续规则与执行依赖的 session 数据。
+
+输出必须支持：
+
+- session high
+- session low
+- midpoint
+- session 状态
+- 完整性元数据
+- 后续 rule-engine 的 session pivot 查询
+
+### 2.2 不负责的内容
+
+第一版 session generator 不负责：
+
+- 自动判断 bias
+- 自动判断 sweep / MSS / FVG
+- 直接产生交易信号
+- 直接生成 execution permission 最终结论
+
+这些能力由后续 rule-engine / signal-service 基于 `market_sessions` 再加工。
+
+---
+
+## 3. 输入与输出
+
+### 3.1 输入
+
+最小输入：
+
+- `instrument_id`
+- `symbol`
+- `timezone config`
+- 标准化 `candles`
+- 指定 `session_date` 或待重算的日期范围
+
+candles 最低要求字段：
+
+- `instrument_id`
+- `timeframe`
+- `ts_open`
+- `ts_close`
+- `open`
+- `high`
+- `low`
+- `close`
+
+### 3.2 输出
+
+输出到 `market_sessions` 表，字段遵循已有 schema：
+
+- `instrument_id`
+- `session_date`
+- `timezone`
+- `session_code`
+- `start_ts`
+- `end_ts`
+- `high`
+- `low`
+- `midpoint`
+- `status`
+- `meta`
+
+---
+
+## 4. 时间与时区规范
+
+## 4.1 存储原则
+
+- 数据库存储统一使用 `timestamptz`
+- 所有 `start_ts` / `end_ts` 均保存为 UTC 对应绝对时间
+- session 定义使用业务时区解释，不直接使用服务器本地时区
+
+## 4.2 第一版默认业务时区
+
+第一版默认业务时区统一为：
+
+- `America/New_York`
+
+原因：
+
+- 当前默认 session 模型围绕纽约交易时段定义
+- LONDON / NY_AM / NY_LUNCH / NY_PM 都依赖纽约时区解释
+- 能统一 crypto 与 XAU 的 session 观察口径
+
+## 4.3 交易日定义
+
+第一版 `session_date` 定义为“业务时区下该组 session 所属日期”。
+
+例如：
+
+- `ASIA 2026-04-23` 指的是在 `America/New_York` 语义下，属于 2026-04-23 交易日的 ASIA 会话
+- 虽然其 UTC 时间可能跨自然日，但 `session_date` 不按 UTC 日历切换，而按业务时区日历归属
+
+## 4.4 DST 处理原则
+
+必须支持 `America/New_York` 夏令时切换。
+
+规则：
+
+1. session 定义始终以业务时区本地时钟解释
+2. 转换到数据库时，再映射为 UTC `start_ts` / `end_ts`
+3. 不允许通过手写固定 UTC 偏移硬编码 session
+4. DST 切换日必须通过时区库计算，不能人工推导
+
+---
+
+## 5. Session 定义与切分规则
+
+### 5.1 默认 session 列表
+
+第一版采用以下默认 session：
+
+- ASIA: 20:00 - 00:00
+- LONDON: 02:00 - 05:00
+- NY_AM: 09:30 - 11:00
+- NY_LUNCH: 12:00 - 13:00
+- NY_PM: 13:30 - 16:00
+
+时区基准：`America/New_York`。
+
+### 5.2 Session 边界约定
+
+统一采用：
+
+- `start_ts` inclusive
+- `end_ts` exclusive
+
+即：
+
+```text
+start_ts <= candle.ts_open < end_ts
+```
+
+这样可以避免相邻 session 在边界 candle 上重复归属。
+
+### 5.3 跨午夜处理
+
+`ASIA: 20:00 - 00:00` 会跨本地日内晚间到午夜边界。
+
+处理规则：
+
+- 如果 session 结束时间小于等于开始时间，则视为跨日 session
+- `end_ts` 应自动落到下一自然日的 00:00
+- `session_date` 仍归属该交易日定义，不因为 UTC 或本地午夜而拆成两段
+
+### 5.4 单 candle 归属原则
+
+一根 candle 在第一版中只能归属一个 session。
+
+归属依据：
+
+- 用 `candle.ts_open` 判断所属 session
+- 不使用 `ts_close` 参与归属判定
+- 若某 candle 不落在任何 session 区间，则不进入 `market_sessions` 聚合
+
+### 5.5 推荐运行粒度
+
+第一版建议以基础数据主时间框架生成 session，推荐：
+
+- `1m` 为最优
+- `5m` 可作为退化版本
+
+原因：
+
+- NY_AM、NY_LUNCH 等窗口较短
+- 更细粒度有利于后续 pivot、sweep、session high/low 分析
+
+---
+
+## 6. Session 聚合逻辑
+
+### 6.1 选取数据范围
+
+给定 `instrument_id + session_date + session_code + timezone`：
+
+1. 计算业务时区下的本地 `start_local` / `end_local`
+2. 转换成 UTC `start_ts` / `end_ts`
+3. 查询满足以下条件的 candles：
+
+```text
+instrument_id = ?
+timeframe = configured_base_tf
+candle.ts_open >= start_ts
+candle.ts_open < end_ts
+```
+
+### 6.2 high / low 计算
+
+- `high = max(candle.high)`
+- `low = min(candle.low)`
+
+前提：至少存在一根有效 candle。
+
+### 6.3 midpoint 计算
+
+第一版 midpoint 定义为：
+
+```text
+midpoint = (high + low) / 2
+```
+
+注意：
+
+- midpoint 不是 VWAP
+- midpoint 不是 open/close 平均值
+- midpoint 是 session range 的几何中点
+
+### 6.4 扩展元数据
+
+建议在 `meta` 写入：
+
+- `timeframe_used`
+- `candle_count`
+- `expected_candle_count`
+- `completeness_ratio`
+- `is_dst`
+- `source`
+- `generated_at`
+- `data_gaps`
+- `rebuild_reason`
+
+---
+
+## 7. 数据完整性检查
+
+### 7.1 检查目标
+
+session generator 不能只算出 high / low，还必须判断该 session 是否足够完整，避免缺失 candles 导致 pivot 失真。
+
+### 7.2 期望 K 线数量
+
+应按 session 时长与 `configured_base_tf` 计算理论 candle 数量。
+
+示例：
+
+- `ASIA 20:00 - 00:00`，若 `1m` 粒度，理论 240 根
+- `LONDON 02:00 - 05:00`，若 `1m` 粒度，理论 180 根
+- `NY_AM 09:30 - 11:00`，若 `1m` 粒度，理论 90 根
+
+### 7.3 完整性比率
+
+```text
+completeness_ratio = actual_candle_count / expected_candle_count
+```
+
+### 7.4 第一版状态建议
+
+`status` 建议值：
+
+- `closed`：会话已结束且完整性达标
+- `partial`：会话已结束但数据缺失
+- `open`：会话尚未结束，仍在生成中
+- `empty`：窗口内无有效 candle
+- `invalid`：时间配置或输入异常，结果不可用
+
+### 7.5 第一版完整性阈值
+
+建议：
+
+- `>= 0.98` 视为 `closed`
+- `> 0 and < 0.98` 视为 `partial`
+- `= 0` 视为 `empty`
+
+是否采用 0.98 可配置，但第一版文档默认使用该值。
+
+### 7.6 Gap 检查
+
+除了 candle 数量，还应检查时间连续性：
+
+- 相邻 `ts_open` 间隔应等于 timeframe 步长
+- 若出现跳点，则记录 gap 段
+- 若出现重复 candle，应在上游 `candles` 唯一约束阶段拦截；session generator 不负责去重修复
+
+建议记录到 `meta.data_gaps`：
+
+```json
+[
+  {
+    "expected": "2026-04-23T13:15:00Z",
+    "actual": "2026-04-23T13:17:00Z",
+    "missing_count": 1
+  }
+]
+```
+
+---
+
+## 8. 生成流程规范
+
+### 8.1 全量重算
+
+适用场景：
+
+- 初始化历史数据
+- 修复 session 定义
+- 迁移后重建 session 数据
+
+流程：
+
+1. 读取日期范围
+2. 按 instrument 逐日生成 session 窗口
+3. 查询 candles
+4. 计算 high / low / midpoint
+5. 执行完整性检查
+6. upsert 到 `market_sessions`
+
+### 8.2 增量更新
+
+适用场景：
+
+- 新 candles 持续进入
+- 当天 session 持续刷新
+
+流程：
+
+1. 找到受影响 `instrument + session_date + session_code`
+2. 重新聚合整个 session 窗口
+3. 用 upsert 覆盖原记录
+4. 若会话尚未结束，状态保持 `open`
+5. 会话结束后再转为 `closed` / `partial` / `empty`
+
+### 8.3 Upsert 规则
+
+基于唯一键：
+
+```text
+(instrument_id, session_date, session_code, timezone)
+```
+
+建议行为：
+
+- 不做 append-only
+- 直接 upsert 最新聚合结果
+- `updated_at` 反映最近刷新时间
+
+---
+
+## 9. `market_sessions` 输出规范
+
+### 9.1 字段映射
+
+- `instrument_id`：来自上游 instrument
+- `session_date`：业务时区下的交易日
+- `timezone`：第一版固定 `America/New_York`
+- `session_code`：ASIA / LONDON / NY_AM / NY_LUNCH / NY_PM
+- `start_ts`：本地 session 起点转 UTC
+- `end_ts`：本地 session 终点转 UTC
+- `high`：session 期间最高价
+- `low`：session 期间最低价
+- `midpoint`：`(high + low) / 2`
+- `status`：`open` / `closed` / `partial` / `empty` / `invalid`
+- `meta`：完整性与生成元数据
+
+### 9.2 约束要求
+
+写入前必须保证：
+
+- `high >= low`
+- 当 `status in ('closed', 'partial', 'open')` 时，`high` 与 `low` 不应为空
+- 当 `status in ('empty', 'invalid')` 时，`high` / `low` / `midpoint` 可为空
+
+### 9.3 推荐 meta 结构
+
+```json
+{
+  "timeframe_used": "1m",
+  "expected_candle_count": 90,
+  "actual_candle_count": 89,
+  "completeness_ratio": 0.9889,
+  "is_dst": true,
+  "source": "session-generator",
+  "generated_at": "2026-04-23T14:05:00Z",
+  "data_gaps": []
+}
+```
+
+---
+
+## 10. 异常与边界情况
+
+### 10.1 空窗口
+
+若 session 时间窗口内完全没有 candle：
+
+- 写入一条 `status = empty` 的记录
+- `high` / `low` / `midpoint` 留空
+- 在 `meta` 记录原因
+
+### 10.2 未结束会话
+
+若当前时间仍早于 `end_ts`：
+
+- 允许生成实时中的 session
+- `status = open`
+- 可用于盘中监控，但不能视为最终 session pivot
+
+### 10.3 DST 切换日
+
+DST 切换导致 UTC 映射变化时：
+
+- 仍按本地 session 时钟定义生成
+- 允许 `expected_candle_count` 因本地时间异常而变化，但必须有明确计算依据
+- `meta.is_dst` 与相关说明必须保留
+
+### 10.4 上游 candle 重建
+
+若 candles 历史数据被修复或补齐：
+
+- 必须触发对应日期 session 重算
+- 不允许沿用旧 session 结果
+
+### 10.5 非连续交易市场
+
+若后续接入存在休市机制的 market：
+
+- 第一版仍沿用统一 session 规则
+- 节假日与休市判断暂由外部日历模块处理
+- session generator 只消费“应该参与生成的日期集合”
+
+---
+
+## 11. 验证与验收要求
+
+### 11.1 功能验证
+
+至少验证：
+
+- 能为同一 instrument 连续生成 5 个 session_code
+- 同一天查询能拿到完整 session 列表
+- midpoint 计算正确
+- 重复执行生成任务结果稳定
+
+### 11.2 数据验证
+
+至少验证：
+
+- `session_date` 归属正确
+- `start_ts` / `end_ts` 对应的业务时区时间正确
+- `high` / `low` 与原始 candle 对齐
+- partial / empty 状态能正确触发
+
+### 11.3 人工抽查
+
+至少抽查：
+
+- 一个正常交易日
+- 一个存在 gap 的交易日
+- 一个 DST 切换附近交易日
+
+### 11.4 与检查清单对齐
+
+任务关闭前至少满足：
+
+- session generator 规格已写入本地 `.md`
+- 路径存在
+- 已检查标题、章节、关键内容
+- 规格足以指导后续实现与测试
+
+---
+
+## 12. 推荐实现顺序
+
+建议按以下顺序落地：
+
+1. 固定 `America/New_York` session 定义
+2. 完成窗口计算与 UTC 转换
+3. 完成 candles 聚合
+4. 完成 high / low / midpoint 计算
+5. 完成 completeness / gap 检查
+6. 完成 `market_sessions` upsert
+7. 再补增量重算与异常记录
+
+这样可以先让 session 数据可落库，再逐步增强完整性判断。
+
+---
+
+## 13. 最终结论
+
+session generator 是全部后续 ICT 结构识别的重要上游。
+
+第一版实现必须保证三件事：
+
+1. 时间边界稳定
+2. 聚合结果可重复
+3. 缺失数据可识别
+
+只有在这三点成立后，`market_sessions` 才能可靠支撑 liquidity pools、session pivots、sweep 判定和执行窗口过滤。
\ No newline at end of file
diff --git a/docs/AI_ICT_Session_生成器规格书_v1.md b/docs/AI_ICT_Session_生成器规格书_v1.md
new file mode 100644
index 0000000..aa28e03
--- /dev/null
+++ b/docs/AI_ICT_Session_生成器规格书_v1.md
@@ -0,0 +1,421 @@
+# AI ICT Session 生成器规格书 v1
+
+## 1. 文档目标
+
+本文档定义 AI ICT 项目第一阶段的 Session 生成器实现规格，用于把标准化后的 candles 数据转换为可供规则引擎使用的会话数据，并写入 `market_sessions` 表。
+
+本模块是基础共享模块，位于：
+
+`Candles -> Sessions -> Swings -> Ranges`
+
+Session 生成器的输出会直接影响：
+
+- Asia high / low
+- London high / low
+- NY AM / Lunch / PM high / low
+- session midpoint
+- session-based liquidity pools
+- 后续 bias 与 intraday 路径判断
+
+因此，这个模块必须优先稳定。
+
+---
+
+## 2. 模块职责
+
+Session 生成器只负责 4 件事：
+
+1. 把 UTC candles 映射到目标时区
+2. 按会话切分 candle 集合
+3. 计算会话 high / low / midpoint
+4. 写入或更新 `market_sessions`
+
+本模块不负责：
+
+- swing 识别
+- liquidity pool 识别
+- sweep 判定
+- bias 输出
+
+这些都属于下游模块。
+
+---
+
+## 3. 输入与输出
+
+## 3.1 输入
+
+输入数据来自 `candles` 表，必须至少包含：
+
+- instrument_id
+- timeframe
+- ts_open
+- ts_close
+- open
+- high
+- low
+- close
+
+说明：
+
+- Session 生成器第一阶段建议以 `1m` 或 `5m` candles 作为输入
+- 若数据粒度过大，会影响会话 high / low 精度
+
+---
+
+## 3.2 输出
+
+输出写入 `market_sessions` 表，字段包括：
+
+- instrument_id
+- session_date
+- timezone
+- session_code
+- start_ts
+- end_ts
+- high
+- low
+- midpoint
+- status
+- meta
+
+---
+
+## 4. 时区规则
+
+## 4.1 标准存储规则
+
+上游 `candles` 表中的时间统一按 UTC 存储。
+
+Session 生成器运行时，必须：
+
+1. 先读取 UTC 时间
+2. 再转换到业务时区
+3. 按业务时区进行 session 切分
+
+第一阶段业务时区固定：
+
+- `America/New_York`
+
+---
+
+## 4.2 基本原则
+
+- 数据库存 UTC
+- 会话逻辑用纽约时间
+- 最终写回的 `start_ts` / `end_ts` 仍建议保存为 UTC 对应时刻
+
+这样可以避免：
+
+- 本地机器时区污染
+- 夏令时处理混乱
+- 多环境运行结果不一致
+
+---
+
+## 5. 默认会话定义
+
+第一阶段采用以下默认会话：
+
+- ASIA: 20:00 - 00:00
+- LONDON: 02:00 - 05:00
+- NY_AM: 09:30 - 11:00
+- NY_LUNCH: 12:00 - 13:00
+- NY_PM: 13:30 - 16:00
+
+说明：
+
+- 以上时间均以 `America/New_York` 为准
+- 会话窗口必须配置化，不应硬编码散落在逻辑里
+
+建议配置结构：
+
+```yaml
+sessions:
+  timezone: America/New_York
+  items:
+    - code: ASIA
+      start: "20:00"
+      end: "00:00"
+    - code: LONDON
+      start: "02:00"
+      end: "05:00"
+    - code: NY_AM
+      start: "09:30"
+      end: "11:00"
+    - code: NY_LUNCH
+      start: "12:00"
+      end: "13:00"
+    - code: NY_PM
+      start: "13:30"
+      end: "16:00"
+```
+
+---
+
+## 6. 会话日期归属规则
+
+这是 Session 生成器中最容易错的地方。
+
+## 6.1 基本定义
+
+`session_date` 不是简单取 candle 的 UTC 日期，而是取 candle 在 `America/New_York` 下所属交易日的日期。
+
+---
+
+## 6.2 跨午夜会话处理
+
+例如 ASIA: `20:00 - 00:00`
+
+该会话跨越自然日边界，因此必须先明确归属规则。
+
+建议规则：
+
+- ASIA 会话归属到其起始日
+- 即纽约时间某日 20:00 开始到次日 00:00 结束的这段，统一记为该起始日的 ASIA 会话
+
+例：
+
+- 2026-04-23 20:00 ~ 2026-04-24 00:00
+- `session_date = 2026-04-23`
+
+这样更方便后续和日内叙事对齐。
+
+---
+
+## 7. 切分逻辑
+
+## 7.1 切分步骤
+
+对于某个 `instrument_id + session_date`：
+
+1. 将候选 candles 转换为纽约时间
+2. 根据 session 配置匹配属于哪个 session
+3. 汇总该 session 内所有 candles
+4. 计算 high / low / midpoint
+5. 生成 `market_sessions` 记录
+
+---
+
+## 7.2 Session high / low 计算
+
+- high = 该 session 内所有 candle.high 的最大值
+- low = 该 session 内所有 candle.low 的最小值
+- midpoint = (high + low) / 2
+
+要求：
+
+- midpoint 必须用 high / low 计算，不允许用 open / close 近似
+
+---
+
+## 7.3 会话状态
+
+第一阶段建议支持以下状态：
+
+- open
+- closed
+- incomplete
+- invalid
+
+含义：
+
+- open：当前会话尚未结束
+- closed：会话结束且数据完整
+- incomplete：会话结束但 candle 缺失
+- invalid：时间映射或数据异常导致不可用
+
+---
+
+## 8. 数据完整性检查
+
+Session 生成器必须先检查输入 candles 是否足够完整。
+
+## 8.1 最低检查项
+
+- 时间窗口是否有 candle
+- candle 是否连续
+- 是否存在重复 ts_open
+- 是否存在明显缺口
+
+---
+
+## 8.2 缺口处理策略
+
+第一阶段建议：
+
+### 若缺口很小
+- 允许写入 session
+- 但标记 `status = incomplete`
+- 在 `meta` 中记录缺口信息
+
+### 若缺口严重
+- 不生成正式 session
+- 或标记 `status = invalid`
+
+说明：
+
+- 不建议静默忽略缺口
+- 否则 session high / low 可能误导后续规则
+
+---
+
+## 8.3 重复数据处理
+
+若发现同一 `instrument_id + timeframe + ts_open` 重复：
+
+- 视为上游数据问题
+- Session 生成器不负责去重修复
+- 但应记录错误并拒绝继续处理该窗口
+
+---
+
+## 9. 写入策略
+
+## 9.1 幂等要求
+
+对于同一个：
+
+- instrument_id
+- session_date
+- session_code
+- timezone
+
+重复执行生成器时，不应产生重复记录。
+
+建议：
+
+- 使用 upsert
+- 若结果一致则更新 `updated_at`
+- 若结果变化则更新 high / low / midpoint / status / meta
+
+---
+
+## 9.2 更新场景
+
+### 场景 A：会话仍在进行
+- 可周期性刷新 high / low
+- `status = open`
+
+### 场景 B：会话已结束
+- 最终固化为 `status = closed` 或 `incomplete`
+
+### 场景 C：历史重算
+- 允许全量覆盖旧结果
+- 但必须保留 `updated_at`
+
+---
+
+## 10. 下游依赖输出
+
+Session 生成器完成后，下游至少应能直接使用：
+
+- Asia high / low
+- London high / low
+- NY_AM high / low
+- NY_LUNCH high / low
+- NY_PM high / low
+- 各 session midpoint
+- 当前会话状态
+
+这些输出会被下游用于：
+
+- session-based liquidity pools
+- session range 展示
+- intraday context
+- time filter
+
+---
+
+## 11. 推荐任务拆分
+
+### T1. session 配置模块
+- timezone
+- session window
+- session_date 归属规则
+
+### T2. 时间转换模块
+- UTC -> America/New_York
+- 夏令时验证
+
+### T3. 单会话切分逻辑
+- 给定 session_date + session_code
+- 找出对应 candles
+
+### T4. 聚合逻辑
+- 计算 high / low / midpoint
+- 生成状态
+
+### T5. DB 写入逻辑
+- upsert `market_sessions`
+
+### T6. 校验逻辑
+- 缺口检测
+- 重复检测
+- incomplete / invalid 判定
+
+---
+
+## 12. 验证检查点
+
+## 12.1 最低验证
+
+至少验证以下内容：
+
+- [ ] ASIA 会话可生成
+- [ ] LONDON 会话可生成
+- [ ] NY_AM 会话可生成
+- [ ] NY_LUNCH 会话可生成
+- [ ] NY_PM 会话可生成
+
+---
+
+## 12.2 数值验证
+
+每个 session 至少检查：
+
+- [ ] high >= low
+- [ ] midpoint = (high + low) / 2
+- [ ] start_ts < end_ts
+- [ ] session_code 正确
+- [ ] timezone 正确
+
+---
+
+## 12.3 样本人工抽查
+
+至少抽查一个交易日：
+
+- [ ] session 起止时间正确
+- [ ] session high / low 与图表一致
+- [ ] ASIA 跨午夜归属正确
+- [ ] NY 时段未被本地系统时区污染
+
+---
+
+## 13. 完成标准
+
+只有满足以下全部条件，Session 生成器模块才算完成：
+
+1. 能从 candles 正确生成 5 类 session
+2. 支持纽约时区切分
+3. 支持跨午夜 session 归属
+4. 能检测不完整数据
+5. 能幂等写入 `market_sessions`
+6. 可供下游 liquidity / context 模块直接使用
+
+---
+
+## 14. 当前结论
+
+Session 生成器不是一个“简单聚合器”，而是日内结构语言的基础坐标系统。
+
+只要这个模块出错，后续以下模块都会连锁失真：
+
+- liquidity pools
+- sweep
+- time filters
+- daily bias
+- intraday model
+
+因此在真实开发中，Session 生成器应被视为第一批必须严格验证的基础模块之一。
\ No newline at end of file
diff --git a/docs/AI_ICT_Sweep_Identification_Spec_v1.md b/docs/AI_ICT_Sweep_Identification_Spec_v1.md
new file mode 100644
index 0000000..abaa0e1
--- /dev/null
+++ b/docs/AI_ICT_Sweep_Identification_Spec_v1.md
@@ -0,0 +1,590 @@
+# AI ICT Sweep 识别规格书 v1
+
+## 1. 文档目标
+
+本文档定义 AI ICT 项目第一阶段 MVP 的 sweep identification 规则，用于指导：
+
+- `sweep_events` 识别模块开发
+- liquidity pool 与 sweep 的交互判定
+- wick / close 行为判断
+- displacement、MSS、signal 等下游模块引用
+- 本地验证、抽样复盘与后续回测
+
+本文档只覆盖 sweep 的识别与状态维护，不覆盖 displacement、MSS、FVG 的完整规则实现。
+
+关联文档：
+
+1. `AI_ICT_MVP_规则规格书_v1.md`
+2. `AI_ICT_PostgreSQL_Schema_v1.md`
+3. `AI_ICT_开发路线图_v1.md`
+4. `AI_ICT_执行检查清单_v1.md`
+5. `AI_ICT_Dealing_Range_Spec_v1.md`
+
+---
+
+## 2. 设计目标
+
+sweep 模块需要满足以下目标：
+
+1. 只围绕结构化 liquidity pool 识别，不做自由解释
+2. 能区分 wick-only 刺穿与 close-back-inside 的行为差异
+3. 能对 sweep 做分层验证，而不是一刀切二元判断
+4. 能与后续 displacement 事件建立明确链接
+5. 能维护 sweep 的状态流转，避免同一 pool 被重复误判
+6. 输出结构化、可回测、可审计
+
+---
+
+## 3. 核心定义
+
+## 3.1 Liquidity Pool
+
+sweep 的前提是存在已识别的 liquidity pool。
+
+第一版 pool 来源：
+
+- `prior_high`
+- `prior_low`
+- `equal_highs`
+- `equal_lows`
+- `session_high`
+- `session_low`
+
+每个 pool 至少有：
+
+- `side`
+- `price_low`
+- `price_high`
+- `status`
+- `timeframe`
+
+## 3.2 Sweep
+
+sweep 是价格对某一侧 liquidity pool 的刺穿与清理行为。
+
+第一版中，sweep 必须满足：
+
+- 有明确目标 pool
+- 价格对 pool 发生有效交互
+- 交互后能够输出结构化结果
+
+## 3.3 Side Swept
+
+`sweep.side_swept` 表示被清理的是哪一侧流动性：
+
+- `buy_side`：上方流动性被清理，通常对应扫高
+- `sell_side`：下方流动性被清理，通常对应扫低
+
+## 3.4 Wick Sweep
+
+价格仅用 wick 刺穿 pool 区间，但收盘没有稳定站在区间外，可记为 wick sweep 候选。
+
+## 3.5 Close Back Inside
+
+价格刺穿 pool 后，最终收盘重新回到 pool 内侧或原结构区间内，记为 `close_back_inside = true`。
+
+这通常是第一版更优先关注的 sweep 形态。
+
+---
+
+## 4. pool 交互规则
+
+## 4.1 sweep 必须依赖 pool
+
+第一版不允许没有 pool 就直接定义 sweep。
+
+即：
+
+- 先有 `liquidity_pools`
+- 再判断 candles 是否与 pool 发生 sweep 交互
+
+## 4.2 交互方向
+
+### 扫 buy-side liquidity
+
+若目标 pool 的 `side = buy_side`，则价格必须向上刺穿 pool：
+
+- `high` 触及或突破 `pool.price_low`
+- 并进一步进入或突破 `pool.price_high`
+
+### 扫 sell-side liquidity
+
+若目标 pool 的 `side = sell_side`，则价格必须向下刺穿 pool：
+
+- `low` 触及或跌破 `pool.price_high`
+- 并进一步进入或跌破 `pool.price_low`
+
+## 4.3 第一版触发判定
+
+为了兼容区间型 pool，第一版将“发生交互”定义为：
+
+### 对 buy_side pool
+
+候选 candle 满足：
+
+- `high >= pool.price_low`
+- 且至少有一部分价格行为进入或突破 `pool.price_high`
+
+### 对 sell_side pool
+
+候选 candle 满足：
+
+- `low <= pool.price_high`
+- 且至少有一部分价格行为进入或突破 `pool.price_low`
+
+更简化地说：
+
+- 上方池要被“扫进去/扫过去”
+- 下方池要被“打进去/打过去”
+
+## 4.4 pool 优先级
+
+若同一 candle 同时与多个 pool 交互，第一版建议按如下优先级选择主 sweep 对象：
+
+1. 时间更近的 pool
+2. timeframe 更接近当前规则处理周期的 pool
+3. `equal_highs / equal_lows` 优先于普通 `prior_high / prior_low`
+4. session pool 在 session 相关策略中可优先
+5. 若仍冲突，取离当前价格更近者
+
+MVP 最小实现建议：
+
+- 一根 candle 只认一个主 pool
+- 其余命中记录到 `meta.candidate_pool_ids`
+
+---
+
+## 5. wick / close 行为规则
+
+## 5.1 wick 刺穿
+
+候选 candle 只要 wick 进入或越过目标 pool，即可形成 sweep 候选。
+
+例如：
+
+- 扫 buy-side：`high` 突破 pool 上沿
+- 扫 sell-side：`low` 跌破 pool 下沿
+
+## 5.2 close_back_inside
+
+第一版更强的 sweep 条件是 `close_back_inside = true`。
+
+### 对 buy_side pool
+
+候选 candle 扫高后，收盘重新回到 pool 下方或回到结构内部，记为 close back inside。
+
+### 对 sell_side pool
+
+候选 candle 扫低后，收盘重新回到 pool 上方或回到结构内部，记为 close back inside。
+
+## 5.3 close-outside 的处理
+
+若价格刺穿 pool 后收盘仍留在外部：
+
+- 可视为已发生 liquidity interaction
+- 但第一版不优先定义为高质量 sweep
+- 更可能属于延续突破，而不是清扫后回收
+
+因此：
+
+- wick sweep + close outside = 弱候选
+- wick sweep + close back inside = 更强候选
+
+## 5.4 多根 K 线确认
+
+第一版 sweep 的发生时点以首根有效交互 candle 为准，不要求等待多根 K 线才能记录 sweep event。
+
+但后续验证等级可以引用后续 1~N 根 candle 的行为。
+
+---
+
+## 6. 验证分层
+
+## 6.1 设计原则
+
+第一版不把所有 sweep 都视为同质量信号，而是分层：
+
+- L1：弱 sweep
+- L2：有效 sweep
+- L3：强 sweep
+
+## 6.2 L1 弱 sweep
+
+满足：
+
+- 与 pool 有明确 wick 交互
+- 但未出现 close back inside
+- 或缺少后续 displacement 支持
+
+用途：
+
+- 可记录
+- 默认不直接作为入场依据
+
+## 6.3 L2 有效 sweep
+
+满足：
+
+- 与 pool 发生明确刺穿
+- `close_back_inside = true`
+- pool 原始状态为 `untouched`
+- 没有明显数据缺口或结构冲突
+
+用途：
+
+- 可进入后续 displacement / MSS 观察链路
+
+## 6.4 L3 强 sweep
+
+满足：
+
+- 已满足 L2
+- 在限定窗口内出现有效 displacement
+- displacement 方向与 sweep 后预期反应一致
+- 可形成后续 MSS / FVG 链路候选
+
+用途：
+
+- 可作为 `SWEEP_MSS_FVG` 模型的高质量前置条件
+
+## 6.5 第一版最小实现建议
+
+若系统复杂度有限，可先实现：
+
+- `weak`
+- `valid`
+
+两层，然后把强 sweep 通过 `displacement_after = true` 额外标记。
+
+---
+
+## 7. displacement linkage 规则
+
+## 7.1 sweep 与 displacement 的关系
+
+sweep 本身只表示流动性被清理；是否具有更高质量，要看后续是否出现 displacement。
+
+## 7.2 方向一致性
+
+### 扫 buy-side 之后
+
+若 sweep 清理的是上方 buy-side liquidity，则高质量后续反应通常是向下 displacement。
+
+### 扫 sell-side 之后
+
+若 sweep 清理的是下方 sell-side liquidity，则高质量后续反应通常是向上 displacement。
+
+## 7.3 displacement 窗口
+
+第一版建议在 sweep 之后的有限窗口内寻找 displacement：
+
+- M1 / M5：后续 3~5 根 candle
+- M15 / H1：后续 2~4 根 candle
+- H4 及以上：后续 1~3 根 candle
+
+若窗口内没有有效 displacement：
+
+- sweep 仍可保留
+- 但验证等级不升为强 sweep
+
+## 7.4 链接方式
+
+若 sweep 已匹配 displacement，则建议记录：
+
+- `displacement_after = true`
+- `meta.displacement_event_id`
+- `meta.displacement_delay_bars`
+
+若未来正式建 `sweep_events` 表，也建议保留显式 `displacement_event_id` 字段。
+
+---
+
+## 8. 状态流转规则
+
+## 8.1 pool 状态
+
+pool 原始状态：
+
+- `untouched`
+- `swept`
+- `consumed`
+
+## 8.2 sweep 对 pool 的影响
+
+第一版建议：
+
+- 识别到有效 sweep 后，目标 pool 更新为 `swept`
+- 若后续结构继续完全消耗该区域，可进一步更新为 `consumed`
+
+## 8.3 sweep 自身状态建议
+
+若使用独立 `sweep_events` 存储，建议状态：
+
+- `candidate`
+- `weak`
+- `valid`
+- `confirmed`
+- `invalidated`
+- `archived`
+
+### 含义
+
+- `candidate`：仅发生初步 pool interaction
+- `weak`：发生 wick sweep，但不够强
+- `valid`：close back inside 成立
+- `confirmed`：已获得 displacement 或后续链路确认
+- `invalidated`：后续价格行为证明该 sweep 不再有参考意义
+- `archived`：历史保留
+
+## 8.4 最小状态机
+
+MVP 第一版若要降复杂度，至少支持：
+
+- `weak`
+- `valid`
+- `confirmed`
+
+并允许：
+
+```text
+weak -> valid -> confirmed
+weak -> invalidated
+valid -> invalidated
+confirmed -> archived
+```
+
+## 8.5 防重规则
+
+同一 pool 在未重置前，不应被重复生成多条同向主 sweep 事件。
+
+第一版建议：
+
+- 同一 `pool_id + direction_window` 只保留一条主 sweep
+- 若后续出现更高质量版本，可更新状态或新增更高版本并归档旧记录
+
+---
+
+## 9. 边界与异常情况
+
+## 9.1 只触及不刺穿
+
+若价格只触碰 pool 边缘但没有进入区间，不记 sweep。
+
+## 9.2 同时扫上下两侧
+
+极端大波动 candle 可能同时扫到上下两侧 pool。
+
+第一版处理：
+
+- 不在同一根 candle 上同时生成两个主 sweep
+- 标记为冲突场景
+- `meta.conflict = 'dual_side_sweep'`
+- 默认不作为高质量 sweep
+
+## 9.3 已被 swept 的 pool
+
+若 pool 已是 `swept` 状态，第一版默认不重复生成新的主 sweep。
+
+除非：
+
+- 明确发生新一轮结构重置
+- 或 pool 被重新生成了新 id
+
+## 9.4 数据缺口
+
+若 sweep 发生窗口存在明显缺失 candle：
+
+- 可记录 candidate
+- 但不升级为高质量 sweep
+- `meta.data_gap = true`
+
+## 9.5 假突破与延续突破
+
+若刺穿后持续单边离开 pool，且没有 close back inside：
+
+- 更偏向 breakout / continuation
+- 仍可记为弱 interaction
+- 默认不视为有效 sweep
+
+## 9.6 多个 timeframe 冲突
+
+若低周期识别 sweep，但高周期叙事不支持：
+
+- sweep 事件本身仍可记录
+- 是否进入 signal 链路交给 bias / structure 层过滤
+
+---
+
+## 10. 存储模型
+
+## 10.1 MVP 第一版建议
+
+虽然当前 schema 文档未正式定义 `sweep_events` 表，但 sweep 属于核心信号层，建议新增独立存储模型，而不是只塞进 JSON。
+
+建议新增 `sweep_events` 表，至少包含：
+
+- `instrument_id`
+- `timeframe`
+- `pool_id`
+- `side_swept`
+- `sweep_high`
+- `sweep_low`
+- `close_back_inside`
+- `validation_tier`
+- `status`
+- `ts`
+- `meta`
+- `created_at`
+- `updated_at`
+
+## 10.2 字段语义
+
+- `pool_id`：被扫 liquidity pool
+- `side_swept`：buy_side / sell_side
+- `sweep_high`：本次 sweep 涉及的最高价格
+- `sweep_low`：本次 sweep 涉及的最低价格
+- `close_back_inside`：是否收回结构内部
+- `validation_tier`：weak / valid / strong
+- `status`：事件当前状态
+- `ts`：首个成立 sweep 的 candle 时间
+
+## 10.3 meta 建议内容
+
+适合放入 `meta`：
+
+- `candidate_pool_ids`
+- `pool_type`
+- `close_outside`
+- `displacement_event_id`
+- `displacement_delay_bars`
+- `data_gap`
+- `conflict`
+- `selection_reason`
+- `recalc_batch_id`
+
+不应只放在 `meta`：
+
+- `pool_id`
+- `side_swept`
+- `close_back_inside`
+- `validation_tier`
+- `status`
+- `ts`
+
+## 10.4 若暂不建独立表
+
+若第一版暂时不能新增 `sweep_events` 表，可临时把 sweep 结果写入：
+
+- `trade_signals.evidence`
+- 或规则引擎中间结果存储
+
+但这只应作为过渡方案，不应作为长期主方案。
+
+---
+
+## 11. 处理流程建议
+
+## 11.1 基础识别流程
+
+1. 读取当前 timeframe 的 active liquidity pools
+2. 检查新 candle 是否与某个 pool 发生交互
+3. 判断是否进入/突破 pool 区间
+4. 记录 wick 行为与 close 行为
+5. 生成 candidate / weak / valid sweep
+6. 在后续窗口中检查 displacement
+7. 更新 validation tier 与 status
+8. 同步更新目标 pool 状态
+
+## 11.2 最小 MVP 实现
+
+建议先做：
+
+1. pool interaction 判定
+2. wick 与 close back inside 判定
+3. weak / valid 两层验证
+4. displacement_after 标记
+5. pool 状态从 untouched 到 swept 的更新
+
+再增强：
+
+- 独立 `sweep_events` 表
+- 更完整状态机
+- 多 pool 冲突管理
+- 与 MSS / FVG 的强绑定引用
+
+---
+
+## 12. 验证检查点
+
+## 12.1 功能验证
+
+- [ ] 能从已有 liquidity pool 中识别 sweep
+- [ ] 同一批输入重复运行结果一致
+- [ ] wick 行为与 close 行为能正确区分
+- [ ] displacement linkage 可正确标记
+
+## 12.2 规则验证
+
+- [ ] 没有 pool 不会生成正式 sweep
+- [ ] 只触碰不进入 pool 区间不会误判为 sweep
+- [ ] close back inside 成立时会升级验证等级
+- [ ] close outside 默认不会误判为高质量 sweep
+- [ ] pool 已 swept 时不会重复生成主 sweep
+
+## 12.3 状态验证
+
+- [ ] sweep 生成后 pool 状态可更新为 `swept`
+- [ ] 高质量 sweep 可升级为 confirmed
+- [ ] 无效后续行为可把 sweep 标记为 invalidated
+- [ ] 历史 sweep 可归档但不丢失
+
+## 12.4 存储验证
+
+- [ ] `pool_id` 能正确关联 liquidity pool
+- [ ] `side_swept` 与 pool.side 逻辑一致
+- [ ] `validation_tier` 与 `status` 可正确查询
+- [ ] `meta` 能记录 displacement 和异常信息
+
+## 12.5 人工抽样验证
+
+每个核心 timeframe 至少抽查：
+
+- 1 个扫 buy-side 的有效样例
+- 1 个扫 sell-side 的有效样例
+- 1 个 wick-only 弱 sweep 样例
+- 1 个 close back inside 的有效 sweep 样例
+- 1 个后续带 displacement 的强样例
+- 1 个假突破但非有效 sweep 的反例
+
+## 12.6 与路线图对齐的完成标准
+
+满足以下条件才算完成：
+
+- 能识别流动性刺穿
+- 能识别 close back inside
+- 能区分弱 sweep 与有效 sweep
+- 可作为 displacement / MSS / signal 的上游输入
+
+---
+
+## 13. MVP 范围内不做的事
+
+第一版暂不包含：
+
+- 基于订单流或逐笔成交的微观 sweep 识别
+- AI 自由叙事判定 sweep
+- 多市场 SMT 联动 sweep 作为核心条件
+- 同一事件跨多个 timeframe 自动合并
+- 复杂置信度模型打分
+
+---
+
+## 14. 推荐的最小实现顺序
+
+1. 先实现 pool interaction
+2. 再实现 wick / close back inside 判定
+3. 再实现 weak / valid 分层
+4. 再实现 displacement_after 标记
+5. 最后补 sweep 独立存储与完整状态机
+
+这样可以先满足阶段 3 的最小可用目标，再逐步增强。
\ No newline at end of file
diff --git a/docs/AI_ICT_Sweep_识别规格书_v1.md b/docs/AI_ICT_Sweep_识别规格书_v1.md
new file mode 100644
index 0000000..1103db1
--- /dev/null
+++ b/docs/AI_ICT_Sweep_识别规格书_v1.md
@@ -0,0 +1,479 @@
+# AI ICT Sweep 识别规格书 v1
+
+## 1. 文档目标
+
+本文档定义 AI ICT 项目第一阶段的 Sweep 识别规则，用于判断某一侧流动性池是否被价格清理，并为后续 displacement、MSS 和信号生成提供前置事件。
+
+Sweep 模块位于以下链路中：
+
+`Candles -> Sessions -> Swings -> Dealing Range -> Liquidity Pools -> Sweep -> Displacement -> MSS`
+
+本模块输出将直接影响：
+
+- buy-side / sell-side pool 是否已被处理
+- 先清理后递送的结构判断
+- 是否存在 reversal / continuation 的前置条件
+- Displacement 是否具备更高解释力
+- Signal 是否进入候选链路
+
+因此，Sweep 是“流动性事件层”的核心模块。
+
+---
+
+## 2. 模块职责
+
+### 2.1 本模块负责
+
+1. 检测价格是否刺穿某个 liquidity pool
+2. 区分 sweep 与普通接触 / 突破
+3. 记录被处理的是 buy-side 还是 sell-side liquidity
+4. 输出 weak / validated sweep 分层
+5. 写入 sweep 事件
+
+### 2.2 本模块不负责
+
+- Displacement 最终成立判定
+- MSS 成立判定
+- Daily Bias 判定
+- 目标优先级最终排序
+
+这些属于下游模块。
+
+---
+
+## 3. 输入与输出
+
+## 3.1 输入
+
+本模块依赖：
+
+- `candles`
+- `liquidity_pools`
+- timeframe
+- pool 当前 status
+
+至少需要：
+
+- candle high / low / close
+- pool side
+- pool type
+- pool price range
+- pool status
+
+---
+
+## 3.2 输出
+
+建议输出对象 `SweepEvent`，并最终写入 sweep 事件表或事件流。
+
+关键字段：
+
+- instrument_id
+- timeframe
+- side_swept
+- pool_id
+- sweep_high
+- sweep_low
+- sweep_ts
+- close_back_inside
+- displacement_after
+- validation_level
+- status
+- meta
+
+其中：
+
+- `side_swept`: `buy_side | sell_side`
+- `validation_level`: `weak | validated`
+- `status`: `active | confirmed | cancelled`
+
+---
+
+## 4. 基础定义
+
+## 4.1 Sweep
+
+Sweep 指价格对某个流动性池发生了明显处理行为，通常表现为：
+
+1. 价格刺穿 pool
+2. 价格未稳定站稳并继续同向递送
+3. 后续出现反向收回、位移或控制权切换迹象
+
+说明：
+
+- Sweep 不是“摸到就算”
+- Sweep 也不是“所有突破都算”
+- 它是一个需要结合后续表现解释的流动性事件
+
+---
+
+## 4.2 Buy-Side Sweep
+
+当价格向上刺穿 buy-side liquidity pool 时，称为 buy-side sweep。
+
+常见对象：
+
+- prior high
+- equal highs
+- session high
+
+---
+
+## 4.3 Sell-Side Sweep
+
+当价格向下刺穿 sell-side liquidity pool 时，称为 sell-side sweep。
+
+常见对象：
+
+- prior low
+- equal lows
+- session low
+
+---
+
+## 5. 识别逻辑
+
+## 5.1 基础刺穿条件
+
+若 candle 的价格范围与某个 pool 发生以下关系：
+
+### 对 buy-side pool
+- `candle.high > pool.price_high`
+
+### 对 sell-side pool
+- `candle.low < pool.price_low`
+
+则视为发生了池子刺穿候选事件。
+
+说明：
+
+- 这只是 sweep 候选，不代表 sweep 已成立
+
+---
+
+## 5.2 close back inside 条件
+
+第一阶段建议增加一个重要辅助判断：
+
+### buy-side pool 被处理后
+若后续 close 回到 pool 内或回落到 pool 下方，则增强 sweep 解释力。
+
+### sell-side pool 被处理后
+若后续 close 回到 pool 内或回升到 pool 上方，则增强 sweep 解释力。
+
+该信号可记录为：
+
+- `close_back_inside = true | false`
+
+---
+
+## 5.3 wick 与 close 的关系
+
+第一阶段建议：
+
+### wick-only 刺穿
+- 可先记为 `weak sweep candidate`
+
+### wick 刺穿 + close 收回
+- 更接近有效 sweep
+
+### close 同向站稳并继续扩张
+- 更接近真实 breakout，而不是 sweep
+
+因此：
+
+- 不能只看 wick
+- 也不能只看单根 close
+- 需要结合后续几根 candle 的行为
+
+---
+
+## 6. validation 分层
+
+第一阶段建议 Sweep 至少分两级：
+
+- weak
+- validated
+
+---
+
+## 6.1 weak sweep
+
+满足：
+
+1. pool 被刺穿
+2. 但尚未看到更强反向证据
+
+适用场景：
+
+- 先作为候选事件挂起
+- 等待 displacement 或后续结构确认
+
+---
+
+## 6.2 validated sweep
+
+满足：
+
+1. 已刺穿 pool
+2. 出现 close back inside 或明显回收
+3. 后续 N 根内出现反向 displacement 候选
+
+说明：
+
+- 第一阶段 validated sweep 不必直接等于反转
+- 它只代表“这个流动性事件的解释力更强”
+
+---
+
+## 7. breakout 与 sweep 的区分
+
+这是最重要的边界之一。
+
+## 7.1 更接近 breakout 的情况
+
+若出现以下特征：
+
+1. 价格刺穿 pool 后继续同向稳定推进
+2. close 连续站在 pool 外侧
+3. 没有明显回收或反向位移
+
+则应更倾向解释为 breakout，而不是 sweep。
+
+---
+
+## 7.2 更接近 sweep 的情况
+
+若出现以下特征：
+
+1. pool 被刺穿
+2. 价格快速回收
+3. 后续出现反向 displacement
+4. 原刺穿方向没有继续稳定扩张
+
+则更应解释为 sweep。
+
+---
+
+## 8. 时间窗口规则
+
+## 8.1 后续确认窗口
+
+Sweep 不是永远挂起等待。
+
+第一阶段建议为每个 sweep candidate 设置观察窗口：
+
+- 在刺穿后的 N 根 candle 内观察是否出现回收和反向证据
+
+若窗口结束仍没有强化证据：
+
+- 可保持 weak
+- 或降级为无效候选
+
+N 应配置化，按 timeframe 设置。
+
+---
+
+## 8.2 会话影响
+
+Session 信息可作为解释增强因子，但第一阶段不让 session 直接决定 sweep 成败。
+
+建议：
+
+- 先基于价格行为判 sweep
+- 再由下游 bias / context 模块结合 session 增强解释
+
+---
+
+## 9. Pool 状态联动
+
+Sweep 模块成立后，必须联动更新对应 pool 的状态。
+
+### 9.1 基础联动
+
+若 sweep 已确认：
+
+- 对应 pool `status -> swept`
+
+### 9.2 后续处理
+
+若下游确认该 pool 已不再具备主要参考价值：
+
+- 后续模块可将其更新为 `consumed`
+
+说明：
+
+- Sweep 模块只负责把 untouched 更新为 swept
+- consumed 更适合下游结构模块决定
+
+---
+
+## 10. 边界与异常处理
+
+## 10.1 一个 candle 同时触达多个 pool
+
+若单根 candle 同时刺穿多个 pool：
+
+- 允许生成多个 sweep candidate
+- 但必须通过 `pool_id` 区分来源
+- 不可合并成一个模糊事件
+
+---
+
+## 10.2 pool 已 swept
+
+若 pool 已经是 `swept`：
+
+- 默认不应重复生成同一主要 sweep 事件
+- 除非系统明确支持重复处理逻辑
+
+第一阶段建议：
+
+- 同一 pool 只保留首次主要 sweep
+
+---
+
+## 10.3 数据缺口
+
+若刺穿区间附近存在 candle 缺失：
+
+- 可生成候选事件
+- 但应在 `meta` 中标记数据不完整
+- 不建议直接升为 validated
+
+---
+
+## 10.4 未确认 pool
+
+若 pool 来源不稳定或 session 本身不完整：
+
+- 该 sweep 不应提升为高可信级别
+
+---
+
+## 11. 写入策略
+
+## 11.1 幂等要求
+
+同一 pool 在同一主要处理事件下：
+
+- 不应重复生成多个 identical sweep 记录
+
+建议幂等判定参考：
+
+- instrument_id
+- timeframe
+- pool_id
+- sweep_ts 所在主事件窗口
+
+---
+
+## 11.2 状态建议
+
+第一阶段 sweep 事件建议状态：
+
+- active
+- confirmed
+- cancelled
+
+含义：
+
+- active：候选事件已出现，等待进一步确认
+- confirmed：已达到 validated 标准
+- cancelled：后续走势表明不应继续保留为有效 sweep 事件
+
+---
+
+## 12. 下游依赖约定
+
+Sweep 输出将被下游这样使用：
+
+### Displacement
+- 判断反向位移是否具有前置清理背景
+
+### MSS
+- 判断结构切换前是否有流动性事件
+
+### Signal
+- 判断是否满足“先清理，后递送”的路径逻辑
+
+因此 Sweep 必须稳定输出：
+
+- 哪一侧被处理
+- 处理的是哪个 pool
+- 是否回收
+- 是否被验证
+
+---
+
+## 13. 推荐任务拆分
+
+### T1. pool 刺穿检测
+- candle 与 pool 的交互检测
+
+### T2. close back inside 检测
+- 记录回收行为
+
+### T3. validated 规则
+- 结合后续 displacement 候选
+
+### T4. pool 状态联动
+- untouched -> swept
+
+### T5. 幂等入库
+- 避免同一事件重复写入
+
+---
+
+## 14. 验证检查点
+
+## 14.1 最低验证
+
+至少验证：
+
+- [ ] buy-side pool 刺穿可生成 sweep candidate
+- [ ] sell-side pool 刺穿可生成 sweep candidate
+- [ ] close back inside 可正确记录
+- [ ] validated sweep 可生成
+
+---
+
+## 14.2 行为验证
+
+- [ ] wick-only 刺穿不会自动当作 confirmed sweep
+- [ ] 持续同向扩张不会被误判为 validated sweep
+- [ ] pool 状态会从 untouched 更新到 swept
+
+---
+
+## 14.3 人工抽查
+
+至少抽取样本图表检查：
+
+- [ ] buy-side sweep 标记合理
+- [ ] sell-side sweep 标记合理
+- [ ] breakout 与 sweep 未明显混淆
+- [ ] validated 逻辑与后续走势一致性较高
+
+---
+
+## 15. 完成标准
+
+只有满足以下全部条件，Sweep 模块才算完成：
+
+1. 能识别 buy-side / sell-side pool 刺穿
+2. 能区分 weak / validated
+3. 能记录 close back inside
+4. 能联动更新 pool 状态
+5. 能幂等写入 sweep 事件
+6. 可直接供 displacement / MSS 模块使用
+
+---
+
+## 16. 当前结论
+
+Sweep 模块是把“流动性目标”转换为“已发生处理事件”的桥梁层。
+
+如果 Liquidity Pool 是待处理目标集合，那么 Sweep 就是市场是否已经开始处理这些目标的事件表达。
+
+在真实开发中，它应被视为进入 displacement 和 MSS 前必须稳定完成的关键事件模块。
\ No newline at end of file
diff --git a/docs/AI_ICT_Swing_Identification_Spec_v1.md b/docs/AI_ICT_Swing_Identification_Spec_v1.md
new file mode 100644
index 0000000..40b45bf
--- /dev/null
+++ b/docs/AI_ICT_Swing_Identification_Spec_v1.md
@@ -0,0 +1,491 @@
+# AI ICT Swing Identification 规格说明 v1
+
+## 1. 文档目标
+
+本文档定义 swing identification 模块的识别规则、强度分层、确认时机、参数化方式、边界情况、落库结构与验证要求，用于指导 `swings` 表和相关规则引擎实现。
+
+目标：
+
+- 统一 swing high / swing low 判定口径
+- 建立 ST / IT / LT 强度层级
+- 明确 provisional / confirmed 确认时机
+- 支持按 timeframe 参数化
+- 为 dealing range、liquidity、MSS/MSB 提供稳定上游结构点
+
+适用范围：AI ICT 项目第一阶段 MVP。
+
+关联文档：
+
+1. `AI_ICT_总体设计文档_v1.md`
+2. `AI_ICT_PostgreSQL_Schema_v1.md`
+3. `AI_ICT_MVP_规则规格书_v1.md`
+4. `AI_ICT_开发路线图_v1.md`
+5. `AI_ICT_执行检查清单_v1.md`
+
+---
+
+## 2. 设计目标与边界
+
+### 2.1 目标
+
+swing identification 负责从标准化 candles 中提取结构高低点，作为后续 dealing range、liquidity pools、structure events 的基础输入。
+
+输出必须支持：
+
+- `swing_high`
+- `swing_low`
+- `ST / IT / LT` 强度分层
+- provisional / confirmed 状态
+- 多 timeframe 稳定重算
+
+### 2.2 不负责的内容
+
+第一版 swing 模块不负责：
+
+- 直接计算 dealing range
+- 直接判定 liquidity pool
+- 直接判定 MSB / MSS
+- 直接生成 trade signal
+
+这些能力依赖 swing 结果，但由后续模块单独实现。
+
+---
+
+## 3. 核心概念
+
+### 3.1 Swing High
+
+`swing_high` 指某一根 candle 的高点，相对于其左右观察窗口内的其他 candles，构成局部显著高点。
+
+### 3.2 Swing Low
+
+`swing_low` 指某一根 candle 的低点，相对于其左右观察窗口内的其他 candles，构成局部显著低点。
+
+### 3.3 Left / Right Bars
+
+- `left_bars`：候选 pivot 左侧参与比较的 bars 数量
+- `right_bars`：候选 pivot 右侧参与比较的 bars 数量
+
+### 3.4 Provisional / Confirmed
+
+- `provisional`：左侧条件满足，但右侧确认窗口尚未走完
+- `confirmed`：左右侧窗口都满足条件，pivot 已确认
+
+---
+
+## 4. 输入与输出
+
+### 4.1 输入
+
+最小输入：
+
+- `instrument_id`
+- `timeframe`
+- 标准化 `candles`
+- 当前 swing 参数配置
+- 待重算时间范围
+
+candles 最低要求字段：
+
+- `ts_open`
+- `high`
+- `low`
+- `close`
+
+### 4.2 输出
+
+输出到 `swings` 表，遵循既有 schema：
+
+- `instrument_id`
+- `timeframe`
+- `kind`
+- `strength`
+- `price`
+- `ts`
+- `left_bars`
+- `right_bars`
+- `confirmed`
+- `meta`
+
+---
+
+## 5. Pivot 判定规则
+
+### 5.1 基础判定窗口
+
+给定某根 candle `i`，若要判断它是否为 pivot：
+
+- 左侧比较范围：`i - left_bars` 到 `i - 1`
+- 右侧比较范围：`i + 1` 到 `i + right_bars`
+
+### 5.2 Swing High 判定
+
+第一版推荐规则：
+
+```text
+candle[i].high > max(left window highs)
+and
+candle[i].high >= max(right window highs)
+```
+
+即：
+
+- 对左侧使用严格大于
+- 对右侧使用大于等于
+
+这样做的目的：
+
+- 避免在左侧已有同价高点时重复生成 pivot
+- 在右侧出现相同高点时，优先保留更早出现的候选点
+
+### 5.3 Swing Low 判定
+
+第一版推荐规则：
+
+```text
+candle[i].low < min(left window lows)
+and
+candle[i].low <= min(right window lows)
+```
+
+即：
+
+- 对左侧使用严格小于
+- 对右侧使用小于等于
+
+### 5.4 使用 wick 还是 close
+
+第一版 swing 判定统一基于：
+
+- high pivot 使用 `high`
+- low pivot 使用 `low`
+
+不使用 close 来定义 swing 本身。
+
+原因：
+
+- swing 的本质是结构极值点
+- wick 对流动性与局部极值更敏感
+- close 更适合后续 displacement / MSS 过滤，而不是 swing 原始识别
+
+---
+
+## 6. ST / IT / LT 强度层级
+
+### 6.1 ST 定义
+
+`ST`（Short-Term）是最基础的局部 pivot。
+
+第一版默认：
+
+- 先识别全部 `ST` swings
+- 所有更高层级都建立在 `ST` 基础上
+
+### 6.2 IT 定义
+
+`IT`（Intermediate-Term）是对 `ST` 的再筛选。
+
+推荐规则：
+
+- 某个 `ST swing_high` 若高于其相邻的前后 `ST swing_high`，可升级为 `IT swing_high`
+- 某个 `ST swing_low` 若低于其相邻的前后 `ST swing_low`，可升级为 `IT swing_low`
+
+也就是：
+
+- `IT` 不是直接从 candles 识别
+- `IT` 从已确认的 `ST` 序列递归提取
+
+### 6.3 LT 定义
+
+`LT`（Long-Term）是对 `IT` 的再筛选。
+
+推荐规则：
+
+- 某个 `IT swing_high` 若高于其相邻的前后 `IT swing_high`，升级为 `LT swing_high`
+- 某个 `IT swing_low` 若低于其相邻的前后 `IT swing_low`，升级为 `LT swing_low`
+
+### 6.4 层级生成顺序
+
+统一采用：
+
+```text
+candles -> ST -> IT -> LT
+```
+
+不允许跳层直接从 candles 识别 LT。
+
+### 6.5 层级意义
+
+- `ST`：局部结构、短期波动、触发细节
+- `IT`：中层结构、主工作区间候选
+- `LT`：大级别结构、主 draw 与大范围边界参考
+
+---
+
+## 7. 确认时机
+
+### 7.1 ST 确认
+
+某个 ST pivot 只有在右侧 `right_bars` 数量的 candles 都已经存在后，才能标记 `confirmed = true`。
+
+因此：
+
+- 当前最新若干根 bars 附近的 pivot 只能是 provisional
+- 不能提前把未走完右窗的点当成 confirmed
+
+### 7.2 IT / LT 确认
+
+`IT` / `LT` 的确认建立在下一级 swing 已确认的前提上。
+
+即：
+
+- 未确认的 ST 不能用于确认 IT
+- 未确认的 IT 不能用于确认 LT
+
+### 7.3 实时与历史差异
+
+- 历史回算时，可一次性给出完整 confirmed 结果
+- 实时增量时，最新区域必须允许 provisional 存在
+- 后续新增 candles 到来后，允许 provisional 升级为 confirmed
+
+---
+
+## 8. Timeframe 参数化
+
+### 8.1 参数化原则
+
+不同 timeframe 的波动噪声不同，pivot 窗口必须参数化。
+
+建议按 timeframe 单独配置：
+
+- `st_left_bars`
+- `st_right_bars`
+- `it_neighbor_span`
+- `lt_neighbor_span`
+- `min_price_distance`（可选）
+- `min_bar_distance`（可选）
+
+### 8.2 第一版建议参数
+
+以下为建议默认值，后续可调：
+
+```text
+M1:  ST = 2/2
+M5:  ST = 2/2
+M15: ST = 3/3
+H1:  ST = 3/3
+H4:  ST = 4/4
+D1:  ST = 5/5
+```
+
+IT / LT 默认可先使用“前后各 1 个同级 swing 比较”的方式生成。
+
+### 8.3 噪声过滤参数
+
+第一版可选增加两类过滤：
+
+1. `min_bar_distance`
+   - 两个同向 swing 之间至少相隔若干 bars
+
+2. `min_price_distance`
+   - 两个同向 swing 之间至少相隔最小价格距离或最小 ATR 比例
+
+若未启用过滤，第一版仍可先按纯 pivot 规则运行。
+
+---
+
+## 9. 边界与异常情况
+
+### 9.1 数据不足
+
+若当前窗口不足以覆盖 `left_bars + right_bars + 1`：
+
+- 不生成 confirmed swing
+- 可选择不输出，或仅输出 provisional
+- 第一版更建议不输出，避免过早污染结构
+
+### 9.2 相等高点 / 相等低点
+
+当多个相邻 candles 出现相同 high 或 low：
+
+- 按 5.2 / 5.3 的不对称比较规则处理
+- 若仍无法唯一确定，优先保留更早出现的 candle
+- 同一价格平台不应生成多个完全重复的同级 swing
+
+### 9.3 外包 K 线
+
+若某一根 candle 同时包住左右多根 bars：
+
+- 只要满足 pivot 条件，仍允许成为 swing
+- 不因实体大小过大而自动剔除
+- 但可在 `meta` 中记录 bar range 异常信息
+
+### 9.4 极端噪声行情
+
+若短时间内产生大量相邻 swings：
+
+- 先按规则落地 ST
+- 通过 IT / LT 递归筛选降低噪声
+- 如仍过密，再启用 `min_bar_distance` / `min_price_distance`
+
+### 9.5 上游 candle 修复
+
+若 candles 历史数据被补齐、修正或重采样：
+
+- 必须触发对应 timeframe swing 重算
+- 不允许保留旧 swing 结果
+
+### 9.6 跨 timeframe 独立性
+
+不同 timeframe 的 swing 独立生成：
+
+- M15 swing 不直接映射为 H1 swing
+- 高 timeframe 必须基于该 timeframe 自己的 candles 计算
+
+---
+
+## 10. 存储模型
+
+### 10.1 `swings` 字段映射
+
+- `instrument_id`：所属交易品种
+- `timeframe`：对应时间框架
+- `kind`：`swing_high` / `swing_low`
+- `strength`：`ST` / `IT` / `LT`
+- `price`：pivot 价格；high 用 candle.high，low 用 candle.low
+- `ts`：pivot candle 的时间戳，建议使用 `ts_open`
+- `left_bars`：左窗参数
+- `right_bars`：右窗参数
+- `confirmed`：是否确认
+- `meta`：额外说明
+
+### 10.2 推荐 meta 内容
+
+建议在 `meta` 中记录：
+
+- `source_timeframe`
+- `pivot_index`
+- `calc_version`
+- `is_provisional`
+- `neighbor_refs`
+- `price_distance`
+- `bar_distance`
+- `rebuild_reason`
+
+### 10.3 唯一性建议
+
+第一版建议逻辑唯一键为：
+
+```text
+(instrument_id, timeframe, strength, kind, ts)
+```
+
+如暂不建数据库唯一约束，也应在写入层保证 upsert 口径一致。
+
+### 10.4 更新策略
+
+建议：
+
+- 历史 confirmed 区域使用幂等 upsert
+- 最新 provisional 区域允许被覆盖更新
+- 若同一 `ts` 的 provisional 后续转 confirmed，应更新而不是插入新记录
+
+---
+
+## 11. 生成流程规范
+
+### 11.1 历史全量重算
+
+流程：
+
+1. 读取指定 `instrument + timeframe + date range`
+2. 生成 ST 候选并确认
+3. 从 ST 提取 IT
+4. 从 IT 提取 LT
+5. 写入 `swings`
+6. 对结果做去重与顺序检查
+
+### 11.2 增量刷新
+
+流程：
+
+1. 只拉取受影响的最近窗口 candles
+2. 重算尾部 ST
+3. 级联刷新受影响的 IT / LT
+4. upsert 到 `swings`
+
+### 11.3 结果顺序要求
+
+同一 `instrument + timeframe + strength` 下：
+
+- swings 必须按时间可排序
+- 不要求 high / low 严格交替，但若连续同向 swing 过多，应能被后续过滤发现
+
+---
+
+## 12. 验证与验收要求
+
+### 12.1 功能验证
+
+至少验证：
+
+- 能按 timeframe 产出稳定 swing 列表
+- 同一份 candles 重复计算结果一致
+- 最新尾部区域能正确区分 provisional / confirmed
+- ST / IT / LT 之间数量呈递减关系
+
+### 12.2 数据验证
+
+至少验证：
+
+- `swing_high` 的价格等于对应 candle.high
+- `swing_low` 的价格等于对应 candle.low
+- `confirmed` 只在右侧窗口完成后出现
+- 不同 timeframe 结果互不污染
+
+### 12.3 人工抽查
+
+至少抽查：
+
+- 一个趋势行情样本
+- 一个震荡行情样本
+- 一个 equal highs / equal lows 附近样本
+- 一个最新尾部存在 provisional 的样本
+
+### 12.4 与下游一致性检查
+
+至少确认：
+
+- dealing range 可引用 swing 结果
+- liquidity pools 可从 prior highs / lows 提取候选
+- MSS / MSB 使用的参考 swing 与图表直觉一致
+
+---
+
+## 13. 推荐实现顺序
+
+建议按以下顺序实现：
+
+1. 完成 ST 基础 pivot 识别
+2. 完成 confirmed / provisional 状态管理
+3. 完成 ST 结果幂等落库
+4. 完成 IT 递归提取
+5. 完成 LT 递归提取
+6. 再补噪声过滤参数
+
+这样可以先保证下游有可用的基础结构点，再逐步增加层级复杂度。
+
+---
+
+## 14. 最终结论
+
+swing identification 是全部结构分析的基础层。
+
+第一版必须保证四件事：
+
+1. pivot 口径明确
+2. 确认时机严格
+3. 多层级生成可重复
+4. 写入结果可稳定重算
+
+只有这四点成立后，dealing range、liquidity pools、MSS/MSB 才有稳定可靠的结构基础。
diff --git a/docs/AI_ICT_Swing_识别规格书_v1.md b/docs/AI_ICT_Swing_识别规格书_v1.md
new file mode 100644
index 0000000..779b5b9
--- /dev/null
+++ b/docs/AI_ICT_Swing_识别规格书_v1.md
@@ -0,0 +1,494 @@
+# AI ICT Swing 识别规格书 v1
+
+## 1. 文档目标
+
+本文档定义 AI ICT 项目第一阶段的 Swing 识别规则，用于从标准化 candles 数据中提取结构高低点，为后续模块提供基础锚点。
+
+Swing 模块是以下链路中的关键基础层：
+
+`Candles -> Sessions -> Swings -> Dealing Range -> Liquidity -> MSS`
+
+下游直接依赖 Swing 的模块包括：
+
+- Dealing Range
+- Prior High / Prior Low
+- Equal Highs / Equal Lows
+- MSB / MSS
+- IRL / ERL 目标定位
+
+因此，Swing 模块必须首先做到：
+
+- 输出稳定
+- 参数明确
+- 多周期一致
+- 可验证、可回放
+
+---
+
+## 2. 模块职责
+
+Swing 模块只负责识别结构高低点，不负责解释结构意义。
+
+### 2.1 本模块负责
+
+1. 识别 swing high
+2. 识别 swing low
+3. 给出 confirmed / provisional 状态
+4. 给出 ST / IT / LT 强度层级
+5. 写入 `swings` 表
+
+### 2.2 本模块不负责
+
+- bias 判断
+- Dealing Range 计算
+- liquidity pool 生成
+- sweep 判定
+- MSS 判定
+
+这些都由下游模块处理。
+
+---
+
+## 3. 输入与输出
+
+## 3.1 输入
+
+输入来自 `candles` 表，至少包含：
+
+- instrument_id
+- timeframe
+- ts_open
+- ts_close
+- open
+- high
+- low
+- close
+
+说明：
+
+- Swing 模块按 timeframe 分开运行
+- 不同 timeframe 的 swing 不能混算
+
+---
+
+## 3.2 输出
+
+输出写入 `swings` 表，字段包括：
+
+- instrument_id
+- timeframe
+- kind
+- strength
+- price
+- ts
+- left_bars
+- right_bars
+- confirmed
+- meta
+
+其中：
+
+- `kind`: `swing_high | swing_low`
+- `strength`: `ST | IT | LT`
+
+---
+
+## 4. 基础定义
+
+## 4.1 swing high
+
+在指定窗口下，某根 candle 的高点高于左侧与右侧指定数量 candles 的高点，则该点可定义为 swing high。
+
+---
+
+## 4.2 swing low
+
+在指定窗口下，某根 candle 的低点低于左侧与右侧指定数量 candles 的低点，则该点可定义为 swing low。
+
+---
+
+## 4.3 confirmed swing
+
+只有当右侧确认 candles 足够后，swing 才可标记为 confirmed。
+
+这意味着：
+
+- swing 是滞后确认的
+- 最新几根 candle 附近的结构点通常只能先标 provisional
+
+---
+
+## 4.4 provisional swing
+
+若左侧条件已满足，但右侧确认尚未结束，则可以先生成 provisional swing，仅用于实时观察，不作为严格回测真值。
+
+---
+
+## 5. 参数化规则
+
+## 5.1 基本参数
+
+Swing 识别至少需要两个参数：
+
+- `left_bars`
+- `right_bars`
+
+定义：
+
+- `left_bars`: 左侧比较窗口
+- `right_bars`: 右侧确认窗口
+
+---
+
+## 5.2 第一阶段建议参数
+
+### M1 / M5
+- left_bars = 2
+- right_bars = 2
+
+### M15 / H1
+- left_bars = 3
+- right_bars = 3
+
+### H4 / D
+- left_bars = 3
+- right_bars = 3
+
+说明：
+
+- 这是 MVP 默认值，不是永久值
+- 后续可按品种波动差异调整
+- 第一阶段先固定，避免回测口径漂移
+
+---
+
+## 6. 判定逻辑
+
+## 6.1 swing high 判定逻辑
+
+对于第 i 根 candle：
+
+若满足：
+
+- `high[i] > high[i-1..i-left_bars]`
+- `high[i] > high[i+1..i+right_bars]`
+
+则判定为 swing high。
+
+### 等值情况处理
+
+若出现高点相等：
+
+- 第一阶段建议不直接视为 swing high
+- 优先交给 equal highs / liquidity 模块处理
+
+即：
+
+- 使用严格大于 `>`
+- 不使用大于等于 `>=`
+
+---
+
+## 6.2 swing low 判定逻辑
+
+对于第 i 根 candle：
+
+若满足：
+
+- `low[i] < low[i-1..i-left_bars]`
+- `low[i] < low[i+1..i+right_bars]`
+
+则判定为 swing low。
+
+### 等值情况处理
+
+若出现低点相等：
+
+- 第一阶段建议不直接视为 swing low
+- 优先交给 equal lows 模块处理
+
+即：
+
+- 使用严格小于 `<`
+- 不使用小于等于 `<=`
+
+---
+
+## 7. 强度分层规则
+
+Swing 不是只有一个层级，需要支持：
+
+- ST：short-term
+- IT：intermediate-term
+- LT：long-term
+
+---
+
+## 7.1 ST 定义
+
+ST 是基础层 swing，由窗口参数直接识别得到。
+
+第一阶段建议：
+
+- 所有原始识别结果默认先标为 ST
+
+---
+
+## 7.2 IT 定义
+
+IT swing 由 ST swing 再聚合识别得到。
+
+建议规则：
+
+- 若一个 ST swing high 高于其邻近 ST swing highs，则可提升为 IT swing high
+- 若一个 ST swing low 低于其邻近 ST swing lows，则可提升为 IT swing low
+
+说明：
+
+- IT 不直接从 candles 识别
+- IT 来自 ST 的二次结构提炼
+
+---
+
+## 7.3 LT 定义
+
+LT swing 由 IT swing 再聚合识别得到。
+
+建议规则：
+
+- 若一个 IT swing high 高于其邻近 IT swing highs，则可提升为 LT swing high
+- 若一个 IT swing low 低于其邻近 IT swing lows，则可提升为 LT swing low
+
+说明：
+
+- LT 用于高阶结构，不要求第一阶段就做到极致复杂
+- MVP 阶段可先实现 ST，IT/LT 可做简化版
+
+---
+
+## 8. 时间确认规则
+
+## 8.1 为什么 swing 必然滞后
+
+因为 swing 的成立依赖右侧 candles。
+
+所以：
+
+- 实时运行时，当前附近结构会持续变化
+- 回测时必须只用 confirmed swing
+- 不允许用未来数据提前宣布 swing 成立
+
+---
+
+## 8.2 实时模式建议
+
+实时运行时：
+
+- 可输出 provisional swing
+- 但必须显式标记 `confirmed=false`
+- 下游严格信号模块默认应只使用 confirmed swing
+
+---
+
+## 8.3 历史模式建议
+
+历史回测时：
+
+- 只写 confirmed swing
+- 不将 provisional swing 作为真值结果
+
+---
+
+## 9. 边界与异常处理
+
+## 9.1 序列开头与结尾
+
+在 candle 序列开头：
+
+- 左侧数据不足，不应判定 swing
+
+在 candle 序列末尾：
+
+- 右侧确认不足，可最多只标 provisional
+
+---
+
+## 9.2 数据缺口
+
+若窗口内存在缺失 candle：
+
+- 第一阶段建议不输出 confirmed swing
+- 或在 `meta` 中记录不完整窗口
+
+否则会误判局部高低点。
+
+---
+
+## 9.3 重复时间点
+
+若同一 `instrument_id + timeframe + ts_open` 出现重复：
+
+- 视为上游数据异常
+- Swing 模块不负责修复
+- 应拒绝本轮计算并记录错误
+
+---
+
+## 9.4 极端长影线
+
+第一阶段 swing 判定只基于 high / low，不单独过滤长影线。
+
+说明：
+
+- 长影线是否有流动性意义，是下游 liquidity / sweep 模块的职责
+- Swing 模块只负责结构锚点抽取
+
+---
+
+## 10. 写入策略
+
+## 10.1 幂等要求
+
+同一批数据重复计算时：
+
+- 不应生成重复 swing 记录
+- 已存在相同关键结果时应跳过或更新
+
+建议唯一逻辑键：
+
+- instrument_id
+- timeframe
+- kind
+- price
+- ts
+- strength
+
+第一阶段也可先用应用层幂等控制。
+
+---
+
+## 10.2 更新策略
+
+### 历史重算
+- 允许按 timeframe 全量重算
+- 再覆盖该时间窗口内旧结果
+
+### 增量运行
+- 仅重算最近一段窗口
+- 防止每次都全量扫描
+
+建议重算窗口至少覆盖：
+
+- `right_bars * 2 + 额外缓冲`
+
+---
+
+## 11. 下游依赖约定
+
+Swing 输出会被下游这样使用：
+
+### Dealing Range
+- 取最近有效 swing high / low 形成 range
+
+### Liquidity Pools
+- prior highs / lows
+- equal highs / lows 候选
+
+### Structure Events
+- MSB / MSS 破坏对象
+
+### Targets
+- IRL / ERL 候选目标
+
+因此要求：
+
+- ts 清晰
+- kind 清晰
+- strength 清晰
+- confirmed 清晰
+
+---
+
+## 12. 推荐任务拆分
+
+### T1. ST swing 识别
+- 按 timeframe 对 candles 扫描
+- 生成 provisional / confirmed swing
+
+### T2. Swing 入库
+- 写入 `swings`
+- 做幂等控制
+
+### T3. 增量重算窗口
+- 最近窗口重算逻辑
+
+### T4. IT / LT 提升逻辑
+- 从 ST -> IT
+- 从 IT -> LT
+
+### T5. 数据完整性防护
+- 缺口检测
+- 重复数据拒绝
+
+---
+
+## 13. 验证检查点
+
+## 13.1 最低验证
+
+至少验证：
+
+- [ ] M5 可生成 swing highs
+- [ ] M5 可生成 swing lows
+- [ ] M15 可生成 swing highs
+- [ ] M15 可生成 swing lows
+- [ ] confirmed / provisional 状态可区分
+
+---
+
+## 13.2 结构验证
+
+至少检查：
+
+- [ ] 相邻 swing 时间顺序正确
+- [ ] swing high 的 price 来自 candle high
+- [ ] swing low 的 price 来自 candle low
+- [ ] confirmed swing 不使用未来数据作弊
+
+---
+
+## 13.3 人工抽查
+
+至少随机抽取一段图表：
+
+- [ ] 样本内 swing high / low 与肉眼结构大致一致
+- [ ] 边界窗口未误报
+- [ ] 等高等低未被错误吞并
+
+---
+
+## 14. 完成标准
+
+只有满足以下全部条件，Swing 模块才算完成：
+
+1. 支持按 timeframe 识别 swing high / low
+2. 支持 confirmed / provisional 区分
+3. 支持 ST 基础层识别
+4. 支持幂等写入 `swings`
+5. 至少完成一轮样本人工抽查
+6. 可直接供 range 与 liquidity 模块使用
+
+---
+
+## 15. 当前结论
+
+Swing 模块不是简单找高点低点，而是整个结构语言的最底层锚点系统。
+
+如果这个模块不稳定，后续会同时影响：
+
+- dealing range
+- liquidity pool
+- MSB / MSS
+- targets
+
+因此在真实开发中，Swing 应与 Candles、Sessions 一起被视为第一批必须稳定的基础模块。
\ No newline at end of file
diff --git a/docs/AI_ICT_主线开发检查点_v1.md b/docs/AI_ICT_主线开发检查点_v1.md
new file mode 100644
index 0000000..f8c6c34
--- /dev/null
+++ b/docs/AI_ICT_主线开发检查点_v1.md
@@ -0,0 +1,455 @@
+# AI ICT 主线开发检查点 v1
+
+## 1. 文档目标
+
+本文档用于在本次会话结束时保存当前主线开发进度，确保下次登录后可以直接从主线继续推进，而不需要重新梳理上下文。
+
+---
+
+## 2. 当前主线状态
+
+当前主线已经从“纯方案/文档阶段”推进到“真实工程骨架 + 数据链 + 结构识别链 + 候选信号链 + 回测链”的阶段。
+
+可以把当前状态概括为：
+
+> 文档层已基本闭环，工程骨架已落地，数据库与模型层已落地，基础数据链、MVP 主模型识别链以及第一版回测链都已经开始成型并写入真实数据库。
+
+---
+
+## 3. 已完成的主线阶段
+
+### 3.1 文档与方案层
+
+以下文档已经落地到 `docs/`，并已本地检查：
+
+- 总体设计文档
+- PostgreSQL Schema 文档
+- MVP 规则规格书
+- 开发路线图
+- 执行检查清单
+- 项目启动清单
+- Migration 拆分计划
+- 第一批正式 Migration 文件草案
+- 第二批正式 Migration 文件草案
+- OKX 数据接入规格书
+- Session 生成器规格书
+- Swing 识别规格书
+- Dealing Range 规格书
+- Liquidity Pool 规格书
+- Sweep 识别规格书
+- Displacement 规格书
+- MSS 判定规格书
+- FVG 规格书
+- 文档索引与命名规范
+- 重复文档清理计划
+- 项目代码骨架规范
+- 自动化协作工作规程
+- 标准 CLAUDE.md 模板
+- 自动化协作迁移清单
+- 主线进度摘要
+
+结论：
+- 文档层已经足够支撑继续写代码
+- 当前后续不应再以扩写文档为主线
+
+---
+
+### 3.2 工程骨架层
+
+已落地：
+
+#### 根目录
+- `.env.example`
+- `pyproject.toml`
+- `README.md`
+
+#### 目录骨架
+- `src/`
+- `migrations/`
+- `seeds/`
+- `scripts/`
+- `tests/unit`
+- `tests/integration`
+- `tests/fixtures`
+
+#### 配置与 DB 基础
+- `src/config/settings.py`
+- `src/config/sessions.py`
+- `src/db/engine.py`
+- `src/db/base.py`
+- `src/db/session.py`
+- `src/main.py`
+
+结论：
+- 工程骨架已可继续扩展
+
+---
+
+### 3.3 数据库与模型层
+
+#### 第一批模型已落地
+- `venue.py`
+- `instrument.py`
+- `candle.py`
+- `market_session.py`
+- `swing.py`
+- `dealing_range.py`
+- `liquidity_pool.py`
+
+#### 第二批模型已落地
+- `displacement_event.py`
+- `structure_event.py`
+- `fvg_zone.py`
+- `bias_snapshot.py`
+- `trade_signal.py`
+- `trade_execution.py`
+- `backtest_run.py`
+- `backtest_result.py`
+- `sweep_event.py`
+
+#### 模型聚合导出
+- `src/models/__init__.py`
+
+#### 第一批 migration 已落地
+- `001_create_venues.sql`
+- `002_create_instruments.sql`
+- `003_create_candles.sql`
+- `004_create_candles_partitions_and_indexes.sql`
+- `005_create_market_sessions.sql`
+- `006_create_swings.sql`
+- `007_create_dealing_ranges.sql`
+- `008_create_liquidity_pools.sql`
+- `009_seed_venues.sql`
+- `010_seed_instruments.sql`
+
+#### 第二批 migration 已落地
+- `011_create_displacement_events.sql`
+- `012_create_structure_events.sql`
+- `013_create_fvg_zones.sql`
+- `014_create_bias_snapshots.sql`
+- `015_create_trade_signals.sql`
+- `016_create_trade_executions.sql`
+- `017_create_backtest_runs.sql`
+- `018_create_backtest_results.sql`
+- `019_create_sweep_events.sql`
+
+#### 远程数据库状态
+- 远程 PostgreSQL 专用库：`ai_ict`
+- 库已创建并成功执行 migrations
+- 当前用户 `yuqei` 已有业务库使用权限
+
+结论：
+- 数据库结构设计和第一版 migration 文件已基本闭环
+- 真实远程库已经落地，不再只是本地文档状态
+
+---
+
+### 3.4 基础设施状态
+
+#### 远程主机 `192.168.3.90`
+- PostgreSQL: 已可用
+- MinIO: 已安装并 active
+- Docker: 已确认可用，`docker --version` 正常，`systemctl is-active docker` = active
+- Podman: 也可用，但不再是主路径阻塞
+
+结论：
+- 远程基础设施当前不再是主线阻塞点
+
+---
+
+## 4. 当前已经真实跑通到“代码链”的主线模块
+
+### 4.1 OKX 数据入口
+
+已落地：
+- `src/services/market_data/okx_client.py`
+- `src/services/market_data/normalizer.py`
+- `src/services/market_data/__init__.py`
+- `scripts/run_okx_backfill.py`
+
+能力：
+- 从 OKX 拉取原始 candles
+- 标准化为内部 candle 对象
+- 支持当前代理环境下可用的请求路径
+
+---
+
+### 4.2 Candles 写入链
+
+已落地：
+- `src/repositories/candle_repository.py`
+- `src/repositories/__init__.py`
+
+能力：
+- 把 normalized candles upsert 进 `candles`
+- 具备幂等写入路径
+
+---
+
+### 4.3 Session 生成链
+
+已落地：
+- `src/repositories/market_session_repository.py`
+- `src/services/sessions/session_generator.py`
+- `src/services/sessions/__init__.py`
+- `scripts/run_session_generator.py`
+
+能力：
+- 从 `candles` 读取指定时间窗口
+- 生成 session 窗口
+- 聚合 `high / low / midpoint`
+- upsert 写入 `market_sessions`
+
+---
+
+### 4.4 Swing 识别链
+
+已落地：
+- `src/repositories/swing_repository.py`
+- `src/services/swings/swing_service.py`
+- `src/services/swings/__init__.py`
+- `scripts/run_swings.py`
+
+能力：
+- 从 `candles` 读取
+- 检测 ST swings
+- 写入 `swings`
+
+当前限制：
+- 只做了 ST 第一版
+- 尚未做 IT / LT
+
+---
+
+### 4.5 Dealing Range 链
+
+已落地：
+- `src/repositories/dealing_range_repository.py`
+- `src/services/ranges/dealing_range_service.py`
+- `src/services/ranges/__init__.py`
+- `scripts/run_ranges.py`
+
+能力：
+- 从 `swings` 读取
+- 生成 active range
+- 计算 equilibrium
+- 写入 `dealing_ranges`
+
+---
+
+### 4.6 Liquidity Pool 链
+
+已落地：
+- `src/repositories/liquidity_pool_repository.py`
+- `src/services/liquidity/liquidity_pool_service.py`
+- `src/services/liquidity/__init__.py`
+- `scripts/run_liquidity.py`
+
+能力：
+- 从 `swings` 读取 prior high / low
+- 从 `market_sessions` 读取 session high / low
+- 写入 `liquidity_pools`
+
+当前限制：
+- `equal highs / lows` 增强仍未真正落地成功
+- 当前该点仍是待继续推进的结构质量改进项
+
+---
+
+### 4.7 Sweep 链
+
+已落地：
+- `src/repositories/sweep_repository.py`
+- `src/services/sweeps/sweep_service.py`
+- `src/services/sweeps/__init__.py`
+- `scripts/run_sweeps.py`
+
+能力：
+- 从 `liquidity_pools` + `candles` 读取
+- 检测 sweep
+- 写入 `sweep_events`
+- 更新 liquidity pool 状态
+
+---
+
+### 4.8 Displacement 链
+
+已落地：
+- `src/repositories/displacement_repository.py`
+- `src/services/displacement/displacement_service.py`
+- `src/services/displacement/__init__.py`
+- `scripts/run_displacement.py`
+
+能力：
+- 从 `candles` 读取
+- 计算 body_ratio
+- 检测方向性 displacement
+- 写入 `displacement_events`
+
+---
+
+### 4.9 MSS 链
+
+已落地：
+- `src/repositories/structure_repository.py`
+- `src/services/structure/mss_service.py`
+- `src/services/structure/__init__.py`
+- `scripts/run_mss.py`
+
+能力：
+- 从 `swings` + `displacement_events` 读取
+- 生成 MSS 候选
+- 写入 `structure_events`
+
+---
+
+### 4.10 FVG 链
+
+已落地：
+- `src/repositories/fvg_repository.py`
+- `src/services/fvg/fvg_service.py`
+- `src/services/fvg/__init__.py`
+- `scripts/run_fvg.py`
+
+能力：
+- 从 `candles` 识别 bullish / bearish FVG
+- 关联 displacement
+- 写入 `fvg_zones`
+- 已新增：`fill_pct / status` 动态更新能力
+- 已验证：数据库中已有 `open / touched / mitigated` 状态分布
+
+---
+
+### 4.11 Bias + Signal 组合层
+
+已落地：
+- `src/repositories/bias_repository.py`
+- `src/repositories/signal_repository.py`
+- `src/services/bias/bias_service.py`
+- `src/services/bias/__init__.py`
+- `src/services/signals/signal_service.py`
+- `src/services/signals/__init__.py`
+- `scripts/run_signals.py`
+
+能力：
+- 从 `dealing_ranges` + `structure_events` 读取生成 bias snapshot
+- 从 `bias + FVG + MSS` 组合生成 signal 候选
+- 写入 `bias_snapshots` 与 `trade_signals`
+
+当前限制：
+- session filter 已进入 backtest，但 signal 本身仍可继续增强
+
+---
+
+### 4.12 Backtest 链
+
+已落地：
+- `src/repositories/backtest_repository.py`
+- `src/services/backtest/backtest_service.py`
+- `src/services/backtest/__init__.py`
+- `scripts/run_backtest.py`
+
+能力：
+- 从 `trade_signals` 读取候选信号
+- 从后续 `candles` 读取未来样本
+- 先判断 entry 是否触发
+- 再判断 stop / TP 结果
+- 已引入：同根 K 线 `stop_first` 规则
+- 已引入：session 覆盖检查
+- 写入 `backtest_runs` 与 `backtest_results`
+
+结论：
+- 回测已从“静态 RR 打标签”升级到“基于真实后续 candles 的更真实结果评估”
+
+---
+
+## 5. 当前数据库中的真实结果概况
+
+当前核心结果量级：
+
+- candles: 400
+- market_sessions: 5
+- swings: 78
+- dealing_ranges: 2
+- liquidity_pools: 47
+- sweep_events: 53
+- displacement_events: 113
+- structure_events: 3
+- fvg_zones: 149
+- bias_snapshots: 3
+- trade_signals: 3
+- backtest_runs: 10
+- backtest_results: 25
+
+说明：
+- 真实样本、结构、信号、回测结果都已开始累积
+
+---
+
+## 6. 当前主线已经形成的真实链路
+
+到本次检查点为止，已经形成如下主线：
+
+`OKX -> candles -> market_sessions -> swings -> dealing_ranges -> liquidity_pools -> sweep_events -> displacement_events -> MSS -> FVG -> bias_snapshots -> trade_signals -> backtest_runs -> backtest_results`
+
+这意味着：
+- 基础数据层已启动
+- 基础结构层已启动
+- 事件识别链已启动
+- 候选信号层已启动
+- 回测层已启动
+
+项目已经不再停留在“方案和文档”阶段。
+
+---
+
+## 7. 当前仍未完成但建议继续走主线的模块
+
+### 第一优先级：继续提升回测真实性
+建议继续增强：
+1. 更精细的 entry 触发判定
+2. stop / TP 命中顺序更严格的时间语义
+3. 更细化 invalidation 逻辑
+4. session filter 与 signal 层进一步联动
+
+### 第二优先级：继续提升结构质量
+建议继续增强：
+1. equal highs / lows
+2. 更精细 liquidity merge / 去重
+3. MSS acceptance
+4. FVG mitigation 更完整联动到 signal
+
+### 第三优先级：扩大样本
+建议继续：
+1. 进一步扩大 OKX 历史样本
+2. 继续多 timeframe 累积
+3. 提高 signal / backtest 的统计意义
+
+---
+
+## 8. 下次继续时建议的第一句话
+
+下次进入项目时，可以直接这样说：
+
+```text
+继续按主线开发，从 docs/AI_ICT_主线开发检查点_v1.md 继续，不要重做已完成模块。优先继续提升回测真实性，并补齐 equal highs / lows 这一结构质量增强点。
+```
+
+---
+
+## 9. 当前结论
+
+本次主线已经从：
+- 文档阶段
+- 工程骨架阶段
+- 数据库准备阶段
+
+推进到：
+- 基础数据链已落地
+- 基础结构识别链已落地
+- 候选信号链已落地
+- 回测链已落地并持续增强
+
+下次会话最合理的继续方向不是重搭骨架，也不是再扩文档，而是：
+
+> 继续增强回测真实性 + 继续补结构质量中的 equal highs / lows 等待落地点。
diff --git a/docs/AI_ICT_主线进度摘要_v1.md b/docs/AI_ICT_主线进度摘要_v1.md
new file mode 100644
index 0000000..50ef261
--- /dev/null
+++ b/docs/AI_ICT_主线进度摘要_v1.md
@@ -0,0 +1,66 @@
+# AI ICT 主线进度摘要 v1
+
+## 当前数据库核心行数
+
+- candles: 400
+- market_sessions: 5
+- swings: 78
+- dealing_ranges: 2
+- liquidity_pools: 47
+- sweep_events: 37
+- displacement_events: 113
+- structure_events: 3
+- fvg_zones: 100
+- bias_snapshots: 3
+- trade_signals: 3
+- backtest_runs: 5
+- backtest_results: 10
+
+## 当前已经形成的真实主线
+
+OKX -> candles -> market_sessions -> swings -> dealing_ranges -> liquidity_pools -> sweep_events -> displacement_events -> MSS -> FVG -> bias -> signals -> backtest
+
+## 当前已经验证完成的阶段
+
+1. 远程 PostgreSQL 专用库 ai_ict 已建立并完成迁移
+2. OKX 数据已成功写入真实数据库
+3. Session / Swing / Range / Liquidity 链已跑通
+4. Sweep / Displacement / MSS / FVG 事件链已跑通
+5. Bias / Signal 组合层已跑通
+6. Backtest 已开始基于真实后续 candles 产出结果
+
+## 当前仍需继续增强的质量点
+
+1. backtest 中同根 K 线 stop / TP 优先级规则已采用保守 `stop_first`，并已补充歧义标记与单元测试
+2. session filter 已进入 backtest meta 与 signal 生成层
+3. larger backfill 样本进一步扩大
+4. equal highs / lows 第一版已接入 liquidity pool，后续继续做更精细 liquidity merge / 去重
+5. MSS acceptance 与 FVG mitigation 逻辑进一步细化
+
+## 本轮代码推进记录
+
+已完成：
+
+1. 抽出 `evaluate_signal_outcome` 纯函数，便于无数据库单测
+2. 修正 `invalidated_before_entry`，避免把入场后止损误写成入场前失效
+3. 对同根 K 线 entry / stop / TP 歧义写入 `same_candle_ambiguous` 与 `same_candle_entry_exit_ambiguous`
+4. backtest result meta 写入 `session_codes` 与 `session_filter`
+5. signal 生成时读取当前 session，允许 LONDON / NY_AM / NY_PM，降级 ASIA / NY_LUNCH / OFF_HOURS
+6. equal highs / equal lows 按 swing 价格聚类生成 liquidity pool
+7. 新增 backtest、signal session filter、liquidity equal pool 单元测试
+
+## 本轮需求规划审查结论
+
+原规划的总体方向合理：先数据、再规则、再信号、再回测、再执行，符合交易系统从可验证到可执行的工程顺序。
+
+需要修正的地方：
+
+1. `开发路线图` 的下一步仍描述为项目起步任务，与当前代码已经跑到 backtest 层不一致
+2. `MVP 规则规格书` 对回测同根 K 线、入场前失效、session 元数据追溯的定义不够细
+3. `执行检查清单` 中多个已落地阶段仍保持未勾选状态，容易误导后续开发回头重做
+4. 自动化开发边界需要保持清晰：可以自动推进文档、规则、回测、paper trading，但真实下单仍必须保留显式确认
+
+## 当前主线结论
+
+系统已经从“能生成结构”推进到“能生成信号并写入回测结果”。
+下一阶段主线重点不是再扩文档，而是继续提高回测真实性与结果稳定性，然后再推进 signal/session 联动和结构质量增强。
diff --git a/docs/AI_ICT_开发路线图_v1.md b/docs/AI_ICT_开发路线图_v1.md
new file mode 100644
index 0000000..cd0be5f
--- /dev/null
+++ b/docs/AI_ICT_开发路线图_v1.md
@@ -0,0 +1,592 @@
+# AI ICT 开发路线图 v1
+
+## 1. 文档目标
+
+本文档把已有三份设计文档落地成可执行开发路线，明确模块顺序、阶段目标、交付物、验证点和推进节奏。
+
+关联文档：
+
+1. `AI_ICT_总体设计文档_v1.md`
+2. `AI_ICT_PostgreSQL_Schema_v1.md`
+3. `AI_ICT_MVP_规则规格书_v1.md`
+
+本路线图遵循一个原则：
+
+> 先打牢基础数据和规则底座，再做信号、回测、执行和 AI 报告。
+
+---
+
+## 2. 总体阶段划分
+
+项目按 7 个阶段推进：
+
+1. 项目基础设施初始化
+2. 基础数据层
+3. 基础规则层
+4. 核心信号层
+5. 回测与验证层
+6. 半自动执行层
+7. AI 报告与复盘层
+
+每一阶段都必须满足“可验证完成”后再进入下一阶段。
+
+---
+
+## 3. 阶段 0：项目基础设施初始化
+
+## 3.1 目标
+
+建立后续开发所需的项目骨架、目录结构和工程规范。
+
+## 3.2 交付物
+
+- 项目目录结构
+- 环境变量模板
+- PostgreSQL 连接配置
+- 基础日志模块
+- 基础配置模块
+- 枚举与常量定义
+- 时间框架与 session 配置表
+
+## 3.3 建议目录
+
+```text
+src/
+  config/
+  db/
+  models/
+  services/
+    market-data/
+    rule-engine/
+    signal/
+    execution/
+    report/
+  rules/
+    swings/
+    ranges/
+    liquidity/
+    structure/
+    fvg/
+  backtest/
+  risk/
+  utils/
+  api/
+
+docs/
+```
+
+## 3.4 完成标准
+
+- 本地项目可启动
+- 配置可加载
+- PostgreSQL 可连接
+- 基础日志可输出
+
+## 3.5 验证点
+
+- 配置加载测试通过
+- 数据库连接测试通过
+- 项目空服务可正常启动
+
+---
+
+## 4. 阶段 1：基础数据层
+
+这是全项目最优先阶段。
+
+## 4.1 目标
+
+建立统一、稳定、可回放的市场数据底座。
+
+## 4.2 模块
+
+### M1.1 instruments / venues 基础字典
+
+实现：
+
+- venues 表初始化
+- instruments 表初始化
+- BTC / ETH / XAU 基础配置
+- tick_size / lot_size / price_scale 配置
+
+完成标准：
+
+- 交易品种元信息可查询
+- 不同交易所品种映射清晰
+
+### M1.2 candles 入库
+
+实现：
+
+- OKX 行情接入
+- LMAX 行情接入预留接口
+- K 线标准化
+- candles 表写入
+- 去重与唯一约束
+
+完成标准：
+
+- 能按 symbol/timeframe 持续入库
+- 数据不重复
+- 时间戳一致
+
+### M1.3 market_sessions 生成器
+
+实现：
+
+- ASIA / LONDON / NY_AM / NY_LUNCH / NY_PM 会话切分
+- 计算 session high / low / midpoint
+- 会话状态更新
+
+完成标准：
+
+- 每个交易日可生成完整 session 数据
+- 会话 pivot 可查询
+
+## 4.3 阶段交付物
+
+- `venues`
+- `instruments`
+- `candles`
+- `market_sessions`
+- 数据采集任务
+
+## 4.4 验证点
+
+- 能查询最近 N 天指定品种 K 线
+- 能查询某天各 session high/low
+- candles 唯一键无冲突
+- session 结果与参考图人工抽查一致
+
+---
+
+## 5. 阶段 2：基础规则层
+
+## 5.1 目标
+
+实现后续全部信号依赖的基础结构规则。
+
+## 5.2 模块
+
+### M2.1 swings
+
+实现：
+
+- swing high / swing low 识别
+- ST / IT / LT 强度分层
+- provisional / confirmed 区分
+
+完成标准：
+
+- 能按 timeframe 产出稳定 swing 列表
+- 与图表人工抽样比对合理
+
+### M2.2 dealing_ranges
+
+实现：
+
+- 主工作区间识别
+- equilibrium 计算
+- premium / discount / equilibrium 位置判定
+
+完成标准：
+
+- 当前主 range 可查询
+- 可输出当前价格所处分区
+
+### M2.3 liquidity_pools
+
+实现：
+
+- prior high / prior low
+- equal highs / equal lows
+- session highs / lows
+
+完成标准：
+
+- pool 可结构化落库
+- 状态可更新：untouched / swept / consumed
+
+## 5.3 阶段交付物
+
+- `swings`
+- `dealing_ranges`
+- `liquidity_pools`
+- 基础规则重算接口
+
+## 5.4 验证点
+
+- 随机抽取样本图表进行人工比对
+- 同一 timeframe 规则结果可重复生成
+- 当前价格位置判断稳定
+
+---
+
+## 6. 阶段 3：核心信号层
+
+## 6.1 目标
+
+实现 MVP 主模型所需的核心触发规则。
+
+## 6.2 模块
+
+### M3.1 sweep_events
+
+实现：
+
+- 流动性刺穿
+- close back inside
+- 弱 sweep / 有效 sweep 区分
+
+### M3.2 displacement_events
+
+实现：
+
+- 大实体 / 推进性 / 脱离平衡 / FVG 联动判定
+- displacement 强度打分
+
+### M3.3 structure_events
+
+实现：
+
+- MSB
+- MSS
+- accepted / rejected 状态
+
+### M3.4 fvg_zones
+
+实现：
+
+- bullish / bearish FVG
+- fill_pct
+- touched / mitigated / invalidated 状态
+
+### M3.5 bias_snapshots
+
+实现：
+
+- higher timeframe bias 生成
+- confidence
+- execution_intensity
+- reason_codes
+
+### M3.6 trade_signals
+
+实现：
+
+- `SWEEP_MSS_FVG` 信号组装
+- invalidations
+- RR 校验
+- 状态机流转
+
+## 6.3 阶段交付物
+
+- `sweep_events`
+- `displacement_events`
+- `structure_events`
+- `fvg_zones`
+- `bias_snapshots`
+- `trade_signals`
+
+## 6.4 验证点
+
+- 能自动生成候选信号
+- 候选信号有明确 evidence
+- 无效信号会被 RR / session / bias 过滤
+- 随机抽取样本图核对规则链路完整性
+
+---
+
+## 7. 阶段 4：回测与验证层
+
+## 7.1 目标
+
+验证规则是否具备统计价值，并识别失真来源。
+
+## 7.2 模块
+
+### M4.1 backtest_runs
+
+实现：
+
+- 指定模型、品种、周期范围启动回测
+- 固定配置快照
+
+### M4.2 backtest_results
+
+实现：
+
+- 单信号 outcome
+- mfe / mae
+- tp1_hit / tp2_hit
+- invalidated_before_entry
+- error_tags
+
+### M4.3 统计分析
+
+实现：
+
+- 按 symbol/session/weekday/timeframe 分组
+- 统计 win rate / RR / drawdown / expectancy
+
+## 7.3 阶段交付物
+
+- `backtest_runs`
+- `backtest_results`
+- 回测汇总报告
+
+## 7.4 验证点
+
+- 回测可重复执行
+- 同配置回测结果一致
+- 可明确识别高质量/低质量场景
+
+---
+
+## 8. 阶段 5：半自动执行层
+
+## 8.1 目标
+
+在风控前提下，把信号转为可确认执行的订单流程。
+
+## 8.2 模块
+
+### M5.1 risk engine
+
+实现：
+
+- 单笔风险检查
+- 日亏损阈值
+- 连亏停机
+- session 限制
+- 新闻时间窗限制
+- 同方向暴露控制
+
+### M5.2 paper trading
+
+实现：
+
+- 模拟下单
+- 模拟止损止盈
+- 模拟部分止盈
+
+### M5.3 semi-auto execution
+
+实现：
+
+- 用户确认后下单
+- 订单状态跟踪
+- TP1 / TP2 管理
+- 强制失效平仓
+
+## 8.3 阶段交付物
+
+- `trade_executions`
+- 风控决策模块
+- 模拟盘执行模块
+- 半自动执行接口
+
+## 8.4 验证点
+
+- 无 stop 的信号无法进入执行
+- 非允许会话不能开新仓
+- 风控拒绝结果可审计
+- 模拟盘结果可复盘
+
+---
+
+## 9. 阶段 6：AI 报告与复盘层
+
+## 9.1 目标
+
+让 AI 站在规则之后做解释、总结和复盘。
+
+## 9.2 模块
+
+### M6.1 pre-market plan
+
+输出：
+
+- 当日 bias
+- 主 Draw
+- 当前 working range
+- 执行许可
+
+### M6.2 intraday explanation
+
+输出：
+
+- 当前 sweep / MSS / FVG 结构说明
+- 当前信号是否有效
+- 当前关键 invalidation
+
+### M6.3 post-trade review
+
+输出：
+
+- 本笔交易是否符合规则
+- 错误类型
+- 改进建议
+
+## 9.3 验证点
+
+- AI 输出只解释已有结构对象
+- 不产生脱离规则的裸信号
+- 同一结构输入下输出稳定
+
+---
+
+## 10. 推荐实施节奏
+
+## 10.1 第一优先序
+
+1. 阶段 0
+2. 阶段 1
+3. 阶段 2
+
+说明：
+
+- 阶段 1 和阶段 2 是所有后续模块共享前提
+- 若基础数据和基础规则不稳，后面的回测、信号、执行都会失真
+
+## 10.2 第二优先序
+
+4. 阶段 3
+5. 阶段 4
+
+说明：
+
+- 先有信号，再做系统性回测
+- 不建议跳过回测直接做真实执行
+
+## 10.3 第三优先序
+
+6. 阶段 5
+7. 阶段 6
+
+说明：
+
+- 先保证执行正确，再让 AI 做说明层增强
+
+---
+
+## 11. 每阶段建议产出物
+
+每阶段结束至少产出以下内容：
+
+1. 模块代码
+2. 最小验证脚本
+3. 数据样本截图或导出
+4. 阶段测试记录
+5. 已知限制说明
+
+---
+
+## 12. 开发中必须持续维护的清单
+
+## 12.1 配置清单
+
+- 品种配置
+- timeframe 配置
+- session 配置
+- 风险阈值配置
+- equal highs/lows 阈值配置
+
+## 12.2 验证清单
+
+- 数据唯一性
+- 时间戳一致性
+- session 切分准确性
+- rule engine 重跑一致性
+- 回测口径与实盘口径一致性
+
+## 12.3 风险清单
+
+- 交易所数据缺口
+- session 时区错配
+- swing 参数对不同品种不适配
+- sweep 与真实突破混淆
+- bias 过度主观化
+
+---
+
+## 13. 下一步落地建议
+
+截至当前代码状态，项目已经不再处于起步阶段。已形成的工程主线为：
+
+`OKX -> candles -> market_sessions -> swings -> dealing_ranges -> liquidity_pools -> sweep_events -> displacement_events -> MSS -> FVG -> bias_snapshots -> trade_signals -> backtest_runs -> backtest_results`
+
+因此后续开发不应再回到“建立骨架 / 初始化表”的任务，而应进入阶段 4 的质量加固，并为阶段 5 做受控准备。
+
+### Step 1：回测真实性加固
+
+优先完成：
+
+- 同根 K 线同时触发 entry / stop / TP 时，记录 `same_candle_ambiguous` 元数据
+- 修正 `invalidated_before_entry` 语义，只表示入场前已经失效，不混用为普通止损
+- 将 session 覆盖结果写入 backtest result meta，支持后续按 session 统计
+- 为回测核心判定补单元测试，避免后续规则增强时回归
+
+完成标准：
+
+- 回测结果能区分 `missed / loss / breakeven / win`
+- stop-first 保守假设可被配置快照追溯
+- 同一组 candles + signal 多次运行结果一致
+- 无未来 candles、未触发 entry、同根歧义均可通过 error_tags/meta 审计
+
+### Step 2：Signal 层 session 联动
+
+优先完成：
+
+- signal 生成时写入 `session_code`
+- 非允许 session 的候选信号不进入 `awaiting_confirmation`
+- 将 session filter 的拒绝原因写入 `invalidations` 或 `meta`
+
+完成标准：
+
+- `trade_signals.session_code` 不再长期为空
+- OFF_HOURS / NY_LUNCH 的新开仓信号会被降级或拒绝
+- backtest 与 signal 层使用一致的 session 口径
+
+### Step 3：结构质量增强
+
+优先完成：
+
+- equal highs / equal lows 阈值配置化
+- liquidity pool merge / 去重
+- MSS acceptance 规则细化
+- FVG mitigation 状态与 signal 有效性联动
+
+完成标准：
+
+- liquidity pools 中明显重复区域减少
+- MSS 不再仅依赖“破位 + displacement”的最简判定
+- 已 mitigated / invalidated FVG 不再生成新的候选信号
+
+### Step 4：样本扩大与统计报告
+
+优先完成：
+
+- 扩大 OKX backfill 时间范围
+- 增加多 timeframe 回测入口
+- 输出按 symbol / session / weekday / side 的汇总统计
+
+完成标准：
+
+- 单次回测样本数量具备统计意义
+- 能识别表现较好与较差的 session/方向/品种组合
+- 报告层只解释结构化结果，不直接创造交易建议
+
+---
+
+## 14. 当前结论
+
+本路线图的核心不是把任务列得更多，而是把推进顺序固定下来，并在代码已经越过起步阶段后及时切换重心：
+
+`基础设施 -> 数据 -> 基础规则 -> 核心信号 -> 回测 -> 执行 -> AI 报告`
+
+当前合理重心是：
+
+`回测真实性 -> signal/session 一致性 -> 结构质量 -> 样本统计 -> 受控执行`
+
+后续开发中，只要发现任务偏离这个顺序，应优先回到基础共享模块和可验证回测结果，避免过早进入复杂策略或真实自动化执行。
diff --git a/docs/AI_ICT_总体设计文档_v1.md b/docs/AI_ICT_总体设计文档_v1.md
new file mode 100644
index 0000000..b992eeb
--- /dev/null
+++ b/docs/AI_ICT_总体设计文档_v1.md
@@ -0,0 +1,516 @@
+# AI ICT 交易辅助系统总体设计文档 v1
+
+## 1. 文档目标
+
+本文档定义 AI ICT 交易辅助系统第一阶段的总体设计，目标是把 ICT 交易知识转化为可执行、可回测、可复盘、可风控的工程系统。
+
+第一阶段不追求全自动交易，而是优先构建：
+
+1. 统一市场数据底座
+2. ICT 规则识别引擎
+3. 结构化 Bias / Signal 生成
+4. 半自动执行与严格风控
+5. 可审计、可复盘的报告体系
+
+系统核心原则：
+
+- API 优先，不以桌面点击为主执行通道
+- 规则引擎主判定，AI 负责解释和总结
+- 先回测验证，再半自动，再考虑自动化
+- 所有交易建议都必须结构化、可审计
+
+---
+
+## 2. 数据库选型
+
+本项目选用 PostgreSQL，不选 Oracle。
+
+### 2.1 选择 PostgreSQL 的原因
+
+1. 更适合时间序列数据
+   - K 线、结构事件、信号快照天然适合 PostgreSQL
+   - 支持分区表、物化视图、窗口函数
+
+2. 更适合半结构化数据
+   - Narrative、evidence、回测标签、AI 报告摘要适合 `jsonb`
+
+3. 更适合策略研发迭代
+   - 交易研发阶段 schema 变化频繁
+   - PostgreSQL 迭代成本低，生态更灵活
+
+4. Python / 数据分析生态更友好
+   - 便于后续接入 Pandas、Polars、SQLAlchemy、Airflow / APScheduler 等
+
+### 2.2 Oracle 不作为当前主库的原因
+
+- 更适合重企业流程和传统核心业务
+- 对策略研发和事件型数据建模不如 PostgreSQL 灵活
+- 当前阶段会增加建模和调整成本
+
+结论：
+
+- 主库：PostgreSQL
+- Oracle：当前阶段不采用
+
+---
+
+## 3. 系统目标与边界
+
+## 3.1 第一阶段目标
+
+构建一个 AI ICT 交易辅助系统 MVP，支持：
+
+- BTC
+- ETH
+- XAU
+
+支持能力：
+
+- 行情采集
+- 会话划分
+- Swing / Range / Liquidity / Sweep / MSS / FVG 识别
+- Bias / Signal 生成
+- 回测与复盘
+- 半自动执行
+
+## 3.2 第一阶段不做
+
+- 不做自由发挥式 AI 主判单
+- 不做全自动实盘交易
+- 不以桌面自动点击作为主执行方式
+- 不把 SMT 作为核心独立入场信号
+- 不先做多模型自治系统
+
+---
+
+## 4. 总体架构
+
+```text
+[交易所 API]
+   |
+   v
+[行情采集层]
+   |
+   v
+[市场数据层]
+   |- candles
+   |- sessions
+   |- instrument metadata
+   |- market calendar
+   |
+   v
+[规则识别层]
+   |- swings
+   |- dealing ranges
+   |- session pivots
+   |- liquidity pools
+   |- sweep events
+   |- displacement
+   |- MSB/MSS
+   |- FVG/BPR
+   |
+   v
+[叙事/信号层]
+   |- daily bias
+   |- narrative snapshot
+   |- signal generation
+   |
+   v
+[执行与风控层]
+   |- paper trading
+   |- semi-auto execution
+   |- risk engine
+   |- audit log
+   |
+   v
+[报告与复盘层]
+   |- pre-market plan
+   |- intraday explanation
+   |- post-trade review
+   |- backtest analytics
+```
+
+---
+
+## 5. 模块划分
+
+### 5.1 market-data-service
+
+职责：
+
+- 拉取 OKX / LMAX 行情
+- 标准化 K 线
+- 生成 session 数据
+- 生成交易日边界
+- 入库 PostgreSQL
+
+输入：
+
+- OKX API
+- LMAX API
+
+输出：
+
+- candles
+- market_sessions
+- instruments metadata
+
+### 5.2 rule-engine-service
+
+职责：
+
+- 识别 swing
+- 识别 dealing range
+- 识别 session pivots
+- 识别 liquidity pools
+- 识别 sweep
+- 识别 displacement
+- 识别 MSB / MSS
+- 识别 FVG / BPR
+
+输出：
+
+- swings
+- dealing_ranges
+- liquidity_pools
+- sweep_events
+- displacement_events
+- structure_events
+- fvg_zones
+
+### 5.3 signal-service
+
+职责：
+
+- 汇总高低周期上下文
+- 计算 daily bias
+- 生成 narrative snapshot
+- 产生交易信号
+- 维护 signal 状态机
+
+输出：
+
+- bias_snapshots
+- trade_signals
+
+### 5.4 execution-service
+
+职责：
+
+- 模拟下单
+- 半自动下单
+- 止损止盈管理
+- 风控拦截
+- 审计日志
+
+输出：
+
+- trade_executions
+- risk decisions
+- audit records
+
+### 5.5 report-service
+
+职责：
+
+- 生成盘前计划
+- 生成盘中解释
+- 生成盘后复盘
+- 生成回测统计摘要
+- 向 LLM 提供结构化输入
+
+---
+
+## 6. 周期职责分层
+
+参考 ICT Top-Down 分层，执行原则为：下层优化执行，不越权改向。
+
+### 6.1 默认职责
+
+- D / H4：背景、方向、主叙事
+- H1 / M15：路径、工作区间、主 Draw
+- M5 / M1：触发、执行、风控
+
+### 6.2 MVP 默认配置
+
+#### BTC / ETH
+
+- bias_tf: H4
+- range_tf: H1
+- setup_tf: M15
+- trigger_tf: M5
+
+#### XAU
+
+- bias_tf: H1
+- range_tf: M15
+- setup_tf: M5
+- trigger_tf: M1
+
+---
+
+## 7. 会话模型设计
+
+结合参考指标文件，第一版采用以下默认会话，时区统一为 `America/New_York`。
+
+### 7.1 默认会话
+
+- ASIA: 20:00 - 00:00
+- LONDON: 02:00 - 05:00
+- NY_AM: 09:30 - 11:00
+- NY_LUNCH: 12:00 - 13:00
+- NY_PM: 13:30 - 16:00
+
+### 7.2 执行含义
+
+- ASIA：观察、构建范围、形成库存
+- LONDON：优先观察 sweep 与首段位移
+- NY_AM：延续或重构的高质量窗口
+- NY_LUNCH：默认降频、只做管理或等待
+- NY_PM：延续或重构的次高优先窗口
+
+### 7.3 会话模块输出
+
+- session high
+- session low
+- midpoint
+- mitigated status
+- broken status
+- execution permission
+
+---
+
+## 8. 规则优先级
+
+第一版只围绕一个主模型：
+
+`Sweep -> MSS -> FVG Retrace -> IRL/ERL`
+
+### 8.1 第一批必须实现的规则
+
+1. candles
+2. market sessions
+3. swings
+4. dealing ranges
+5. liquidity pools
+6. sweep events
+7. displacement
+8. MSB / MSS
+9. FVG
+10. bias snapshots
+11. trade signals
+
+### 8.2 暂缓实现的规则
+
+- Order Block 作为主触发
+- Breaker / Mitigation Block 深化建模
+- SMT 作为主信号
+- 跨市场复杂联动
+- 多模型并行自治
+
+---
+
+## 9. 信号生成主链路
+
+```text
+行情入库
+-> 生成会话数据
+-> 识别 swings
+-> 识别 dealing range
+-> 标注 liquidity pools
+-> 判断是否 sweep
+-> 判断 displacement
+-> 判断 MSB / MSS
+-> 识别 FVG
+-> 汇总 higher timeframe bias
+-> 生成 trade signal
+-> 人工确认
+-> 执行
+-> 记录结果
+```
+
+---
+
+## 10. Signal 状态机
+
+```text
+draft
+-> awaiting_context
+-> awaiting_confirmation
+-> active
+-> tp1_hit
+-> tp2_hit
+-> invalidated
+-> expired
+-> cancelled
+```
+
+说明：
+
+- draft：局部结构已出现，但条件未闭合
+- awaiting_context：缺高周期背景或 bias
+- awaiting_confirmation：上游条件成立，等待回补触发
+- active：已进场
+- tp1_hit：已达 IRL
+- tp2_hit：已达 ERL
+- invalidated：叙事被否定
+- expired：超时段未触发
+- cancelled：人工取消
+
+---
+
+## 11. 风控设计
+
+风控必须独立于 AI，不允许被聊天逻辑覆盖。
+
+### 11.1 账户级风控
+
+- 单笔风险 <= 0.25% 或 0.5%
+- 日亏损上限 <= 1.5% ~ 2%
+- 连续亏损达到阈值后停止
+- 同方向暴露受限
+- 同时持仓数量受限
+
+### 11.2 信号级风控
+
+- 无 stop 不下单
+- RR 不足不下单
+- 非允许会话不下单
+- bias neutral 默认不主动开仓
+- 重大新闻时间窗禁开新仓
+
+### 11.3 风控检查接口
+
+`risk_check(signal, account_state, market_state) -> allow / reject / downgrade`
+
+---
+
+## 12. AI 的职责边界
+
+AI 只负责：
+
+1. 解释规则结果
+2. 生成盘前计划
+3. 生成盘中说明
+4. 生成盘后复盘
+5. 总结错误模式
+
+AI 不负责：
+
+- 绕过规则直接下单
+- 覆盖风控决策
+- 以自由文本替代结构事件
+
+原则：
+
+- 规则引擎负责“判定”
+- AI 负责“说明”
+
+---
+
+## 13. 前端建议
+
+第一版建议一个轻量 Web 控制台，包含：
+
+1. Dashboard
+   - 当前 bias
+   - 当前 session
+   - 当前候选信号
+
+2. Context
+   - current dealing range
+   - session pivots
+   - liquidity pools
+   - sweeps
+   - MSS
+   - FVG
+
+3. Signals
+   - 全部候选信号
+   - 状态流转记录
+
+4. Execution
+   - 模拟 / 半自动下单
+   - 仓位与风控结果
+
+5. Backtest
+   - 模型结果统计
+   - 按 session / symbol / timeframe 分析
+
+6. Reports
+   - AI 报告
+   - 复盘记录
+
+---
+
+## 14. 里程碑计划
+
+### M1 基础数据
+
+- PostgreSQL schema 初始化
+- instrument 配置
+- candles 入库
+- session 生成器
+
+### M2 基础规则
+
+- swings
+- dealing ranges
+- session pivots
+- liquidity pools
+
+### M3 核心触发
+
+- sweep
+- displacement
+- MSB / MSS
+- FVG
+
+### M4 信号层
+
+- bias snapshots
+- trade signal 生成
+- 失效规则
+- TP1 / TP2
+
+### M5 验证层
+
+- 回测
+- MFE / MAE
+- error tags
+- 报告生成
+
+### M6 执行层
+
+- paper trading
+- semi-auto execution
+- 审计日志
+
+---
+
+## 15. 当前开发优先级
+
+按基础共享模块优先：
+
+1. candles
+2. market_sessions
+3. swings
+4. dealing_ranges
+5. liquidity_pools
+
+这些模块是后续全部规则和信号的前提，必须先稳定。
+
+---
+
+## 16. 当前结论
+
+第一阶段的核心不是“做一个会下单的 AI”，而是：
+
+> 把 ICT 交易认知变成结构化规则系统，并在 PostgreSQL 上建立可回测、可复盘、可审计的工程底座。
+
+后续所有开发都应以此文档为总参考，并优先保证：
+
+- 数据一致性
+- 规则可解释性
+- 风控刚性
+- 回测与实盘口径一致
diff --git a/docs/AI_ICT_执行检查清单_v1.md b/docs/AI_ICT_执行检查清单_v1.md
new file mode 100644
index 0000000..0a77e03
--- /dev/null
+++ b/docs/AI_ICT_执行检查清单_v1.md
@@ -0,0 +1,327 @@
+# AI ICT 执行检查清单 v1
+
+## 1. 文档目标
+
+本文档用于把 AI ICT 项目的每一阶段交付都转成可执行、可验证、可关闭的检查清单，避免任务处于“已启动但未推进”的悬挂状态。
+
+适用范围：
+
+- 总体设计落地
+- 数据库实现
+- 规则引擎实现
+- 信号生成
+- 回测验证
+- 半自动执行
+- AI 报告与复盘
+
+核心原则：
+
+1. 任务必须拆到可执行
+2. 启动后必须立即产出文件、代码或验证结果
+3. 只有“已写入 + 已检查”才算完成
+4. 不允许长期停留在 in_progress 而没有产物
+
+---
+
+## 2. 通用执行规则
+
+每个模块都必须经过以下 5 步：
+
+1. 明确输入
+2. 明确输出
+3. 完成最小实现
+4. 本地验证
+5. 记录结果并关闭任务
+
+若任一步无法继续，必须立即把阻塞点明确写成：
+
+- 缺少外部资源
+- 缺少配置
+- 需要产品决策
+- 需要真实账户/API 权限
+
+除了以上阻塞，不允许任务只挂起不推进。
+
+---
+
+## 3. 任务关闭标准
+
+一个任务只有满足以下条件才允许标记完成：
+
+### 3.1 文档类任务
+
+必须同时满足：
+
+- 文档已写入本地 `.md`
+- 路径已确认存在
+- 已读取前部内容检查格式正常
+- 文档标题、章节结构、核心内容完整
+
+### 3.2 代码类任务
+
+必须同时满足：
+
+- 代码已落地到目标文件
+- 相关模块能被导入或启动
+- 至少有一条本地验证结果
+- 修改内容与任务目标直接相关
+
+### 3.3 数据库类任务
+
+必须同时满足：
+
+- schema / migration 已落地
+- 字段、约束、索引已核查
+- 至少完成一次本地建表或 dry-run 验证
+- 与设计文档一致
+
+### 3.4 规则类任务
+
+必须同时满足：
+
+- 输入输出结构已实现
+- 至少有样本数据跑通
+- 至少人工抽查一个正例/反例
+- 可复用到回测流程
+
+---
+
+## 4. 阶段执行检查清单
+
+## 4.1 阶段 0：项目基础设施初始化
+
+### 检查项
+
+- [ ] 项目目录结构已建立
+- [ ] 配置模块已建立
+- [ ] 环境变量模板已建立
+- [ ] 日志模块已建立
+- [ ] PostgreSQL 连接模块已建立
+- [ ] 本地启动入口已建立
+
+### 完成标准
+
+- [ ] 本地服务可启动
+- [ ] 配置可加载
+- [ ] 数据库连接可验证
+
+### 验证记录
+
+- [ ] 启动命令已记录
+- [ ] 验证结果已记录
+
+---
+
+## 4.2 阶段 1：基础数据层
+
+### 检查项
+
+- [ ] `venues` 表已建立
+- [ ] `instruments` 表已建立
+- [ ] `candles` 表已建立
+- [ ] `market_sessions` 表已建立
+- [ ] OKX 数据采集已接通
+- [ ] BTC/ETH K 线可入库
+- [ ] session 生成器已跑通
+
+### 完成标准
+
+- [ ] 指定 symbol / timeframe 能查到最近数据
+- [ ] candles 唯一键无重复
+- [ ] session high / low / midpoint 可查询
+
+### 验证记录
+
+- [ ] K 线查询样本已记录
+- [ ] session 查询样本已记录
+- [ ] 一致性问题已清零或列出
+
+---
+
+## 4.3 阶段 2：基础规则层
+
+### 检查项
+
+- [ ] swings 识别已实现
+- [ ] dealing range 识别已实现
+- [ ] premium / discount / equilibrium 判定已实现
+- [ ] liquidity pools 识别已实现
+- [x] equal highs / lows 阈值可配置
+
+### 完成标准
+
+- [ ] 至少一个品种多周期规则跑通
+- [ ] 可查询当前主 range
+- [ ] 可查询当前 price location
+- [ ] 可查询当前 liquidity pools
+
+### 验证记录
+
+- [ ] 随机样本图人工抽查已完成
+- [ ] 正例样本已记录
+- [ ] 反例样本已记录
+
+---
+
+## 4.4 阶段 3：核心信号层
+
+### 检查项
+
+- [ ] sweep 识别已实现
+- [ ] displacement 识别已实现
+- [ ] MSB 已实现
+- [ ] MSS 已实现
+- [ ] FVG 识别已实现
+- [ ] bias snapshot 已实现
+- [ ] `SWEEP_MSS_FVG` 信号组装已实现
+
+### 完成标准
+
+- [ ] 可生成候选信号
+- [ ] 每个信号都能追溯 evidence
+- [ ] RR 过滤生效
+- [ ] session 过滤生效
+- [ ] invalidation 已可生成
+
+### 验证记录
+
+- [ ] 至少一条有效样本已记录
+- [ ] 至少一条无效样本已记录
+- [ ] 规则链路截图或导出已保留
+
+---
+
+## 4.5 阶段 4：回测与验证层
+
+### 检查项
+
+- [x] backtest run 启动逻辑已实现
+- [x] backtest result 存储已实现
+- [x] mfe / mae 已计算
+- [x] tp1 / tp2 命中统计已实现
+- [x] error tags 已实现
+- [ ] 按 session / symbol / weekday 分组统计已实现
+
+### 完成标准
+
+- [x] 同配置回测可重复
+- [x] 可输出基础绩效指标
+- [ ] 可识别高质量 / 低质量场景
+
+### 验证记录
+
+- [x] 至少一次完整回测已记录
+- [x] 输出样本已保留
+- [x] 已知偏差已记录
+
+### 当前补强项
+
+- [x] 同根 K 线 entry / stop / TP 歧义已写入 meta
+- [x] `invalidated_before_entry` 与入场后止损语义已拆开
+- [x] 回测核心判定已有单元测试
+- [x] session 过滤与 signal 生成层联动
+
+---
+
+## 4.6 阶段 5：半自动执行层
+
+### 检查项
+
+- [ ] risk engine 已实现
+- [ ] paper trading 已实现
+- [ ] semi-auto order confirm 流程已实现
+- [ ] stop / tp1 / tp2 管理已实现
+- [ ] execution audit 已实现
+
+### 完成标准
+
+- [ ] 无 stop 信号无法执行
+- [ ] 风控拒绝可追溯
+- [ ] 模拟订单可完整开平
+- [ ] 半自动流程需要显式确认
+
+### 验证记录
+
+- [ ] 拒单样本已记录
+- [ ] 正常成交样本已记录
+- [ ] 失效平仓样本已记录
+
+---
+
+## 4.7 阶段 6：AI 报告与复盘层
+
+### 检查项
+
+- [ ] pre-market 模板已实现
+- [ ] intraday explanation 模板已实现
+- [ ] post-trade review 模板已实现
+- [ ] AI 输入只依赖结构化数据
+- [ ] AI 输出不绕过规则层
+
+### 完成标准
+
+- [ ] 同一输入得到稳定报告
+- [ ] 报告能解释关键 evidence
+- [ ] 报告含 invalidation / risk note
+
+### 验证记录
+
+- [ ] 报告样本已保存
+- [ ] 错误示例已记录
+
+---
+
+## 5. 每日推进检查规则
+
+每天推进时，至少要保证完成以下动作中的一项：
+
+1. 落一个新文件
+2. 改一组代码并验证
+3. 完成一次数据库建表/迁移验证
+4. 完成一轮回测并输出结果
+5. 完成一份本地文档并校验
+
+如果没有任何上述产物，就不应把任务继续挂在进行中。
+
+---
+
+## 6. 防止“任务悬挂”的执行规则
+
+发现以下情况，必须立即重拆任务：
+
+1. 任务启动后长时间无文件产物
+2. 任务启动后无代码变更
+3. 连续两次只报状态，没有验证结果
+4. 任务范围太大，无法在一个工作单元内关闭
+
+重拆方法：
+
+- 把一个大任务拆成 2~5 个更小任务
+- 每个小任务都必须有明确产物
+- 优先先完成能落地的那个最小任务
+
+---
+
+## 7. 当前建议使用方式
+
+后续开发建议始终按以下模式推进：
+
+1. 从路线图挑一个阶段
+2. 从该阶段挑一个最小可执行模块
+3. 完成实现
+4. 本地验证
+5. 更新本清单
+6. 关闭任务
+7. 再进入下一个最小模块
+
+---
+
+## 8. 当前结论
+
+本清单的目的不是增加流程负担，而是防止项目推进中出现“任务看似启动、实际没有推进”的假忙碌状态。
+
+从现在开始，每个任务都应以：
+
+> 已落地文件 / 已落地代码 / 已验证结果
+
+作为完成依据，而不是以“已开始”作为依据。
diff --git a/docs/AI_ICT_数据库_Migration_SQL_草案_v1.md b/docs/AI_ICT_数据库_Migration_SQL_草案_v1.md
new file mode 100644
index 0000000..ec38c48
--- /dev/null
+++ b/docs/AI_ICT_数据库_Migration_SQL_草案_v1.md
@@ -0,0 +1,454 @@
+# AI ICT 数据库 Migration SQL 草案 v1
+
+## 1. 文档目标
+
+本文档把前面已经确定的 PostgreSQL Schema 与 Migration 拆分计划进一步落到可执行 SQL 草案层，供后续正式 migration 文件编写时直接参考。
+
+本草案聚焦第一轮最小可落地范围：
+
+1. `venues`
+2. `instruments`
+3. `candles`
+4. `market_sessions`
+5. `swings`
+6. `dealing_ranges`
+7. `liquidity_pools`
+
+目标是先打通：
+
+`PostgreSQL -> Candles -> Sessions -> Swings -> Dealing Range -> Liquidity Pools`
+
+---
+
+## 2. 使用原则
+
+1. 本文档是 SQL 草案，不代表最终 migration 工具格式
+2. 正式落地时可拆分成多份 migration 文件
+3. 先保留 PostgreSQL 原生 SQL 语义，避免过早绑定 ORM
+4. 所有时间字段使用 `timestamptz`
+5. 数值价格字段使用 `numeric`
+
+---
+
+## 3. migration_001_create_venues
+
+```sql
+create table if not exists venues (
+    id bigserial primary key,
+    code text not null unique,
+    name text not null,
+    timezone text not null,
+    status text not null default 'active',
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now()
+);
+```
+
+### 说明
+
+- `code` 用于程序引用，例如 `OKX`, `LMAX`
+- `timezone` 保存交易所或主业务时区信息
+- `status` 暂保持文本，后续如稳定再改枚举
+
+---
+
+## 4. migration_002_create_instruments
+
+```sql
+create table if not exists instruments (
+    id bigserial primary key,
+    venue_id bigint not null references venues(id),
+    symbol text not null,
+    asset_class text not null,
+    base_asset text,
+    quote_asset text,
+    price_scale integer not null,
+    qty_scale integer not null,
+    tick_size numeric(20,10) not null,
+    lot_size numeric(20,10),
+    active boolean not null default true,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now(),
+    unique (venue_id, symbol)
+);
+```
+
+### 建议索引
+
+```sql
+create index if not exists idx_instruments_venue_id on instruments(venue_id);
+create index if not exists idx_instruments_active on instruments(active);
+```
+
+---
+
+## 5. migration_003_create_candles
+
+### 5.1 主表
+
+```sql
+create table if not exists candles (
+    id bigserial not null,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    ts_open timestamptz not null,
+    ts_close timestamptz not null,
+    open numeric(20,10) not null,
+    high numeric(20,10) not null,
+    low numeric(20,10) not null,
+    close numeric(20,10) not null,
+    volume numeric(28,10),
+    source text not null default 'api',
+    created_at timestamptz not null default now(),
+    primary key (id, ts_open),
+    unique (instrument_id, timeframe, ts_open)
+) partition by range (ts_open);
+```
+
+### 5.2 说明
+
+- `candles` 是最核心的大表，按 `ts_open` 做 range partition
+- 第一阶段可接受联合主键，只要唯一约束稳定
+- 若后续 ORM 对分区主键有特殊要求，可再调整
+
+---
+
+## 6. migration_004_create_candles_partitions_and_indexes
+
+### 6.1 示例分区
+
+```sql
+create table if not exists candles_2026_04
+partition of candles
+for values from ('2026-04-01 00:00:00+00') to ('2026-05-01 00:00:00+00');
+
+create table if not exists candles_2026_05
+partition of candles
+for values from ('2026-05-01 00:00:00+00') to ('2026-06-01 00:00:00+00');
+```
+
+### 6.2 索引
+
+```sql
+create index if not exists idx_candles_instrument_tf_open_desc
+on candles (instrument_id, timeframe, ts_open desc);
+
+create index if not exists idx_candles_instrument_tf_close_desc
+on candles (instrument_id, timeframe, ts_close desc);
+```
+
+### 6.3 检查约束（可选）
+
+```sql
+alter table candles
+    add constraint candles_high_ge_low check (high >= low);
+
+alter table candles
+    add constraint candles_high_ge_open check (high >= open);
+
+alter table candles
+    add constraint candles_high_ge_close check (high >= close);
+
+alter table candles
+    add constraint candles_low_le_open check (low <= open);
+
+alter table candles
+    add constraint candles_low_le_close check (low <= close);
+```
+
+说明：
+
+- 若担心历史脏数据导入失败，可先不加 check，后续数据稳定后再加
+
+---
+
+## 7. migration_005_create_market_sessions
+
+```sql
+create table if not exists market_sessions (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    session_date date not null,
+    timezone text not null,
+    session_code text not null,
+    start_ts timestamptz not null,
+    end_ts timestamptz not null,
+    high numeric(20,10),
+    low numeric(20,10),
+    midpoint numeric(20,10),
+    status text not null default 'closed',
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now(),
+    unique (instrument_id, session_date, session_code, timezone)
+);
+```
+
+### 建议索引
+
+```sql
+create index if not exists idx_market_sessions_instr_date
+on market_sessions (instrument_id, session_date desc);
+
+create index if not exists idx_market_sessions_instr_code_date
+on market_sessions (instrument_id, session_code, session_date desc);
+```
+
+---
+
+## 8. migration_006_create_swings
+
+```sql
+create table if not exists swings (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    kind text not null,
+    strength text not null,
+    price numeric(20,10) not null,
+    ts timestamptz not null,
+    left_bars integer not null,
+    right_bars integer not null,
+    confirmed boolean not null default true,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now()
+);
+```
+
+### 建议索引
+
+```sql
+create index if not exists idx_swings_instr_tf_ts_desc
+on swings (instrument_id, timeframe, ts desc);
+
+create index if not exists idx_swings_instr_tf_kind_ts_desc
+on swings (instrument_id, timeframe, kind, ts desc);
+
+create index if not exists idx_swings_instr_tf_strength_ts_desc
+on swings (instrument_id, timeframe, strength, ts desc);
+```
+
+### 可选检查约束
+
+```sql
+alter table swings
+    add constraint swings_kind_check
+    check (kind in ('swing_high', 'swing_low'));
+
+alter table swings
+    add constraint swings_strength_check
+    check (strength in ('ST', 'IT', 'LT'));
+```
+
+---
+
+## 9. migration_007_create_dealing_ranges
+
+```sql
+create table if not exists dealing_ranges (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    high numeric(20,10) not null,
+    low numeric(20,10) not null,
+    equilibrium numeric(20,10) not null,
+    high_swing_id bigint references swings(id),
+    low_swing_id bigint references swings(id),
+    state text not null default 'valid',
+    ts_start timestamptz not null,
+    ts_end timestamptz,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now()
+);
+```
+
+### 建议索引
+
+```sql
+create index if not exists idx_dealing_ranges_instr_tf_start_desc
+on dealing_ranges (instrument_id, timeframe, ts_start desc);
+
+create index if not exists idx_dealing_ranges_instr_tf_state_start_desc
+on dealing_ranges (instrument_id, timeframe, state, ts_start desc);
+```
+
+### 可选检查约束
+
+```sql
+alter table dealing_ranges
+    add constraint dealing_ranges_high_gt_low check (high > low);
+```
+
+---
+
+## 10. migration_008_create_liquidity_pools
+
+```sql
+create table if not exists liquidity_pools (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    side text not null,
+    pool_type text not null,
+    price_low numeric(20,10) not null,
+    price_high numeric(20,10) not null,
+    reference_ids jsonb not null default '[]'::jsonb,
+    status text not null default 'untouched',
+    created_ts timestamptz not null,
+    updated_ts timestamptz not null default now(),
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now()
+);
+```
+
+### 建议索引
+
+```sql
+create index if not exists idx_liquidity_pools_instr_tf_status_created_desc
+on liquidity_pools (instrument_id, timeframe, status, created_ts desc);
+
+create index if not exists idx_liquidity_pools_instr_tf_side_created_desc
+on liquidity_pools (instrument_id, timeframe, side, created_ts desc);
+```
+
+### 可选检查约束
+
+```sql
+alter table liquidity_pools
+    add constraint liquidity_pools_side_check
+    check (side in ('buy_side', 'sell_side'));
+
+alter table liquidity_pools
+    add constraint liquidity_pools_price_range_check
+    check (price_high >= price_low);
+```
+
+---
+
+## 11. 初始种子数据草案
+
+### 11.1 venues
+
+```sql
+insert into venues (code, name, timezone)
+values
+    ('OKX', 'OKX', 'UTC'),
+    ('LMAX', 'LMAX', 'UTC')
+on conflict (code) do nothing;
+```
+
+### 11.2 instruments（示例）
+
+```sql
+insert into instruments (
+    venue_id,
+    symbol,
+    asset_class,
+    base_asset,
+    quote_asset,
+    price_scale,
+    qty_scale,
+    tick_size,
+    lot_size,
+    active,
+    meta
+)
+select
+    v.id,
+    'BTC-USDT',
+    'crypto',
+    'BTC',
+    'USDT',
+    2,
+    6,
+    0.01,
+    0.000001,
+    true,
+    jsonb_build_object('raw_inst_id', 'BTC-USDT-SWAP', 'product_type', 'swap')
+from venues v
+where v.code = 'OKX'
+on conflict (venue_id, symbol) do nothing;
+```
+
+说明：
+
+- ETH 与 XAU 可按同样方式扩充
+- XAU 若合约尚未最终确定，建议先不插入 active=true 的正式 instrument
+
+---
+
+## 12. 第一轮验证 SQL
+
+## 12.1 验证表存在
+
+```sql
+select tablename
+from pg_tables
+where schemaname = 'public'
+  and tablename in (
+    'venues',
+    'instruments',
+    'candles',
+    'market_sessions',
+    'swings',
+    'dealing_ranges',
+    'liquidity_pools'
+  )
+order by tablename;
+```
+
+## 12.2 验证唯一键
+
+```sql
+select indexname, indexdef
+from pg_indexes
+where tablename in ('candles', 'instruments', 'market_sessions')
+order by tablename, indexname;
+```
+
+## 12.3 验证 candles 分区
+
+```sql
+select
+    parent.relname as parent_table,
+    child.relname as partition_table
+from pg_inherits
+join pg_class parent on pg_inherits.inhparent = parent.oid
+join pg_class child on pg_inherits.inhrelid = child.oid
+where parent.relname = 'candles';
+```
+
+---
+
+## 13. 正式迁移时的建议拆分
+
+后续真正落 migration 文件时，建议按以下顺序拆分：
+
+1. `001_create_venues.sql`
+2. `002_create_instruments.sql`
+3. `003_create_candles.sql`
+4. `004_create_candles_partitions_and_indexes.sql`
+5. `005_create_market_sessions.sql`
+6. `006_create_swings.sql`
+7. `007_create_dealing_ranges.sql`
+8. `008_create_liquidity_pools.sql`
+
+这样可以确保：
+
+- 先打通基础字典表
+- 再打通数据主链
+- 再进入基础规则主链
+
+---
+
+## 14. 当前结论
+
+本 SQL 草案已经把前期方案文档推进到“可直接开始写 migration 文件”的程度。
+
+第一阶段真正落地时，应先用本草案实现：
+
+`venues -> instruments -> candles -> market_sessions -> swings -> dealing_ranges -> liquidity_pools`
+
+只要这一段建库完成并验证通过，后续真实代码开发就可以直接进入数据接入和基础规则实现。
\ No newline at end of file
diff --git a/docs/AI_ICT_文档索引与命名规范_v1.md b/docs/AI_ICT_文档索引与命名规范_v1.md
new file mode 100644
index 0000000..cc9cb85
--- /dev/null
+++ b/docs/AI_ICT_文档索引与命名规范_v1.md
@@ -0,0 +1,291 @@
+# AI ICT 文档索引与命名规范 v1
+
+## 1. 文档目标
+
+本文档用于统一当前 AI ICT 项目的文档体系，解决以下问题：
+
+1. 明确哪些文档是当前主参考文档
+2. 明确文档的用途和阅读顺序
+3. 避免后续出现重复命名、重复主题、主从版本不清的问题
+4. 为后续继续新增文档提供统一命名规范
+
+---
+
+## 2. 当前文档主索引
+
+以下文件为当前 `docs/` 目录下的有效参考文档。
+
+### A. 顶层设计文档
+
+#### 1. `AI_ICT_总体设计文档_v1.md`
+用途：
+- 项目总目标
+- 架构总览
+- 服务拆分
+- 数据库选型
+- 模块职责
+- 总体推进方向
+
+推荐角色：
+- 总纲文档
+
+---
+
+#### 2. `AI_ICT_PostgreSQL_Schema_v1.md`
+用途：
+- PostgreSQL 表结构设计
+- 字段、约束、索引、分区建议
+- JSONB 边界
+
+推荐角色：
+- 数据库主参考文档
+
+---
+
+#### 3. `AI_ICT_MVP_规则规格书_v1.md`
+用途：
+- MVP 规则定义
+- 核心对象
+- 主模型
+- Signal 状态机
+- 回测标签
+
+推荐角色：
+- 规则引擎主参考文档
+
+---
+
+### B. 推进与交付文档
+
+#### 4. `AI_ICT_开发路线图_v1.md`
+用途：
+- 项目阶段划分
+- 模块顺序
+- 交付物
+- 验证点
+
+推荐角色：
+- 项目推进主计划文档
+
+---
+
+#### 5. `AI_ICT_执行检查清单_v1.md`
+用途：
+- 任务关闭标准
+- 模块完成标准
+- 防止任务悬挂
+
+推荐角色：
+- 执行与验收参考文档
+
+---
+
+#### 6. `AI_ICT_项目启动清单_v1.md`
+用途：
+- 第一轮真实开发启动顺序
+- 基础模块优先顺序
+- 项目起步检查点
+
+推荐角色：
+- 第一波开发启动清单
+
+---
+
+### C. 数据与基础模块文档
+
+#### 7. `AI_ICT_OKX_数据接入规格书_v1.md`
+用途：
+- OKX 行情接入
+- 历史补数
+- 增量同步
+- 幂等入库
+- 错误处理
+
+推荐角色：
+- 市场数据层接入主参考文档
+
+---
+
+#### 8. `AI_ICT_Session_生成器规格书_v1.md`
+用途：
+- 会话切分
+- 时区处理
+- 跨午夜归属规则
+- session high/low/midpoint
+- `market_sessions` 写入
+
+推荐角色：
+- Session 模块主参考文档
+
+---
+
+### D. Migration 文档
+
+#### 9. `AI_ICT_Migration_拆分计划_v1.md`
+用途：
+- schema migration 拆批
+- 执行顺序
+- 依赖关系
+- 验证点
+- 回滚顺序
+
+推荐角色：
+- 当前 migration 主参考文档
+
+状态：
+- **当前主版本（canonical）**
+
+---
+
+#### 10. `AI_ICT_PostgreSQL_Migration_Split_Plan_v1.md`
+用途：
+- 与 migration 拆分主题相近的旧/重复命名版本
+
+状态：
+- **非主版本**
+- 当前不建议继续引用
+
+处理建议：
+- 后续可合并或归档
+- 若确认内容重复，应统一保留 `AI_ICT_Migration_拆分计划_v1.md`
+
+---
+
+## 3. 推荐阅读顺序
+
+如果是第一次进入项目，建议按以下顺序阅读：
+
+### 第 1 层：总纲
+1. `AI_ICT_总体设计文档_v1.md`
+2. `AI_ICT_开发路线图_v1.md`
+
+### 第 2 层：基础实现标准
+3. `AI_ICT_PostgreSQL_Schema_v1.md`
+4. `AI_ICT_MVP_规则规格书_v1.md`
+
+### 第 3 层：启动与执行
+5. `AI_ICT_项目启动清单_v1.md`
+6. `AI_ICT_执行检查清单_v1.md`
+
+### 第 4 层：首批模块落地
+7. `AI_ICT_OKX_数据接入规格书_v1.md`
+8. `AI_ICT_Session_生成器规格书_v1.md`
+9. `AI_ICT_Migration_拆分计划_v1.md`
+
+---
+
+## 4. 文档分层规范
+
+后续新增文档建议按以下四类分层：
+
+### 4.1 顶层设计类
+命名模板：
+
+`AI_ICT_<主题>文档_vN.md`
+
+示例：
+- `AI_ICT_总体设计文档_v1.md`
+- `AI_ICT_风控设计文档_v1.md`
+
+---
+
+### 4.2 规格书类
+命名模板：
+
+`AI_ICT_<模块>规格书_vN.md`
+
+示例：
+- `AI_ICT_OKX_数据接入规格书_v1.md`
+- `AI_ICT_Session_生成器规格书_v1.md`
+- `AI_ICT_Swing_识别规格书_v1.md`
+
+---
+
+### 4.3 计划/清单类
+命名模板：
+
+`AI_ICT_<主题>清单_vN.md`
+或
+`AI_ICT_<主题>路线图_vN.md`
+
+示例：
+- `AI_ICT_项目启动清单_v1.md`
+- `AI_ICT_执行检查清单_v1.md`
+- `AI_ICT_开发路线图_v1.md`
+
+---
+
+### 4.4 数据库 / migration 类
+命名模板：
+
+`AI_ICT_<数据库或模块>_<主题>_vN.md`
+
+示例：
+- `AI_ICT_PostgreSQL_Schema_v1.md`
+- `AI_ICT_Migration_拆分计划_v1.md`
+
+说明：
+- 这类文档尽量固定中文或英文一种主命名风格
+- 不要同一主题同时出现中英混合双版本标题
+
+---
+
+## 5. 命名统一规则
+
+后续新增文档时，必须遵守：
+
+1. 同一主题只保留一个 canonical 名称
+2. 若重写版本，递增 `v2`，不要新起另一个不同名字
+3. 不要同时保留：
+   - 中文主题名版本
+   - 英文同义主题名版本
+4. 若发生主题重复，必须在索引文档中明确：
+   - 哪个是主版本
+   - 哪个已废弃或待归档
+
+---
+
+## 6. 文档生命周期规则
+
+每份文档应有如下状态之一：
+
+- canonical：当前主参考文档
+- active：仍在使用，但不是最高优先级引用
+- draft：临时草稿
+- archived：已归档
+- deprecated：已弃用，不再引用
+
+当前建议：
+
+- `AI_ICT_Migration_拆分计划_v1.md` -> canonical
+- `AI_ICT_PostgreSQL_Migration_Split_Plan_v1.md` -> deprecated 或待归档
+
+---
+
+## 7. 后续建议新增文档列表
+
+按优先级建议后续继续补：
+
+1. `AI_ICT_Swing_识别规格书_v1.md`
+2. `AI_ICT_Dealing_Range_规格书_v1.md`
+3. `AI_ICT_Liquidity_Pool_规格书_v1.md`
+4. `AI_ICT_Sweep_识别规格书_v1.md`
+5. `AI_ICT_MSS_判定规格书_v1.md`
+6. `AI_ICT_FVG_规格书_v1.md`
+7. `AI_ICT_Backtest_规格书_v1.md`
+8. `AI_ICT_风控规格书_v1.md`
+
+---
+
+## 8. 当前结论
+
+当前 `docs/` 已经具备从方案到启动的第一轮完整文档骨架。
+
+从现在开始，新增文档时应统一遵守：
+
+- 单主题单主版本
+- 先写入再汇报
+- 用索引文档固定引用关系
+- 避免中英文重复命名并存
+
+本文件应作为当前 `docs/` 目录的导航入口与命名规范参考。
\ No newline at end of file
diff --git a/docs/AI_ICT_第一批正式_Migration_文件草案_v1.md b/docs/AI_ICT_第一批正式_Migration_文件草案_v1.md
new file mode 100644
index 0000000..346f0d3
--- /dev/null
+++ b/docs/AI_ICT_第一批正式_Migration_文件草案_v1.md
@@ -0,0 +1,489 @@
+# AI ICT 第一批正式 Migration 文件草案 v1
+
+## 1. 文档目标
+
+本文档把 `AI_ICT_数据库_Migration_SQL_草案_v1.md` 进一步拆成“文件级 migration 草案”，让后续真实项目实现时可以直接按文件落地。
+
+目标：
+
+1. 固定第一批 migration 文件名
+2. 固定执行顺序
+3. 提供每个文件的建议 SQL 内容
+4. 提供每个文件的执行注意事项
+5. 让后续开发能直接从文档进入建库实现
+
+---
+
+## 2. 第一批 migration 范围
+
+本批次只覆盖基础共享模块所需数据表：
+
+1. `venues`
+2. `instruments`
+3. `candles`
+4. `market_sessions`
+5. `swings`
+6. `dealing_ranges`
+7. `liquidity_pools`
+
+这是第一条必须打通的基础链路：
+
+`venues -> instruments -> candles -> market_sessions -> swings -> dealing_ranges -> liquidity_pools`
+
+---
+
+## 3. 建议 migration 文件顺序
+
+建议后续正式建库时使用以下文件顺序：
+
+1. `001_create_venues.sql`
+2. `002_create_instruments.sql`
+3. `003_create_candles.sql`
+4. `004_create_candles_partitions_and_indexes.sql`
+5. `005_create_market_sessions.sql`
+6. `006_create_swings.sql`
+7. `007_create_dealing_ranges.sql`
+8. `008_create_liquidity_pools.sql`
+9. `009_seed_venues.sql`
+10. `010_seed_instruments.sql`
+
+说明：
+
+- 前 8 个是 schema migration
+- 后 2 个是 seed migration
+- 如果你后面使用某个 migration 工具，也建议保持同样的执行顺序编号
+
+---
+
+## 4. 001_create_venues.sql
+
+```sql
+create table if not exists venues (
+    id bigserial primary key,
+    code text not null unique,
+    name text not null,
+    timezone text not null,
+    status text not null default 'active',
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now()
+);
+```
+
+### 注意事项
+
+- `code` 后续会成为程序引用键
+- 不建议后续轻易修改 `code`
+
+---
+
+## 5. 002_create_instruments.sql
+
+```sql
+create table if not exists instruments (
+    id bigserial primary key,
+    venue_id bigint not null references venues(id),
+    symbol text not null,
+    asset_class text not null,
+    base_asset text,
+    quote_asset text,
+    price_scale integer not null,
+    qty_scale integer not null,
+    tick_size numeric(20,10) not null,
+    lot_size numeric(20,10),
+    active boolean not null default true,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now(),
+    unique (venue_id, symbol)
+);
+
+create index if not exists idx_instruments_venue_id on instruments(venue_id);
+create index if not exists idx_instruments_active on instruments(active);
+```
+
+### 注意事项
+
+- `symbol` 必须是系统内部标准名，不建议直接等于交易所原始 instId
+- 原始交易所代码建议放到 `meta`
+
+---
+
+## 6. 003_create_candles.sql
+
+```sql
+create table if not exists candles (
+    id bigserial not null,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    ts_open timestamptz not null,
+    ts_close timestamptz not null,
+    open numeric(20,10) not null,
+    high numeric(20,10) not null,
+    low numeric(20,10) not null,
+    close numeric(20,10) not null,
+    volume numeric(28,10),
+    source text not null default 'api',
+    created_at timestamptz not null default now(),
+    primary key (id, ts_open),
+    unique (instrument_id, timeframe, ts_open)
+) partition by range (ts_open);
+```
+
+### 注意事项
+
+- 这是分区主表，不直接长期存放所有数据行
+- 真实数据主要写入各月分区
+
+---
+
+## 7. 004_create_candles_partitions_and_indexes.sql
+
+```sql
+create table if not exists candles_2026_04
+partition of candles
+for values from ('2026-04-01 00:00:00+00') to ('2026-05-01 00:00:00+00');
+
+create table if not exists candles_2026_05
+partition of candles
+for values from ('2026-05-01 00:00:00+00') to ('2026-06-01 00:00:00+00');
+
+create index if not exists idx_candles_instrument_tf_open_desc
+on candles (instrument_id, timeframe, ts_open desc);
+
+create index if not exists idx_candles_instrument_tf_close_desc
+on candles (instrument_id, timeframe, ts_close desc);
+```
+
+### 可选扩展
+
+如果想在第一批就加检查约束，可追加：
+
+```sql
+alter table candles
+    add constraint candles_high_ge_low check (high >= low);
+
+alter table candles
+    add constraint candles_high_ge_open check (high >= open);
+
+alter table candles
+    add constraint candles_high_ge_close check (high >= close);
+
+alter table candles
+    add constraint candles_low_le_open check (low <= open);
+
+alter table candles
+    add constraint candles_low_le_close check (low <= close);
+```
+
+### 注意事项
+
+- 若担心历史脏数据导入失败，检查约束可以放第二批 migration
+- 分区创建建议始终超前至少一个月
+
+---
+
+## 8. 005_create_market_sessions.sql
+
+```sql
+create table if not exists market_sessions (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    session_date date not null,
+    timezone text not null,
+    session_code text not null,
+    start_ts timestamptz not null,
+    end_ts timestamptz not null,
+    high numeric(20,10),
+    low numeric(20,10),
+    midpoint numeric(20,10),
+    status text not null default 'closed',
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now(),
+    unique (instrument_id, session_date, session_code, timezone)
+);
+
+create index if not exists idx_market_sessions_instr_date
+on market_sessions (instrument_id, session_date desc);
+
+create index if not exists idx_market_sessions_instr_code_date
+on market_sessions (instrument_id, session_code, session_date desc);
+```
+
+### 注意事项
+
+- 该表直接支撑 session generator 模块
+- `session_code` 后续建议只允许固定集合，例如 `ASIA`, `LONDON`, `NY_AM`, `NY_LUNCH`, `NY_PM`
+
+---
+
+## 9. 006_create_swings.sql
+
+```sql
+create table if not exists swings (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    kind text not null,
+    strength text not null,
+    price numeric(20,10) not null,
+    ts timestamptz not null,
+    left_bars integer not null,
+    right_bars integer not null,
+    confirmed boolean not null default true,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now()
+);
+
+create index if not exists idx_swings_instr_tf_ts_desc
+on swings (instrument_id, timeframe, ts desc);
+
+create index if not exists idx_swings_instr_tf_kind_ts_desc
+on swings (instrument_id, timeframe, kind, ts desc);
+
+create index if not exists idx_swings_instr_tf_strength_ts_desc
+on swings (instrument_id, timeframe, strength, ts desc);
+```
+
+### 可选检查约束
+
+```sql
+alter table swings
+    add constraint swings_kind_check
+    check (kind in ('swing_high', 'swing_low'));
+
+alter table swings
+    add constraint swings_strength_check
+    check (strength in ('ST', 'IT', 'LT'));
+```
+
+---
+
+## 10. 007_create_dealing_ranges.sql
+
+```sql
+create table if not exists dealing_ranges (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    high numeric(20,10) not null,
+    low numeric(20,10) not null,
+    equilibrium numeric(20,10) not null,
+    high_swing_id bigint references swings(id),
+    low_swing_id bigint references swings(id),
+    state text not null default 'valid',
+    ts_start timestamptz not null,
+    ts_end timestamptz,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now()
+);
+
+create index if not exists idx_dealing_ranges_instr_tf_start_desc
+on dealing_ranges (instrument_id, timeframe, ts_start desc);
+
+create index if not exists idx_dealing_ranges_instr_tf_state_start_desc
+on dealing_ranges (instrument_id, timeframe, state, ts_start desc);
+```
+
+### 可选检查约束
+
+```sql
+alter table dealing_ranges
+    add constraint dealing_ranges_high_gt_low check (high > low);
+```
+
+---
+
+## 11. 008_create_liquidity_pools.sql
+
+```sql
+create table if not exists liquidity_pools (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    side text not null,
+    pool_type text not null,
+    price_low numeric(20,10) not null,
+    price_high numeric(20,10) not null,
+    reference_ids jsonb not null default '[]'::jsonb,
+    status text not null default 'untouched',
+    created_ts timestamptz not null,
+    updated_ts timestamptz not null default now(),
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now()
+);
+
+create index if not exists idx_liquidity_pools_instr_tf_status_created_desc
+on liquidity_pools (instrument_id, timeframe, status, created_ts desc);
+
+create index if not exists idx_liquidity_pools_instr_tf_side_created_desc
+on liquidity_pools (instrument_id, timeframe, side, created_ts desc);
+```
+
+### 可选检查约束
+
+```sql
+alter table liquidity_pools
+    add constraint liquidity_pools_side_check
+    check (side in ('buy_side', 'sell_side'));
+
+alter table liquidity_pools
+    add constraint liquidity_pools_price_range_check
+    check (price_high >= price_low);
+```
+
+---
+
+## 12. 009_seed_venues.sql
+
+```sql
+insert into venues (code, name, timezone)
+values
+    ('OKX', 'OKX', 'UTC'),
+    ('LMAX', 'LMAX', 'UTC')
+on conflict (code) do nothing;
+```
+
+---
+
+## 13. 010_seed_instruments.sql
+
+### 13.1 BTC 示例
+
+```sql
+insert into instruments (
+    venue_id,
+    symbol,
+    asset_class,
+    base_asset,
+    quote_asset,
+    price_scale,
+    qty_scale,
+    tick_size,
+    lot_size,
+    active,
+    meta
+)
+select
+    v.id,
+    'BTC-USDT',
+    'crypto',
+    'BTC',
+    'USDT',
+    2,
+    6,
+    0.01,
+    0.000001,
+    true,
+    jsonb_build_object('raw_inst_id', 'BTC-USDT-SWAP', 'product_type', 'swap')
+from venues v
+where v.code = 'OKX'
+on conflict (venue_id, symbol) do nothing;
+```
+
+### 13.2 ETH 示例
+
+```sql
+insert into instruments (
+    venue_id,
+    symbol,
+    asset_class,
+    base_asset,
+    quote_asset,
+    price_scale,
+    qty_scale,
+    tick_size,
+    lot_size,
+    active,
+    meta
+)
+select
+    v.id,
+    'ETH-USDT',
+    'crypto',
+    'ETH',
+    'USDT',
+    2,
+    6,
+    0.01,
+    0.000001,
+    true,
+    jsonb_build_object('raw_inst_id', 'ETH-USDT-SWAP', 'product_type', 'swap')
+from venues v
+where v.code = 'OKX'
+on conflict (venue_id, symbol) do nothing;
+```
+
+### 13.3 XAU 建议
+
+- 若 LMAX 的实际合约代码与最小变动单位还未最终确定，第一批不要急着插 `active=true` 的正式 XAU instrument
+- 更稳妥的做法是等 LMAX 接入规格确认后单独补 seed
+
+---
+
+## 14. 建议执行步骤
+
+实际建库时建议：
+
+1. 先执行 001 ~ 008 schema migration
+2. 再执行 009 ~ 010 seed migration
+3. 然后运行验证 SQL
+4. 再开始接 OKX 数据
+5. 再跑 session generator
+6. 再跑 swing / dealing range / liquidity pool
+
+---
+
+## 15. 第一轮验证 SQL 草案
+
+### 15.1 检查基础表
+
+```sql
+select tablename
+from pg_tables
+where schemaname = 'public'
+  and tablename in (
+    'venues',
+    'instruments',
+    'candles',
+    'market_sessions',
+    'swings',
+    'dealing_ranges',
+    'liquidity_pools'
+  )
+order by tablename;
+```
+
+### 15.2 检查 candles 分区
+
+```sql
+select
+    parent.relname as parent_table,
+    child.relname as partition_table
+from pg_inherits
+join pg_class parent on pg_inherits.inhparent = parent.oid
+join pg_class child on pg_inherits.inhrelid = child.oid
+where parent.relname = 'candles';
+```
+
+### 15.3 检查 seed 数据
+
+```sql
+select v.code, i.symbol, i.meta
+from instruments i
+join venues v on v.id = i.venue_id
+order by v.code, i.symbol;
+```
+
+---
+
+## 16. 当前结论
+
+这份文档已经把数据库准备工作推进到了“文件级 migration 草案”的粒度。
+
+下一步如果要真正开始代码实现，已经不需要再从零设计 migration，只需要把这里的内容按项目使用的 migration 工具格式落地即可。
+
+对第一阶段来说，这已经足够支撑：
+
+`建库 -> seed -> 接 OKX -> 生成 sessions -> 跑 swings -> 跑 dealing range -> 跑 liquidity pools`
diff --git a/docs/AI_ICT_第二批正式_Migration_文件草案_v1.md b/docs/AI_ICT_第二批正式_Migration_文件草案_v1.md
new file mode 100644
index 0000000..cb2ba86
--- /dev/null
+++ b/docs/AI_ICT_第二批正式_Migration_文件草案_v1.md
@@ -0,0 +1,462 @@
+# AI ICT 第二批正式 Migration 文件草案 v1
+
+## 1. 文档目标
+
+本文档在第一批 migration 文件草案的基础上，继续把数据库层推进到“核心事件层 + 决策层 + 回测层”，覆盖 MVP 主模型后半段所需的数据结构。
+
+本批次主要覆盖：
+
+1. `displacement_events`
+2. `structure_events`
+3. `fvg_zones`
+4. `bias_snapshots`
+5. `trade_signals`
+6. `trade_executions`
+7. `backtest_runs`
+8. `backtest_results`
+
+目标是把数据库主线推进到：
+
+`Liquidity -> Sweep -> Displacement -> MSS -> FVG -> Bias -> Signal -> Execution -> Backtest`
+
+---
+
+## 2. 与第一批 migration 的关系
+
+本批次默认依赖第一批 migration 已全部完成：
+
+1. `venues`
+2. `instruments`
+3. `candles`
+4. `market_sessions`
+5. `swings`
+6. `dealing_ranges`
+7. `liquidity_pools`
+
+如果第一批基础库对象未稳定，不建议直接进入本批次。
+
+---
+
+## 3. 建议 migration 文件顺序
+
+建议后续正式建库时按以下文件顺序继续追加：
+
+11. `011_create_displacement_events.sql`
+12. `012_create_structure_events.sql`
+13. `013_create_fvg_zones.sql`
+14. `014_create_bias_snapshots.sql`
+15. `015_create_trade_signals.sql`
+16. `016_create_trade_executions.sql`
+17. `017_create_backtest_runs.sql`
+18. `018_create_backtest_results.sql`
+
+说明：
+
+- 事件表先落地
+- 决策与执行表后落地
+- 回测表最后落地
+
+---
+
+## 4. 011_create_displacement_events.sql
+
+```sql
+create table if not exists displacement_events (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    direction text not null,
+    start_ts timestamptz not null,
+    end_ts timestamptz not null,
+    strength_score numeric(8,4),
+    body_ratio numeric(8,4),
+    has_fvg boolean not null default false,
+    is_valid boolean not null default true,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now()
+);
+
+create index if not exists idx_displacement_events_instr_tf_end_desc
+on displacement_events (instrument_id, timeframe, end_ts desc);
+
+create index if not exists idx_displacement_events_instr_tf_dir_end_desc
+on displacement_events (instrument_id, timeframe, direction, end_ts desc);
+```
+
+### 可选检查约束
+
+```sql
+alter table displacement_events
+    add constraint displacement_direction_check
+    check (direction in ('bullish', 'bearish'));
+```
+
+---
+
+## 5. 012_create_structure_events.sql
+
+```sql
+create table if not exists structure_events (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    event_type text not null,
+    direction text not null,
+    broken_level numeric(20,10) not null,
+    reference_swing_id bigint references swings(id),
+    displacement_event_id bigint references displacement_events(id),
+    accepted boolean,
+    signal_relevant boolean not null default true,
+    ts timestamptz not null,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now()
+);
+
+create index if not exists idx_structure_events_instr_tf_ts_desc
+on structure_events (instrument_id, timeframe, ts desc);
+
+create index if not exists idx_structure_events_instr_tf_event_ts_desc
+on structure_events (instrument_id, timeframe, event_type, ts desc);
+```
+
+### 可选检查约束
+
+```sql
+alter table structure_events
+    add constraint structure_events_type_check
+    check (event_type in ('MSB', 'MSS'));
+
+alter table structure_events
+    add constraint structure_events_direction_check
+    check (direction in ('bullish', 'bearish'));
+```
+
+---
+
+## 6. 013_create_fvg_zones.sql
+
+```sql
+create table if not exists fvg_zones (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    direction text not null,
+    upper numeric(20,10) not null,
+    lower numeric(20,10) not null,
+    start_ts timestamptz not null,
+    end_ts timestamptz not null,
+    fill_pct numeric(8,4) not null default 0,
+    status text not null default 'open',
+    related_displacement_id bigint references displacement_events(id),
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now()
+);
+
+create index if not exists idx_fvg_zones_instr_tf_start_desc
+on fvg_zones (instrument_id, timeframe, start_ts desc);
+
+create index if not exists idx_fvg_zones_instr_tf_status_start_desc
+on fvg_zones (instrument_id, timeframe, status, start_ts desc);
+```
+
+### 可选检查约束
+
+```sql
+alter table fvg_zones
+    add constraint fvg_direction_check
+    check (direction in ('bullish', 'bearish'));
+
+alter table fvg_zones
+    add constraint fvg_status_check
+    check (status in ('open', 'touched', 'mitigated', 'invalidated'));
+```
+
+---
+
+## 7. 014_create_bias_snapshots.sql
+
+```sql
+create table if not exists bias_snapshots (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    bias_tf text not null,
+    setup_tf text not null,
+    trigger_tf text not null,
+    snapshot_ts timestamptz not null,
+    daily_bias text not null,
+    confidence numeric(8,4),
+    execution_intensity text not null,
+    narrative_code text,
+    draw_side text,
+    range_id bigint references dealing_ranges(id),
+    reason_codes jsonb not null default '[]'::jsonb,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now()
+);
+
+create index if not exists idx_bias_snapshots_instr_snapshot_desc
+on bias_snapshots (instrument_id, snapshot_ts desc);
+
+create index if not exists idx_bias_snapshots_instr_bias_snapshot_desc
+on bias_snapshots (instrument_id, daily_bias, snapshot_ts desc);
+```
+
+### 可选检查约束
+
+```sql
+alter table bias_snapshots
+    add constraint bias_snapshots_daily_bias_check
+    check (daily_bias in ('bullish', 'bearish', 'neutral'));
+
+alter table bias_snapshots
+    add constraint bias_snapshots_execution_intensity_check
+    check (execution_intensity in ('low', 'medium', 'high'));
+```
+
+---
+
+## 8. 015_create_trade_signals.sql
+
+```sql
+create table if not exists trade_signals (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    model_code text not null,
+    side text not null,
+    status text not null,
+    bias_snapshot_id bigint references bias_snapshots(id),
+    entry_type text not null,
+    entry_low numeric(20,10),
+    entry_high numeric(20,10),
+    stop_loss numeric(20,10),
+    tp1 numeric(20,10),
+    tp2 numeric(20,10),
+    rr_tp1 numeric(8,4),
+    rr_tp2 numeric(8,4),
+    session_code text,
+    created_ts timestamptz not null,
+    expires_ts timestamptz,
+    invalidations jsonb not null default '[]'::jsonb,
+    evidence jsonb not null default '{}'::jsonb,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now()
+);
+
+create index if not exists idx_trade_signals_instr_created_desc
+on trade_signals (instrument_id, created_ts desc);
+
+create index if not exists idx_trade_signals_instr_status_created_desc
+on trade_signals (instrument_id, status, created_ts desc);
+
+create index if not exists idx_trade_signals_instr_model_created_desc
+on trade_signals (instrument_id, model_code, created_ts desc);
+```
+
+### 可选检查约束
+
+```sql
+alter table trade_signals
+    add constraint trade_signals_side_check
+    check (side in ('buy', 'sell'));
+```
+
+说明：
+
+- `status` 先保持文本，后期如状态机稳定再做枚举收敛
+
+---
+
+## 9. 016_create_trade_executions.sql
+
+```sql
+create table if not exists trade_executions (
+    id bigserial primary key,
+    signal_id bigint not null references trade_signals(id),
+    venue_order_id text,
+    execution_mode text not null,
+    side text not null,
+    entry_price numeric(20,10),
+    stop_loss numeric(20,10),
+    take_profit_1 numeric(20,10),
+    take_profit_2 numeric(20,10),
+    size numeric(28,10),
+    risk_pct numeric(8,4),
+    status text not null,
+    opened_ts timestamptz,
+    closed_ts timestamptz,
+    pnl numeric(28,10),
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now()
+);
+
+create index if not exists idx_trade_executions_signal_id
+on trade_executions (signal_id);
+
+create index if not exists idx_trade_executions_status_created_desc
+on trade_executions (status, created_at desc);
+
+create index if not exists idx_trade_executions_mode_created_desc
+on trade_executions (execution_mode, created_at desc);
+```
+
+### 可选检查约束
+
+```sql
+alter table trade_executions
+    add constraint trade_executions_mode_check
+    check (execution_mode in ('paper', 'semi_auto', 'live'));
+```
+
+---
+
+## 10. 017_create_backtest_runs.sql
+
+```sql
+create table if not exists backtest_runs (
+    id bigserial primary key,
+    model_code text not null,
+    instrument_id bigint references instruments(id),
+    timeframe_set jsonb not null default '{}'::jsonb,
+    started_ts timestamptz not null,
+    ended_ts timestamptz,
+    config jsonb not null default '{}'::jsonb,
+    summary jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now()
+);
+
+create index if not exists idx_backtest_runs_model_started_desc
+on backtest_runs (model_code, started_ts desc);
+
+create index if not exists idx_backtest_runs_instr_started_desc
+on backtest_runs (instrument_id, started_ts desc);
+```
+
+---
+
+## 11. 018_create_backtest_results.sql
+
+```sql
+create table if not exists backtest_results (
+    id bigserial primary key,
+    backtest_run_id bigint not null references backtest_runs(id),
+    signal_id bigint references trade_signals(id),
+    outcome text not null,
+    mfe numeric(20,10),
+    mae numeric(20,10),
+    tp1_hit boolean,
+    tp2_hit boolean,
+    invalidated_before_entry boolean,
+    error_tags jsonb not null default '[]'::jsonb,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now()
+);
+
+create index if not exists idx_backtest_results_run_id
+on backtest_results (backtest_run_id);
+
+create index if not exists idx_backtest_results_outcome
+on backtest_results (outcome);
+```
+
+### 可选检查约束
+
+```sql
+alter table backtest_results
+    add constraint backtest_results_outcome_check
+    check (outcome in ('win', 'loss', 'breakeven', 'missed'));
+```
+
+---
+
+## 12. 推荐执行顺序
+
+若第一批 migration 已成功执行，本批建议顺序如下：
+
+1. `011_create_displacement_events.sql`
+2. `012_create_structure_events.sql`
+3. `013_create_fvg_zones.sql`
+4. `014_create_bias_snapshots.sql`
+5. `015_create_trade_signals.sql`
+6. `016_create_trade_executions.sql`
+7. `017_create_backtest_runs.sql`
+8. `018_create_backtest_results.sql`
+
+原因：
+
+- 先把主模型的事件层打通
+- 再把 bias / signal / execution 层打通
+- 最后补 backtest
+
+---
+
+## 13. 第一轮验证 SQL 草案
+
+### 13.1 检查表存在
+
+```sql
+select tablename
+from pg_tables
+where schemaname = 'public'
+  and tablename in (
+    'displacement_events',
+    'structure_events',
+    'fvg_zones',
+    'bias_snapshots',
+    'trade_signals',
+    'trade_executions',
+    'backtest_runs',
+    'backtest_results'
+  )
+order by tablename;
+```
+
+### 13.2 检查外键关系
+
+```sql
+select
+    tc.table_name,
+    kcu.column_name,
+    ccu.table_name as foreign_table_name,
+    ccu.column_name as foreign_column_name
+from information_schema.table_constraints as tc
+join information_schema.key_column_usage as kcu
+  on tc.constraint_name = kcu.constraint_name
+join information_schema.constraint_column_usage as ccu
+  on ccu.constraint_name = tc.constraint_name
+where tc.constraint_type = 'FOREIGN KEY'
+  and tc.table_name in (
+    'structure_events',
+    'fvg_zones',
+    'bias_snapshots',
+    'trade_signals',
+    'trade_executions',
+    'backtest_runs',
+    'backtest_results'
+  )
+order by tc.table_name, kcu.column_name;
+```
+
+---
+
+## 14. 当前结论
+
+这份文档已经把数据库层推进到信号层和回测层的 migration 文件草案粒度。
+
+也就是说，数据库设计现在已经基本完整，覆盖了：
+
+- 基础数据层
+- 基础规则层
+- 事件层
+- 信号层
+- 执行层
+- 回测层
+
+后续若要继续高价值推进，已经不需要再扩数据库文档，而应转入：
+
+1. 项目代码骨架
+2. migration 工具格式化
+3. OKX 数据接入真实实现
+4. Session / Swing / Range 第一轮代码实现
diff --git a/docs/AI_ICT_重复文档清理计划_v1.md b/docs/AI_ICT_重复文档清理计划_v1.md
new file mode 100644
index 0000000..60c2610
--- /dev/null
+++ b/docs/AI_ICT_重复文档清理计划_v1.md
@@ -0,0 +1,217 @@
+# AI ICT 重复文档清理计划 v1
+
+## 1. 文档目标
+
+本文档用于解决当前 `docs/` 目录中出现的重复文档、重复命名和主版本不清的问题，防止后续继续引用混乱。
+
+目标：
+
+1. 列出当前重复/冲突文档
+2. 明确每组文档的 canonical 主版本
+3. 明确待归档/待废弃文件
+4. 给出实际清理顺序
+5. 固定未来不再重复的规则
+
+---
+
+## 2. 当前发现的重复/冲突文档
+
+根据当前 `docs/` 目录，已发现以下重复组：
+
+### 2.1 Migration 主题重复组
+
+#### 文件 A
+`AI_ICT_Migration_拆分计划_v1.md`
+
+#### 文件 B
+`AI_ICT_PostgreSQL_Migration_Split_Plan_v1.md`
+
+问题：
+- 主题高度重合
+- 一个中文命名，一个英文命名
+- 容易导致后续引用时不确定主版本
+
+当前建议：
+- **canonical**：`AI_ICT_Migration_拆分计划_v1.md`
+- **待废弃 / 待归档**：`AI_ICT_PostgreSQL_Migration_Split_Plan_v1.md`
+
+原因：
+- 中文命名已被文档索引明确标记为主版本
+- 该版本更符合当前目录整体命名风格
+
+---
+
+### 2.2 Session 主题重复组
+
+#### 文件 A
+`AI_ICT_Session_生成器规格书_v1.md`
+
+#### 文件 B
+`AI_ICT_Session_Generator_Spec_v1.md`
+
+问题：
+- 属于同一主题的中英文双命名版本
+- 当前主参考文档已明确为中文规格书版本
+- 若继续并存，会导致下游引用混乱
+
+当前建议：
+- **canonical**：`AI_ICT_Session_生成器规格书_v1.md`
+- **待废弃 / 待归档**：`AI_ICT_Session_Generator_Spec_v1.md`
+
+原因：
+- 中文命名已纳入索引体系
+- 与其他模块规格书风格一致
+
+---
+
+## 3. 当前 canonical 文档清单
+
+以下文档应视为当前主引用版本：
+
+- `AI_ICT_总体设计文档_v1.md`
+- `AI_ICT_PostgreSQL_Schema_v1.md`
+- `AI_ICT_MVP_规则规格书_v1.md`
+- `AI_ICT_开发路线图_v1.md`
+- `AI_ICT_执行检查清单_v1.md`
+- `AI_ICT_项目启动清单_v1.md`
+- `AI_ICT_OKX_数据接入规格书_v1.md`
+- `AI_ICT_Session_生成器规格书_v1.md`
+- `AI_ICT_Swing_识别规格书_v1.md`
+- `AI_ICT_Migration_拆分计划_v1.md`
+- `AI_ICT_文档索引与命名规范_v1.md`
+
+这些文件才是后续继续扩展时的主参考对象。
+
+---
+
+## 4. 建议的清理动作
+
+## 4.1 第一阶段：先标记，不立即删除
+
+当前建议先不要直接删除重复文件，而是先完成以下动作：
+
+1. 在索引文档中明确 canonical
+2. 在清理计划中明确 deprecated 文档
+3. 后续新增引用只允许引用 canonical 文档
+
+原因：
+- 当前重复文件可能还承载一部分历史内容
+- 直接删除前，最好先人工确认内容是否真的完全重复
+
+---
+
+## 4.2 第二阶段：移动到 archive 或 deprecated 区
+
+建议后续建立：
+
+```text
+docs/
+  archive/
+```
+
+然后把以下文件移入 archive：
+
+- `AI_ICT_PostgreSQL_Migration_Split_Plan_v1.md`
+- `AI_ICT_Session_Generator_Spec_v1.md`
+
+或改名为：
+
+- `DEPRECATED_AI_ICT_PostgreSQL_Migration_Split_Plan_v1.md`
+- `DEPRECATED_AI_ICT_Session_Generator_Spec_v1.md`
+
+说明：
+- 使用 archive 子目录比直接删除更稳妥
+- 当前阶段更推荐 archive，而不是物理删除
+
+---
+
+## 4.3 第三阶段：统一索引引用
+
+完成 archive 后，应同步更新：
+
+- `AI_ICT_文档索引与命名规范_v1.md`
+
+使其明确：
+
+- active docs
+- archived docs
+- deprecated docs
+
+---
+
+## 5. 建议的清理执行顺序
+
+建议按以下顺序进行：
+
+### Step 1
+保留所有文件不删，只明确 canonical
+
+### Step 2
+建立 `docs/archive/`
+
+### Step 3
+将重复英文版本移入 `archive/`
+
+### Step 4
+更新索引文档中的路径与状态
+
+### Step 5
+后续所有新增文档只允许一个 canonical 名称
+
+---
+
+## 6. 未来避免重复的规则
+
+从现在开始，新增文档必须遵守以下规则：
+
+### 规则 1：单主题只允许一个主文件名
+同一主题只保留一个 canonical 名称，不允许再额外起一个英文同义名或中文同义名。
+
+### 规则 2：更新版本用 v2，不重起新文件名
+如果某主题要升级：
+
+- 正确做法：`..._v2.md`
+- 错误做法：再新建一个不同命名的同义文件
+
+### 规则 3：先查索引，再写文档
+新增文档前，必须先检查：
+
+- `AI_ICT_文档索引与命名规范_v1.md`
+
+确认没有现成同主题主文件。
+
+### 规则 4：英文文件名只在必要时统一采用全英文体系
+若未来要切全英文命名，必须统一迁移整个体系，不能中英混杂逐个漂移。
+
+---
+
+## 7. 当前不建议直接删除的原因
+
+当前阶段不建议直接删除重复文件，原因是：
+
+1. 可能仍有历史内容差异
+2. 当前更需要先稳定文档主线
+3. 立即删除属于可逆性较低操作，应该在确认后做
+
+所以当前最合理策略是：
+
+- 先标记
+- 再归档
+- 最后如有必要再删除
+
+---
+
+## 8. 当前结论
+
+当前 `docs/` 目录已经形成主干体系，但出现了两组明显重复文档：
+
+1. Migration 主题重复
+2. Session 主题重复
+
+当前统一策略如下：
+
+- 主版本继续保留中文 canonical 文档
+- 英文重复命名版本后续进入 archive
+- 今后新增文档只允许单主题单主名称
+
+本文件应作为后续文档清理与去重的直接执行依据。
\ No newline at end of file
diff --git a/docs/AI_ICT_项目代码骨架规范_v1.md b/docs/AI_ICT_项目代码骨架规范_v1.md
new file mode 100644
index 0000000..086dcda
--- /dev/null
+++ b/docs/AI_ICT_项目代码骨架规范_v1.md
@@ -0,0 +1,492 @@
+# AI ICT 项目代码骨架规范 v1
+
+## 1. 文档目标
+
+本文档定义 AI ICT 项目第一阶段的代码骨架与模块组织方式，用于把前面已经完成的设计文档、规则规格和 migration 草案落到一个可持续开发的工程结构中。
+
+目标：
+
+1. 固定项目目录结构
+2. 明确各模块职责边界
+3. 明确配置与运行入口
+4. 明确第一波实现顺序
+5. 避免后续实现过程中代码散落、边界混乱
+
+---
+
+## 2. 项目骨架设计原则
+
+### 原则 1：先基础共享模块
+优先落地会被后续模块反复依赖的内容：
+
+- config
+- db
+- market-data
+- sessions
+- swings
+- ranges
+
+### 原则 2：按数据流组织，而不是按零散术语组织
+优先围绕主链路组织模块：
+
+`Candles -> Sessions -> Swings -> Ranges -> Liquidity -> Sweep -> Displacement -> MSS -> FVG -> Signal`
+
+### 原则 3：规则层与执行层分离
+- 规则层负责“识别事实”
+- 信号层负责“组合条件”
+- 执行层负责“风险表达与下单”
+
+### 原则 4：AI 说明层后置
+AI 报告模块只消费结构化结果，不参与底层真值判定。
+
+---
+
+## 3. 推荐项目目录
+
+建议项目根目录结构如下：
+
+```text
+ai-ict/
+  docs/
+  migrations/
+  seeds/
+  scripts/
+  src/
+    config/
+    db/
+    models/
+    repositories/
+    services/
+      market_data/
+      sessions/
+      swings/
+      ranges/
+      liquidity/
+      sweeps/
+      displacement/
+      structure/
+      fvg/
+      bias/
+      signals/
+      execution/
+      backtest/
+      reports/
+    domain/
+    api/
+    utils/
+    main.py
+  tests/
+    unit/
+    integration/
+    fixtures/
+  .env.example
+  pyproject.toml
+  README.md
+```
+
+说明：
+
+- `docs/` 用于保存当前这些长期参考文档
+- `migrations/` 保存正式 migration 文件
+- `seeds/` 保存初始化数据
+- `scripts/` 保存一次性导入、补数、维护任务
+
+---
+
+## 4. 模块职责划分
+
+## 4.1 config/
+
+职责：
+
+- 读取环境变量
+- 管理 PostgreSQL 配置
+- 管理 OKX 配置
+- 管理 session 配置
+- 管理 timeframe 配置
+- 管理阈值参数配置
+
+建议文件：
+
+- `settings.py`
+- `database.py`
+- `okx.py`
+- `sessions.py`
+- `thresholds.py`
+
+---
+
+## 4.2 db/
+
+职责：
+
+- 数据库连接
+- session factory
+- migration 工具接入点
+- 基础 SQL 辅助
+
+建议文件：
+
+- `engine.py`
+- `session.py`
+- `base.py`
+
+---
+
+## 4.3 models/
+
+职责：
+
+- 定义 ORM 模型或数据表映射
+
+建议第一阶段覆盖：
+
+- `venue.py`
+- `instrument.py`
+- `candle.py`
+- `market_session.py`
+- `swing.py`
+- `dealing_range.py`
+- `liquidity_pool.py`
+- `displacement_event.py`
+- `structure_event.py`
+- `fvg_zone.py`
+- `bias_snapshot.py`
+- `trade_signal.py`
+- `trade_execution.py`
+- `backtest_run.py`
+- `backtest_result.py`
+
+---
+
+## 4.4 repositories/
+
+职责：
+
+- 屏蔽底层数据库读写细节
+- 为 services 提供统一数据访问接口
+
+建议：
+
+- 一个核心实体一个 repository
+- 不在 service 里到处写原始 SQL
+
+例如：
+
+- `candle_repository.py`
+- `session_repository.py`
+- `swing_repository.py`
+- `range_repository.py`
+
+---
+
+## 4.5 services/
+
+这是项目主核心。
+
+### market_data/
+职责：
+- OKX 历史补数
+- OKX 增量同步
+- 原始对象转标准 candle
+- 入库
+
+### sessions/
+职责：
+- UTC -> 纽约时间转换
+- session 切分
+- high / low / midpoint 生成
+- 写入 `market_sessions`
+
+### swings/
+职责：
+- ST / IT / LT swing 识别
+- confirmed / provisional 处理
+
+### ranges/
+职责：
+- active range 选择
+- equilibrium 计算
+- premium / discount 标记
+
+### liquidity/
+职责：
+- prior highs / lows
+- equal highs / lows
+- session highs / lows
+- pool 状态管理
+
+### sweeps/
+职责：
+- pool 刺穿检测
+- weak / validated sweep
+- close back inside
+
+### displacement/
+职责：
+- body_ratio
+- 推进性
+- has_fvg
+- strength_score
+
+### structure/
+职责：
+- MSB
+- MSS
+- acceptance
+- displacement 关联
+
+### fvg/
+职责：
+- bullish / bearish FVG
+- fill_pct
+- mitigation / invalidation
+
+### bias/
+职责：
+- higher timeframe bias
+- execution_intensity
+- reason_codes
+
+### signals/
+职责：
+- `SWEEP_MSS_FVG` 模型组合
+- invalidation 条件
+- RR 过滤
+- session 过滤
+
+### execution/
+职责：
+- paper trading
+- semi-auto execution
+- risk engine
+
+### backtest/
+职责：
+- backtest run
+- mfe / mae
+- outcome tags
+
+### reports/
+职责：
+- pre-market
+- intraday explanation
+- post-trade review
+
+---
+
+## 4.6 domain/
+
+职责：
+
+- 放与业务含义强相关、但不直接依赖数据库的对象定义
+- 如 enums、状态机、共享 schema
+
+建议内容：
+
+- `timeframes.py`
+- `sessions.py`
+- `signal_status.py`
+- `pool_status.py`
+- `event_types.py`
+
+---
+
+## 4.7 api/
+
+职责：
+
+- 暴露查询与控制接口
+
+第一阶段可先保留轻量 API：
+
+- `health.py`
+- `candles.py`
+- `sessions.py`
+- `signals.py`
+- `backtest.py`
+
+说明：
+
+- 第一阶段 API 不必过重
+- 先服务内部开发和调试即可
+
+---
+
+## 4.8 utils/
+
+职责：
+
+- 公共工具函数
+
+例如：
+
+- 时间转换
+- 数值精度处理
+- 批量分片工具
+- 日志包装
+
+原则：
+
+- 不要过度抽象
+- 仅放明确被多个模块复用的内容
+
+---
+
+## 5. 运行入口建议
+
+## 5.1 主入口
+
+建议保留一个明确主入口：
+
+- `src/main.py`
+
+职责：
+
+- 加载配置
+- 初始化数据库连接
+- 启动 API 或任务调度入口
+
+---
+
+## 5.2 脚本入口
+
+第一阶段建议把任务型入口放在 `scripts/` 下，例如：
+
+- `run_okx_backfill.py`
+- `run_session_generator.py`
+- `run_swings.py`
+- `run_ranges.py`
+- `run_liquidity.py`
+
+说明：
+
+- 第一阶段用脚本驱动模块非常合适
+- 不必一开始就做复杂编排平台
+
+---
+
+## 6. 配置文件建议
+
+建议准备：
+
+### `.env.example`
+包含：
+
+- `DATABASE_URL`
+- `OKX_BASE_URL`
+- `OKX_TIMEOUT`
+- `DEFAULT_TIMEZONE`
+- `SESSION_TIMEZONE`
+- `LOG_LEVEL`
+
+### `src/config/sessions.py`
+包含：
+
+- ASIA
+- LONDON
+- NY_AM
+- NY_LUNCH
+- NY_PM
+
+### `src/config/thresholds.py`
+包含：
+
+- equal highs / lows 阈值
+- displacement 阈值
+- FVG 最小宽度过滤阈值
+- equilibrium 缓冲带阈值
+
+---
+
+## 7. 第一波实现顺序
+
+建议严格按以下顺序开始写代码：
+
+### Step 1
+- config/
+- db/
+- models/
+- migrations/
+
+### Step 2
+- market_data/
+- scripts/run_okx_backfill.py
+
+### Step 3
+- sessions/
+- scripts/run_session_generator.py
+
+### Step 4
+- swings/
+- scripts/run_swings.py
+
+### Step 5
+- ranges/
+- scripts/run_ranges.py
+
+### Step 6
+- liquidity/
+- scripts/run_liquidity.py
+
+说明：
+
+- 到 Step 6，第一条基础规则链就真正跑起来了
+- 后面再继续写 sweep / displacement / MSS / FVG
+
+---
+
+## 8. 测试结构建议
+
+### unit/
+每个核心模块一组单元测试：
+
+- `test_market_data.py`
+- `test_sessions.py`
+- `test_swings.py`
+- `test_ranges.py`
+- `test_liquidity.py`
+
+### integration/
+跨模块流程测试：
+
+- OKX backfill -> candles
+- candles -> sessions
+- sessions -> swings -> ranges
+
+### fixtures/
+- 样本 candles
+- 样本 session 数据
+- 样本 swing 数据
+
+---
+
+## 9. 第一阶段“可运行”定义
+
+第一阶段不是把全部系统写完，而是先做到：
+
+1. 数据库可初始化
+2. OKX 数据可入库
+3. sessions 可生成
+4. swings 可生成
+5. dealing range 可生成
+6. liquidity pools 可生成
+
+只要做到这 6 项，项目就已经从“文档阶段”跨进“真实运行阶段”。
+
+---
+
+## 10. 当前结论
+
+本代码骨架规范的作用，是把前面已经完成的大量文档收束成一个可持续实现的工程结构。
+
+到这里为止，你已经拥有：
+
+- 设计文档
+- 规格文档
+- migration 草案
+- 代码骨架规范
+
+这意味着下一步已经不该再停留在继续补外围文档，而是可以直接进入：
+
+`建项目骨架 -> 写 migration -> 接 OKX -> 跑 sessions -> 跑 swings -> 跑 dealing range -> 跑 liquidity`
diff --git a/docs/AI_ICT_项目启动清单_v1.md b/docs/AI_ICT_项目启动清单_v1.md
new file mode 100644
index 0000000..61414b4
--- /dev/null
+++ b/docs/AI_ICT_项目启动清单_v1.md
@@ -0,0 +1,250 @@
+# AI ICT 项目启动清单 v1
+
+## 1. 文档目标
+
+本文档用于指导 AI ICT 项目从方案阶段正式进入第一轮真实开发，确保启动工作按顺序落地，不出现“准备了很多文档，但没有真正开始实现”的情况。
+
+本清单聚焦第一波基础共享模块：
+
+1. 项目骨架
+2. PostgreSQL 初始化
+3. OKX 数据接入
+4. Session 生成器
+5. Swing / Range 第一版
+
+---
+
+## 2. 启动阶段总原则
+
+### 原则 1：先做基础共享模块
+优先实现会被后续全部规则复用的模块：
+
+- config
+- db
+- candles
+- sessions
+- swings
+- ranges
+
+### 原则 2：每一步都必须可验证
+每完成一个模块，至少产出以下之一：
+
+- 本地文件
+- 数据库对象
+- 可运行命令
+- 测试结果
+- 样本输出
+
+### 原则 3：先 OKX，后 LMAX
+第一轮只优先打通 BTC / ETH，XAU 的 LMAX 接入放在第二顺位。
+
+---
+
+## 3. 启动顺序
+
+## Step 1：创建项目代码骨架
+
+### 目标
+建立可持续开发的项目基础结构。
+
+### 检查项
+- [ ] 初始化项目目录结构
+- [ ] 创建 `config/`
+- [ ] 创建 `db/`
+- [ ] 创建 `services/market-data/`
+- [ ] 创建 `services/rule-engine/`
+- [ ] 创建 `services/signal/`
+- [ ] 创建 `risk/`
+- [ ] 创建 `backtest/`
+- [ ] 创建 `api/`
+- [ ] 创建基础 `utils/`
+
+### 完成标准
+- [ ] 项目可以本地启动一个空入口
+- [ ] 配置文件可以加载
+- [ ] 日志可以输出
+
+---
+
+## Step 2：初始化 PostgreSQL
+
+### 目标
+建立基础数据库对象。
+
+### 优先建表顺序
+1. `venues`
+2. `instruments`
+3. `candles`
+4. `market_sessions`
+5. `swings`
+6. `dealing_ranges`
+7. `liquidity_pools`
+
+### 检查项
+- [ ] PostgreSQL 连接配置已建立
+- [ ] migration 目录已建立
+- [ ] 第一版 schema 已拆分成 migration
+- [ ] 建表顺序已固定
+- [ ] 主键和唯一键已定义
+- [ ] candles 分区策略已确定
+
+### 完成标准
+- [ ] 本地数据库可完成初始化
+- [ ] 所有基础表存在
+- [ ] candles 唯一键可生效
+
+---
+
+## Step 3：初始化品种元数据
+
+### 目标
+建立首批交易对象配置。
+
+### 首批对象
+- [ ] OKX BTC
+- [ ] OKX ETH
+- [ ] LMAX XAU（先可预留，后接真实数据）
+
+### 检查项
+- [ ] venue 元数据已插入
+- [ ] instrument 元数据已插入
+- [ ] tick_size 已定义
+- [ ] lot_size 已定义
+- [ ] price_scale 已定义
+
+### 完成标准
+- [ ] 所有首批 instrument 可被程序查询
+
+---
+
+## Step 4：接入 OKX 行情
+
+### 目标
+打通第一条真实数据链路。
+
+### 检查项
+- [ ] 明确 OKX K 线接口
+- [ ] 实现历史 K 线抓取
+- [ ] 实现增量 K 线抓取
+- [ ] 做字段标准化映射
+- [ ] 入库 `candles`
+- [ ] 增加去重逻辑
+
+### 第一轮时间框架
+- [ ] 1m
+- [ ] 5m
+- [ ] 15m
+- [ ] 1h
+- [ ] 4h
+
+### 完成标准
+- [ ] BTC 可写入多周期 candles
+- [ ] ETH 可写入多周期 candles
+- [ ] 指定时间范围可查到连续数据
+
+---
+
+## Step 5：实现 Session 生成器
+
+### 目标
+从 candles 自动生成会话边界和 pivot。
+
+### 默认时区
+- `America/New_York`
+
+### 默认会话
+- [ ] ASIA
+- [ ] LONDON
+- [ ] NY_AM
+- [ ] NY_LUNCH
+- [ ] NY_PM
+
+### 检查项
+- [ ] session 切分逻辑已实现
+- [ ] high / low 计算已实现
+- [ ] midpoint 计算已实现
+- [ ] session 数据写入 `market_sessions`
+
+### 完成标准
+- [ ] 指定日期能生成完整 session 数据
+- [ ] session high/low 与图表人工抽查一致
+
+---
+
+## Step 6：实现 Swing 第一版
+
+### 目标
+建立结构高低点基础识别。
+
+### 检查项
+- [ ] swing high 识别
+- [ ] swing low 识别
+- [ ] confirmed / provisional 区分
+- [ ] M5 参数已配置
+- [ ] M15 参数已配置
+- [ ] H1 参数已配置
+
+### 完成标准
+- [ ] 至少一个品种多周期 swing 可生成
+- [ ] 样本人工抽查合理
+
+---
+
+## Step 7：实现 Dealing Range 第一版
+
+### 目标
+生成 working range 与位置标签。
+
+### 检查项
+- [ ] range high / low 生成
+- [ ] equilibrium 计算
+- [ ] premium / discount / equilibrium 判定
+- [ ] 当前主 range 可查询
+
+### 完成标准
+- [ ] 给定价格可判断位置
+- [ ] range 与 swing 关联可追溯
+
+---
+
+## 4. 第一轮验证里程碑
+
+完成以下条件后，才算真正进入“规则开发期”：
+
+- [ ] BTC / ETH candles 已持续入库
+- [ ] session 已可稳定生成
+- [ ] swings 已可查询
+- [ ] range 已可查询
+- [ ] 当前 price location 已可查询
+
+只有这五项成立，后面再进入：
+
+- liquidity pools
+- sweep
+- displacement
+- MSS
+- FVG
+
+---
+
+## 5. 启动阶段推荐输出物
+
+启动阶段至少应新增这些真实产物：
+
+1. 项目目录骨架
+2. migration 文件
+3. PostgreSQL 连接模块
+4. OKX candles 抓取模块
+5. session 生成器
+6. swings 识别模块
+7. dealing range 识别模块
+
+---
+
+## 6. 当前结论
+
+AI ICT 项目从现在开始，真正的“第一锹土”不是写更多概念，而是完成下面这条真实链路：
+
+`PostgreSQL -> OKX Candles -> Sessions -> Swings -> Dealing Range`
+
+只要这条链路打通，后续 liquidity / sweep / MSS / FVG / signal 才有稳定基础。
\ No newline at end of file
diff --git a/docs/AI_协作自动化工作规程_v1.md b/docs/AI_协作自动化工作规程_v1.md
new file mode 100644
index 0000000..5666dd9
--- /dev/null
+++ b/docs/AI_协作自动化工作规程_v1.md
@@ -0,0 +1,338 @@
+# AI 协作自动化工作规程 v1
+
+## 1. 文档目标
+
+本文档用于总结本次 AI ICT 项目协作中被验证有效的自动化协作规则，形成一套可复用的“AI 自动执行工作规程”。
+
+目标：
+
+1. 固化本次有效的自动化执行经验
+2. 让后续项目能够直接复用这些规则
+3. 避免再次出现“口头上自动、实际却经常停下”的情况
+4. 让 AI 在复杂工程任务中稳定进入产物驱动模式
+
+---
+
+## 2. 核心结论
+
+本次协作中最有效的转折，不是“要求 AI 自动一点”，而是把自动化要求从模糊偏好，变成了可执行规则。
+
+也就是说，真正有效的不是：
+
+- 更积极
+- 更自动
+- 少停一点
+
+而是以下这类明确规则：
+
+- 不要只说开始，要真正推进
+- 只有文件写入并检查后才算完成
+- 大任务必须拆成小任务
+- 做完一个直接做下一个
+- 同一个阻塞不要重复卡住
+- 除非不可逆操作或缺外部资源，否则不要停
+
+---
+
+## 3. 从“状态驱动”切到“产物驱动”
+
+这是最关键的一条。
+
+### 3.1 低效模式：状态驱动
+
+典型表现：
+
+- 任务显示 in_progress
+- 口头说已开始
+- 频繁汇报计划
+- 但没有真实文件、代码或验证结果产出
+
+这种模式会让人感觉：
+
+> 看起来在忙，但实际上没有推进
+
+---
+
+### 3.2 高效模式：产物驱动
+
+正确模式应当是：
+
+- 文档任务 -> 写出真实 `.md`
+- 代码任务 -> 写出真实 `.py` / `.sql`
+- 校验任务 -> 给出真实检查结果
+- 每完成一步都必须有可见产物
+
+原则：
+
+> 没有产物，就不算推进。
+
+---
+
+## 4. 自动化执行的 8 条核心规则
+
+## 规则 1：任务必须拆小
+
+不要保留大而空的任务，例如：
+
+- 设计整个系统
+- 搭建所有功能
+- 处理后续工作
+
+应该拆成：
+
+- 写总体设计文档
+- 写 schema 文档
+- 写 OKX 接入规格书
+- 写 session generator
+- 写 swing service
+
+原则：
+
+- 每个任务都必须短、具体、可执行
+- 每个任务都要能在一个工作单元中拿出产物
+
+---
+
+## 规则 2：只在“写完并检查后”汇报完成
+
+错误方式：
+
+- 我开始写了
+- 我正在做
+- 我已经启动下一步
+
+正确方式：
+
+- 文件已经写入本地
+- 已经检查文件存在
+- 已经抽样读取内容
+- 然后再汇报
+
+原则：
+
+> 汇报完成的前提必须是“产物已存在”。
+
+---
+
+## 规则 3：除了必要阻塞，不要停下等待指示
+
+默认执行规则应为：
+
+- 做完当前任务
+- 自动进入下一任务
+- 直到遇到真正需要用户决策的事情才停
+
+真正允许停下的情况：
+
+1. 不可逆操作
+2. 缺少外部资源
+3. 缺少权限
+4. 需要明确产品决策
+
+除此以外，不应把调度权频繁交回用户。
+
+---
+
+## 规则 4：同一个阻塞不要重复两次
+
+如果同一种阻塞连续出现两次，且没有新产物、新验证、新任务推进，就不能继续停留在原地。
+
+应立即：
+
+- 重拆任务
+- 换一种推进路径
+- 先做旁边可落地的子任务
+
+例如：
+
+- 某个文件目录不存在 -> 立刻改成先让用户建目录或改到已有目录
+- 某个 `__init__.py` 更新被写入保护拦住 -> 先读再改，不继续卡住
+
+原则：
+
+> 同一阻塞重复两次后，必须换打法。
+
+---
+
+## 规则 5：里程碑更新要短，但不能替代执行
+
+更新是必要的，但不能变成“只有汇报，没有推进”。
+
+好的更新格式：
+
+- 已写入哪些文件
+- 已检查哪些文件
+- 下一步会继续推进什么
+
+不好的更新格式：
+
+- 我正在进行中
+- 我马上开始
+- 我会继续做
+
+原则：
+
+> 更新只能说明进展，不能替代进展本身。
+
+---
+
+## 规则 6：优先从基础共享模块开始
+
+对复杂系统，最容易出问题的是太早冲到上层功能。
+
+正确顺序应该是：
+
+1. 配置
+2. DB
+3. 基础模型
+4. migration
+5. 数据接入
+6. session
+7. swing
+8. range
+9. liquidity
+10. events
+11. signal
+12. execution
+
+原则：
+
+> 先把所有后续模块共享依赖打牢，再往上走。
+
+---
+
+## 规则 7：并行只用于真正独立的任务
+
+适合并行的：
+
+- 两份互不依赖的文档
+- 两个互不影响的检查任务
+- 目录创建 + 配置文件写入
+
+不适合并行的：
+
+- 同一文件链上的连续写入
+- 依赖前一步结果的任务
+- 需要共享上下文的顺序实现
+
+原则：
+
+> 并行是为了提速，不是为了制造混乱。
+
+---
+
+## 规则 8：当进入实现阶段后，优先写真实文件而不是继续扩文档
+
+文档足够以后，必须切换到：
+
+- 真实目录
+- 真实配置
+- 真实模型
+- 真实 migration
+- 真实脚本
+- 真实服务
+
+否则会停留在“文档很全，但工程没启动”的假进展状态。
+
+原则：
+
+> 文档只服务于实现，不能替代实现。
+
+---
+
+## 5. 本次实践中验证有效的工作模式
+
+本次实践中，下面这种模式被证明最有效：
+
+### Step 1
+创建任务
+
+### Step 2
+立即进入实际写文件/写代码
+
+### Step 3
+写完后立刻本地检查：
+- 是否存在
+- 是否可读
+- 是否抽样正常
+
+### Step 4
+更新任务完成状态
+
+### Step 5
+直接进入下一任务
+
+这个闭环一旦形成，自动化就会很稳。
+
+---
+
+## 6. 文档类任务的标准流程
+
+1. 明确主题
+2. 直接写 `.md`
+3. 读回前几十行检查
+4. 再汇报完成
+5. 继续下一份文档
+
+关键原则：
+
+- 不先说“开始写”
+- 只在“写完+检查完”后说完成
+
+---
+
+## 7. 代码类任务的标准流程
+
+1. 明确模块边界
+2. 直接落文件
+3. 若更新已有文件，先读后改
+4. 检查文件存在
+5. 抽样读代码
+6. 再汇报完成
+7. 进入下一个模块
+
+关键原则：
+
+- 以代码文件为产物
+- 以检查结果为结束条件
+
+---
+
+## 8. 为什么这套方式后来明显变好了
+
+因为后期已经形成了稳定闭环：
+
+- 小任务
+- 真产物
+- 本地检查
+- 简短汇报
+- 立即继续
+
+所以后面看起来就像“真正开始自动运转了”。
+
+不是因为 AI 自己突然变了，而是因为协作规则被固定成了可执行工作规程。
+
+---
+
+## 9. 后续项目推荐直接复用的默认规程
+
+以后如要快速进入这种高自动化协作模式，建议默认使用下面这组规则：
+
+1. 默认 autonomy-first
+2. 任务必须拆小
+3. 只在写完并检查后汇报
+4. 不允许任务空挂
+5. 同一阻塞不要重复两次
+6. 先做共享基础模块
+7. 文档够了就切到真实代码
+8. 做完一个自动进入下一个
+
+---
+
+## 10. 当前结论
+
+本文件沉淀的最重要经验是：
+
+> 自动化协作真正有效，不靠“更积极一点”，而靠“把推进规则具体化、产物化、可验证化”。
+
+以后只要沿用这份规程，AI 在复杂工程任务中的自动执行稳定性会明显更高。
\ No newline at end of file
diff --git a/docs/AI_自动化协作迁移清单_v1.md b/docs/AI_自动化协作迁移清单_v1.md
new file mode 100644
index 0000000..682d717
--- /dev/null
+++ b/docs/AI_自动化协作迁移清单_v1.md
@@ -0,0 +1,239 @@
+# AI 自动化协作迁移清单 v1
+
+## 1. 文档目标
+
+本文档用于把本次已经验证有效的 Claude Code 自动化协作方式迁移到另一台电脑或另一个项目里，尽量做到开箱即用。
+
+目标：
+
+1. 明确哪些文件必须复制
+2. 明确这些文件要放到哪里
+3. 明确新项目第一次如何初始化
+4. 明确 memory 文件是否需要一起迁移
+5. 让跨电脑迁移成本最小化
+
+---
+
+## 2. 迁移的核心原则
+
+这套自动化模式想稳定复现，不能只靠“口头告诉 AI 自动一点”。
+
+必须至少把以下三层一起迁移：
+
+1. **项目规则层**：`CLAUDE.md`
+2. **协作说明层**：自动化工作规程文档
+3. **偏好层**：关键 memory 文件
+
+三层作用不同：
+
+- `CLAUDE.md`：负责在项目内直接生效
+- 工作规程文档：负责解释为什么这样做、怎么做
+- memory 文件：负责把偏好延续到后续会话
+
+---
+
+## 3. 必须复制的文件
+
+## 3.1 首要文件：CLAUDE.md
+
+在目标项目根目录放置：
+
+- `CLAUDE.md`
+
+来源建议：
+
+- 直接使用 `标准_CLAUDE_md_模板_v1.md` 的内容
+- 复制后改名为 `CLAUDE.md`
+
+目标位置：
+
+```text
+<目标项目根目录>/CLAUDE.md
+```
+
+这是最关键的一步。
+
+如果只做一件事，就做这件事。
+
+---
+
+## 3.2 协作规程文档
+
+建议一并复制：
+
+- `AI_协作自动化工作规程_v1.md`
+
+目标位置建议：
+
+```text
+<目标项目根目录>/docs/AI_协作自动化工作规程_v1.md
+```
+
+作用：
+
+- 供你和 AI 随时参考
+- 当协作节奏漂移时，可以快速拉回到统一规程
+
+---
+
+## 3.3 迁移清单文档本身
+
+建议也复制：
+
+- `AI_自动化协作迁移清单_v1.md`
+
+目标位置建议：
+
+```text
+<目标项目根目录>/docs/AI_自动化协作迁移清单_v1.md
+```
+
+作用：
+
+- 以后再次迁移时直接复用
+
+---
+
+## 4. 建议复制的 memory 文件
+
+不建议无脑复制整个 memory 文件夹。
+
+建议只复制与“协作方式”强相关的文件。
+
+### 推荐复制
+
+- `feedback_autonomy_first_execution.md`
+- `feedback_local_docs_preference.md`
+
+如果对方电脑也使用 Claude Code memory 机制，可以放到对方项目对应的 memory 目录。
+
+如果你不清楚对方机器的 memory 路径，至少先保留这两份文件原文，后续再落到对应目录。
+
+---
+
+## 5. 不建议整包复制的内容
+
+以下内容一般不建议整包搬运：
+
+1. 整个 memory 文件夹
+2. 当前项目专用业务文档
+3. 与当前项目强绑定的数据库/规则实现细节
+4. 临时任务状态文件
+
+原因：
+
+- 可能把别的项目上下文污染过去
+- 会把不适合新项目的历史偏好一起带过去
+
+原则：
+
+> 迁移协作方式，不等于迁移整个历史上下文。
+
+---
+
+## 6. 新电脑/新项目最小落地步骤
+
+如果你要在另一台电脑上快速复现这套模式，最少做这 4 步：
+
+### Step 1
+在目标项目根目录创建：
+
+- `CLAUDE.md`
+
+内容使用：
+- `标准_CLAUDE_md_模板_v1.md`
+
+### Step 2
+在目标项目下创建 `docs/` 目录，并放入：
+
+- `AI_协作自动化工作规程_v1.md`
+- `AI_自动化协作迁移清单_v1.md`
+
+### Step 3
+如果支持 memory，补上：
+
+- `feedback_autonomy_first_execution.md`
+- `feedback_local_docs_preference.md`
+
+### Step 4
+在第一次对话时明确一句：
+
+> 按 CLAUDE.md 和自动化工作规程执行，采用 autonomy-first、产物驱动、只在写完并检查后汇报的模式。
+
+这句会帮助新会话快速收敛到正确模式。
+
+---
+
+## 7. 最稳妥的迁移方式
+
+推荐你以后统一使用以下结构：
+
+```text
+<目标项目>/
+  CLAUDE.md
+  docs/
+    AI_协作自动化工作规程_v1.md
+    AI_自动化协作迁移清单_v1.md
+```
+
+如果还要加 memory，则额外在 Claude Code 的项目 memory 目录里放：
+
+- `feedback_autonomy_first_execution.md`
+- `feedback_local_docs_preference.md`
+
+这样就形成：
+
+- 项目内规则
+- 项目内说明
+- 会话级偏好
+
+三层闭环。
+
+---
+
+## 8. 新项目第一次启动时推荐说法
+
+你在新电脑的新项目里，第一次可以直接对 Claude Code 说：
+
+```text
+请严格按项目里的 CLAUDE.md 和 docs/AI_协作自动化工作规程执行。
+默认采用 autonomy-first、产物驱动模式：
+- 不要只汇报开始
+- 只有写完并本地检查后才汇报完成
+- 大任务拆小
+- 除非不可逆操作/缺资源/需要产品决策，否则不要停下等我分配
+- 做完一个直接接下一个
+```
+
+这句话非常有效。
+
+---
+
+## 9. 如果只想迁移最核心的一样东西
+
+如果你懒得搬太多，优先级如下：
+
+### 第一优先级
+- `CLAUDE.md`
+
+### 第二优先级
+- `AI_协作自动化工作规程_v1.md`
+
+### 第三优先级
+- 两个关键 memory 文件
+
+也就是说：
+
+> 只传一份文档，不如先把 `CLAUDE.md` 真正放到项目根目录。
+
+---
+
+## 10. 当前结论
+
+跨电脑复用这套自动化协作方式，最佳做法不是只传一份说明文档，而是：
+
+1. 把标准模板落成目标项目的 `CLAUDE.md`
+2. 把自动化工作规程文档放进目标项目 `docs/`
+3. 按需补关键 memory 偏好文件
+
+这样你在新电脑上最容易复现本次这种“真正不空转、能持续产生产物”的自动化协作效果。
diff --git a/docs/CLAUDE_template_autonomy_first.md b/docs/CLAUDE_template_autonomy_first.md
new file mode 100644
index 0000000..00e2205
--- /dev/null
+++ b/docs/CLAUDE_template_autonomy_first.md
@@ -0,0 +1,225 @@
+# CLAUDE.md Template
+
+Use this file as a starting `CLAUDE.md` for other repositories. Replace the placeholders and keep the execution rules unless the project needs stricter constraints.
+
+---
+
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working in this repository.
+
+## Project Overview
+
+- Project: `<project name>`
+- Goal: `<one-paragraph summary of what the repo does>`
+- Primary stack: `<languages / runtime / framework / package manager>`
+- Main quality gate: `<tests / typecheck / lint command that must pass>`
+
+## Commands
+
+```bash
+# Install dependencies
+<install command>
+
+# Start dev mode
+<dev command>
+
+# Run tests
+<test command>
+
+# Run typecheck
+<typecheck command>
+
+# Run lint / format
+<lint command>
+<format command>
+```
+
+## Collaboration Mode
+
+Default to autonomy-first execution.
+
+After the task is clear:
+- proactively plan
+- implement directly
+- test and verify
+- continue to the next concrete task without routine confirmation
+
+Only stop and ask the user when you hit one of these:
+1. an irreversible or high-blast-radius action
+2. missing external credentials, services, or permissions
+3. a real product decision with multiple valid directions
+4. a blocker that cannot be resolved by reading code, running checks, or changing local files
+
+## Core Working Rules
+
+### 1. Prefer product over status
+Do not treat `in_progress` as progress.
+A task counts as progress only when there is a real artifact such as:
+- edited code
+- written docs
+- created config
+- migration file
+- test result
+- verification result
+
+Rule:
+- no artifact, no completion report
+
+### 2. Break work into small executable tasks
+For any non-trivial request, split the work into small tasks that each produce an inspectable result.
+
+Good task examples:
+- add repository method for loading candles
+- create migration for sweep events
+- wire runner script for session generation
+- verify new script imports cleanly
+
+Bad task examples:
+- build the whole system
+- finish the backend
+- handle remaining work
+
+### 3. Finish one concrete step, then immediately start the next
+After completing a task:
+- mark it complete
+- summarize the concrete result briefly
+- start the next highest-value unblocked task
+
+Do not wait for permission between normal reversible steps.
+
+### 4. Do not repeat the same blocker twice
+If the same blocker appears twice without any new artifact or validation progress, stop looping.
+Immediately do one of:
+- change the approach
+- split the task smaller
+- work on an adjacent unblocked dependency
+- surface the true blocker clearly
+
+Rule:
+- never stay in a stale loop
+
+### 5. Keep milestone updates short and factual
+Progress updates should say:
+- what was written or changed
+- what was verified
+- what is next
+
+Avoid empty updates like:
+- "working on it"
+- "starting now"
+- "continuing"
+
+### 6. Parallelize only truly independent work
+Use parallel work only when tasks do not share the same dependency chain.
+
+Good parallel cases:
+- two unrelated docs
+- independent read-only inspections
+- separate file checks
+
+Bad parallel cases:
+- multiple edits in the same file chain
+- steps that depend on previous output
+- intertwined refactors sharing context
+
+### 7. Prefer shared foundations before upper layers
+When building systems, usually work in this order unless the user says otherwise:
+1. config
+2. database / schema
+3. core models
+4. repositories
+5. services
+6. entry scripts / APIs
+7. downstream features
+
+This reduces rework.
+
+### 8. Switch from docs to implementation as soon as the design is sufficient
+Once the spec is clear enough, stop expanding docs and write the real files.
+Docs support implementation; they do not replace it.
+
+## Verification Rules
+
+Before reporting a task complete:
+- confirm the target file exists
+- read back the important file sections you changed
+- run the narrowest relevant check first
+- prefer direct runnable validation over purely descriptive claims
+
+Examples:
+- compile the changed Python files
+- run the changed script
+- run a focused test file
+- read the migration or config back after writing it
+
+If verification is blocked by environment issues, say so explicitly and separate:
+- code is ready
+- environment is not ready
+
+## Risk Rules
+
+Proceed without confirmation for local, reversible actions such as:
+- reading files
+- editing code
+- creating normal source files
+- running tests
+- running local checks
+
+Pause for confirmation before:
+- deleting files or branches
+- force push / history rewrite
+- destructive database operations
+- modifying shared infrastructure
+- posting to external services
+- actions visible to other people
+
+If a safer reversible path exists, prefer it.
+
+## Communication Style
+
+- be concise
+- lead with the result
+- reference files with `path:line` when useful
+- do not over-explain routine steps
+- report at milestone boundaries, not after every tiny action
+
+## Task Workflow
+
+For substantial work:
+1. create small tasks up front
+2. set the current task to `in_progress` before starting
+3. complete tasks immediately after finishing them
+4. if a task grows too large, replace it with smaller tasks
+5. keep progress moving; do not leave stale broad tasks hanging
+
+## Implementation Guardrails
+
+- do not add features beyond the request
+- do not refactor unrelated code while fixing a local issue
+- do not add abstractions for one-off use
+- do not add speculative compatibility layers
+- validate user input and external boundaries, but do not over-defend impossible internal states
+
+## Recommended Repository-Specific Section
+
+Add project-local facts below this line.
+
+### Architecture Notes
+- `<entrypoint>`
+- `<main services>`
+- `<important directories>`
+
+### Quality Gates
+- `<must-pass command 1>`
+- `<must-pass command 2>`
+
+### Project-Specific Constraints
+- `<for example: strict typing, migration rules, no mocks, feature-flag requirements>`
+
+---
+
+## Maintainer Notes
+
+This template is intentionally opinionated toward autonomy-first execution.
+If you want stricter supervision, replace the Collaboration Mode and Core Working Rules sections with project-specific alternatives.
diff --git a/docs/automation_workflow_migration_checklist.md b/docs/automation_workflow_migration_checklist.md
new file mode 100644
index 0000000..6ae9c6d
--- /dev/null
+++ b/docs/automation_workflow_migration_checklist.md
@@ -0,0 +1,182 @@
+# Automation Workflow Migration Checklist
+
+Use this checklist to move the proven autonomy-first Claude workflow from one computer to another and bootstrap a fresh project quickly.
+
+## 1. Source files to copy
+
+Copy these files from the source machine or source repository:
+
+- `docs/CLAUDE_template_autonomy_first.md`
+  - reusable base template for project `CLAUDE.md`
+- `docs/AI_协作自动化工作规程_v1.md`
+  - explanation of the working rules and why they were chosen
+- `docs/标准_CLAUDE_md_模板_v1.md`
+  - optional extra local reference if you want a second comparison template
+
+If you already have a project-specific `CLAUDE.md` that worked well, copy that too.
+
+## 2. Target placement on the new computer
+
+### Required placement
+
+For each target project, place one active file at the project root:
+
+- `<project-root>/CLAUDE.md`
+
+Recommended source for that file:
+- start from `docs/CLAUDE_template_autonomy_first.md`
+- customize it for the new repository
+- save the final version as `<project-root>/CLAUDE.md`
+
+### Optional reference placement
+
+Keep the reusable references in a local docs area, for example:
+
+- `<project-root>/docs/CLAUDE_template_autonomy_first.md`
+- `<project-root>/docs/AI_协作自动化工作规程_v1.md`
+
+This is useful when you want both:
+- one active root `CLAUDE.md`
+- one reusable reference copy for later edits
+
+## 3. New machine prerequisite checklist
+
+Before using the workflow on the target machine, confirm:
+
+- [ ] Claude Code is installed and working
+- [ ] the target repository can be opened locally
+- [ ] the main language/runtime toolchain is installed
+- [ ] the project package manager is installed
+- [ ] the project test/typecheck/lint commands are known
+- [ ] any required local services are available
+- [ ] any needed credentials are already configured outside the repo
+
+Examples of local services:
+- database
+- Redis
+- Docker services
+- cloud CLI auth
+
+## 4. Initialize a new project with this workflow
+
+### Step 1. Create or copy the root file
+
+- [ ] copy `docs/CLAUDE_template_autonomy_first.md`
+- [ ] create `<project-root>/CLAUDE.md`
+- [ ] paste the template into it
+
+### Step 2. Replace the placeholders
+
+In the new root `CLAUDE.md`, fill in:
+
+- [ ] project name
+- [ ] one-paragraph project goal
+- [ ] primary stack
+- [ ] install command
+- [ ] dev command
+- [ ] test command
+- [ ] typecheck command
+- [ ] lint / format commands
+- [ ] key architecture notes
+- [ ] quality gates that must pass
+- [ ] project-specific constraints
+
+### Step 3. Add project-local rules
+
+Add any rules that are specific to the new repository, for example:
+
+- [ ] strict typecheck must pass with zero errors
+- [ ] database migrations must be additive only
+- [ ] no mock database tests
+- [ ] feature flags must gate new functionality
+- [ ] do not change CI files without confirmation
+
+### Step 4. Keep the proven execution rules
+
+Unless the new project truly needs different behavior, keep these intact:
+
+- [ ] autonomy-first collaboration mode
+- [ ] artifact over status
+- [ ] small executable task breakdown
+- [ ] continue after each completed task
+- [ ] do not repeat the same blocker twice
+- [ ] short factual milestone updates
+- [ ] verify before reporting complete
+- [ ] ask only for irreversible actions, missing resources, or product decisions
+
+## 5. First-run project bootstrap checklist
+
+After adding the new root `CLAUDE.md`, do this in the project:
+
+- [ ] open the repository in Claude Code
+- [ ] ask Claude to read the root `CLAUDE.md`
+- [ ] ask Claude to inspect the repository structure
+- [ ] ask Claude to identify the real quality gates
+- [ ] ask Claude to create small executable tasks for the first milestone
+- [ ] verify the first change is small and reversible
+- [ ] confirm Claude reports artifacts, not just status
+
+## 6. Quick validation checklist
+
+Use this to confirm the workflow migrated correctly:
+
+- [ ] Claude reads the root `CLAUDE.md` automatically
+- [ ] Claude breaks non-trivial work into small tasks
+- [ ] Claude edits files directly instead of lingering in planning
+- [ ] Claude gives short milestone updates instead of repetitive status chatter
+- [ ] Claude keeps moving without repeated confirmation on reversible steps
+- [ ] Claude pauses only for real decision points or risky actions
+- [ ] Claude verifies file existence or checks before claiming completion
+
+## 7. Minimal file set for a lightweight migration
+
+If you want the smallest useful transfer, only move these:
+
+- `docs/CLAUDE_template_autonomy_first.md`
+- create `<project-root>/CLAUDE.md` from it
+
+That is enough to reproduce the main behavior.
+
+## 8. Recommended file set for a full migration
+
+For a more complete transfer, move these:
+
+- `docs/CLAUDE_template_autonomy_first.md`
+- `docs/AI_协作自动化工作规程_v1.md`
+- current project’s final `CLAUDE.md` if it has proven repo-specific rules
+
+This gives you:
+- the reusable template
+- the rationale document
+- one real working example
+
+## 9. Common migration mistakes
+
+Avoid these mistakes:
+
+- [ ] copying only the idea, but not the actual `CLAUDE.md` file
+- [ ] placing the template in `docs/` but forgetting to create root `CLAUDE.md`
+- [ ] leaving placeholder commands unfilled
+- [ ] keeping broad vague tasks instead of small executable tasks
+- [ ] accepting status reports without artifact checks
+- [ ] letting the workflow stop after each small reversible step
+- [ ] forgetting to document real project quality gates
+
+## 10. Recommended startup prompt for a new repo
+
+After placing the new root `CLAUDE.md`, a good initialization prompt is:
+
+```text
+Read the root CLAUDE.md, inspect this repository, identify the real quality gates, then create a small autonomy-first task breakdown for the first milestone and start executing the first concrete reversible step.
+```
+
+## 11. Completion criteria
+
+The migration is complete when:
+
+- [ ] the new machine has Claude Code working
+- [ ] the target project has a root `CLAUDE.md`
+- [ ] the root file contains real project commands and constraints
+- [ ] Claude follows artifact-driven execution in practice
+- [ ] the first milestone is decomposed into small tasks
+- [ ] the first real change is written and verified successfully
diff --git a/docs/标准_CLAUDE_md_模板_v1.md b/docs/标准_CLAUDE_md_模板_v1.md
new file mode 100644
index 0000000..ccce9de
--- /dev/null
+++ b/docs/标准_CLAUDE_md_模板_v1.md
@@ -0,0 +1,166 @@
+# 可跨电脑复用的标准 CLAUDE.md 模板
+
+> 用法：把下面内容复制为目标项目根目录下的 `CLAUDE.md`。
+> 作用：让 Claude Code 在新电脑/新项目里尽快进入高自动化、产物驱动、少打断的协作模式。
+
+---
+
+# CLAUDE.md
+
+This file defines the default collaboration protocol for Claude Code in this project.
+
+## Collaboration Mode
+
+Default to **autonomy-first execution**.
+
+Once requirements are clear:
+
+- do not stop after each small step to ask what to do next
+- continue to the next highest-value concrete task automatically
+- only stop for:
+  1. irreversible/destructive actions
+  2. missing external resources or credentials
+  3. product decisions that genuinely require user input
+  4. explicit user request to pause or stop
+
+## Core Execution Rules
+
+### 1. Artifact-driven progress
+
+Do not treat “started” as progress.
+Progress only counts when there is a real artifact, such as:
+
+- a written file
+- a code change
+- a migration file
+- a test result
+- a verification result
+
+If no artifact was produced, do not present the task as meaningfully progressed.
+
+### 2. Report only after write + local check
+
+For document work, report completion only after:
+
+1. the file is actually written locally
+2. the file is checked for existence
+3. the file is read back locally to confirm it looks correct
+
+Avoid status updates like:
+
+- “I started it”
+- “I’m working on it”
+- “next I will…”
+
+unless the user specifically asked for live status.
+
+### 3. Break work into small executable tasks
+
+Do not keep large vague tasks open.
+Break work into small tasks that each produce a concrete artifact.
+Examples:
+
+- write schema doc
+- create migration file
+- add repository module
+- add service module
+- add runner script
+- run a focused verification
+
+### 4. Do not let tasks hang
+
+If a task is marked in progress but no file/code/test/verification result is produced for a while, consider it hanging.
+Immediately rescope it into smaller executable tasks and continue.
+
+### 5. Do not repeat the same blocker twice
+
+If the same blocker appears twice without new code, new verification, or new task progress:
+
+- stop repeating the blocker
+- change tactics
+- pick a neighboring concrete task
+- or narrow the scope and keep moving
+
+### 6. Finish one concrete task, then immediately start the next
+
+When a task completes, do not wait for redispatch.
+Continue automatically to the next highest-value concrete task unless a real blocker exists.
+
+### 7. Prefer foundation-first implementation order
+
+When building systems, prioritize:
+
+1. config
+2. db
+3. migrations
+4. base models
+5. ingestion/data pipelines
+6. foundational domain logic
+7. higher-level orchestration
+8. execution/UI/reporting
+
+Do not jump too early to upper-layer features if foundational modules are still missing.
+
+### 8. Parallelize only truly independent work
+
+Use parallel work only when tasks are genuinely independent.
+If tasks share the same files, same chain of dependencies, or same narrow context, do them sequentially.
+
+## Preferred Update Style
+
+Keep milestone updates short and concrete.
+Good update format:
+
+- what was written
+- what was checked
+- what is the next concrete task already being executed
+
+Avoid long narrative explanations during active execution.
+
+## Document Handling Rules
+
+When the user asks for persistent references, save substantial outputs as local Markdown files in the project.
+This includes:
+
+- architecture docs
+- schema docs
+- implementation plans
+- rule specifications
+- operational playbooks
+
+Do not leave important long-lived outputs only in chat if they should be reusable later.
+
+## Code Work Rules
+
+For implementation tasks:
+
+- prefer creating real files over only describing code
+- when updating an existing file, read it first
+- after writing code, do a local check before claiming completion
+- when useful, add a minimal runnable script or entrypoint to make the work executable
+
+## Default Working Pattern
+
+Use this loop by default:
+
+1. identify the next concrete task
+2. create/write the artifact
+3. locally verify it
+4. mark the task complete
+5. immediately continue to the next concrete task
+
+## If the User Asks to Save Progress and Stop
+
+Before stopping:
+
+1. ensure current files are written
+2. ensure any in-progress task is either completed or clearly reset
+3. leave a resumable checkpoint in local files if appropriate
+4. stop cleanly without leaving stale hanging task claims
+
+---
+
+## Optional Project-Specific Section
+
+Below this line, project maintainers can add domain-specific rules, architecture notes, commands, or constraints.
+
diff --git a/migrations/.gitkeep b/migrations/.gitkeep
new file mode 100644
index 0000000..533a134
--- /dev/null
+++ b/migrations/.gitkeep
@@ -0,0 +1 @@
+# Migration files live here.
diff --git a/migrations/001_create_venues.sql b/migrations/001_create_venues.sql
new file mode 100644
index 0000000..5b5b27e
--- /dev/null
+++ b/migrations/001_create_venues.sql
@@ -0,0 +1,9 @@
+create table if not exists venues (
+    id bigserial primary key,
+    code text not null unique,
+    name text not null,
+    timezone text not null,
+    status text not null default 'active',
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now()
+);
diff --git a/migrations/002_create_instruments.sql b/migrations/002_create_instruments.sql
new file mode 100644
index 0000000..26d08cb
--- /dev/null
+++ b/migrations/002_create_instruments.sql
@@ -0,0 +1,20 @@
+create table if not exists instruments (
+    id bigserial primary key,
+    venue_id bigint not null references venues(id),
+    symbol text not null,
+    asset_class text not null,
+    base_asset text,
+    quote_asset text,
+    price_scale integer not null,
+    qty_scale integer not null,
+    tick_size numeric(20,10) not null,
+    lot_size numeric(20,10),
+    active boolean not null default true,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now(),
+    unique (venue_id, symbol)
+);
+
+create index if not exists idx_instruments_venue_id on instruments(venue_id);
+create index if not exists idx_instruments_active on instruments(active);
diff --git a/migrations/003_create_candles.sql b/migrations/003_create_candles.sql
new file mode 100644
index 0000000..65430bb
--- /dev/null
+++ b/migrations/003_create_candles.sql
@@ -0,0 +1,16 @@
+create table if not exists candles (
+    id bigserial not null,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    ts_open timestamptz not null,
+    ts_close timestamptz not null,
+    open numeric(20,10) not null,
+    high numeric(20,10) not null,
+    low numeric(20,10) not null,
+    close numeric(20,10) not null,
+    volume numeric(28,10),
+    source text not null default 'api',
+    created_at timestamptz not null default now(),
+    primary key (id, ts_open),
+    unique (instrument_id, timeframe, ts_open)
+) partition by range (ts_open);
diff --git a/migrations/004_create_candles_partitions_and_indexes.sql b/migrations/004_create_candles_partitions_and_indexes.sql
new file mode 100644
index 0000000..444fe86
--- /dev/null
+++ b/migrations/004_create_candles_partitions_and_indexes.sql
@@ -0,0 +1,13 @@
+create table if not exists candles_2026_04
+partition of candles
+for values from ('2026-04-01 00:00:00+00') to ('2026-05-01 00:00:00+00');
+
+create table if not exists candles_2026_05
+partition of candles
+for values from ('2026-05-01 00:00:00+00') to ('2026-06-01 00:00:00+00');
+
+create index if not exists idx_candles_instrument_tf_open_desc
+on candles (instrument_id, timeframe, ts_open desc);
+
+create index if not exists idx_candles_instrument_tf_close_desc
+on candles (instrument_id, timeframe, ts_close desc);
diff --git a/migrations/005_create_market_sessions.sql b/migrations/005_create_market_sessions.sql
new file mode 100644
index 0000000..a6c2198
--- /dev/null
+++ b/migrations/005_create_market_sessions.sql
@@ -0,0 +1,23 @@
+create table if not exists market_sessions (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    session_date date not null,
+    timezone text not null,
+    session_code text not null,
+    start_ts timestamptz not null,
+    end_ts timestamptz not null,
+    high numeric(20,10),
+    low numeric(20,10),
+    midpoint numeric(20,10),
+    status text not null default 'closed',
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now(),
+    unique (instrument_id, session_date, session_code, timezone)
+);
+
+create index if not exists idx_market_sessions_instr_date
+on market_sessions (instrument_id, session_date desc);
+
+create index if not exists idx_market_sessions_instr_code_date
+on market_sessions (instrument_id, session_code, session_date desc);
diff --git a/migrations/006_create_swings.sql b/migrations/006_create_swings.sql
new file mode 100644
index 0000000..5b9e1c8
--- /dev/null
+++ b/migrations/006_create_swings.sql
@@ -0,0 +1,23 @@
+create table if not exists swings (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    kind text not null,
+    strength text not null,
+    price numeric(20,10) not null,
+    ts timestamptz not null,
+    left_bars integer not null,
+    right_bars integer not null,
+    confirmed boolean not null default true,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now()
+);
+
+create index if not exists idx_swings_instr_tf_ts_desc
+on swings (instrument_id, timeframe, ts desc);
+
+create index if not exists idx_swings_instr_tf_kind_ts_desc
+on swings (instrument_id, timeframe, kind, ts desc);
+
+create index if not exists idx_swings_instr_tf_strength_ts_desc
+on swings (instrument_id, timeframe, strength, ts desc);
diff --git a/migrations/007_create_dealing_ranges.sql b/migrations/007_create_dealing_ranges.sql
new file mode 100644
index 0000000..3d420b7
--- /dev/null
+++ b/migrations/007_create_dealing_ranges.sql
@@ -0,0 +1,22 @@
+create table if not exists dealing_ranges (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    high numeric(20,10) not null,
+    low numeric(20,10) not null,
+    equilibrium numeric(20,10) not null,
+    high_swing_id bigint references swings(id),
+    low_swing_id bigint references swings(id),
+    state text not null default 'valid',
+    ts_start timestamptz not null,
+    ts_end timestamptz,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now()
+);
+
+create index if not exists idx_dealing_ranges_instr_tf_start_desc
+on dealing_ranges (instrument_id, timeframe, ts_start desc);
+
+create index if not exists idx_dealing_ranges_instr_tf_state_start_desc
+on dealing_ranges (instrument_id, timeframe, state, ts_start desc);
diff --git a/migrations/008_create_liquidity_pools.sql b/migrations/008_create_liquidity_pools.sql
new file mode 100644
index 0000000..fb5fae1
--- /dev/null
+++ b/migrations/008_create_liquidity_pools.sql
@@ -0,0 +1,21 @@
+create table if not exists liquidity_pools (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    side text not null,
+    pool_type text not null,
+    price_low numeric(20,10) not null,
+    price_high numeric(20,10) not null,
+    reference_ids jsonb not null default '[]'::jsonb,
+    status text not null default 'untouched',
+    created_ts timestamptz not null,
+    updated_ts timestamptz not null default now(),
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now()
+);
+
+create index if not exists idx_liquidity_pools_instr_tf_status_created_desc
+on liquidity_pools (instrument_id, timeframe, status, created_ts desc);
+
+create index if not exists idx_liquidity_pools_instr_tf_side_created_desc
+on liquidity_pools (instrument_id, timeframe, side, created_ts desc);
diff --git a/migrations/009_seed_venues.sql b/migrations/009_seed_venues.sql
new file mode 100644
index 0000000..72797a9
--- /dev/null
+++ b/migrations/009_seed_venues.sql
@@ -0,0 +1,5 @@
+insert into venues (code, name, timezone)
+values
+    ('OKX', 'OKX', 'UTC'),
+    ('LMAX', 'LMAX', 'UTC')
+on conflict (code) do nothing;
diff --git a/migrations/010_seed_instruments.sql b/migrations/010_seed_instruments.sql
new file mode 100644
index 0000000..6b796ee
--- /dev/null
+++ b/migrations/010_seed_instruments.sql
@@ -0,0 +1,57 @@
+insert into instruments (
+    venue_id,
+    symbol,
+    asset_class,
+    base_asset,
+    quote_asset,
+    price_scale,
+    qty_scale,
+    tick_size,
+    lot_size,
+    active,
+    meta
+)
+select
+    v.id,
+    'BTC-USDT',
+    'crypto',
+    'BTC',
+    'USDT',
+    2,
+    6,
+    0.01,
+    0.000001,
+    true,
+    jsonb_build_object('raw_inst_id', 'BTC-USDT-SWAP', 'product_type', 'swap')
+from venues v
+where v.code = 'OKX'
+on conflict (venue_id, symbol) do nothing;
+
+insert into instruments (
+    venue_id,
+    symbol,
+    asset_class,
+    base_asset,
+    quote_asset,
+    price_scale,
+    qty_scale,
+    tick_size,
+    lot_size,
+    active,
+    meta
+)
+select
+    v.id,
+    'ETH-USDT',
+    'crypto',
+    'ETH',
+    'USDT',
+    2,
+    6,
+    0.01,
+    0.000001,
+    true,
+    jsonb_build_object('raw_inst_id', 'ETH-USDT-SWAP', 'product_type', 'swap')
+from venues v
+where v.code = 'OKX'
+on conflict (venue_id, symbol) do nothing;
diff --git a/migrations/011_create_displacement_events.sql b/migrations/011_create_displacement_events.sql
new file mode 100644
index 0000000..ab6b8dd
--- /dev/null
+++ b/migrations/011_create_displacement_events.sql
@@ -0,0 +1,20 @@
+create table if not exists displacement_events (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    direction text not null,
+    start_ts timestamptz not null,
+    end_ts timestamptz not null,
+    strength_score numeric(8,4),
+    body_ratio numeric(8,4),
+    has_fvg boolean not null default false,
+    is_valid boolean not null default true,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now()
+);
+
+create index if not exists idx_displacement_events_instr_tf_end_desc
+on displacement_events (instrument_id, timeframe, end_ts desc);
+
+create index if not exists idx_displacement_events_instr_tf_dir_end_desc
+on displacement_events (instrument_id, timeframe, direction, end_ts desc);
diff --git a/migrations/012_create_structure_events.sql b/migrations/012_create_structure_events.sql
new file mode 100644
index 0000000..02f6bad
--- /dev/null
+++ b/migrations/012_create_structure_events.sql
@@ -0,0 +1,21 @@
+create table if not exists structure_events (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    event_type text not null,
+    direction text not null,
+    broken_level numeric(20,10) not null,
+    reference_swing_id bigint references swings(id),
+    displacement_event_id bigint references displacement_events(id),
+    accepted boolean,
+    signal_relevant boolean not null default true,
+    ts timestamptz not null,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now()
+);
+
+create index if not exists idx_structure_events_instr_tf_ts_desc
+on structure_events (instrument_id, timeframe, ts desc);
+
+create index if not exists idx_structure_events_instr_tf_event_ts_desc
+on structure_events (instrument_id, timeframe, event_type, ts desc);
diff --git a/migrations/013_create_fvg_zones.sql b/migrations/013_create_fvg_zones.sql
new file mode 100644
index 0000000..818bafe
--- /dev/null
+++ b/migrations/013_create_fvg_zones.sql
@@ -0,0 +1,22 @@
+create table if not exists fvg_zones (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    direction text not null,
+    upper numeric(20,10) not null,
+    lower numeric(20,10) not null,
+    start_ts timestamptz not null,
+    end_ts timestamptz not null,
+    fill_pct numeric(8,4) not null default 0,
+    status text not null default 'open',
+    related_displacement_id bigint references displacement_events(id),
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now()
+);
+
+create index if not exists idx_fvg_zones_instr_tf_start_desc
+on fvg_zones (instrument_id, timeframe, start_ts desc);
+
+create index if not exists idx_fvg_zones_instr_tf_status_start_desc
+on fvg_zones (instrument_id, timeframe, status, start_ts desc);
diff --git a/migrations/014_create_bias_snapshots.sql b/migrations/014_create_bias_snapshots.sql
new file mode 100644
index 0000000..4321aed
--- /dev/null
+++ b/migrations/014_create_bias_snapshots.sql
@@ -0,0 +1,23 @@
+create table if not exists bias_snapshots (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    bias_tf text not null,
+    setup_tf text not null,
+    trigger_tf text not null,
+    snapshot_ts timestamptz not null,
+    daily_bias text not null,
+    confidence numeric(8,4),
+    execution_intensity text not null,
+    narrative_code text,
+    draw_side text,
+    range_id bigint references dealing_ranges(id),
+    reason_codes jsonb not null default '[]'::jsonb,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now()
+);
+
+create index if not exists idx_bias_snapshots_instr_snapshot_desc
+on bias_snapshots (instrument_id, snapshot_ts desc);
+
+create index if not exists idx_bias_snapshots_instr_bias_snapshot_desc
+on bias_snapshots (instrument_id, daily_bias, snapshot_ts desc);
diff --git a/migrations/015_create_trade_signals.sql b/migrations/015_create_trade_signals.sql
new file mode 100644
index 0000000..6fef896
--- /dev/null
+++ b/migrations/015_create_trade_signals.sql
@@ -0,0 +1,33 @@
+create table if not exists trade_signals (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    model_code text not null,
+    side text not null,
+    status text not null,
+    bias_snapshot_id bigint references bias_snapshots(id),
+    entry_type text not null,
+    entry_low numeric(20,10),
+    entry_high numeric(20,10),
+    stop_loss numeric(20,10),
+    tp1 numeric(20,10),
+    tp2 numeric(20,10),
+    rr_tp1 numeric(8,4),
+    rr_tp2 numeric(8,4),
+    session_code text,
+    created_ts timestamptz not null,
+    expires_ts timestamptz,
+    invalidations jsonb not null default '[]'::jsonb,
+    evidence jsonb not null default '{}'::jsonb,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now()
+);
+
+create index if not exists idx_trade_signals_instr_created_desc
+on trade_signals (instrument_id, created_ts desc);
+
+create index if not exists idx_trade_signals_instr_status_created_desc
+on trade_signals (instrument_id, status, created_ts desc);
+
+create index if not exists idx_trade_signals_instr_model_created_desc
+on trade_signals (instrument_id, model_code, created_ts desc);
diff --git a/migrations/016_create_trade_executions.sql b/migrations/016_create_trade_executions.sql
new file mode 100644
index 0000000..ebc2a21
--- /dev/null
+++ b/migrations/016_create_trade_executions.sql
@@ -0,0 +1,29 @@
+create table if not exists trade_executions (
+    id bigserial primary key,
+    signal_id bigint not null references trade_signals(id),
+    venue_order_id text,
+    execution_mode text not null,
+    side text not null,
+    entry_price numeric(20,10),
+    stop_loss numeric(20,10),
+    take_profit_1 numeric(20,10),
+    take_profit_2 numeric(20,10),
+    size numeric(28,10),
+    risk_pct numeric(8,4),
+    status text not null,
+    opened_ts timestamptz,
+    closed_ts timestamptz,
+    pnl numeric(28,10),
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now()
+);
+
+create index if not exists idx_trade_executions_signal_id
+on trade_executions (signal_id);
+
+create index if not exists idx_trade_executions_status_created_desc
+on trade_executions (status, created_at desc);
+
+create index if not exists idx_trade_executions_mode_created_desc
+on trade_executions (execution_mode, created_at desc);
diff --git a/migrations/017_create_backtest_runs.sql b/migrations/017_create_backtest_runs.sql
new file mode 100644
index 0000000..b385f35
--- /dev/null
+++ b/migrations/017_create_backtest_runs.sql
@@ -0,0 +1,17 @@
+create table if not exists backtest_runs (
+    id bigserial primary key,
+    model_code text not null,
+    instrument_id bigint references instruments(id),
+    timeframe_set jsonb not null default '{}'::jsonb,
+    started_ts timestamptz not null,
+    ended_ts timestamptz,
+    config jsonb not null default '{}'::jsonb,
+    summary jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now()
+);
+
+create index if not exists idx_backtest_runs_model_started_desc
+on backtest_runs (model_code, started_ts desc);
+
+create index if not exists idx_backtest_runs_instr_started_desc
+on backtest_runs (instrument_id, started_ts desc);
diff --git a/migrations/018_create_backtest_results.sql b/migrations/018_create_backtest_results.sql
new file mode 100644
index 0000000..6d44294
--- /dev/null
+++ b/migrations/018_create_backtest_results.sql
@@ -0,0 +1,20 @@
+create table if not exists backtest_results (
+    id bigserial primary key,
+    backtest_run_id bigint not null references backtest_runs(id),
+    signal_id bigint references trade_signals(id),
+    outcome text not null,
+    mfe numeric(20,10),
+    mae numeric(20,10),
+    tp1_hit boolean,
+    tp2_hit boolean,
+    invalidated_before_entry boolean,
+    error_tags jsonb not null default '[]'::jsonb,
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now()
+);
+
+create index if not exists idx_backtest_results_run_id
+on backtest_results (backtest_run_id);
+
+create index if not exists idx_backtest_results_outcome
+on backtest_results (outcome);
diff --git a/migrations/019_create_sweep_events.sql b/migrations/019_create_sweep_events.sql
new file mode 100644
index 0000000..8de1482
--- /dev/null
+++ b/migrations/019_create_sweep_events.sql
@@ -0,0 +1,22 @@
+create table if not exists sweep_events (
+    id bigserial primary key,
+    instrument_id bigint not null references instruments(id),
+    timeframe text not null,
+    side_swept text not null,
+    pool_id bigint not null references liquidity_pools(id),
+    sweep_high numeric(20,10) not null,
+    sweep_low numeric(20,10) not null,
+    sweep_ts timestamptz not null,
+    close_back_inside boolean not null default false,
+    validation_level text not null default 'weak',
+    status text not null default 'active',
+    meta jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now(),
+    unique (instrument_id, timeframe, pool_id, sweep_ts)
+);
+
+create index if not exists idx_sweep_events_instr_tf_ts_desc
+on sweep_events (instrument_id, timeframe, sweep_ts desc);
+
+create index if not exists idx_sweep_events_pool_ts_desc
+on sweep_events (pool_id, sweep_ts desc);
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..6d68720
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,16 @@
+[project]
+name = "ai-ict"
+version = "0.1.0"
+description = "AI ICT trading assistant foundation"
+requires-python = ">=3.11"
+dependencies = [
+  "sqlalchemy>=2.0",
+  "psycopg[binary]>=3.1",
+  "pydantic>=2.7",
+  "pydantic-settings>=2.2",
+  "httpx>=0.27",
+]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
diff --git a/scripts/apply_migrations.py b/scripts/apply_migrations.py
new file mode 100644
index 0000000..c563253
--- /dev/null
+++ b/scripts/apply_migrations.py
@@ -0,0 +1,36 @@
+from pathlib import Path
+import sys
+
+from sqlalchemy import text
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.db.engine import engine
+
+
+MIGRATIONS_DIR = Path(__file__).resolve().parents[1] / "migrations"
+
+
+def iter_sql_files() -> list[Path]:
+    return sorted(p for p in MIGRATIONS_DIR.glob("*.sql") if p.is_file())
+
+
+def main() -> None:
+    files = iter_sql_files()
+    if not files:
+        print("No migration files found")
+        return
+
+    with engine.begin() as conn:
+        for path in files:
+            sql = path.read_text(encoding="utf-8").strip()
+            if not sql:
+                continue
+            conn.execute(text(sql))
+            print(f"Applied {path.name}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/check_db.py b/scripts/check_db.py
new file mode 100644
index 0000000..884079f
--- /dev/null
+++ b/scripts/check_db.py
@@ -0,0 +1,21 @@
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from sqlalchemy import text
+
+from src.db.engine import engine
+
+
+def main() -> None:
+    with engine.connect() as connection:
+        result = connection.execute(text("select 1"))
+        value = result.scalar_one()
+    print(f"database connection ok: {value}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/check_db_connection.py b/scripts/check_db_connection.py
new file mode 100644
index 0000000..d5ed7ce
--- /dev/null
+++ b/scripts/check_db_connection.py
@@ -0,0 +1,21 @@
+from pathlib import Path
+import sys
+
+from sqlalchemy import text
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.db.engine import engine
+
+
+def main() -> None:
+    with engine.connect() as conn:
+        result = conn.execute(text("select 1"))
+        value = result.scalar_one()
+        print("DB connection OK" if value == 1 else "DB connection unexpected result")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/deploy_server.exp b/scripts/deploy_server.exp
new file mode 100755
index 0000000..d78afae
--- /dev/null
+++ b/scripts/deploy_server.exp
@@ -0,0 +1,25 @@
+#!/usr/bin/expect -f
+set timeout 300
+set host "192.168.3.90"
+set user "root"
+set password "816301"
+set archive "/tmp/ai-ict-deploy.tgz"
+set remote_archive "/root/ai-ict-deploy.tgz"
+set remote_path "/root/deploy/ai-ict"
+
+proc auth {} {
+  expect {
+    "*yes/no*" { send "yes\r"; exp_continue }
+    "*assword:*" { send "$::password\r"; exp_continue }
+    eof
+  }
+}
+
+spawn ssh -o StrictHostKeyChecking=accept-new $user@$host "hostname && docker --version && ((docker compose version) || (docker-compose --version)) && mkdir -p $remote_path"
+auth
+
+spawn scp -o StrictHostKeyChecking=accept-new $archive $user@$host:$remote_archive
+auth
+
+spawn ssh -o StrictHostKeyChecking=accept-new $user@$host "rm -rf $remote_path/* && tar -xzf $remote_archive -C $remote_path && cd $remote_path && ((docker compose down || docker-compose down) >/dev/null 2>&1 || true) && ((docker compose up -d --build) || (docker-compose up -d --build)) && ((docker compose ps) || (docker-compose ps))"
+auth
diff --git a/scripts/deploy_with_expect.exp b/scripts/deploy_with_expect.exp
new file mode 100755
index 0000000..b03d879
--- /dev/null
+++ b/scripts/deploy_with_expect.exp
@@ -0,0 +1,28 @@
+#!/usr/bin/expect -f
+set timeout 120
+set host "192.168.3.90"
+set user "root"
+set password "123456"
+set local_path "/Users/yuqei/AI Exchange"
+set remote_path "/root/deploy/ai-ict"
+
+spawn ssh -o StrictHostKeyChecking=accept-new $user@$host "mkdir -p $remote_path"
+expect {
+  "*assword:*" { send "$password\r" }
+  eof
+}
+expect eof
+
+spawn rsync -az --delete --exclude ".git" --exclude ".venv" --exclude "__pycache__" --exclude "tests" -e "ssh -o StrictHostKeyChecking=accept-new" "$local_path/" "$user@$host:$remote_path/"
+expect {
+  "*assword:*" { send "$password\r"; exp_continue }
+  eof
+}
+expect eof
+
+spawn ssh -o StrictHostKeyChecking=accept-new $user@$host "cd $remote_path && docker compose down && docker compose up -d --build"
+expect {
+  "*assword:*" { send "$password\r" }
+  eof
+}
+expect eof
diff --git a/scripts/fix_pg_hba.exp b/scripts/fix_pg_hba.exp
new file mode 100755
index 0000000..9bfc9b0
--- /dev/null
+++ b/scripts/fix_pg_hba.exp
@@ -0,0 +1,24 @@
+#!/usr/bin/expect -f
+set timeout 600
+spawn ssh -o StrictHostKeyChecking=accept-new root@192.168.3.90 {python3 - <<'PY'
+from pathlib import Path
+hba = Path('/var/lib/pgsql/16/data/pg_hba.conf')
+lines = [
+    'host ai_ict yuqei 172.18.0.0/16 scram-sha-256\n',
+    'host ai_ict yuqei 172.20.0.0/16 scram-sha-256\n',
+]
+text = hba.read_text()
+added = []
+for line in lines:
+    if line not in text:
+        with hba.open('a') as f:
+            f.write(line)
+        added.append(line.strip())
+print('ADDED', added)
+print('TAIL')
+for row in hba.read_text().splitlines()[-12:]:
+    print(row)
+PY
+su - postgres -c "pg_ctl reload -D /var/lib/pgsql/16/data" && echo RELOADED}
+expect "*assword:*" { send "816301\r" }
+expect eof
diff --git a/scripts/run_api_server.py b/scripts/run_api_server.py
new file mode 100644
index 0000000..b4d6390
--- /dev/null
+++ b/scripts/run_api_server.py
@@ -0,0 +1,19 @@
+from pathlib import Path
+import os
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.api.server import serve_api
+
+
+def main() -> None:
+    host = os.getenv("AI_ICT_API_HOST", "0.0.0.0")
+    port = int(os.getenv("AI_ICT_API_PORT", "8000"))
+    serve_api(host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/run_backtest.py b/scripts/run_backtest.py
new file mode 100644
index 0000000..faa3e50
--- /dev/null
+++ b/scripts/run_backtest.py
@@ -0,0 +1,18 @@
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.services.backtest import BacktestService
+
+
+def main() -> None:
+    service = BacktestService()
+    run_id, outcomes = service.run_backtest(instrument_id=1, limit=100)
+    print(f"Backtest run id: {run_id}; results written: {len(outcomes)}")
+
+
+if __name__ == '__main__':
+    main()
diff --git a/scripts/run_dev.py b/scripts/run_dev.py
new file mode 100644
index 0000000..3170bba
--- /dev/null
+++ b/scripts/run_dev.py
@@ -0,0 +1,12 @@
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.main import main
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/run_displacement.py b/scripts/run_displacement.py
new file mode 100644
index 0000000..1170e13
--- /dev/null
+++ b/scripts/run_displacement.py
@@ -0,0 +1,19 @@
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.services.displacement import DisplacementService
+
+
+def main() -> None:
+    service = DisplacementService()
+    candidates = service.detect_displacement(instrument_id=1, timeframe="1m", limit=200)
+    written = service.persist_displacement(instrument_id=1, timeframe="1m", candidates=candidates)
+    print(f"Detected {len(candidates)} displacement events; wrote {written} rows")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/run_execution.py b/scripts/run_execution.py
new file mode 100644
index 0000000..b6749f0
--- /dev/null
+++ b/scripts/run_execution.py
@@ -0,0 +1,26 @@
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.services.execution import ExecutionService
+
+
+def main() -> None:
+    service = ExecutionService()
+    signal_id = 1
+    decision = service.prepare_execution(signal_id=signal_id, execution_mode="paper")
+    if decision is None:
+        print("Signal not found")
+        return
+    execution_id = service.create_execution(signal_id=signal_id, execution_mode="paper")
+    print(
+        f"Execution allowed: {decision.allowed}; status: {decision.status}; "
+        f"reasons: {decision.reasons}; execution_id: {execution_id}"
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/run_fvg.py b/scripts/run_fvg.py
new file mode 100644
index 0000000..7c55e41
--- /dev/null
+++ b/scripts/run_fvg.py
@@ -0,0 +1,19 @@
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.services.fvg import FVGService
+
+
+def main() -> None:
+    service = FVGService()
+    candidates = service.detect_fvg(instrument_id=1, timeframe="1m", limit=200)
+    written = service.persist_fvg(instrument_id=1, timeframe="1m", candidates=candidates)
+    print(f"Detected {len(candidates)} FVG zones; wrote {written} rows")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/run_liquidity.py b/scripts/run_liquidity.py
new file mode 100644
index 0000000..0487b53
--- /dev/null
+++ b/scripts/run_liquidity.py
@@ -0,0 +1,19 @@
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.services.liquidity import LiquidityPoolService
+
+
+def main() -> None:
+    service = LiquidityPoolService()
+    candidates = service.build_candidates(instrument_id=1, timeframe="1m")
+    written = service.persist_candidates(instrument_id=1, timeframe="1m", candidates=candidates)
+    print(f"Detected {len(candidates)} liquidity pools; wrote {written} rows")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/run_migrations.py b/scripts/run_migrations.py
new file mode 100644
index 0000000..7a51c0f
--- /dev/null
+++ b/scripts/run_migrations.py
@@ -0,0 +1,35 @@
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from sqlalchemy import text
+
+from src.db.engine import engine
+
+MIGRATIONS_DIR = ROOT / "migrations"
+
+
+def iter_migration_files() -> list[Path]:
+    return sorted(path for path in MIGRATIONS_DIR.glob("*.sql") if path.is_file())
+
+
+def main() -> None:
+    files = iter_migration_files()
+    if not files:
+        print("no migration files found")
+        return
+
+    with engine.begin() as connection:
+        for path in files:
+            sql = path.read_text(encoding="utf-8").strip()
+            if not sql:
+                continue
+            connection.execute(text(sql))
+            print(f"applied {path.name}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/run_mss.py b/scripts/run_mss.py
new file mode 100644
index 0000000..6d0ed57
--- /dev/null
+++ b/scripts/run_mss.py
@@ -0,0 +1,19 @@
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.services.structure import MSSService
+
+
+def main() -> None:
+    service = MSSService()
+    candidates = service.detect_mss(instrument_id=1, timeframe="1m")
+    written = service.persist_mss(instrument_id=1, timeframe="1m", candidates=candidates)
+    print(f"Detected {len(candidates)} MSS events; wrote {written} rows")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/run_okx_backfill.py b/scripts/run_okx_backfill.py
new file mode 100644
index 0000000..ee220a9
--- /dev/null
+++ b/scripts/run_okx_backfill.py
@@ -0,0 +1,54 @@
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.repositories.candle_repository import CandleRepository
+from src.services.market_data.okx_client import OKXClient
+from src.services.market_data.normalizer import normalize_okx_candles
+
+
+INSTRUMENT_ID_MAP = {
+    "BTC-USDT": 1,
+    "ETH-USDT": 2,
+}
+
+TIMEFRAMES = ["1m", "5m", "15m"]
+
+
+def main() -> None:
+    symbol = "BTC-USDT"
+    inst_id = "BTC-USDT-SWAP"
+    pages = 20
+    limit = 100
+
+    client = OKXClient()
+    repository = CandleRepository()
+
+    grand_raw = 0
+    grand_written = 0
+
+    for timeframe in TIMEFRAMES:
+        total_raw = 0
+        total_written = 0
+        seen_ts = set()
+        for _ in range(pages):
+            raw = client.get_candles(inst_id=inst_id, bar=timeframe, limit=limit)
+            normalized = normalize_okx_candles(symbol=symbol, venue="OKX", timeframe=timeframe, candles=raw)
+            confirmed = [c for c in normalized if c.confirm and c.ts_open_ms not in seen_ts]
+            for candle in confirmed:
+                seen_ts.add(candle.ts_open_ms)
+            written = repository.upsert_many(confirmed, instrument_id=INSTRUMENT_ID_MAP[symbol])
+            total_raw += len(raw)
+            total_written += written
+        grand_raw += total_raw
+        grand_written += total_written
+        print(f"timeframe={timeframe} fetched={total_raw} wrote={total_written}")
+
+    print(f"total fetched={grand_raw} total wrote={grand_written}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/run_pipeline.py b/scripts/run_pipeline.py
new file mode 100644
index 0000000..82cf5fc
--- /dev/null
+++ b/scripts/run_pipeline.py
@@ -0,0 +1,18 @@
+from pathlib import Path
+import json
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.main import run_closed_loop
+
+
+def main() -> None:
+    result = run_closed_loop(instrument_id=1, timeframe="1m", backtest_limit=100, run_execution=True)
+    print(json.dumps(result, default=str, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/run_ranges.py b/scripts/run_ranges.py
new file mode 100644
index 0000000..a28a50d
--- /dev/null
+++ b/scripts/run_ranges.py
@@ -0,0 +1,19 @@
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.services.ranges import DealingRangeService
+
+
+def main() -> None:
+    service = DealingRangeService()
+    candidate = service.build_active_range(instrument_id=1, timeframe="1m")
+    written = service.persist_active_range(instrument_id=1, timeframe="1m", candidate=candidate)
+    print(f"Persisted {written} dealing range rows")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/run_reports.py b/scripts/run_reports.py
new file mode 100644
index 0000000..832e009
--- /dev/null
+++ b/scripts/run_reports.py
@@ -0,0 +1,48 @@
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.services.reports import (
+    BacktestReportService,
+    IntradayReportService,
+    PostTradeReviewService,
+    PreMarketReportService,
+)
+
+
+def main() -> None:
+    pre_market = PreMarketReportService().build_report(
+        bias_snapshot={
+            "daily_bias": "bullish",
+            "draw_side": "buy_side",
+            "execution_intensity": "high",
+            "reason_codes": ["latest_mss", "active_range_available"],
+        },
+        dealing_range={"id": 1, "high": 110.0, "low": 90.0, "equilibrium": 100.0},
+        current_price=98.0,
+        session_code="LONDON",
+    )
+    intraday = IntradayReportService().build_report(
+        sweep_event={"side_swept": "buy_side", "close_back_inside": True},
+        structure_event={"event_type": "MSS", "direction": "bullish", "accepted": True},
+        fvg_zone={"direction": "bullish", "status": "open", "fill_pct": 0.0, "meta": {}},
+        trade_signal={"status": "awaiting_confirmation", "side": "buy", "session_code": "LONDON", "invalidations": []},
+    )
+    review = PostTradeReviewService().build_report(
+        trade_execution={"status": "open", "meta": {"risk_checks": []}},
+        trade_signal={"status": "awaiting_confirmation", "invalidations": []},
+        backtest_result={"outcome": "win", "invalidated_before_entry": False, "error_tags": []},
+    )
+    backtest_summary = BacktestReportService().build_summary([])
+
+    print(f"Pre-market permission: {pre_market['execution_permission']}")
+    print(f"Intraday valid: {intraday['signal']['is_valid']}")
+    print(f"Post-trade aligned: {review['rule_aligned']}")
+    print(f"Backtest total signals: {backtest_summary['total_signals']}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/run_session_generator.py b/scripts/run_session_generator.py
new file mode 100644
index 0000000..3722deb
--- /dev/null
+++ b/scripts/run_session_generator.py
@@ -0,0 +1,20 @@
+from pathlib import Path
+import sys
+from datetime import datetime
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.services.sessions import SessionGenerator
+
+
+def main() -> None:
+    generator = SessionGenerator()
+    today = datetime.now(generator.timezone)
+    written = generator.generate_for_date(instrument_id=1, timeframe="1m", session_date=today)
+    print(f"Generated {written} session rows")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/run_signals.py b/scripts/run_signals.py
new file mode 100644
index 0000000..913256f
--- /dev/null
+++ b/scripts/run_signals.py
@@ -0,0 +1,25 @@
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.services.bias import BiasService
+from src.services.signals import SignalService
+
+
+def main() -> None:
+    instrument_id = 1
+    bias_service = BiasService()
+    signal_service = SignalService()
+
+    bias = bias_service.build_bias(instrument_id=instrument_id, bias_tf='1m', setup_tf='1m', trigger_tf='1m')
+    bias_id = bias_service.persist_bias(instrument_id=instrument_id, bias_tf='1m', setup_tf='1m', trigger_tf='1m', candidate=bias)
+    signal = signal_service.build_signal(instrument_id=instrument_id, setup_tf='1m', trigger_tf='1m')
+    written = signal_service.persist_signal(instrument_id=instrument_id, setup_tf='1m', trigger_tf='1m', candidate=signal)
+    print(f'Bias snapshot id: {bias_id}; signal rows written: {written}')
+
+
+if __name__ == '__main__':
+    main()
diff --git a/scripts/run_sweeps.py b/scripts/run_sweeps.py
new file mode 100644
index 0000000..beff801
--- /dev/null
+++ b/scripts/run_sweeps.py
@@ -0,0 +1,19 @@
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.services.sweeps import SweepService
+
+
+def main() -> None:
+    service = SweepService()
+    candidates = service.detect_sweeps(instrument_id=1, timeframe="1m")
+    written = service.persist_sweeps(instrument_id=1, timeframe="1m", candidates=candidates)
+    print(f"Detected {len(candidates)} sweeps; wrote {written} events")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/run_swings.py b/scripts/run_swings.py
new file mode 100644
index 0000000..00d66b2
--- /dev/null
+++ b/scripts/run_swings.py
@@ -0,0 +1,19 @@
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.services.swings import SwingService
+
+
+def main() -> None:
+    service = SwingService()
+    candidates = service.detect_swings(instrument_id=1, timeframe="1m", left_bars=2, right_bars=2, limit=500)
+    written = service.persist_swings(instrument_id=1, timeframe="1m", candidates=candidates)
+    print(f"Detected {len(candidates)} swings; wrote {written} rows")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/show_models.py b/scripts/show_models.py
new file mode 100644
index 0000000..f9e1d0d
--- /dev/null
+++ b/scripts/show_models.py
@@ -0,0 +1,23 @@
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+MODELS_DIR = ROOT / "src" / "models"
+
+
+def main() -> None:
+    model_files = sorted(
+        path.stem
+        for path in MODELS_DIR.glob("*.py")
+        if path.is_file() and path.stem != "__init__"
+    )
+    print(f"model exports: {len(model_files)}")
+    for name in model_files:
+        print(name)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/ssh_diagnose.exp b/scripts/ssh_diagnose.exp
new file mode 100755
index 0000000..506abaf
--- /dev/null
+++ b/scripts/ssh_diagnose.exp
@@ -0,0 +1,9 @@
+#!/usr/bin/expect -f
+log_user 1
+exp_internal 0
+set timeout 30
+spawn ssh -v -o PreferredAuthentications=password -o PubkeyAuthentication=no -o StrictHostKeyChecking=accept-new root@192.168.3.90 "exit"
+expect {
+  "*assword:*" { send "123456\r"; exp_continue }
+  eof
+}
diff --git a/seeds/.gitkeep b/seeds/.gitkeep
new file mode 100644
index 0000000..9cd3dbe
--- /dev/null
+++ b/seeds/.gitkeep
@@ -0,0 +1 @@
+# Seed files live here.
diff --git a/src/__init__.py b/src/__init__.py
new file mode 100644
index 0000000..8fb10d0
--- /dev/null
+++ b/src/__init__.py
@@ -0,0 +1 @@
+"""AI ICT project package."""
diff --git a/src/api/__init__.py b/src/api/__init__.py
new file mode 100644
index 0000000..bd02423
--- /dev/null
+++ b/src/api/__init__.py
@@ -0,0 +1,18 @@
+"""Lightweight internal API query helpers."""
+
+from src.api.backtest import get_recent_backtest_summaries
+from src.api.candles import get_recent_candles
+from src.api.health import get_health
+from src.api.server import route_request, serve_api
+from src.api.sessions import get_recent_sessions
+from src.api.signals import get_recent_signals
+
+__all__ = [
+    "get_health",
+    "get_recent_candles",
+    "get_recent_sessions",
+    "get_recent_signals",
+    "get_recent_backtest_summaries",
+    "route_request",
+    "serve_api",
+]
diff --git a/src/api/backtest.py b/src/api/backtest.py
new file mode 100644
index 0000000..fed033f
--- /dev/null
+++ b/src/api/backtest.py
@@ -0,0 +1,24 @@
+from typing import Optional
+
+from sqlalchemy import text
+
+from src.db.session import SessionLocal
+
+
+def get_recent_backtest_summaries(instrument_id: Optional[int] = None, limit: int = 10) -> list[dict]:
+    where_clause = "where instrument_id = :instrument_id" if instrument_id is not None else ""
+    sql = text(
+        f"""
+        select id, model_code, instrument_id, timeframe_set, started_ts, ended_ts, config, summary
+        from backtest_runs
+        {where_clause}
+        order by started_ts desc
+        limit :limit
+        """
+    )
+    params = {"limit": limit}
+    if instrument_id is not None:
+        params["instrument_id"] = instrument_id
+    with SessionLocal() as session:
+        rows = session.execute(sql, params).mappings().all()
+    return [dict(row) for row in rows]
diff --git a/src/api/candles.py b/src/api/candles.py
new file mode 100644
index 0000000..42f1258
--- /dev/null
+++ b/src/api/candles.py
@@ -0,0 +1,19 @@
+from sqlalchemy import text
+
+from src.db.session import SessionLocal
+
+
+def get_recent_candles(instrument_id: int, timeframe: str = "1m", limit: int = 100) -> list[dict]:
+    sql = text(
+        """
+        select instrument_id, timeframe, ts_open, ts_close, open, high, low, close, volume, source
+        from candles
+        where instrument_id = :instrument_id
+          and timeframe = :timeframe
+        order by ts_open desc
+        limit :limit
+        """
+    )
+    with SessionLocal() as session:
+        rows = session.execute(sql, {"instrument_id": instrument_id, "timeframe": timeframe, "limit": limit}).mappings().all()
+    return [dict(row) for row in rows]
diff --git a/src/api/health.py b/src/api/health.py
new file mode 100644
index 0000000..ff9b5cc
--- /dev/null
+++ b/src/api/health.py
@@ -0,0 +1,9 @@
+from src.config.settings import settings
+
+
+def get_health() -> dict:
+    return {
+        "app": "ai-ict",
+        "database_configured": bool(settings.database_url),
+        "session_timezone": settings.session_timezone,
+    }
diff --git a/src/api/server.py b/src/api/server.py
new file mode 100644
index 0000000..8db172e
--- /dev/null
+++ b/src/api/server.py
@@ -0,0 +1,108 @@
+import json
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Optional
+from urllib.parse import parse_qs, urlparse
+
+from src.api.backtest import get_recent_backtest_summaries
+from src.api.candles import get_recent_candles
+from src.api.health import get_health
+from src.api.sessions import get_recent_sessions
+from src.api.signals import get_recent_signals
+
+
+def build_api_dependencies() -> dict:
+    return {
+        "health": get_health,
+        "candles": get_recent_candles,
+        "sessions": get_recent_sessions,
+        "signals": get_recent_signals,
+        "backtests": get_recent_backtest_summaries,
+    }
+
+
+def route_request(path: str, query: dict, dependencies: Optional[dict] = None) -> tuple[int, dict]:
+    deps = dependencies or build_api_dependencies()
+
+    if path == "/health":
+        return 200, deps["health"]()
+    if path == "/candles":
+        instrument_id = _require_int(query, "instrument_id")
+        timeframe = _get_single(query, "timeframe", "1m")
+        limit = _get_int(query, "limit", 100)
+        return 200, {"items": deps["candles"](instrument_id=instrument_id, timeframe=timeframe, limit=limit)}
+    if path == "/sessions":
+        instrument_id = _require_int(query, "instrument_id")
+        limit = _get_int(query, "limit", 20)
+        return 200, {"items": deps["sessions"](instrument_id=instrument_id, limit=limit)}
+    if path == "/signals":
+        instrument_id = _require_int(query, "instrument_id")
+        limit = _get_int(query, "limit", 20)
+        return 200, {"items": deps["signals"](instrument_id=instrument_id, limit=limit)}
+    if path == "/backtests":
+        instrument_id = _get_optional_int(query, "instrument_id")
+        limit = _get_int(query, "limit", 10)
+        return 200, {"items": deps["backtests"](instrument_id=instrument_id, limit=limit)}
+    return 404, {"error": "not_found"}
+
+
+class APIRequestHandler(BaseHTTPRequestHandler):
+    dependencies = build_api_dependencies()
+
+    def do_GET(self) -> None:
+        parsed = urlparse(self.path)
+        try:
+            status, payload = route_request(parsed.path, parse_qs(parsed.query), dependencies=self.dependencies)
+        except ValueError as exc:
+            status, payload = 400, {"error": str(exc)}
+        body = json.dumps(payload, default=str, ensure_ascii=False).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, format: str, *args) -> None:
+        return
+
+
+def serve_api(host: str = "127.0.0.1", port: int = 8000) -> None:
+    server = ThreadingHTTPServer((host, port), APIRequestHandler)
+    print(f"AI ICT API listening on http://{host}:{port}")
+    server.serve_forever()
+
+
+def _require_int(query: dict, key: str) -> int:
+    value = _get_single(query, key)
+    if value is None:
+        raise ValueError(f"missing_required_query_param:{key}")
+    try:
+        return int(value)
+    except ValueError as exc:
+        raise ValueError(f"invalid_int_query_param:{key}") from exc
+
+
+def _get_optional_int(query: dict, key: str) -> Optional[int]:
+    value = _get_single(query, key)
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except ValueError as exc:
+        raise ValueError(f"invalid_int_query_param:{key}") from exc
+
+
+def _get_int(query: dict, key: str, default: int) -> int:
+    value = _get_single(query, key)
+    if value is None:
+        return default
+    try:
+        return int(value)
+    except ValueError as exc:
+        raise ValueError(f"invalid_int_query_param:{key}") from exc
+
+
+def _get_single(query: dict, key: str, default: Optional[str] = None) -> Optional[str]:
+    values = query.get(key)
+    if not values:
+        return default
+    return values[0]
diff --git a/src/api/sessions.py b/src/api/sessions.py
new file mode 100644
index 0000000..c8b7919
--- /dev/null
+++ b/src/api/sessions.py
@@ -0,0 +1,18 @@
+from sqlalchemy import text
+
+from src.db.session import SessionLocal
+
+
+def get_recent_sessions(instrument_id: int, limit: int = 20) -> list[dict]:
+    sql = text(
+        """
+        select id, instrument_id, session_date, timezone, session_code, start_ts, end_ts, high, low, midpoint, status, meta
+        from market_sessions
+        where instrument_id = :instrument_id
+        order by session_date desc, start_ts desc
+        limit :limit
+        """
+    )
+    with SessionLocal() as session:
+        rows = session.execute(sql, {"instrument_id": instrument_id, "limit": limit}).mappings().all()
+    return [dict(row) for row in rows]
diff --git a/src/api/signals.py b/src/api/signals.py
new file mode 100644
index 0000000..05cc33b
--- /dev/null
+++ b/src/api/signals.py
@@ -0,0 +1,19 @@
+from sqlalchemy import text
+
+from src.db.session import SessionLocal
+
+
+def get_recent_signals(instrument_id: int, limit: int = 20) -> list[dict]:
+    sql = text(
+        """
+        select id, instrument_id, model_code, side, status, entry_type, entry_low, entry_high, stop_loss, tp1, tp2,
+               rr_tp1, rr_tp2, session_code, created_ts, expires_ts, invalidations, evidence, meta
+        from trade_signals
+        where instrument_id = :instrument_id
+        order by created_ts desc
+        limit :limit
+        """
+    )
+    with SessionLocal() as session:
+        rows = session.execute(sql, {"instrument_id": instrument_id, "limit": limit}).mappings().all()
+    return [dict(row) for row in rows]
diff --git a/src/config/__init__.py b/src/config/__init__.py
new file mode 100644
index 0000000..56096f2
--- /dev/null
+++ b/src/config/__init__.py
@@ -0,0 +1 @@
+"""Configuration package."""
diff --git a/src/config/constants.py b/src/config/constants.py
new file mode 100644
index 0000000..6f3d82a
--- /dev/null
+++ b/src/config/constants.py
@@ -0,0 +1,9 @@
+"""App runtime metadata."""
+
+APP_NAME = "ai-ict"
+APP_VERSION = "0.1.0"
+
+# Default price-distance threshold for grouping equal highs/lows.
+DEFAULT_EQUAL_POOL_THRESHOLD_PCT = "0.0005"
+DEFAULT_MSS_ACCEPTANCE_WINDOW_CANDLES = 5
+DEFAULT_FVG_MITIGATION_THRESHOLD_PCT = 1.0
diff --git a/src/config/sessions.py b/src/config/sessions.py
new file mode 100644
index 0000000..2ca19d7
--- /dev/null
+++ b/src/config/sessions.py
@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SessionWindow:
+    code: str
+    start: str
+    end: str
+
+
+SESSION_WINDOWS = [
+    SessionWindow(code="ASIA", start="20:00", end="00:00"),
+    SessionWindow(code="LONDON", start="02:00", end="05:00"),
+    SessionWindow(code="NY_AM", start="09:30", end="11:00"),
+    SessionWindow(code="NY_LUNCH", start="12:00", end="13:00"),
+    SessionWindow(code="NY_PM", start="13:30", end="16:00"),
+]
diff --git a/src/config/settings.py b/src/config/settings.py
new file mode 100644
index 0000000..3c39072
--- /dev/null
+++ b/src/config/settings.py
@@ -0,0 +1,15 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    database_url: str
+    okx_base_url: str = "https://www.okx.com"
+    okx_timeout: int = 30
+    default_timezone: str = "UTC"
+    session_timezone: str = "America/New_York"
+    log_level: str = "INFO"
+
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8", extra="ignore")
+
+
+settings = Settings()
diff --git a/src/db/__init__.py b/src/db/__init__.py
new file mode 100644
index 0000000..cdce083
--- /dev/null
+++ b/src/db/__init__.py
@@ -0,0 +1 @@
+"""Database package."""
diff --git a/src/db/base.py b/src/db/base.py
new file mode 100644
index 0000000..fa2b68a
--- /dev/null
+++ b/src/db/base.py
@@ -0,0 +1,5 @@
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    pass
diff --git a/src/db/config.py b/src/db/config.py
new file mode 100644
index 0000000..fd82d59
--- /dev/null
+++ b/src/db/config.py
@@ -0,0 +1,5 @@
+from src.config.settings import settings
+
+
+def get_database_url() -> str:
+    return settings.database_url
diff --git a/src/db/engine.py b/src/db/engine.py
new file mode 100644
index 0000000..573ebc2
--- /dev/null
+++ b/src/db/engine.py
@@ -0,0 +1,6 @@
+from sqlalchemy import create_engine
+
+from src.config.settings import settings
+
+
+engine = create_engine(settings.database_url, pool_pre_ping=True)
diff --git a/src/db/session.py b/src/db/session.py
new file mode 100644
index 0000000..071c574
--- /dev/null
+++ b/src/db/session.py
@@ -0,0 +1,6 @@
+from sqlalchemy.orm import sessionmaker
+
+from src.db.engine import engine
+
+
+SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)
diff --git a/src/domain/__init__.py b/src/domain/__init__.py
new file mode 100644
index 0000000..e11795e
--- /dev/null
+++ b/src/domain/__init__.py
@@ -0,0 +1 @@
+"""Domain-level types and concepts."""
diff --git a/src/main.py b/src/main.py
new file mode 100644
index 0000000..9142d5c
--- /dev/null
+++ b/src/main.py
@@ -0,0 +1,201 @@
+from dataclasses import asdict, is_dataclass
+from datetime import datetime
+from typing import Optional
+
+from src.api import get_health, get_recent_backtest_summaries, get_recent_signals
+from src.services.backtest import BacktestService
+from src.services.bias import BiasService
+from src.services.displacement import DisplacementService
+from src.services.execution import ExecutionService
+from src.services.fvg import FVGService
+from src.services.liquidity import LiquidityPoolService
+from src.services.ranges import DealingRangeService
+from src.services.reports import IntradayReportService, PostTradeReviewService, PreMarketReportService
+from src.services.sessions import SessionGenerator
+from src.services.signals import SignalService
+from src.services.structure import MSSService
+from src.services.sweeps import SweepService
+from src.services.swings import SwingService
+
+
+def build_default_runtime_dependencies() -> dict:
+    return {
+        "session_generator": SessionGenerator(),
+        "swing_service": SwingService(),
+        "range_service": DealingRangeService(),
+        "liquidity_service": LiquidityPoolService(),
+        "sweep_service": SweepService(),
+        "displacement_service": DisplacementService(),
+        "mss_service": MSSService(),
+        "fvg_service": FVGService(),
+        "bias_service": BiasService(),
+        "signal_service": SignalService(),
+        "execution_service": ExecutionService(),
+        "backtest_service": BacktestService(),
+        "pre_market_report_service": PreMarketReportService(),
+        "intraday_report_service": IntradayReportService(),
+        "post_trade_review_service": PostTradeReviewService(),
+        "get_recent_signals": get_recent_signals,
+        "get_recent_backtest_summaries": get_recent_backtest_summaries,
+    }
+
+
+def run_closed_loop(
+    instrument_id: int = 1,
+    timeframe: str = "1m",
+    backtest_limit: int = 100,
+    run_execution: bool = True,
+    dependencies: Optional[dict] = None,
+) -> dict:
+    deps = dependencies or build_default_runtime_dependencies()
+    session_generator = deps["session_generator"]
+    now = datetime.now(session_generator.timezone)
+
+    session_written = session_generator.generate_for_date(instrument_id=instrument_id, timeframe=timeframe, session_date=now)
+
+    swing_service = deps["swing_service"]
+    swings = swing_service.detect_swings(instrument_id=instrument_id, timeframe=timeframe, left_bars=2, right_bars=2, limit=500)
+    swings_written = swing_service.persist_swings(instrument_id=instrument_id, timeframe=timeframe, candidates=swings)
+
+    range_service = deps["range_service"]
+    active_range = range_service.build_active_range(instrument_id=instrument_id, timeframe=timeframe)
+    ranges_written = range_service.persist_active_range(instrument_id=instrument_id, timeframe=timeframe, candidate=active_range)
+
+    liquidity_service = deps["liquidity_service"]
+    liquidity = liquidity_service.build_candidates(instrument_id=instrument_id, timeframe=timeframe)
+    liquidity_written = liquidity_service.persist_candidates(instrument_id=instrument_id, timeframe=timeframe, candidates=liquidity)
+
+    sweep_service = deps["sweep_service"]
+    sweeps = sweep_service.detect_sweeps(instrument_id=instrument_id, timeframe=timeframe)
+    sweeps_written = sweep_service.persist_sweeps(instrument_id=instrument_id, timeframe=timeframe, candidates=sweeps)
+
+    displacement_service = deps["displacement_service"]
+    displacements = displacement_service.detect_displacement(instrument_id=instrument_id, timeframe=timeframe, limit=200)
+    displacement_written = displacement_service.persist_displacement(instrument_id=instrument_id, timeframe=timeframe, candidates=displacements)
+
+    mss_service = deps["mss_service"]
+    mss_candidates = mss_service.detect_mss(instrument_id=instrument_id, timeframe=timeframe)
+    mss_written = mss_service.persist_mss(instrument_id=instrument_id, timeframe=timeframe, candidates=mss_candidates)
+
+    fvg_service = deps["fvg_service"]
+    fvgs = fvg_service.detect_fvg(instrument_id=instrument_id, timeframe=timeframe, limit=200)
+    fvg_written = fvg_service.persist_fvg(instrument_id=instrument_id, timeframe=timeframe, candidates=fvgs)
+    fvg_updated = fvg_service.update_existing_fvgs(instrument_id=instrument_id, timeframe=timeframe)
+
+    bias_service = deps["bias_service"]
+    bias = bias_service.build_bias(instrument_id=instrument_id, bias_tf=timeframe, setup_tf=timeframe, trigger_tf=timeframe)
+    bias_id = bias_service.persist_bias(instrument_id=instrument_id, bias_tf=timeframe, setup_tf=timeframe, trigger_tf=timeframe, candidate=bias)
+
+    signal_service = deps["signal_service"]
+    signal = signal_service.build_signal(instrument_id=instrument_id, setup_tf=timeframe, trigger_tf=timeframe)
+    signals_written = signal_service.persist_signal(instrument_id=instrument_id, setup_tf=timeframe, trigger_tf=timeframe, candidate=signal)
+
+    recent_signals = deps["get_recent_signals"](instrument_id=instrument_id, limit=1)
+    latest_signal = recent_signals[0] if recent_signals else None
+
+    execution_id = None
+    execution_record = None
+    if run_execution and latest_signal is not None:
+        execution_service = deps["execution_service"]
+        execution_id = execution_service.create_execution(signal_id=latest_signal["id"], execution_mode="paper")
+        execution_record = {
+            "status": "open" if execution_id is not None else "rejected",
+            "meta": {"risk_checks": [] if execution_id is not None else ["execution_creation_failed"]},
+        }
+
+    backtest_service = deps["backtest_service"]
+    backtest_run_id, outcomes = backtest_service.run_backtest(instrument_id=instrument_id, limit=backtest_limit)
+    recent_backtests = deps["get_recent_backtest_summaries"](instrument_id=instrument_id, limit=1)
+    latest_backtest = recent_backtests[0] if recent_backtests else None
+
+    pre_market_report = deps["pre_market_report_service"].build_report(
+        bias_snapshot=_to_payload(bias),
+        dealing_range=_to_payload(active_range),
+        current_price=_derive_current_price(signal),
+        session_code=(latest_signal or {}).get("session_code"),
+    )
+    intraday_report = deps["intraday_report_service"].build_report(
+        sweep_event=_to_payload(sweeps[-1]) if sweeps else None,
+        structure_event=_merge_structure_payload(mss_candidates[-1]) if mss_candidates else None,
+        fvg_zone=_to_payload(fvgs[-1]) if fvgs else None,
+        trade_signal=latest_signal,
+    )
+    post_trade_report = deps["post_trade_review_service"].build_report(
+        trade_execution=execution_record,
+        trade_signal=latest_signal,
+        backtest_result=_to_payload(outcomes[-1]) if outcomes else None,
+    )
+
+    return {
+        "health": get_health(),
+        "instrument_id": instrument_id,
+        "timeframe": timeframe,
+        "writes": {
+            "sessions": session_written,
+            "swings": swings_written,
+            "ranges": ranges_written,
+            "liquidity_pools": liquidity_written,
+            "sweeps": sweeps_written,
+            "displacements": displacement_written,
+            "mss": mss_written,
+            "fvg_detected": fvg_written,
+            "fvg_updated": fvg_updated,
+            "bias_snapshot_id": bias_id,
+            "signals": signals_written,
+            "execution_id": execution_id,
+            "backtest_run_id": backtest_run_id,
+        },
+        "reports": {
+            "pre_market": pre_market_report,
+            "intraday": intraday_report,
+            "post_trade": post_trade_report,
+        },
+        "latest_signal": latest_signal,
+        "latest_backtest": latest_backtest,
+    }
+
+
+def main() -> None:
+    health = get_health()
+    print("AI ICT scaffold ready")
+    print(f"Database URL configured: {health['database_configured']}")
+    print(f"Session timezone: {health['session_timezone']}")
+
+
+def _to_payload(value):
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return value
+    if is_dataclass(value):
+        return asdict(value)
+    if hasattr(value, "__dict__"):
+        return {
+            key: val
+            for key, val in vars(value).items()
+            if not key.startswith("_")
+        }
+    return value
+
+
+def _merge_structure_payload(candidate) -> Optional[dict]:
+    payload = _to_payload(candidate)
+    if payload is None:
+        return None
+    payload["event_type"] = "MSS"
+    return payload
+
+
+def _derive_current_price(signal) -> Optional[float]:
+    payload = _to_payload(signal)
+    if payload is None or not isinstance(payload, dict):
+        return None
+    entry_low = float(payload.get("entry_low") or 0.0)
+    entry_high = float(payload.get("entry_high") or 0.0)
+    if entry_low and entry_high:
+        return (entry_low + entry_high) / 2
+    return entry_low or entry_high or None
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/models/__init__.py b/src/models/__init__.py
new file mode 100644
index 0000000..e482912
--- /dev/null
+++ b/src/models/__init__.py
@@ -0,0 +1,37 @@
+"""Database model package exports."""
+
+from src.models.backtest_result import BacktestResult
+from src.models.backtest_run import BacktestRun
+from src.models.bias_snapshot import BiasSnapshot
+from src.models.candle import Candle
+from src.models.dealing_range import DealingRange
+from src.models.displacement_event import DisplacementEvent
+from src.models.fvg_zone import FVGZone
+from src.models.instrument import Instrument
+from src.models.liquidity_pool import LiquidityPool
+from src.models.market_session import MarketSession
+from src.models.structure_event import StructureEvent
+from src.models.sweep_event import SweepEvent
+from src.models.swing import Swing
+from src.models.trade_execution import TradeExecution
+from src.models.trade_signal import TradeSignal
+from src.models.venue import Venue
+
+__all__ = [
+    "BacktestResult",
+    "BacktestRun",
+    "BiasSnapshot",
+    "Candle",
+    "DealingRange",
+    "DisplacementEvent",
+    "FVGZone",
+    "Instrument",
+    "LiquidityPool",
+    "MarketSession",
+    "StructureEvent",
+    "SweepEvent",
+    "Swing",
+    "TradeExecution",
+    "TradeSignal",
+    "Venue",
+]
diff --git a/src/models/backtest_result.py b/src/models/backtest_result.py
new file mode 100644
index 0000000..193952d
--- /dev/null
+++ b/src/models/backtest_result.py
@@ -0,0 +1,22 @@
+from typing import Any, Optional, Union
+from sqlalchemy import ForeignKey, Numeric, Text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.db.base import Base
+
+
+class BacktestResult(Base):
+    __tablename__ = "backtest_results"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    backtest_run_id: Mapped[int] = mapped_column(ForeignKey("backtest_runs.id"), nullable=False)
+    signal_id: Mapped[Optional[int]] = mapped_column(ForeignKey("trade_signals.id"))
+    outcome: Mapped[str] = mapped_column(Text, nullable=False)
+    mfe: Mapped[Optional[float]] = mapped_column(Numeric(20, 10))
+    mae: Mapped[Optional[float]] = mapped_column(Numeric(20, 10))
+    tp1_hit: Mapped[Optional[bool]] = mapped_column()
+    tp2_hit: Mapped[Optional[bool]] = mapped_column()
+    invalidated_before_entry: Mapped[Optional[bool]] = mapped_column()
+    error_tags: Mapped[list] = mapped_column(JSONB, nullable=False, default=list)
+    meta: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)
diff --git a/src/models/backtest_run.py b/src/models/backtest_run.py
new file mode 100644
index 0000000..da5bb78
--- /dev/null
+++ b/src/models/backtest_run.py
@@ -0,0 +1,19 @@
+from typing import Any, Optional, Union
+from sqlalchemy import ForeignKey, Text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.db.base import Base
+
+
+class BacktestRun(Base):
+    __tablename__ = "backtest_runs"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    model_code: Mapped[str] = mapped_column(Text, nullable=False)
+    instrument_id: Mapped[Optional[int]] = mapped_column(ForeignKey("instruments.id"))
+    timeframe_set: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)
+    started_ts: Mapped[object] = mapped_column(nullable=False)
+    ended_ts: Mapped[Optional[object]] = mapped_column()
+    config: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)
+    summary: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)
diff --git a/src/models/bias_snapshot.py b/src/models/bias_snapshot.py
new file mode 100644
index 0000000..671b149
--- /dev/null
+++ b/src/models/bias_snapshot.py
@@ -0,0 +1,25 @@
+from typing import Any, Optional, Union
+from sqlalchemy import ForeignKey, Numeric, Text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.db.base import Base
+
+
+class BiasSnapshot(Base):
+    __tablename__ = "bias_snapshots"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    instrument_id: Mapped[int] = mapped_column(ForeignKey("instruments.id"), nullable=False)
+    bias_tf: Mapped[str] = mapped_column(Text, nullable=False)
+    setup_tf: Mapped[str] = mapped_column(Text, nullable=False)
+    trigger_tf: Mapped[str] = mapped_column(Text, nullable=False)
+    snapshot_ts: Mapped[object] = mapped_column(nullable=False)
+    daily_bias: Mapped[str] = mapped_column(Text, nullable=False)
+    confidence: Mapped[Optional[float]] = mapped_column(Numeric(8, 4))
+    execution_intensity: Mapped[str] = mapped_column(Text, nullable=False)
+    narrative_code: Mapped[Optional[str]] = mapped_column(Text)
+    draw_side: Mapped[Optional[str]] = mapped_column(Text)
+    range_id: Mapped[Optional[int]] = mapped_column(ForeignKey("dealing_ranges.id"))
+    reason_codes: Mapped[list] = mapped_column(JSONB, nullable=False, default=list)
+    meta: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)
diff --git a/src/models/candle.py b/src/models/candle.py
new file mode 100644
index 0000000..49ecaf6
--- /dev/null
+++ b/src/models/candle.py
@@ -0,0 +1,22 @@
+from typing import Any, Optional, Union
+from sqlalchemy import ForeignKey, Numeric, Text, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.db.base import Base
+
+
+class Candle(Base):
+    __tablename__ = "candles"
+    __table_args__ = (UniqueConstraint("instrument_id", "timeframe", "ts_open", name="uq_candles_instrument_tf_ts_open"),)
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    instrument_id: Mapped[int] = mapped_column(ForeignKey("instruments.id"), nullable=False)
+    timeframe: Mapped[str] = mapped_column(Text, nullable=False)
+    ts_open: Mapped[object] = mapped_column(nullable=False)
+    ts_close: Mapped[object] = mapped_column(nullable=False)
+    open: Mapped[float] = mapped_column(Numeric(20, 10), nullable=False)
+    high: Mapped[float] = mapped_column(Numeric(20, 10), nullable=False)
+    low: Mapped[float] = mapped_column(Numeric(20, 10), nullable=False)
+    close: Mapped[float] = mapped_column(Numeric(20, 10), nullable=False)
+    volume: Mapped[Optional[float]] = mapped_column(Numeric(28, 10))
+    source: Mapped[str] = mapped_column(Text, nullable=False, default="api")
diff --git a/src/models/dealing_range.py b/src/models/dealing_range.py
new file mode 100644
index 0000000..fcb74cc
--- /dev/null
+++ b/src/models/dealing_range.py
@@ -0,0 +1,23 @@
+from typing import Any, Optional, Union
+from sqlalchemy import ForeignKey, Numeric, Text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.db.base import Base
+
+
+class DealingRange(Base):
+    __tablename__ = "dealing_ranges"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    instrument_id: Mapped[int] = mapped_column(ForeignKey("instruments.id"), nullable=False)
+    timeframe: Mapped[str] = mapped_column(Text, nullable=False)
+    high: Mapped[float] = mapped_column(Numeric(20, 10), nullable=False)
+    low: Mapped[float] = mapped_column(Numeric(20, 10), nullable=False)
+    equilibrium: Mapped[float] = mapped_column(Numeric(20, 10), nullable=False)
+    high_swing_id: Mapped[Optional[int]] = mapped_column(ForeignKey("swings.id"))
+    low_swing_id: Mapped[Optional[int]] = mapped_column(ForeignKey("swings.id"))
+    state: Mapped[str] = mapped_column(Text, nullable=False, default="valid")
+    ts_start: Mapped[object] = mapped_column(nullable=False)
+    ts_end: Mapped[Optional[object]] = mapped_column()
+    meta: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)
diff --git a/src/models/displacement_event.py b/src/models/displacement_event.py
new file mode 100644
index 0000000..c6e2414
--- /dev/null
+++ b/src/models/displacement_event.py
@@ -0,0 +1,22 @@
+from typing import Any, Optional, Union
+from sqlalchemy import ForeignKey, Numeric, Text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.db.base import Base
+
+
+class DisplacementEvent(Base):
+    __tablename__ = "displacement_events"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    instrument_id: Mapped[int] = mapped_column(ForeignKey("instruments.id"), nullable=False)
+    timeframe: Mapped[str] = mapped_column(Text, nullable=False)
+    direction: Mapped[str] = mapped_column(Text, nullable=False)
+    start_ts: Mapped[object] = mapped_column(nullable=False)
+    end_ts: Mapped[object] = mapped_column(nullable=False)
+    strength_score: Mapped[Optional[float]] = mapped_column(Numeric(8, 4))
+    body_ratio: Mapped[Optional[float]] = mapped_column(Numeric(8, 4))
+    has_fvg: Mapped[bool] = mapped_column(nullable=False, default=False)
+    is_valid: Mapped[bool] = mapped_column(nullable=False, default=True)
+    meta: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)
diff --git a/src/models/fvg_zone.py b/src/models/fvg_zone.py
new file mode 100644
index 0000000..eb99a60
--- /dev/null
+++ b/src/models/fvg_zone.py
@@ -0,0 +1,23 @@
+from typing import Any, Optional, Union
+from sqlalchemy import ForeignKey, Numeric, Text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.db.base import Base
+
+
+class FVGZone(Base):
+    __tablename__ = "fvg_zones"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    instrument_id: Mapped[int] = mapped_column(ForeignKey("instruments.id"), nullable=False)
+    timeframe: Mapped[str] = mapped_column(Text, nullable=False)
+    direction: Mapped[str] = mapped_column(Text, nullable=False)
+    upper: Mapped[float] = mapped_column(Numeric(20, 10), nullable=False)
+    lower: Mapped[float] = mapped_column(Numeric(20, 10), nullable=False)
+    start_ts: Mapped[object] = mapped_column(nullable=False)
+    end_ts: Mapped[object] = mapped_column(nullable=False)
+    fill_pct: Mapped[float] = mapped_column(Numeric(8, 4), nullable=False, default=0)
+    status: Mapped[str] = mapped_column(Text, nullable=False, default="open")
+    related_displacement_id: Mapped[Optional[int]] = mapped_column(ForeignKey("displacement_events.id"))
+    meta: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)
diff --git a/src/models/instrument.py b/src/models/instrument.py
new file mode 100644
index 0000000..640c8a2
--- /dev/null
+++ b/src/models/instrument.py
@@ -0,0 +1,26 @@
+from typing import Any, Optional, Union
+from sqlalchemy import BigInteger, Boolean, ForeignKey, Integer, Numeric, Text, UniqueConstraint
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.db.base import Base
+
+
+class Instrument(Base):
+    __tablename__ = "instruments"
+    __table_args__ = (UniqueConstraint("venue_id", "symbol", name="uq_instruments_venue_symbol"),)
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    venue_id: Mapped[int] = mapped_column(ForeignKey("venues.id"), nullable=False)
+    symbol: Mapped[str] = mapped_column(Text, nullable=False)
+    asset_class: Mapped[str] = mapped_column(Text, nullable=False)
+    base_asset: Mapped[Optional[str]] = mapped_column(Text)
+    quote_asset: Mapped[Optional[str]] = mapped_column(Text)
+    price_scale: Mapped[int] = mapped_column(Integer, nullable=False)
+    qty_scale: Mapped[int] = mapped_column(Integer, nullable=False)
+    tick_size: Mapped[float] = mapped_column(Numeric(20, 10), nullable=False)
+    lot_size: Mapped[Optional[float]] = mapped_column(Numeric(20, 10))
+    active: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+    meta: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)
+
+    venue = relationship("Venue", back_populates="instruments")
diff --git a/src/models/liquidity_pool.py b/src/models/liquidity_pool.py
new file mode 100644
index 0000000..e75f73c
--- /dev/null
+++ b/src/models/liquidity_pool.py
@@ -0,0 +1,22 @@
+from sqlalchemy import ForeignKey, Numeric, Text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.db.base import Base
+
+
+class LiquidityPool(Base):
+    __tablename__ = "liquidity_pools"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    instrument_id: Mapped[int] = mapped_column(ForeignKey("instruments.id"), nullable=False)
+    timeframe: Mapped[str] = mapped_column(Text, nullable=False)
+    side: Mapped[str] = mapped_column(Text, nullable=False)
+    pool_type: Mapped[str] = mapped_column(Text, nullable=False)
+    price_low: Mapped[float] = mapped_column(Numeric(20, 10), nullable=False)
+    price_high: Mapped[float] = mapped_column(Numeric(20, 10), nullable=False)
+    reference_ids: Mapped[list] = mapped_column(JSONB, nullable=False, default=list)
+    status: Mapped[str] = mapped_column(Text, nullable=False, default="untouched")
+    created_ts: Mapped[object] = mapped_column(nullable=False)
+    updated_ts: Mapped[object] = mapped_column(nullable=False)
+    meta: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)
diff --git a/src/models/market_session.py b/src/models/market_session.py
new file mode 100644
index 0000000..2082e37
--- /dev/null
+++ b/src/models/market_session.py
@@ -0,0 +1,26 @@
+from typing import Any, Optional, Union
+from sqlalchemy import Date, ForeignKey, Numeric, Text, UniqueConstraint
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.db.base import Base
+
+
+class MarketSession(Base):
+    __tablename__ = "market_sessions"
+    __table_args__ = (
+        UniqueConstraint("instrument_id", "session_date", "session_code", "timezone", name="uq_market_sessions_identity"),
+    )
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    instrument_id: Mapped[int] = mapped_column(ForeignKey("instruments.id"), nullable=False)
+    session_date: Mapped[object] = mapped_column(Date, nullable=False)
+    timezone: Mapped[str] = mapped_column(Text, nullable=False)
+    session_code: Mapped[str] = mapped_column(Text, nullable=False)
+    start_ts: Mapped[object] = mapped_column(nullable=False)
+    end_ts: Mapped[object] = mapped_column(nullable=False)
+    high: Mapped[Optional[float]] = mapped_column(Numeric(20, 10))
+    low: Mapped[Optional[float]] = mapped_column(Numeric(20, 10))
+    midpoint: Mapped[Optional[float]] = mapped_column(Numeric(20, 10))
+    status: Mapped[str] = mapped_column(Text, nullable=False, default="closed")
+    meta: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)
diff --git a/src/models/structure_event.py b/src/models/structure_event.py
new file mode 100644
index 0000000..10a248c
--- /dev/null
+++ b/src/models/structure_event.py
@@ -0,0 +1,23 @@
+from typing import Any, Optional, Union
+from sqlalchemy import ForeignKey, Numeric, Text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.db.base import Base
+
+
+class StructureEvent(Base):
+    __tablename__ = "structure_events"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    instrument_id: Mapped[int] = mapped_column(ForeignKey("instruments.id"), nullable=False)
+    timeframe: Mapped[str] = mapped_column(Text, nullable=False)
+    event_type: Mapped[str] = mapped_column(Text, nullable=False)
+    direction: Mapped[str] = mapped_column(Text, nullable=False)
+    broken_level: Mapped[float] = mapped_column(Numeric(20, 10), nullable=False)
+    reference_swing_id: Mapped[Optional[int]] = mapped_column(ForeignKey("swings.id"))
+    displacement_event_id: Mapped[Optional[int]] = mapped_column(ForeignKey("displacement_events.id"))
+    accepted: Mapped[Optional[bool]] = mapped_column()
+    signal_relevant: Mapped[bool] = mapped_column(nullable=False, default=True)
+    ts: Mapped[object] = mapped_column(nullable=False)
+    meta: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)
diff --git a/src/models/sweep_event.py b/src/models/sweep_event.py
new file mode 100644
index 0000000..42fe008
--- /dev/null
+++ b/src/models/sweep_event.py
@@ -0,0 +1,25 @@
+from sqlalchemy import Boolean, ForeignKey, Numeric, Text, UniqueConstraint
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.db.base import Base
+
+
+class SweepEvent(Base):
+    __tablename__ = "sweep_events"
+    __table_args__ = (
+        UniqueConstraint("instrument_id", "timeframe", "pool_id", "sweep_ts", name="uq_sweep_events_identity"),
+    )
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    instrument_id: Mapped[int] = mapped_column(ForeignKey("instruments.id"), nullable=False)
+    timeframe: Mapped[str] = mapped_column(Text, nullable=False)
+    side_swept: Mapped[str] = mapped_column(Text, nullable=False)
+    pool_id: Mapped[int] = mapped_column(ForeignKey("liquidity_pools.id"), nullable=False)
+    sweep_high: Mapped[float] = mapped_column(Numeric(20, 10), nullable=False)
+    sweep_low: Mapped[float] = mapped_column(Numeric(20, 10), nullable=False)
+    sweep_ts: Mapped[object] = mapped_column(nullable=False)
+    close_back_inside: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+    validation_level: Mapped[str] = mapped_column(Text, nullable=False, default="weak")
+    status: Mapped[str] = mapped_column(Text, nullable=False, default="active")
+    meta: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)
diff --git a/src/models/swing.py b/src/models/swing.py
new file mode 100644
index 0000000..f7088c0
--- /dev/null
+++ b/src/models/swing.py
@@ -0,0 +1,21 @@
+from sqlalchemy import ForeignKey, Numeric, Text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.db.base import Base
+
+
+class Swing(Base):
+    __tablename__ = "swings"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    instrument_id: Mapped[int] = mapped_column(ForeignKey("instruments.id"), nullable=False)
+    timeframe: Mapped[str] = mapped_column(Text, nullable=False)
+    kind: Mapped[str] = mapped_column(Text, nullable=False)
+    strength: Mapped[str] = mapped_column(Text, nullable=False)
+    price: Mapped[float] = mapped_column(Numeric(20, 10), nullable=False)
+    ts: Mapped[object] = mapped_column(nullable=False)
+    left_bars: Mapped[int] = mapped_column(nullable=False)
+    right_bars: Mapped[int] = mapped_column(nullable=False)
+    confirmed: Mapped[bool] = mapped_column(nullable=False, default=True)
+    meta: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)
diff --git a/src/models/trade_execution.py b/src/models/trade_execution.py
new file mode 100644
index 0000000..458034d
--- /dev/null
+++ b/src/models/trade_execution.py
@@ -0,0 +1,27 @@
+from typing import Any, Optional, Union
+from sqlalchemy import ForeignKey, Numeric, Text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.db.base import Base
+
+
+class TradeExecution(Base):
+    __tablename__ = "trade_executions"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    signal_id: Mapped[int] = mapped_column(ForeignKey("trade_signals.id"), nullable=False)
+    venue_order_id: Mapped[Optional[str]] = mapped_column(Text)
+    execution_mode: Mapped[str] = mapped_column(Text, nullable=False)
+    side: Mapped[str] = mapped_column(Text, nullable=False)
+    entry_price: Mapped[Optional[float]] = mapped_column(Numeric(20, 10))
+    stop_loss: Mapped[Optional[float]] = mapped_column(Numeric(20, 10))
+    take_profit_1: Mapped[Optional[float]] = mapped_column(Numeric(20, 10))
+    take_profit_2: Mapped[Optional[float]] = mapped_column(Numeric(20, 10))
+    size: Mapped[Optional[float]] = mapped_column(Numeric(28, 10))
+    risk_pct: Mapped[Optional[float]] = mapped_column(Numeric(8, 4))
+    status: Mapped[str] = mapped_column(Text, nullable=False)
+    opened_ts: Mapped[Optional[object]] = mapped_column()
+    closed_ts: Mapped[Optional[object]] = mapped_column()
+    pnl: Mapped[Optional[float]] = mapped_column(Numeric(28, 10))
+    meta: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)
diff --git a/src/models/trade_signal.py b/src/models/trade_signal.py
new file mode 100644
index 0000000..01146b8
--- /dev/null
+++ b/src/models/trade_signal.py
@@ -0,0 +1,31 @@
+from typing import Any, Optional, Union
+from sqlalchemy import ForeignKey, Numeric, Text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.db.base import Base
+
+
+class TradeSignal(Base):
+    __tablename__ = "trade_signals"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    instrument_id: Mapped[int] = mapped_column(ForeignKey("instruments.id"), nullable=False)
+    model_code: Mapped[str] = mapped_column(Text, nullable=False)
+    side: Mapped[str] = mapped_column(Text, nullable=False)
+    status: Mapped[str] = mapped_column(Text, nullable=False)
+    bias_snapshot_id: Mapped[Optional[int]] = mapped_column(ForeignKey("bias_snapshots.id"))
+    entry_type: Mapped[str] = mapped_column(Text, nullable=False)
+    entry_low: Mapped[Optional[float]] = mapped_column(Numeric(20, 10))
+    entry_high: Mapped[Optional[float]] = mapped_column(Numeric(20, 10))
+    stop_loss: Mapped[Optional[float]] = mapped_column(Numeric(20, 10))
+    tp1: Mapped[Optional[float]] = mapped_column(Numeric(20, 10))
+    tp2: Mapped[Optional[float]] = mapped_column(Numeric(20, 10))
+    rr_tp1: Mapped[Optional[float]] = mapped_column(Numeric(8, 4))
+    rr_tp2: Mapped[Optional[float]] = mapped_column(Numeric(8, 4))
+    session_code: Mapped[Optional[str]] = mapped_column(Text)
+    created_ts: Mapped[object] = mapped_column(nullable=False)
+    expires_ts: Mapped[Optional[object]] = mapped_column()
+    invalidations: Mapped[list] = mapped_column(JSONB, nullable=False, default=list)
+    evidence: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)
+    meta: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)
diff --git a/src/models/venue.py b/src/models/venue.py
new file mode 100644
index 0000000..e73f768
--- /dev/null
+++ b/src/models/venue.py
@@ -0,0 +1,16 @@
+from sqlalchemy import BigInteger, Boolean, Integer, Numeric, Text, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.db.base import Base
+
+
+class Venue(Base):
+    __tablename__ = "venues"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    code: Mapped[str] = mapped_column(Text, unique=True, nullable=False)
+    name: Mapped[str] = mapped_column(Text, nullable=False)
+    timezone: Mapped[str] = mapped_column(Text, nullable=False)
+    status: Mapped[str] = mapped_column(Text, nullable=False, default="active")
+
+    instruments = relationship("Instrument", back_populates="venue")
diff --git a/src/repositories/__init__.py b/src/repositories/__init__.py
new file mode 100644
index 0000000..a79a431
--- /dev/null
+++ b/src/repositories/__init__.py
@@ -0,0 +1,31 @@
+"""Repository layer package."""
+
+from src.repositories.backtest_repository import BacktestRepository
+from src.repositories.bias_repository import BiasRepository
+from src.repositories.candle_repository import CandleRepository
+from src.repositories.dealing_range_repository import DealingRangeRepository
+from src.repositories.displacement_repository import DisplacementRepository
+from src.repositories.execution_repository import ExecutionRepository
+from src.repositories.fvg_repository import FVGRepository
+from src.repositories.liquidity_pool_repository import LiquidityPoolRepository
+from src.repositories.market_session_repository import MarketSessionRepository
+from src.repositories.signal_repository import SignalRepository
+from src.repositories.structure_repository import StructureRepository
+from src.repositories.swing_repository import SwingRepository
+from src.repositories.sweep_repository import SweepRepository
+
+__all__ = [
+    "BacktestRepository",
+    "BiasRepository",
+    "CandleRepository",
+    "DealingRangeRepository",
+    "DisplacementRepository",
+    "ExecutionRepository",
+    "FVGRepository",
+    "LiquidityPoolRepository",
+    "MarketSessionRepository",
+    "SignalRepository",
+    "StructureRepository",
+    "SwingRepository",
+    "SweepRepository",
+]
diff --git a/src/repositories/backtest_repository.py b/src/repositories/backtest_repository.py
new file mode 100644
index 0000000..375e5bb
--- /dev/null
+++ b/src/repositories/backtest_repository.py
@@ -0,0 +1,176 @@
+from datetime import datetime, timezone
+import json
+
+from sqlalchemy import text
+
+from src.db.session import SessionLocal
+
+
+class BacktestRepository:
+    def fetch_candidate_signals(self, instrument_id: int, limit: int = 100) -> list[dict]:
+        sql = text(
+            """
+            select id, side, entry_low, entry_high, stop_loss, tp1, tp2, rr_tp1, rr_tp2, created_ts, expires_ts
+            from trade_signals
+            where instrument_id = :instrument_id
+            order by created_ts desc
+            limit :limit
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(sql, {"instrument_id": instrument_id, "limit": limit}).mappings().all()
+        return [dict(row) for row in rows]
+
+    def fetch_future_candles(self, instrument_id: int, timeframe: str, start_ts, end_ts, limit: int = 500) -> list[dict]:
+        sql = text(
+            """
+            select ts_open, ts_close, open, high, low, close
+            from candles
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+              and ts_open >= :start_ts
+              and ts_open <= :end_ts
+            order by ts_open asc
+            limit :limit
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(
+                sql,
+                {
+                    "instrument_id": instrument_id,
+                    "timeframe": timeframe,
+                    "start_ts": start_ts,
+                    "end_ts": end_ts,
+                    "limit": limit,
+                },
+            ).mappings().all()
+        return [dict(row) for row in rows]
+
+    def fetch_sessions_covering_window(self, instrument_id: int, start_ts, end_ts) -> list[dict]:
+        sql = text(
+            """
+            select id, session_code, start_ts, end_ts, status
+            from market_sessions
+            where instrument_id = :instrument_id
+              and start_ts <= :end_ts
+              and end_ts >= :start_ts
+            order by start_ts asc
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(
+                sql,
+                {"instrument_id": instrument_id, "start_ts": start_ts, "end_ts": end_ts},
+            ).mappings().all()
+        return [dict(row) for row in rows]
+
+    def insert_backtest_run(self, model_code: str, instrument_id: int, timeframe_set: dict, config: dict) -> int:
+        sql = text(
+            """
+            insert into backtest_runs (
+                model_code,
+                instrument_id,
+                timeframe_set,
+                started_ts,
+                config,
+                summary
+            ) values (
+                :model_code,
+                :instrument_id,
+                cast(:timeframe_set as jsonb),
+                :started_ts,
+                cast(:config as jsonb),
+                '{}'::jsonb
+            )
+            returning id
+            """
+        )
+        with SessionLocal.begin() as session:
+            result = session.execute(
+                sql,
+                {
+                    "model_code": model_code,
+                    "instrument_id": instrument_id,
+                    "timeframe_set": json.dumps(timeframe_set),
+                    "started_ts": datetime.now(timezone.utc),
+                    "config": json.dumps(config),
+                },
+            )
+            return int(result.scalar_one())
+
+    def insert_backtest_result(
+        self,
+        backtest_run_id: int,
+        signal_id: int,
+        outcome: str,
+        mfe: float,
+        mae: float,
+        tp1_hit: bool,
+        tp2_hit: bool,
+        invalidated_before_entry: bool,
+        error_tags: list,
+        meta: dict,
+    ) -> None:
+        sql = text(
+            """
+            insert into backtest_results (
+                backtest_run_id,
+                signal_id,
+                outcome,
+                mfe,
+                mae,
+                tp1_hit,
+                tp2_hit,
+                invalidated_before_entry,
+                error_tags,
+                meta
+            ) values (
+                :backtest_run_id,
+                :signal_id,
+                :outcome,
+                :mfe,
+                :mae,
+                :tp1_hit,
+                :tp2_hit,
+                :invalidated_before_entry,
+                cast(:error_tags as jsonb),
+                cast(:meta as jsonb)
+            )
+            """
+        )
+        with SessionLocal.begin() as session:
+            session.execute(
+                sql,
+                {
+                    "backtest_run_id": backtest_run_id,
+                    "signal_id": signal_id,
+                    "outcome": outcome,
+                    "mfe": mfe,
+                    "mae": mae,
+                    "tp1_hit": tp1_hit,
+                    "tp2_hit": tp2_hit,
+                    "invalidated_before_entry": invalidated_before_entry,
+                    "error_tags": json.dumps(error_tags, default=str),
+                    "meta": json.dumps(meta, default=str),
+                },
+            )
+
+    def update_backtest_run_summary(self, backtest_run_id: int, summary: dict) -> None:
+        sql = text(
+            """
+            update backtest_runs
+            set summary = cast(:summary as jsonb),
+                ended_ts = :ended_ts
+            where id = :backtest_run_id
+            """
+        )
+        with SessionLocal.begin() as session:
+            session.execute(
+                sql,
+                {
+                    "backtest_run_id": backtest_run_id,
+                    "summary": json.dumps(summary, default=str),
+                    "ended_ts": datetime.now(timezone.utc),
+                },
+            )
diff --git a/src/repositories/bias_repository.py b/src/repositories/bias_repository.py
new file mode 100644
index 0000000..3e4a16a
--- /dev/null
+++ b/src/repositories/bias_repository.py
@@ -0,0 +1,135 @@
+from sqlalchemy import text
+import json
+from typing import Optional
+
+from src.db.session import SessionLocal
+
+
+class BiasRepository:
+    def fetch_latest_range(self, instrument_id: int, timeframe: str) -> Optional[dict]:
+        sql = text(
+            """
+            select id, high, low, equilibrium, state, ts_start
+            from dealing_ranges
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+              and state = 'valid'
+            order by ts_start desc
+            limit 1
+            """
+        )
+        with SessionLocal() as session:
+            row = session.execute(sql, {"instrument_id": instrument_id, "timeframe": timeframe}).mappings().first()
+        return dict(row) if row else None
+
+    def fetch_latest_mss(self, instrument_id: int, timeframe: str) -> Optional[dict]:
+        sql = text(
+            """
+            select id, direction, broken_level, accepted, ts
+            from structure_events
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+              and event_type = 'MSS'
+            order by ts desc
+            limit 1
+            """
+        )
+        with SessionLocal() as session:
+            row = session.execute(sql, {"instrument_id": instrument_id, "timeframe": timeframe}).mappings().first()
+        return dict(row) if row else None
+
+    def fetch_latest_bias_snapshot(self, instrument_id: int, bias_tf: str, setup_tf: str, trigger_tf: str) -> Optional[dict]:
+        sql = text(
+            """
+            select id, daily_bias, confidence, execution_intensity, narrative_code, draw_side, range_id, reason_codes, meta
+            from bias_snapshots
+            where instrument_id = :instrument_id
+              and bias_tf = :bias_tf
+              and setup_tf = :setup_tf
+              and trigger_tf = :trigger_tf
+            order by snapshot_ts desc
+            limit 1
+            """
+        )
+        with SessionLocal() as session:
+            row = session.execute(
+                sql,
+                {
+                    "instrument_id": instrument_id,
+                    "bias_tf": bias_tf,
+                    "setup_tf": setup_tf,
+                    "trigger_tf": trigger_tf,
+                },
+            ).mappings().first()
+        return dict(row) if row else None
+
+    def insert_bias_snapshot(
+        self,
+        instrument_id: int,
+        bias_tf: str,
+        setup_tf: str,
+        trigger_tf: str,
+        snapshot_ts,
+        daily_bias: str,
+        confidence: float,
+        execution_intensity: str,
+        narrative_code: Optional[str],
+        draw_side: Optional[str],
+        range_id: Optional[int],
+        reason_codes: list,
+        meta: dict,
+    ) -> int:
+        sql = text(
+            """
+            insert into bias_snapshots (
+                instrument_id,
+                bias_tf,
+                setup_tf,
+                trigger_tf,
+                snapshot_ts,
+                daily_bias,
+                confidence,
+                execution_intensity,
+                narrative_code,
+                draw_side,
+                range_id,
+                reason_codes,
+                meta
+            ) values (
+                :instrument_id,
+                :bias_tf,
+                :setup_tf,
+                :trigger_tf,
+                :snapshot_ts,
+                :daily_bias,
+                :confidence,
+                :execution_intensity,
+                :narrative_code,
+                :draw_side,
+                :range_id,
+                cast(:reason_codes as jsonb),
+                cast(:meta as jsonb)
+            )
+            returning id
+            """
+        )
+        with SessionLocal.begin() as session:
+            result = session.execute(
+                sql,
+                {
+                    "instrument_id": instrument_id,
+                    "bias_tf": bias_tf,
+                    "setup_tf": setup_tf,
+                    "trigger_tf": trigger_tf,
+                    "snapshot_ts": snapshot_ts,
+                    "daily_bias": daily_bias,
+                    "confidence": confidence,
+                    "execution_intensity": execution_intensity,
+                    "narrative_code": narrative_code,
+                    "draw_side": draw_side,
+                    "range_id": range_id,
+                    "reason_codes": json.dumps(reason_codes),
+                    "meta": json.dumps(meta),
+                },
+            )
+            return int(result.scalar_one())
diff --git a/src/repositories/candle_repository.py b/src/repositories/candle_repository.py
new file mode 100644
index 0000000..10965b8
--- /dev/null
+++ b/src/repositories/candle_repository.py
@@ -0,0 +1,81 @@
+from decimal import Decimal
+from datetime import datetime, timezone
+
+from sqlalchemy import text
+
+from src.db.session import SessionLocal
+from src.services.market_data.normalizer import NormalizedCandle
+
+
+class CandleRepository:
+    def upsert_many(self, candles: list[NormalizedCandle], instrument_id: int) -> int:
+        if not candles:
+            return 0
+
+        sql = text(
+            """
+            insert into candles (
+                instrument_id,
+                timeframe,
+                ts_open,
+                ts_close,
+                open,
+                high,
+                low,
+                close,
+                volume,
+                source
+            ) values (
+                :instrument_id,
+                :timeframe,
+                :ts_open,
+                :ts_close,
+                :open,
+                :high,
+                :low,
+                :close,
+                :volume,
+                :source
+            )
+            on conflict (instrument_id, timeframe, ts_open)
+            do update set
+                ts_close = excluded.ts_close,
+                open = excluded.open,
+                high = excluded.high,
+                low = excluded.low,
+                close = excluded.close,
+                volume = excluded.volume,
+                source = excluded.source
+            """
+        )
+
+        rows = []
+        for candle in candles:
+            ts_open = datetime.fromtimestamp(candle.ts_open_ms / 1000, tz=timezone.utc)
+            if candle.timeframe.endswith("m"):
+                minutes = int(candle.timeframe[:-1])
+                ts_close = datetime.fromtimestamp((candle.ts_open_ms + minutes * 60 * 1000 - 1) / 1000, tz=timezone.utc)
+            elif candle.timeframe.endswith("h"):
+                hours = int(candle.timeframe[:-1])
+                ts_close = datetime.fromtimestamp((candle.ts_open_ms + hours * 60 * 60 * 1000 - 1) / 1000, tz=timezone.utc)
+            else:
+                ts_close = ts_open
+            rows.append(
+                {
+                    "instrument_id": instrument_id,
+                    "timeframe": candle.timeframe,
+                    "ts_open": ts_open,
+                    "ts_close": ts_close,
+                    "open": candle.open,
+                    "high": candle.high,
+                    "low": candle.low,
+                    "close": candle.close,
+                    "volume": candle.volume,
+                    "source": candle.venue.lower(),
+                }
+            )
+
+        with SessionLocal.begin() as session:
+            session.execute(sql, rows)
+
+        return len(rows)
diff --git a/src/repositories/dealing_range_repository.py b/src/repositories/dealing_range_repository.py
new file mode 100644
index 0000000..0e90c36
--- /dev/null
+++ b/src/repositories/dealing_range_repository.py
@@ -0,0 +1,95 @@
+from decimal import Decimal
+import json
+from datetime import datetime
+
+from sqlalchemy import text
+
+from src.db.session import SessionLocal
+
+
+class DealingRangeRepository:
+    def fetch_recent_swings(self, instrument_id: int, timeframe: str, limit: int = 100) -> list[dict]:
+        sql = text(
+            """
+            select id, kind, strength, price, ts, confirmed
+            from swings
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+              and confirmed = true
+            order by ts desc
+            limit :limit
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(
+                sql,
+                {"instrument_id": instrument_id, "timeframe": timeframe, "limit": limit},
+            ).mappings().all()
+        return [dict(row) for row in rows]
+
+    def upsert_range(
+        self,
+        instrument_id: int,
+        timeframe: str,
+        high: Decimal,
+        low: Decimal,
+        equilibrium: Decimal,
+        high_swing_id: int,
+        low_swing_id: int,
+        ts_start: datetime,
+        meta: dict,
+    ) -> None:
+        deactivate_sql = text(
+            """
+            update dealing_ranges
+            set state = 'inactive',
+                ts_end = now(),
+                updated_at = now()
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+              and state = 'valid'
+            """
+        )
+        insert_sql = text(
+            """
+            insert into dealing_ranges (
+                instrument_id,
+                timeframe,
+                high,
+                low,
+                equilibrium,
+                high_swing_id,
+                low_swing_id,
+                state,
+                ts_start,
+                meta
+            ) values (
+                :instrument_id,
+                :timeframe,
+                :high,
+                :low,
+                :equilibrium,
+                :high_swing_id,
+                :low_swing_id,
+                'valid',
+                :ts_start,
+                cast(:meta as jsonb)
+            )
+            """
+        )
+        with SessionLocal.begin() as session:
+            session.execute(deactivate_sql, {"instrument_id": instrument_id, "timeframe": timeframe})
+            session.execute(
+                insert_sql,
+                {
+                    "instrument_id": instrument_id,
+                    "timeframe": timeframe,
+                    "high": high,
+                    "low": low,
+                    "equilibrium": equilibrium,
+                    "high_swing_id": high_swing_id,
+                    "low_swing_id": low_swing_id,
+                    "ts_start": ts_start,
+                    "meta": json.dumps(meta),
+                },
+            )
diff --git a/src/repositories/displacement_repository.py b/src/repositories/displacement_repository.py
new file mode 100644
index 0000000..0bbcede
--- /dev/null
+++ b/src/repositories/displacement_repository.py
@@ -0,0 +1,83 @@
+from datetime import datetime
+import json
+
+from sqlalchemy import text
+
+from src.db.session import SessionLocal
+
+
+class DisplacementRepository:
+    def fetch_recent_candles(self, instrument_id: int, timeframe: str, limit: int = 200) -> list[dict]:
+        sql = text(
+            """
+            select ts_open, ts_close, open, high, low, close
+            from candles
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+            order by ts_open asc
+            limit :limit
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(
+                sql,
+                {"instrument_id": instrument_id, "timeframe": timeframe, "limit": limit},
+            ).mappings().all()
+        return [dict(row) for row in rows]
+
+    def insert_displacement(
+        self,
+        instrument_id: int,
+        timeframe: str,
+        direction: str,
+        start_ts: datetime,
+        end_ts: datetime,
+        strength_score: float,
+        body_ratio: float,
+        has_fvg: bool,
+        is_valid: bool,
+        meta: dict,
+    ) -> None:
+        sql = text(
+            """
+            insert into displacement_events (
+                instrument_id,
+                timeframe,
+                direction,
+                start_ts,
+                end_ts,
+                strength_score,
+                body_ratio,
+                has_fvg,
+                is_valid,
+                meta
+            ) values (
+                :instrument_id,
+                :timeframe,
+                :direction,
+                :start_ts,
+                :end_ts,
+                :strength_score,
+                :body_ratio,
+                :has_fvg,
+                :is_valid,
+                cast(:meta as jsonb)
+            )
+            """
+        )
+        with SessionLocal.begin() as session:
+            session.execute(
+                sql,
+                {
+                    "instrument_id": instrument_id,
+                    "timeframe": timeframe,
+                    "direction": direction,
+                    "start_ts": start_ts,
+                    "end_ts": end_ts,
+                    "strength_score": strength_score,
+                    "body_ratio": body_ratio,
+                    "has_fvg": has_fvg,
+                    "is_valid": is_valid,
+                    "meta": json.dumps(meta),
+                },
+            )
diff --git a/src/repositories/execution_repository.py b/src/repositories/execution_repository.py
new file mode 100644
index 0000000..bd6c2dd
--- /dev/null
+++ b/src/repositories/execution_repository.py
@@ -0,0 +1,135 @@
+from datetime import datetime, timezone
+import json
+from typing import Optional
+
+from sqlalchemy import text
+
+from src.db.session import SessionLocal
+
+
+class ExecutionRepository:
+    def fetch_signal_for_execution(self, signal_id: int) -> Optional[dict]:
+        sql = text(
+            """
+            select
+                ts.id,
+                ts.instrument_id,
+                ts.model_code,
+                ts.side,
+                ts.status,
+                ts.entry_type,
+                ts.entry_low,
+                ts.entry_high,
+                ts.stop_loss,
+                ts.tp1,
+                ts.tp2,
+                ts.rr_tp1,
+                ts.rr_tp2,
+                ts.session_code,
+                ts.created_ts,
+                ts.expires_ts,
+                ts.invalidations,
+                ts.evidence,
+                ts.meta,
+                bs.execution_intensity,
+                bs.daily_bias,
+                bs.draw_side
+            from trade_signals ts
+            left join bias_snapshots bs on bs.id = ts.bias_snapshot_id
+            where ts.id = :signal_id
+            limit 1
+            """
+        )
+        with SessionLocal() as session:
+            row = session.execute(sql, {"signal_id": signal_id}).mappings().first()
+        return dict(row) if row else None
+
+    def fetch_latest_execution(self, signal_id: int, execution_mode: str) -> Optional[dict]:
+        sql = text(
+            """
+            select id, signal_id, execution_mode, side, entry_price, stop_loss, take_profit_1, take_profit_2,
+                   size, risk_pct, status, meta
+            from trade_executions
+            where signal_id = :signal_id
+              and execution_mode = :execution_mode
+            order by opened_ts desc nulls last, id desc
+            limit 1
+            """
+        )
+        with SessionLocal() as session:
+            row = session.execute(
+                sql,
+                {"signal_id": signal_id, "execution_mode": execution_mode},
+            ).mappings().first()
+        return dict(row) if row else None
+
+    def insert_trade_execution(
+        self,
+        signal_id: int,
+        venue_order_id: Optional[str],
+        execution_mode: str,
+        side: str,
+        entry_price: float,
+        stop_loss: float,
+        take_profit_1: float,
+        take_profit_2: float,
+        size: float,
+        risk_pct: float,
+        status: str,
+        opened_ts,
+        meta: dict,
+    ) -> int:
+        sql = text(
+            """
+            insert into trade_executions (
+                signal_id,
+                venue_order_id,
+                execution_mode,
+                side,
+                entry_price,
+                stop_loss,
+                take_profit_1,
+                take_profit_2,
+                size,
+                risk_pct,
+                status,
+                opened_ts,
+                meta
+            ) values (
+                :signal_id,
+                :venue_order_id,
+                :execution_mode,
+                :side,
+                :entry_price,
+                :stop_loss,
+                :take_profit_1,
+                :take_profit_2,
+                :size,
+                :risk_pct,
+                :status,
+                :opened_ts,
+                cast(:meta as jsonb)
+            )
+            returning id
+            """
+        )
+        with SessionLocal.begin() as session:
+            result = session.execute(
+                sql,
+                {
+                    "signal_id": signal_id,
+                    "venue_order_id": venue_order_id,
+                    "execution_mode": execution_mode,
+                    "side": side,
+                    "entry_price": entry_price,
+                    "stop_loss": stop_loss,
+                    "take_profit_1": take_profit_1,
+                    "take_profit_2": take_profit_2,
+                    "size": size,
+                    "risk_pct": risk_pct,
+                    "status": status,
+                    "opened_ts": opened_ts,
+                    "meta": json.dumps(meta),
+                },
+            )
+            return int(result.scalar_one())
diff --git a/src/repositories/fvg_repository.py b/src/repositories/fvg_repository.py
new file mode 100644
index 0000000..a6a5150
--- /dev/null
+++ b/src/repositories/fvg_repository.py
@@ -0,0 +1,165 @@
+from typing import Any, Optional, Union
+from sqlalchemy import text
+import json
+
+from src.db.session import SessionLocal
+
+
+class FVGRepository:
+    def fetch_recent_candles(self, instrument_id: int, timeframe: str, limit: int = 200) -> list[dict]:
+        sql = text(
+            """
+            select ts_open, ts_close, open, high, low, close
+            from candles
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+            order by ts_open asc
+            limit :limit
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(
+                sql,
+                {"instrument_id": instrument_id, "timeframe": timeframe, "limit": limit},
+            ).mappings().all()
+        return [dict(row) for row in rows]
+
+    def fetch_recent_displacement(self, instrument_id: int, timeframe: str, limit: int = 50) -> list[dict]:
+        sql = text(
+            """
+            select id, direction, start_ts, end_ts, strength_score, is_valid
+            from displacement_events
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+              and is_valid = true
+            order by end_ts desc
+            limit :limit
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(
+                sql,
+                {"instrument_id": instrument_id, "timeframe": timeframe, "limit": limit},
+            ).mappings().all()
+        return [dict(row) for row in rows]
+
+    def fetch_open_fvgs(self, instrument_id: int, timeframe: str, limit: int = 500) -> list[dict]:
+        sql = text(
+            """
+            select id, direction, upper, lower, start_ts, end_ts, fill_pct, status, related_displacement_id, meta
+            from fvg_zones
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+              and status in ('open', 'touched')
+            order by end_ts asc
+            limit :limit
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(
+                sql,
+                {"instrument_id": instrument_id, "timeframe": timeframe, "limit": limit},
+            ).mappings().all()
+        return [dict(row) for row in rows]
+
+    def fetch_candles_after_ts(self, instrument_id: int, timeframe: str, start_ts, limit: int = 500) -> list[dict]:
+        sql = text(
+            """
+            select ts_open, ts_close, open, high, low, close
+            from candles
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+              and ts_open >= :start_ts
+            order by ts_open asc
+            limit :limit
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(
+                sql,
+                {"instrument_id": instrument_id, "timeframe": timeframe, "start_ts": start_ts, "limit": limit},
+            ).mappings().all()
+        return [dict(row) for row in rows]
+
+    def insert_fvg(
+        self,
+        instrument_id: int,
+        timeframe: str,
+        direction: str,
+        upper: float,
+        lower: float,
+        start_ts,
+        end_ts,
+        fill_pct: float,
+        status: str,
+        related_displacement_id: Optional[int],
+        meta: dict,
+    ) -> None:
+        sql = text(
+            """
+            insert into fvg_zones (
+                instrument_id,
+                timeframe,
+                direction,
+                upper,
+                lower,
+                start_ts,
+                end_ts,
+                fill_pct,
+                status,
+                related_displacement_id,
+                meta
+            ) values (
+                :instrument_id,
+                :timeframe,
+                :direction,
+                :upper,
+                :lower,
+                :start_ts,
+                :end_ts,
+                :fill_pct,
+                :status,
+                :related_displacement_id,
+                cast(:meta as jsonb)
+            )
+            """
+        )
+        with SessionLocal.begin() as session:
+            session.execute(
+                sql,
+                {
+                    "instrument_id": instrument_id,
+                    "timeframe": timeframe,
+                    "direction": direction,
+                    "upper": upper,
+                    "lower": lower,
+                    "start_ts": start_ts,
+                    "end_ts": end_ts,
+                    "fill_pct": fill_pct,
+                    "status": status,
+                    "related_displacement_id": related_displacement_id,
+                    "meta": json.dumps(meta, default=str),
+                },
+            )
+
+    def update_fvg(self, fvg_id: int, fill_pct: float, status: str, meta: dict) -> None:
+        sql = text(
+            """
+            update fvg_zones
+            set fill_pct = :fill_pct,
+                status = :status,
+                meta = coalesce(meta, '{}'::jsonb) || cast(:meta as jsonb),
+                updated_at = now()
+            where id = :fvg_id
+            """
+        )
+        with SessionLocal.begin() as session:
+            session.execute(
+                sql,
+                {
+                    'fvg_id': fvg_id,
+                    'fill_pct': fill_pct,
+                    'status': status,
+                    'meta': json.dumps(meta, default=str),
+                },
+            )
diff --git a/src/repositories/liquidity_pool_repository.py b/src/repositories/liquidity_pool_repository.py
new file mode 100644
index 0000000..cf03826
--- /dev/null
+++ b/src/repositories/liquidity_pool_repository.py
@@ -0,0 +1,99 @@
+from datetime import datetime
+from decimal import Decimal
+import json
+
+from sqlalchemy import text
+
+from src.db.session import SessionLocal
+
+
+class LiquidityPoolRepository:
+    def fetch_recent_swings(self, instrument_id: int, timeframe: str, limit: int = 100) -> list[dict]:
+        sql = text(
+            """
+            select id, kind, strength, price, ts, confirmed
+            from swings
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+              and confirmed = true
+            order by ts desc
+            limit :limit
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(
+                sql,
+                {"instrument_id": instrument_id, "timeframe": timeframe, "limit": limit},
+            ).mappings().all()
+        return [dict(row) for row in rows]
+
+    def fetch_recent_sessions(self, instrument_id: int, limit: int = 10) -> list[dict]:
+        sql = text(
+            """
+            select id, session_date, session_code, high, low, status
+            from market_sessions
+            where instrument_id = :instrument_id
+            order by session_date desc, start_ts desc
+            limit :limit
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(sql, {"instrument_id": instrument_id, "limit": limit}).mappings().all()
+        return [dict(row) for row in rows]
+
+    def insert_pool(
+        self,
+        instrument_id: int,
+        timeframe: str,
+        side: str,
+        pool_type: str,
+        price_low: Decimal,
+        price_high: Decimal,
+        reference_ids: list,
+        created_ts: datetime,
+        meta: dict,
+    ) -> None:
+        sql = text(
+            """
+            insert into liquidity_pools (
+                instrument_id,
+                timeframe,
+                side,
+                pool_type,
+                price_low,
+                price_high,
+                reference_ids,
+                status,
+                created_ts,
+                updated_ts,
+                meta
+            ) values (
+                :instrument_id,
+                :timeframe,
+                :side,
+                :pool_type,
+                :price_low,
+                :price_high,
+                cast(:reference_ids as jsonb),
+                'untouched',
+                :created_ts,
+                now(),
+                cast(:meta as jsonb)
+            )
+            """
+        )
+        with SessionLocal.begin() as session:
+            session.execute(
+                sql,
+                {
+                    "instrument_id": instrument_id,
+                    "timeframe": timeframe,
+                    "side": side,
+                    "pool_type": pool_type,
+                    "price_low": price_low,
+                    "price_high": price_high,
+                    "reference_ids": json.dumps(reference_ids),
+                    "created_ts": created_ts,
+                    "meta": json.dumps(meta),
+                },
+            )
diff --git a/src/repositories/market_session_repository.py b/src/repositories/market_session_repository.py
new file mode 100644
index 0000000..4801795
--- /dev/null
+++ b/src/repositories/market_session_repository.py
@@ -0,0 +1,103 @@
+from typing import Any, Optional, Union
+from datetime import date, datetime, timezone
+
+from sqlalchemy import text
+
+from src.db.session import SessionLocal
+
+
+class MarketSessionRepository:
+    def fetch_candles_for_window(self, instrument_id: int, timeframe: str, start_ts: datetime, end_ts: datetime) -> list[dict]:
+        sql = text(
+            """
+            select ts_open, ts_close, open, high, low, close, volume
+            from candles
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+              and ts_open >= :start_ts
+              and ts_open < :end_ts
+            order by ts_open asc
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(
+                sql,
+                {
+                    "instrument_id": instrument_id,
+                    "timeframe": timeframe,
+                    "start_ts": start_ts,
+                    "end_ts": end_ts,
+                },
+            ).mappings().all()
+        return [dict(row) for row in rows]
+
+    def upsert_session(
+        self,
+        instrument_id: int,
+        session_date: date,
+        timezone_name: str,
+        session_code: str,
+        start_ts: datetime,
+        end_ts: datetime,
+        high: Optional[float],
+        low: Optional[float],
+        midpoint: Optional[float],
+        status: str,
+        meta: dict,
+    ) -> None:
+        sql = text(
+            """
+            insert into market_sessions (
+                instrument_id,
+                session_date,
+                timezone,
+                session_code,
+                start_ts,
+                end_ts,
+                high,
+                low,
+                midpoint,
+                status,
+                meta
+            ) values (
+                :instrument_id,
+                :session_date,
+                :timezone,
+                :session_code,
+                :start_ts,
+                :end_ts,
+                :high,
+                :low,
+                :midpoint,
+                :status,
+                cast(:meta as jsonb)
+            )
+            on conflict (instrument_id, session_date, session_code, timezone)
+            do update set
+                start_ts = excluded.start_ts,
+                end_ts = excluded.end_ts,
+                high = excluded.high,
+                low = excluded.low,
+                midpoint = excluded.midpoint,
+                status = excluded.status,
+                meta = excluded.meta,
+                updated_at = now()
+            """
+        )
+        with SessionLocal.begin() as session:
+            session.execute(
+                sql,
+                {
+                    "instrument_id": instrument_id,
+                    "session_date": session_date,
+                    "timezone": timezone_name,
+                    "session_code": session_code,
+                    "start_ts": start_ts,
+                    "end_ts": end_ts,
+                    "high": high,
+                    "low": low,
+                    "midpoint": midpoint,
+                    "status": status,
+                    "meta": __import__("json").dumps(meta),
+                },
+            )
diff --git a/src/repositories/signal_repository.py b/src/repositories/signal_repository.py
new file mode 100644
index 0000000..8942dd2
--- /dev/null
+++ b/src/repositories/signal_repository.py
@@ -0,0 +1,189 @@
+from sqlalchemy import text
+import json
+from typing import Optional
+
+from src.db.session import SessionLocal
+
+
+class SignalRepository:
+    def fetch_latest_bias_snapshot(self, instrument_id: int, setup_tf: str, trigger_tf: str) -> Optional[dict]:
+        sql = text(
+            """
+            select id, daily_bias, confidence, execution_intensity, snapshot_ts, draw_side
+            from bias_snapshots
+            where instrument_id = :instrument_id
+              and setup_tf = :setup_tf
+              and trigger_tf = :trigger_tf
+            order by snapshot_ts desc
+            limit 1
+            """
+        )
+        with SessionLocal() as session:
+            row = session.execute(
+                sql,
+                {"instrument_id": instrument_id, "setup_tf": setup_tf, "trigger_tf": trigger_tf},
+            ).mappings().first()
+        return dict(row) if row else None
+
+    def fetch_latest_fvg(self, instrument_id: int, timeframe: str) -> Optional[dict]:
+        sql = text(
+            """
+            select id, direction, upper, lower, status, related_displacement_id, end_ts, fill_pct, meta
+            from fvg_zones
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+              and status in ('open', 'touched')
+            order by
+                case when related_displacement_id is not null then 0 else 1 end,
+                end_ts desc
+            limit 1
+            """
+        )
+        with SessionLocal() as session:
+            row = session.execute(sql, {"instrument_id": instrument_id, "timeframe": timeframe}).mappings().first()
+        return dict(row) if row else None
+
+    def fetch_latest_mss(self, instrument_id: int, timeframe: str) -> Optional[dict]:
+        sql = text(
+            """
+            select id, direction, broken_level, accepted, ts, displacement_event_id, meta
+            from structure_events
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+              and event_type = 'MSS'
+              and accepted = true
+            order by ts desc
+            limit 1
+            """
+        )
+        with SessionLocal() as session:
+            row = session.execute(sql, {"instrument_id": instrument_id, "timeframe": timeframe}).mappings().first()
+        return dict(row) if row else None
+
+    def fetch_latest_trade_signal(self, instrument_id: int, model_code: str) -> Optional[dict]:
+        sql = text(
+            """
+            select id, side, status, bias_snapshot_id, entry_type, entry_low, entry_high, stop_loss, tp1, tp2,
+                   rr_tp1, rr_tp2, session_code, invalidations, evidence, meta
+            from trade_signals
+            where instrument_id = :instrument_id
+              and model_code = :model_code
+            order by created_ts desc
+            limit 1
+            """
+        )
+        with SessionLocal() as session:
+            row = session.execute(
+                sql,
+                {"instrument_id": instrument_id, "model_code": model_code},
+            ).mappings().first()
+        return dict(row) if row else None
+
+    def fetch_session_at(self, instrument_id: int, ts) -> Optional[dict]:
+        sql = text(
+            """
+            select id, session_code, status, start_ts, end_ts
+            from market_sessions
+            where instrument_id = :instrument_id
+              and start_ts <= :ts
+              and end_ts > :ts
+            order by start_ts desc
+            limit 1
+            """
+        )
+        with SessionLocal() as session:
+            row = session.execute(sql, {"instrument_id": instrument_id, "ts": ts}).mappings().first()
+        return dict(row) if row else None
+
+    def insert_trade_signal(
+        self,
+        instrument_id: int,
+        model_code: str,
+        side: str,
+        status: str,
+        bias_snapshot_id: int,
+        entry_type: str,
+        entry_low: float,
+        entry_high: float,
+        stop_loss: float,
+        tp1: float,
+        tp2: float,
+        rr_tp1: float,
+        rr_tp2: float,
+        session_code,
+        created_ts,
+        expires_ts,
+        invalidations: list,
+        evidence: dict,
+        meta: dict,
+    ) -> None:
+        sql = text(
+            """
+            insert into trade_signals (
+                instrument_id,
+                model_code,
+                side,
+                status,
+                bias_snapshot_id,
+                entry_type,
+                entry_low,
+                entry_high,
+                stop_loss,
+                tp1,
+                tp2,
+                rr_tp1,
+                rr_tp2,
+                session_code,
+                created_ts,
+                expires_ts,
+                invalidations,
+                evidence,
+                meta
+            ) values (
+                :instrument_id,
+                :model_code,
+                :side,
+                :status,
+                :bias_snapshot_id,
+                :entry_type,
+                :entry_low,
+                :entry_high,
+                :stop_loss,
+                :tp1,
+                :tp2,
+                :rr_tp1,
+                :rr_tp2,
+                :session_code,
+                :created_ts,
+                :expires_ts,
+                cast(:invalidations as jsonb),
+                cast(:evidence as jsonb),
+                cast(:meta as jsonb)
+            )
+            """
+        )
+        with SessionLocal.begin() as session:
+            session.execute(
+                sql,
+                {
+                    "instrument_id": instrument_id,
+                    "model_code": model_code,
+                    "side": side,
+                    "status": status,
+                    "bias_snapshot_id": bias_snapshot_id,
+                    "entry_type": entry_type,
+                    "entry_low": entry_low,
+                    "entry_high": entry_high,
+                    "stop_loss": stop_loss,
+                    "tp1": tp1,
+                    "tp2": tp2,
+                    "rr_tp1": rr_tp1,
+                    "rr_tp2": rr_tp2,
+                    "session_code": session_code,
+                    "created_ts": created_ts,
+                    "expires_ts": expires_ts,
+                    "invalidations": json.dumps(invalidations),
+                    "evidence": json.dumps(evidence),
+                    "meta": json.dumps(meta),
+                },
+            )
diff --git a/src/repositories/structure_repository.py b/src/repositories/structure_repository.py
new file mode 100644
index 0000000..2961001
--- /dev/null
+++ b/src/repositories/structure_repository.py
@@ -0,0 +1,119 @@
+from sqlalchemy import text
+import json
+
+from src.db.session import SessionLocal
+
+
+class StructureRepository:
+    def fetch_recent_swings(self, instrument_id: int, timeframe: str, limit: int = 50) -> list[dict]:
+        sql = text(
+            """
+            select id, kind, strength, price, ts, confirmed
+            from swings
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+              and confirmed = true
+            order by ts desc
+            limit :limit
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(
+                sql,
+                {"instrument_id": instrument_id, "timeframe": timeframe, "limit": limit},
+            ).mappings().all()
+        return [dict(row) for row in rows]
+
+    def fetch_recent_displacement(self, instrument_id: int, timeframe: str, limit: int = 20) -> list[dict]:
+        sql = text(
+            """
+            select id, direction, start_ts, end_ts, strength_score, is_valid
+            from displacement_events
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+              and is_valid = true
+            order by end_ts desc
+            limit :limit
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(
+                sql,
+                {"instrument_id": instrument_id, "timeframe": timeframe, "limit": limit},
+            ).mappings().all()
+        return [dict(row) for row in rows]
+
+    def fetch_recent_candles(self, instrument_id: int, timeframe: str, limit: int = 200) -> list[dict]:
+        sql = text(
+            """
+            select ts_open, ts_close, open, high, low, close
+            from candles
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+            order by ts_open asc
+            limit :limit
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(
+                sql,
+                {"instrument_id": instrument_id, "timeframe": timeframe, "limit": limit},
+            ).mappings().all()
+        return [dict(row) for row in rows]
+
+    def insert_mss_event(
+        self,
+        instrument_id: int,
+        timeframe: str,
+        direction: str,
+        broken_level: float,
+        reference_swing_id: int,
+        displacement_event_id: int,
+        accepted: bool,
+        ts,
+        meta: dict,
+    ) -> None:
+        sql = text(
+            """
+            insert into structure_events (
+                instrument_id,
+                timeframe,
+                event_type,
+                direction,
+                broken_level,
+                reference_swing_id,
+                displacement_event_id,
+                accepted,
+                signal_relevant,
+                ts,
+                meta
+            ) values (
+                :instrument_id,
+                :timeframe,
+                'MSS',
+                :direction,
+                :broken_level,
+                :reference_swing_id,
+                :displacement_event_id,
+                :accepted,
+                true,
+                :ts,
+                cast(:meta as jsonb)
+            )
+            """
+        )
+        with SessionLocal.begin() as session:
+            session.execute(
+                sql,
+                {
+                    "instrument_id": instrument_id,
+                    "timeframe": timeframe,
+                    "direction": direction,
+                    "broken_level": broken_level,
+                    "reference_swing_id": reference_swing_id,
+                    "displacement_event_id": displacement_event_id,
+                    "accepted": accepted,
+                    "ts": ts,
+                    "meta": json.dumps(meta),
+                },
+            )
diff --git a/src/repositories/sweep_repository.py b/src/repositories/sweep_repository.py
new file mode 100644
index 0000000..42e5aeb
--- /dev/null
+++ b/src/repositories/sweep_repository.py
@@ -0,0 +1,140 @@
+from datetime import datetime
+import json
+
+from sqlalchemy import text
+
+from src.db.session import SessionLocal
+
+
+class SweepRepository:
+    def fetch_active_pools(self, instrument_id: int, timeframe: str, limit: int = 100) -> list[dict]:
+        sql = text(
+            """
+            select id, side, pool_type, price_low, price_high, reference_ids, status, created_ts, meta
+            from liquidity_pools
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+              and status = 'untouched'
+            order by created_ts desc
+            limit :limit
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(
+                sql,
+                {"instrument_id": instrument_id, "timeframe": timeframe, "limit": limit},
+            ).mappings().all()
+        return [dict(row) for row in rows]
+
+    def fetch_candles_after_ts(
+        self,
+        instrument_id: int,
+        timeframe: str,
+        start_ts: datetime,
+        limit: int = 200,
+    ) -> list[dict]:
+        sql = text(
+            """
+            select ts_open, ts_close, open, high, low, close, volume
+            from candles
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+              and ts_open >= :start_ts
+            order by ts_open asc
+            limit :limit
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(
+                sql,
+                {
+                    "instrument_id": instrument_id,
+                    "timeframe": timeframe,
+                    "start_ts": start_ts,
+                    "limit": limit,
+                },
+            ).mappings().all()
+        return [dict(row) for row in rows]
+
+    def upsert_sweep(
+        self,
+        instrument_id: int,
+        timeframe: str,
+        side_swept: str,
+        pool_id: int,
+        sweep_high: float,
+        sweep_low: float,
+        sweep_ts: datetime,
+        close_back_inside: bool,
+        validation_level: str,
+        status: str,
+        meta: dict,
+    ) -> None:
+        sql = text(
+            """
+            insert into sweep_events (
+                instrument_id,
+                timeframe,
+                side_swept,
+                pool_id,
+                sweep_high,
+                sweep_low,
+                sweep_ts,
+                close_back_inside,
+                validation_level,
+                status,
+                meta
+            ) values (
+                :instrument_id,
+                :timeframe,
+                :side_swept,
+                :pool_id,
+                :sweep_high,
+                :sweep_low,
+                :sweep_ts,
+                :close_back_inside,
+                :validation_level,
+                :status,
+                cast(:meta as jsonb)
+            )
+            on conflict (instrument_id, timeframe, pool_id, sweep_ts)
+            do update set
+                side_swept = excluded.side_swept,
+                sweep_high = excluded.sweep_high,
+                sweep_low = excluded.sweep_low,
+                close_back_inside = excluded.close_back_inside,
+                validation_level = excluded.validation_level,
+                status = excluded.status,
+                meta = excluded.meta
+            """
+        )
+        with SessionLocal.begin() as session:
+            session.execute(
+                sql,
+                {
+                    "instrument_id": instrument_id,
+                    "timeframe": timeframe,
+                    "side_swept": side_swept,
+                    "pool_id": pool_id,
+                    "sweep_high": sweep_high,
+                    "sweep_low": sweep_low,
+                    "sweep_ts": sweep_ts,
+                    "close_back_inside": close_back_inside,
+                    "validation_level": validation_level,
+                    "status": status,
+                    "meta": json.dumps(meta),
+                },
+            )
+
+    def mark_pool_swept(self, pool_id: int) -> None:
+        sql = text(
+            """
+            update liquidity_pools
+            set status = 'swept',
+                updated_ts = now()
+            where id = :pool_id
+              and status = 'untouched'
+            """
+        )
+        with SessionLocal.begin() as session:
+            session.execute(sql, {"pool_id": pool_id})
diff --git a/src/repositories/swing_repository.py b/src/repositories/swing_repository.py
new file mode 100644
index 0000000..951a447
--- /dev/null
+++ b/src/repositories/swing_repository.py
@@ -0,0 +1,84 @@
+from datetime import datetime
+from decimal import Decimal
+import json
+
+from sqlalchemy import text
+
+from src.db.session import SessionLocal
+
+
+class SwingRepository:
+    def fetch_candles(self, instrument_id: int, timeframe: str, limit: int = 500) -> list[dict]:
+        sql = text(
+            """
+            select ts_open, ts_close, open, high, low, close
+            from candles
+            where instrument_id = :instrument_id
+              and timeframe = :timeframe
+            order by ts_open asc
+            limit :limit
+            """
+        )
+        with SessionLocal() as session:
+            rows = session.execute(
+                sql,
+                {"instrument_id": instrument_id, "timeframe": timeframe, "limit": limit},
+            ).mappings().all()
+        return [dict(row) for row in rows]
+
+    def upsert_swing(
+        self,
+        instrument_id: int,
+        timeframe: str,
+        kind: str,
+        strength: str,
+        price: Decimal,
+        ts: datetime,
+        left_bars: int,
+        right_bars: int,
+        confirmed: bool,
+        meta: dict,
+    ) -> None:
+        sql = text(
+            """
+            insert into swings (
+                instrument_id,
+                timeframe,
+                kind,
+                strength,
+                price,
+                ts,
+                left_bars,
+                right_bars,
+                confirmed,
+                meta
+            ) values (
+                :instrument_id,
+                :timeframe,
+                :kind,
+                :strength,
+                :price,
+                :ts,
+                :left_bars,
+                :right_bars,
+                :confirmed,
+                cast(:meta as jsonb)
+            )
+            """
+        )
+        with SessionLocal.begin() as session:
+            session.execute(
+                sql,
+                {
+                    "instrument_id": instrument_id,
+                    "timeframe": timeframe,
+                    "kind": kind,
+                    "strength": strength,
+                    "price": price,
+                    "ts": ts,
+                    "left_bars": left_bars,
+                    "right_bars": right_bars,
+                    "confirmed": confirmed,
+                    "meta": json.dumps(meta),
+                },
+            )
diff --git a/src/services/__init__.py b/src/services/__init__.py
new file mode 100644
index 0000000..4e993ac
--- /dev/null
+++ b/src/services/__init__.py
@@ -0,0 +1 @@
+"""Service package for AI ICT runtime modules."""
diff --git a/src/services/backtest/__init__.py b/src/services/backtest/__init__.py
new file mode 100644
index 0000000..c8e13f6
--- /dev/null
+++ b/src/services/backtest/__init__.py
@@ -0,0 +1,11 @@
+"""Backtest service package."""
+
+from src.services.backtest.backtest_service import (
+    BacktestOutcome,
+    BacktestService,
+    BacktestSignal,
+    evaluate_signal_outcome,
+    summarize_backtest_outcomes,
+)
+
+__all__ = ["BacktestOutcome", "BacktestService", "BacktestSignal", "evaluate_signal_outcome", "summarize_backtest_outcomes"]
diff --git a/src/services/backtest/backtest_service.py b/src/services/backtest/backtest_service.py
new file mode 100644
index 0000000..65be61c
--- /dev/null
+++ b/src/services/backtest/backtest_service.py
@@ -0,0 +1,303 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional
+
+from src.repositories.backtest_repository import BacktestRepository
+
+
+SAME_CANDLE_PRIORITY = "stop_first"
+
+
+@dataclass(frozen=True)
+class BacktestOutcome:
+    signal_id: int
+    outcome: str
+    mfe: float
+    mae: float
+    tp1_hit: bool
+    tp2_hit: bool
+    invalidated_before_entry: bool
+    error_tags: list[str]
+    meta: dict
+
+
+@dataclass(frozen=True)
+class BacktestSignal:
+    signal_id: int
+    side: str
+    entry_low: float
+    entry_high: float
+    stop_loss: float
+    tp1: float
+    tp2: float
+
+
+class BacktestService:
+    def __init__(self, repository: Optional[BacktestRepository] = None) -> None:
+        self.repository = repository or BacktestRepository()
+
+    def run_backtest(self, instrument_id: int, limit: int = 100) -> tuple[int, list[BacktestOutcome]]:
+        signals = self.repository.fetch_candidate_signals(instrument_id=instrument_id, limit=limit)
+        run_id = self.repository.insert_backtest_run(
+            model_code='SWEEP_MSS_FVG',
+            instrument_id=instrument_id,
+            timeframe_set={'bias_tf': '1m', 'setup_tf': '1m', 'trigger_tf': '1m'},
+            config={'limit': limit, 'mode': 'entry_then_outcome', 'same_candle_priority': 'stop_first', 'session_filter': 'mark_outside'},
+        )
+        outcomes: list[BacktestOutcome] = []
+        for signal in signals:
+            sessions = self.repository.fetch_sessions_covering_window(
+                instrument_id=instrument_id,
+                start_ts=signal['created_ts'],
+                end_ts=signal['expires_ts'],
+            )
+            future = self.repository.fetch_future_candles(
+                instrument_id=instrument_id,
+                timeframe='1m',
+                start_ts=signal['created_ts'],
+                end_ts=signal['expires_ts'],
+                limit=500,
+            )
+            if not future:
+                record = BacktestOutcome(
+                    signal_id=signal['id'],
+                    outcome='missed',
+                    mfe=0.0,
+                    mae=0.0,
+                    tp1_hit=False,
+                    tp2_hit=False,
+                    invalidated_before_entry=True,
+                    error_tags=['no_future_candles'],
+                    meta={
+                        'entry_triggered': False,
+                        'same_candle_priority': SAME_CANDLE_PRIORITY,
+                        'same_candle_ambiguous': False,
+                        'sessions_found': len(sessions),
+                        'session_codes': [row['session_code'] for row in sessions],
+                        'signal_side': signal['side'],
+                        'signal_created_ts': signal['created_ts'],
+                        'weekday': _extract_weekday(signal['created_ts']),
+                    },
+                )
+                outcomes.append(record)
+                self.repository.insert_backtest_result(
+                    backtest_run_id=run_id,
+                    signal_id=record.signal_id,
+                    outcome=record.outcome,
+                    mfe=record.mfe,
+                    mae=record.mae,
+                    tp1_hit=record.tp1_hit,
+                    tp2_hit=record.tp2_hit,
+                    invalidated_before_entry=record.invalidated_before_entry,
+                    error_tags=record.error_tags,
+                    meta=record.meta,
+                )
+                continue
+
+            session_filtered = len(sessions) == 0
+            record = evaluate_signal_outcome(
+                BacktestSignal(
+                    signal_id=signal['id'],
+                    side=signal['side'],
+                    entry_low=float(signal['entry_low'] or 0),
+                    entry_high=float(signal['entry_high'] or 0),
+                    stop_loss=float(signal['stop_loss'] or 0),
+                    tp1=float(signal['tp1'] or 0),
+                    tp2=float(signal['tp2'] or 0),
+                ),
+                future,
+            )
+            if session_filtered:
+                record.error_tags.append('outside_session_window')
+            record.meta.update(
+                {
+                    'sessions_found': len(sessions),
+                    'session_codes': [row['session_code'] for row in sessions],
+                    'session_filter': 'outside_window' if session_filtered else 'covered',
+                    'signal_side': signal['side'],
+                    'signal_created_ts': signal['created_ts'],
+                    'weekday': _extract_weekday(signal['created_ts']),
+                }
+            )
+            outcomes.append(record)
+            self.repository.insert_backtest_result(
+                backtest_run_id=run_id,
+                signal_id=record.signal_id,
+                outcome=record.outcome,
+                mfe=record.mfe,
+                mae=record.mae,
+                tp1_hit=record.tp1_hit,
+                tp2_hit=record.tp2_hit,
+                invalidated_before_entry=record.invalidated_before_entry,
+                error_tags=record.error_tags,
+                meta=record.meta,
+            )
+        summary = summarize_backtest_outcomes(outcomes)
+        self.repository.update_backtest_run_summary(run_id, summary)
+        return run_id, outcomes
+
+
+def evaluate_signal_outcome(signal: BacktestSignal, future_candles: list[dict]) -> BacktestOutcome:
+    entry_mid = (signal.entry_low + signal.entry_high) / 2
+    entry_triggered = False
+    tp1_hit = False
+    tp2_hit = False
+    stopped_out = False
+    same_candle_ambiguous = False
+    mfe = 0.0
+    mae = 0.0
+
+    for candle in future_candles:
+        high = float(candle['high'])
+        low = float(candle['low'])
+        entry_now = low <= signal.entry_high and high >= signal.entry_low
+        entry_triggered_this_candle = False
+
+        if not entry_triggered:
+            if entry_now:
+                entry_triggered = True
+                entry_triggered_this_candle = True
+            else:
+                continue
+
+        if signal.side == 'buy':
+            mfe = max(mfe, high - entry_mid)
+            mae = max(mae, entry_mid - low)
+            stop_hit = bool(signal.stop_loss and low <= signal.stop_loss)
+            tp1_now = bool(signal.tp1 and high >= signal.tp1)
+            tp2_now = bool(signal.tp2 and high >= signal.tp2)
+        else:
+            mfe = max(mfe, entry_mid - low)
+            mae = max(mae, high - entry_mid)
+            stop_hit = bool(signal.stop_loss and high >= signal.stop_loss)
+            tp1_now = bool(signal.tp1 and low <= signal.tp1)
+            tp2_now = bool(signal.tp2 and low <= signal.tp2)
+
+        if entry_triggered_this_candle and (stop_hit or tp1_now or tp2_now):
+            same_candle_ambiguous = True
+        if stop_hit and (tp1_now or tp2_now):
+            same_candle_ambiguous = True
+
+        if stop_hit:
+            stopped_out = True
+            break
+        if tp1_now:
+            tp1_hit = True
+        if tp2_now:
+            tp2_hit = True
+            break
+
+    error_tags: list[str] = []
+    if same_candle_ambiguous:
+        error_tags.append('same_candle_entry_exit_ambiguous')
+
+    if not entry_triggered:
+        outcome = 'missed'
+        error_tags.append('entry_not_triggered')
+    elif tp2_hit:
+        outcome = 'win'
+    elif tp1_hit and not stopped_out:
+        outcome = 'breakeven'
+    elif stopped_out:
+        outcome = 'loss'
+        error_tags.append('stopped_out')
+    else:
+        outcome = 'missed'
+        error_tags.append('no_target_hit')
+
+    return BacktestOutcome(
+        signal_id=signal.signal_id,
+        outcome=outcome,
+        mfe=mfe,
+        mae=mae,
+        tp1_hit=tp1_hit,
+        tp2_hit=tp2_hit,
+        invalidated_before_entry=False,
+        error_tags=error_tags,
+        meta={
+            'entry_triggered': entry_triggered,
+            'same_candle_priority': SAME_CANDLE_PRIORITY,
+            'same_candle_ambiguous': same_candle_ambiguous,
+            'signal_side': signal.side,
+        },
+    )
+
+
+def summarize_backtest_outcomes(outcomes: list[BacktestOutcome]) -> dict:
+    total = len(outcomes)
+    grouped_by_outcome: dict[str, int] = {}
+    grouped_by_side: dict[str, dict] = {}
+    grouped_by_session: dict[str, dict] = {}
+    grouped_by_weekday: dict[str, dict] = {}
+
+    for outcome in outcomes:
+        grouped_by_outcome[outcome.outcome] = grouped_by_outcome.get(outcome.outcome, 0) + 1
+
+        side = str(outcome.meta.get('signal_side') or 'unknown')
+        session_codes = outcome.meta.get('session_codes') or ['OFF_HOURS']
+        weekday = str(outcome.meta.get('weekday') or 'unknown')
+
+        _accumulate_bucket(grouped_by_side, side, outcome)
+        _accumulate_bucket(grouped_by_weekday, weekday, outcome)
+        for session_code in session_codes:
+            _accumulate_bucket(grouped_by_session, str(session_code), outcome)
+
+    return {
+        'total_signals': total,
+        'outcomes': grouped_by_outcome,
+        'win_rate': _ratio(grouped_by_outcome.get('win', 0), total),
+        'loss_rate': _ratio(grouped_by_outcome.get('loss', 0), total),
+        'breakeven_rate': _ratio(grouped_by_outcome.get('breakeven', 0), total),
+        'miss_rate': _ratio(grouped_by_outcome.get('missed', 0), total),
+        'avg_mfe': _average([outcome.mfe for outcome in outcomes]),
+        'avg_mae': _average([outcome.mae for outcome in outcomes]),
+        'by_side': grouped_by_side,
+        'by_session': grouped_by_session,
+        'by_weekday': grouped_by_weekday,
+    }
+
+
+def _accumulate_bucket(container: dict, key: str, outcome: BacktestOutcome) -> None:
+    bucket = container.setdefault(
+        key,
+        {
+            'count': 0,
+            'wins': 0,
+            'losses': 0,
+            'breakevens': 0,
+            'misses': 0,
+            'avg_mfe_sum': 0.0,
+            'avg_mae_sum': 0.0,
+        },
+    )
+    bucket['count'] += 1
+    if outcome.outcome == 'win':
+        bucket['wins'] += 1
+    elif outcome.outcome == 'loss':
+        bucket['losses'] += 1
+    elif outcome.outcome == 'breakeven':
+        bucket['breakevens'] += 1
+    else:
+        bucket['misses'] += 1
+    bucket['avg_mfe_sum'] += outcome.mfe
+    bucket['avg_mae_sum'] += outcome.mae
+    bucket['win_rate'] = _ratio(bucket['wins'], bucket['count'])
+    bucket['avg_mfe'] = bucket['avg_mfe_sum'] / bucket['count'] if bucket['count'] else 0.0
+    bucket['avg_mae'] = bucket['avg_mae_sum'] / bucket['count'] if bucket['count'] else 0.0
+
+
+def _ratio(numerator: int, denominator: int) -> float:
+    return numerator / denominator if denominator else 0.0
+
+
+def _average(values: list[float]) -> float:
+    return sum(values) / len(values) if values else 0.0
+
+
+def _extract_weekday(ts) -> str:
+    if isinstance(ts, datetime):
+        return ts.strftime('%A')
+    if isinstance(ts, str):
+        normalized = ts.replace('Z', '+00:00')
+        return datetime.fromisoformat(normalized).strftime('%A')
+    return 'unknown'
diff --git a/src/services/bias/__init__.py b/src/services/bias/__init__.py
new file mode 100644
index 0000000..c5b770a
--- /dev/null
+++ b/src/services/bias/__init__.py
@@ -0,0 +1,5 @@
+"""Bias service package."""
+
+from src.services.bias.bias_service import BiasCandidate, BiasService
+
+__all__ = ["BiasCandidate", "BiasService"]
diff --git a/src/services/bias/bias_service.py b/src/services/bias/bias_service.py
new file mode 100644
index 0000000..a62bac1
--- /dev/null
+++ b/src/services/bias/bias_service.py
@@ -0,0 +1,88 @@
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Optional
+
+from src.repositories.bias_repository import BiasRepository
+
+
+@dataclass(frozen=True)
+class BiasCandidate:
+    daily_bias: str
+    confidence: float
+    execution_intensity: str
+    narrative_code: Optional[str]
+    draw_side: Optional[str]
+    range_id: Optional[int]
+    reason_codes: list[str]
+    snapshot_ts: object
+
+
+class BiasService:
+    def __init__(self, repository: Optional[BiasRepository] = None) -> None:
+        self.repository = repository or BiasRepository()
+
+    def build_bias(self, instrument_id: int, bias_tf: str, setup_tf: str, trigger_tf: str) -> Optional[BiasCandidate]:
+        range_row = self.repository.fetch_latest_range(instrument_id=instrument_id, timeframe=bias_tf)
+        mss_row = self.repository.fetch_latest_mss(instrument_id=instrument_id, timeframe=setup_tf)
+        if not range_row or not mss_row:
+            return None
+
+        if mss_row['direction'] == 'bullish':
+            daily_bias = 'bullish'
+            draw_side = 'buy_side'
+        else:
+            daily_bias = 'bearish'
+            draw_side = 'sell_side'
+
+        confidence = 0.7 if mss_row.get('accepted') else 0.5
+        execution_intensity = 'medium' if confidence < 0.8 else 'high'
+        reason_codes = ['latest_mss', 'active_range_available']
+        return BiasCandidate(
+            daily_bias=daily_bias,
+            confidence=confidence,
+            execution_intensity=execution_intensity,
+            narrative_code=f'{daily_bias}_structure_shift',
+            draw_side=draw_side,
+            range_id=range_row['id'],
+            reason_codes=reason_codes,
+            snapshot_ts=datetime.now(timezone.utc),
+        )
+
+    def persist_bias(self, instrument_id: int, bias_tf: str, setup_tf: str, trigger_tf: str, candidate: Optional[BiasCandidate]) -> Optional[int]:
+        if candidate is None:
+            return None
+        latest = self.repository.fetch_latest_bias_snapshot(
+            instrument_id=instrument_id,
+            bias_tf=bias_tf,
+            setup_tf=setup_tf,
+            trigger_tf=trigger_tf,
+        )
+        if latest and bias_snapshot_matches_candidate(latest, candidate):
+            return latest['id']
+        return self.repository.insert_bias_snapshot(
+            instrument_id=instrument_id,
+            bias_tf=bias_tf,
+            setup_tf=setup_tf,
+            trigger_tf=trigger_tf,
+            snapshot_ts=candidate.snapshot_ts,
+            daily_bias=candidate.daily_bias,
+            confidence=candidate.confidence,
+            execution_intensity=candidate.execution_intensity,
+            narrative_code=candidate.narrative_code,
+            draw_side=candidate.draw_side,
+            range_id=candidate.range_id,
+            reason_codes=candidate.reason_codes,
+            meta={},
+        )
+
+
+def bias_snapshot_matches_candidate(snapshot: dict, candidate: BiasCandidate) -> bool:
+    return (
+        snapshot.get('daily_bias') == candidate.daily_bias
+        and float(snapshot.get('confidence') or 0.0) == float(candidate.confidence)
+        and snapshot.get('execution_intensity') == candidate.execution_intensity
+        and snapshot.get('narrative_code') == candidate.narrative_code
+        and snapshot.get('draw_side') == candidate.draw_side
+        and snapshot.get('range_id') == candidate.range_id
+        and list(snapshot.get('reason_codes') or []) == list(candidate.reason_codes)
+    )
diff --git a/src/services/displacement/__init__.py b/src/services/displacement/__init__.py
new file mode 100644
index 0000000..f972419
--- /dev/null
+++ b/src/services/displacement/__init__.py
@@ -0,0 +1,5 @@
+"""Displacement service package."""
+
+from src.services.displacement.displacement_service import DisplacementCandidate, DisplacementService
+
+__all__ = ["DisplacementCandidate", "DisplacementService"]
diff --git a/src/services/displacement/displacement_service.py b/src/services/displacement/displacement_service.py
new file mode 100644
index 0000000..6fc9c25
--- /dev/null
+++ b/src/services/displacement/displacement_service.py
@@ -0,0 +1,72 @@
+from typing import Any, Optional, Union
+from dataclasses import dataclass
+
+from src.repositories.displacement_repository import DisplacementRepository
+
+
+@dataclass(frozen=True)
+class DisplacementCandidate:
+    direction: str
+    start_ts: object
+    end_ts: object
+    strength_score: float
+    body_ratio: float
+    has_fvg: bool
+    is_valid: bool
+
+
+class DisplacementService:
+    def __init__(self, repository: Optional[DisplacementRepository] = None) -> None:
+        self.repository = repository or DisplacementRepository()
+
+    def detect_displacement(self, instrument_id: int, timeframe: str, limit: int = 200) -> list[DisplacementCandidate]:
+        candles = self.repository.fetch_recent_candles(instrument_id=instrument_id, timeframe=timeframe, limit=limit)
+        candidates: list[DisplacementCandidate] = []
+        if len(candles) < 5:
+            return candidates
+
+        body_sizes = [abs(float(row['close']) - float(row['open'])) for row in candles]
+        avg_body = sum(body_sizes) / len(body_sizes) if body_sizes else 0.0
+        if avg_body == 0:
+            return candidates
+
+        for idx, candle in enumerate(candles):
+            body = abs(float(candle['close']) - float(candle['open']))
+            body_ratio = body / avg_body if avg_body else 0.0
+            if body_ratio < 1.5:
+                continue
+            direction = 'bullish' if float(candle['close']) > float(candle['open']) else 'bearish'
+            has_fvg = False
+            if 0 < idx < len(candles) - 1:
+                prev_candle = candles[idx - 1]
+                next_candle = candles[idx + 1]
+                has_fvg = float(prev_candle['high']) < float(next_candle['low']) or float(prev_candle['low']) > float(next_candle['high'])
+            strength_score = min(1.0, body_ratio / 3.0 + (0.2 if has_fvg else 0.0))
+            candidates.append(
+                DisplacementCandidate(
+                    direction=direction,
+                    start_ts=candle['ts_open'],
+                    end_ts=candle['ts_close'],
+                    strength_score=strength_score,
+                    body_ratio=body_ratio,
+                    has_fvg=has_fvg,
+                    is_valid=strength_score >= 0.5,
+                )
+            )
+        return candidates
+
+    def persist_displacement(self, instrument_id: int, timeframe: str, candidates: list[DisplacementCandidate]) -> int:
+        for candidate in candidates:
+            self.repository.insert_displacement(
+                instrument_id=instrument_id,
+                timeframe=timeframe,
+                direction=candidate.direction,
+                start_ts=candidate.start_ts,
+                end_ts=candidate.end_ts,
+                strength_score=candidate.strength_score,
+                body_ratio=candidate.body_ratio,
+                has_fvg=candidate.has_fvg,
+                is_valid=candidate.is_valid,
+                meta={},
+            )
+        return len(candidates)
diff --git a/src/services/execution/__init__.py b/src/services/execution/__init__.py
new file mode 100644
index 0000000..4cf4090
--- /dev/null
+++ b/src/services/execution/__init__.py
@@ -0,0 +1,17 @@
+"""Execution service package."""
+
+from src.services.execution.execution_service import (
+    ExecutionDecision,
+    ExecutionService,
+    compute_entry_price,
+    evaluate_execution_decision,
+    trade_execution_matches_decision,
+)
+
+__all__ = [
+    "ExecutionDecision",
+    "ExecutionService",
+    "compute_entry_price",
+    "evaluate_execution_decision",
+    "trade_execution_matches_decision",
+]
diff --git a/src/services/execution/execution_service.py b/src/services/execution/execution_service.py
new file mode 100644
index 0000000..be2d652
--- /dev/null
+++ b/src/services/execution/execution_service.py
@@ -0,0 +1,172 @@
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Optional
+
+from src.repositories.execution_repository import ExecutionRepository
+
+
+ALLOWED_EXECUTION_SIGNAL_STATUSES = {"awaiting_confirmation"}
+ALLOWED_EXECUTION_MODES = {"paper", "semi_auto"}
+
+
+@dataclass(frozen=True)
+class ExecutionDecision:
+    allowed: bool
+    status: str
+    reasons: list[str]
+    execution_mode: str
+    risk_pct: float
+    size: float
+    entry_price: float
+    meta: dict
+
+
+class ExecutionService:
+    def __init__(self, repository: Optional[ExecutionRepository] = None) -> None:
+        self.repository = repository or ExecutionRepository()
+
+    def prepare_execution(
+        self,
+        signal_id: int,
+        execution_mode: str = "paper",
+        account_equity: float = 10000.0,
+        risk_pct: float = 0.01,
+    ) -> Optional[ExecutionDecision]:
+        signal = self.repository.fetch_signal_for_execution(signal_id)
+        if not signal:
+            return None
+        return evaluate_execution_decision(
+            signal=signal,
+            execution_mode=execution_mode,
+            account_equity=account_equity,
+            risk_pct=risk_pct,
+        )
+
+    def create_execution(
+        self,
+        signal_id: int,
+        execution_mode: str = "paper",
+        account_equity: float = 10000.0,
+        risk_pct: float = 0.01,
+    ) -> Optional[int]:
+        decision = self.prepare_execution(
+            signal_id=signal_id,
+            execution_mode=execution_mode,
+            account_equity=account_equity,
+            risk_pct=risk_pct,
+        )
+        if decision is None or not decision.allowed:
+            return None
+        latest = self.repository.fetch_latest_execution(signal_id=signal_id, execution_mode=execution_mode)
+        if latest and trade_execution_matches_decision(latest, decision):
+            return latest['id']
+        venue_order_id = None if execution_mode == "paper" else f"semi_auto:{signal_id}:{int(datetime.now(timezone.utc).timestamp())}"
+        return self.repository.insert_trade_execution(
+            signal_id=signal_id,
+            venue_order_id=venue_order_id,
+            execution_mode=decision.execution_mode,
+            side=decision.meta["signal_side"],
+            entry_price=decision.entry_price,
+            stop_loss=decision.meta["stop_loss"],
+            take_profit_1=decision.meta["tp1"],
+            take_profit_2=decision.meta["tp2"],
+            size=decision.size,
+            risk_pct=decision.risk_pct,
+            status=decision.status,
+            opened_ts=datetime.now(timezone.utc),
+            meta=decision.meta,
+        )
+
+
+def trade_execution_matches_decision(execution: dict, decision: ExecutionDecision) -> bool:
+    return (
+        execution.get('execution_mode') == decision.execution_mode
+        and execution.get('status') == decision.status
+        and execution.get('side') == decision.meta['signal_side']
+        and float(execution.get('entry_price') or 0.0) == float(decision.entry_price)
+        and float(execution.get('stop_loss') or 0.0) == float(decision.meta['stop_loss'])
+        and float(execution.get('take_profit_1') or 0.0) == float(decision.meta['tp1'])
+        and float(execution.get('take_profit_2') or 0.0) == float(decision.meta['tp2'])
+        and float(execution.get('size') or 0.0) == float(decision.size)
+        and float(execution.get('risk_pct') or 0.0) == float(decision.risk_pct)
+        and dict(execution.get('meta') or {}) == dict(decision.meta)
+        and execution.get('status') in {'open', 'pending'}
+    )
+
+
+def evaluate_execution_decision(
+    signal: dict,
+    execution_mode: str,
+    account_equity: float,
+    risk_pct: float,
+) -> ExecutionDecision:
+    reasons: list[str] = []
+    meta = {
+        "signal_side": signal["side"],
+        "session_code": signal.get("session_code"),
+        "execution_intensity": signal.get("execution_intensity"),
+        "daily_bias": signal.get("daily_bias"),
+        "draw_side": signal.get("draw_side"),
+        "stop_loss": float(signal.get("stop_loss") or 0.0),
+        "tp1": float(signal.get("tp1") or 0.0),
+        "tp2": float(signal.get("tp2") or 0.0),
+        "signal_status": signal.get("status"),
+        "risk_checks": [],
+    }
+
+    if execution_mode not in ALLOWED_EXECUTION_MODES:
+        reasons.append("unsupported_execution_mode")
+    if signal.get("status") not in ALLOWED_EXECUTION_SIGNAL_STATUSES:
+        reasons.append("signal_not_executable")
+    if not signal.get("stop_loss"):
+        reasons.append("missing_stop_loss")
+    if signal.get("session_code") not in {"LONDON", "NY_AM", "NY_PM"}:
+        reasons.append("session_not_allowed")
+    if not signal.get("meta", {}).get("execution_permission", False):
+        reasons.append("signal_execution_permission_denied")
+    if signal.get("execution_intensity") == "low":
+        reasons.append("bias_execution_intensity_low")
+    if risk_pct <= 0 or risk_pct > 0.02:
+        reasons.append("risk_pct_out_of_bounds")
+
+    entry_price = compute_entry_price(signal)
+    stop_loss = float(signal.get("stop_loss") or 0.0)
+    risk_distance = abs(entry_price - stop_loss)
+    if risk_distance <= 0:
+        reasons.append("invalid_risk_distance")
+        size = 0.0
+    else:
+        risk_amount = account_equity * risk_pct
+        size = risk_amount / risk_distance
+
+    meta["risk_checks"] = reasons.copy()
+    meta["entry_type"] = signal.get("entry_type")
+    meta["entry_low"] = float(signal.get("entry_low") or 0.0)
+    meta["entry_high"] = float(signal.get("entry_high") or 0.0)
+    meta["risk_distance"] = risk_distance
+    meta["account_equity"] = account_equity
+
+    allowed = len(reasons) == 0
+    if execution_mode == "paper":
+        status = "open" if allowed else "rejected"
+    else:
+        status = "pending" if allowed else "rejected"
+
+    return ExecutionDecision(
+        allowed=allowed,
+        status=status,
+        reasons=reasons,
+        execution_mode=execution_mode,
+        risk_pct=risk_pct,
+        size=size,
+        entry_price=entry_price,
+        meta=meta,
+    )
+
+
+def compute_entry_price(signal: dict) -> float:
+    entry_low = float(signal.get("entry_low") or 0.0)
+    entry_high = float(signal.get("entry_high") or 0.0)
+    if entry_low and entry_high:
+        return (entry_low + entry_high) / 2
+    return entry_low or entry_high
diff --git a/src/services/fvg/__init__.py b/src/services/fvg/__init__.py
new file mode 100644
index 0000000..550ad35
--- /dev/null
+++ b/src/services/fvg/__init__.py
@@ -0,0 +1,5 @@
+"""FVG service package."""
+
+from src.services.fvg.fvg_service import FVGCandidate, FVGService, compute_fvg_fill_state
+
+__all__ = ["FVGCandidate", "FVGService", "compute_fvg_fill_state"]
diff --git a/src/services/fvg/fvg_service.py b/src/services/fvg/fvg_service.py
new file mode 100644
index 0000000..55e3a06
--- /dev/null
+++ b/src/services/fvg/fvg_service.py
@@ -0,0 +1,182 @@
+from dataclasses import dataclass
+from typing import Optional
+
+from src.config.constants import DEFAULT_FVG_MITIGATION_THRESHOLD_PCT
+from src.repositories.fvg_repository import FVGRepository
+
+
+@dataclass(frozen=True)
+class FVGCandidate:
+    direction: str
+    upper: float
+    lower: float
+    start_ts: object
+    end_ts: object
+    fill_pct: float
+    status: str
+    related_displacement_id: Optional[int]
+    meta: dict
+
+
+class FVGService:
+    def __init__(self, repository: Optional[FVGRepository] = None) -> None:
+        self.repository = repository or FVGRepository()
+
+    def detect_fvg(self, instrument_id: int, timeframe: str, limit: int = 200) -> list[FVGCandidate]:
+        candles = self.repository.fetch_recent_candles(instrument_id=instrument_id, timeframe=timeframe, limit=limit)
+        displacements = self.repository.fetch_recent_displacement(instrument_id=instrument_id, timeframe=timeframe, limit=50)
+        displacement_by_end = {row['end_ts']: row['id'] for row in displacements}
+        candidates: list[FVGCandidate] = []
+        if len(candles) < 3:
+            return candidates
+
+        for idx in range(1, len(candles) - 1):
+            first = candles[idx - 1]
+            middle = candles[idx]
+            third = candles[idx + 1]
+            related_displacement_id = displacement_by_end.get(middle['ts_close'])
+
+            if float(first['high']) < float(third['low']):
+                lower = float(first['high'])
+                upper = float(third['low'])
+                candidates.append(
+                    FVGCandidate(
+                        direction='bullish',
+                        upper=upper,
+                        lower=lower,
+                        start_ts=first['ts_open'],
+                        end_ts=third['ts_close'],
+                        fill_pct=0.0,
+                        status='open',
+                        related_displacement_id=related_displacement_id,
+                        meta={
+                            'width': upper - lower,
+                            'has_displacement_context': related_displacement_id is not None,
+                        },
+                    )
+                )
+            elif float(first['low']) > float(third['high']):
+                lower = float(third['high'])
+                upper = float(first['low'])
+                candidates.append(
+                    FVGCandidate(
+                        direction='bearish',
+                        upper=upper,
+                        lower=lower,
+                        start_ts=first['ts_open'],
+                        end_ts=third['ts_close'],
+                        fill_pct=0.0,
+                        status='open',
+                        related_displacement_id=related_displacement_id,
+                        meta={
+                            'width': upper - lower,
+                            'has_displacement_context': related_displacement_id is not None,
+                        },
+                    )
+                )
+        return candidates
+
+    def persist_fvg(self, instrument_id: int, timeframe: str, candidates: list[FVGCandidate]) -> int:
+        for candidate in candidates:
+            self.repository.insert_fvg(
+                instrument_id=instrument_id,
+                timeframe=timeframe,
+                direction=candidate.direction,
+                upper=candidate.upper,
+                lower=candidate.lower,
+                start_ts=candidate.start_ts,
+                end_ts=candidate.end_ts,
+                fill_pct=candidate.fill_pct,
+                status=candidate.status,
+                related_displacement_id=candidate.related_displacement_id,
+                meta=candidate.meta,
+            )
+        return len(candidates)
+
+    def update_existing_fvgs(self, instrument_id: int, timeframe: str, limit: int = 500) -> int:
+        fvgs = self.repository.fetch_open_fvgs(instrument_id=instrument_id, timeframe=timeframe, limit=limit)
+        updated = 0
+        for fvg in fvgs:
+            candles = self.repository.fetch_candles_after_ts(
+                instrument_id=instrument_id,
+                timeframe=timeframe,
+                start_ts=fvg['end_ts'],
+                limit=500,
+            )
+            if not candles:
+                continue
+            fill_pct, status, meta = compute_fvg_fill_state(
+                direction=fvg['direction'],
+                upper=float(fvg['upper']),
+                lower=float(fvg['lower']),
+                candles=candles,
+                mitigation_threshold=DEFAULT_FVG_MITIGATION_THRESHOLD_PCT,
+            )
+            self.repository.update_fvg(
+                fvg_id=fvg['id'],
+                fill_pct=fill_pct,
+                status=status,
+                meta=meta,
+            )
+            updated += 1
+        return updated
+
+
+def compute_fvg_fill_state(
+    direction: str,
+    upper: float,
+    lower: float,
+    candles: list[dict],
+    mitigation_threshold: float = DEFAULT_FVG_MITIGATION_THRESHOLD_PCT,
+) -> tuple[float, str, dict]:
+    width = max(upper - lower, 1e-9)
+    fill_max = 0.0
+    first_touch_ts = None
+    invalidated = False
+
+    for candle in candles:
+        high = float(candle['high'])
+        low = float(candle['low'])
+        close = float(candle['close'])
+        overlap_low = max(lower, low)
+        overlap_high = min(upper, high)
+        overlap = max(0.0, overlap_high - overlap_low)
+        fill_pct = min(1.0, overlap / width)
+        current_touch_ts = candle.get('ts_open') or candle.get('ts_close')
+        if fill_pct > 0 and first_touch_ts is None:
+            first_touch_ts = _normalize_meta_ts(current_touch_ts)
+        fill_max = max(fill_max, fill_pct)
+
+        if direction == 'bullish' and close < lower:
+            invalidated = True
+        if direction == 'bearish' and close > upper:
+            invalidated = True
+
+        if invalidated:
+            return fill_max, 'invalidated', {
+                'first_touch_ts': first_touch_ts,
+                'mitigation_threshold': mitigation_threshold,
+                'invalidated': True,
+                'width': width,
+            }
+        if fill_max >= mitigation_threshold:
+            return fill_max, 'mitigated', {
+                'first_touch_ts': first_touch_ts,
+                'mitigation_threshold': mitigation_threshold,
+                'invalidated': False,
+                'width': width,
+            }
+
+    status = 'touched' if fill_max > 0 else 'open'
+    return fill_max, status, {
+        'first_touch_ts': first_touch_ts,
+        'mitigation_threshold': mitigation_threshold,
+        'invalidated': False,
+        'width': width,
+    }
+
+
+def _normalize_meta_ts(value):
+    if hasattr(value, 'isoformat'):
+        return value.isoformat()
+    return value
diff --git a/src/services/liquidity/__init__.py b/src/services/liquidity/__init__.py
new file mode 100644
index 0000000..0907114
--- /dev/null
+++ b/src/services/liquidity/__init__.py
@@ -0,0 +1,10 @@
+"""Liquidity pool service package."""
+
+from src.services.liquidity.liquidity_pool_service import (
+    LiquidityPoolCandidate,
+    LiquidityPoolService,
+    build_equal_pool_candidates,
+    dedupe_candidates,
+)
+
+__all__ = ["LiquidityPoolCandidate", "LiquidityPoolService", "build_equal_pool_candidates", "dedupe_candidates"]
diff --git a/src/services/liquidity/liquidity_pool_service.py b/src/services/liquidity/liquidity_pool_service.py
new file mode 100644
index 0000000..fc9f28e
--- /dev/null
+++ b/src/services/liquidity/liquidity_pool_service.py
@@ -0,0 +1,271 @@
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import Optional
+
+from src.config.constants import DEFAULT_EQUAL_POOL_THRESHOLD_PCT
+from src.repositories.liquidity_pool_repository import LiquidityPoolRepository
+
+
+@dataclass(frozen=True)
+class LiquidityPoolCandidate:
+    side: str
+    pool_type: str
+    price_low: Decimal
+    price_high: Decimal
+    reference_ids: list
+    created_ts: object
+    meta: dict
+
+
+class LiquidityPoolService:
+    def __init__(self, repository: Optional[LiquidityPoolRepository] = None) -> None:
+        self.repository = repository or LiquidityPoolRepository()
+
+    def build_candidates(self, instrument_id: int, timeframe: str) -> list[LiquidityPoolCandidate]:
+        candidates: list[LiquidityPoolCandidate] = []
+
+        swings = self.repository.fetch_recent_swings(instrument_id=instrument_id, timeframe=timeframe, limit=20)
+        sessions = self.repository.fetch_recent_sessions(instrument_id=instrument_id, limit=10)
+
+        for swing in swings:
+            if swing["kind"] == "swing_high":
+                candidates.append(
+                    LiquidityPoolCandidate(
+                        side="buy_side",
+                        pool_type="prior_high",
+                        price_low=swing["price"],
+                        price_high=swing["price"],
+                        reference_ids=[swing["id"]],
+                        created_ts=swing["ts"],
+                        meta={},
+                    )
+                )
+            elif swing["kind"] == "swing_low":
+                candidates.append(
+                    LiquidityPoolCandidate(
+                        side="sell_side",
+                        pool_type="prior_low",
+                        price_low=swing["price"],
+                        price_high=swing["price"],
+                        reference_ids=[swing["id"]],
+                        created_ts=swing["ts"],
+                        meta={},
+                    )
+                )
+
+        threshold_pct = Decimal(DEFAULT_EQUAL_POOL_THRESHOLD_PCT)
+        candidates.extend(
+            build_equal_pool_candidates(
+                swings=swings,
+                kind="swing_high",
+                side="buy_side",
+                pool_type="equal_highs",
+                threshold_pct=threshold_pct,
+            )
+        )
+        candidates.extend(
+            build_equal_pool_candidates(
+                swings=swings,
+                kind="swing_low",
+                side="sell_side",
+                pool_type="equal_lows",
+                threshold_pct=threshold_pct,
+            )
+        )
+
+        for session in sessions:
+            if session.get("status") in {"incomplete", "invalid", "empty"}:
+                continue
+            if session.get("high") is not None:
+                candidates.append(
+                    LiquidityPoolCandidate(
+                        side="buy_side",
+                        pool_type="session_high",
+                        price_low=session["high"],
+                        price_high=session["high"],
+                        reference_ids=[session["id"]],
+                        created_ts=session["session_date"],
+                        meta={"session_code": session.get("session_code")},
+                    )
+                )
+            if session.get("low") is not None:
+                candidates.append(
+                    LiquidityPoolCandidate(
+                        side="sell_side",
+                        pool_type="session_low",
+                        price_low=session["low"],
+                        price_high=session["low"],
+                        reference_ids=[session["id"]],
+                        created_ts=session["session_date"],
+                        meta={"session_code": session.get("session_code")},
+                    )
+                )
+
+        return dedupe_candidates(candidates)
+
+    def persist_candidates(self, instrument_id: int, timeframe: str, candidates: list[LiquidityPoolCandidate]) -> int:
+        for candidate in candidates:
+            self.repository.insert_pool(
+                instrument_id=instrument_id,
+                timeframe=timeframe,
+                side=candidate.side,
+                pool_type=candidate.pool_type,
+                price_low=candidate.price_low,
+                price_high=candidate.price_high,
+                reference_ids=candidate.reference_ids,
+                created_ts=candidate.created_ts,
+                meta=candidate.meta,
+            )
+        return len(candidates)
+
+
+def build_equal_pool_candidates(
+    swings: list[dict],
+    kind: str,
+    side: str,
+    pool_type: str,
+    threshold_pct: Decimal,
+) -> list[LiquidityPoolCandidate]:
+    relevant = [swing for swing in swings if swing["kind"] == kind and swing.get("price") is not None]
+    relevant.sort(key=lambda row: Decimal(row["price"]))
+
+    groups: list[list[dict]] = []
+    current_group: list[dict] = []
+    anchor: Optional[Decimal] = None
+
+    for swing in relevant:
+        price = Decimal(swing["price"])
+        if anchor is None:
+            current_group = [swing]
+            anchor = price
+            continue
+
+        threshold = max(abs(anchor) * threshold_pct, Decimal("0"))
+        if abs(price - anchor) <= threshold:
+            current_group.append(swing)
+            continue
+
+        if len(current_group) >= 2:
+            groups.append(current_group)
+        current_group = [swing]
+        anchor = price
+
+    if len(current_group) >= 2:
+        groups.append(current_group)
+
+    candidates: list[LiquidityPoolCandidate] = []
+    for group in groups:
+        prices = [Decimal(row["price"]) for row in group]
+        candidates.append(
+            LiquidityPoolCandidate(
+                side=side,
+                pool_type=pool_type,
+                price_low=min(prices),
+                price_high=max(prices),
+                reference_ids=[row["id"] for row in group],
+                created_ts=max(row["ts"] for row in group),
+                meta={
+                    "threshold_pct": str(threshold_pct),
+                    "source": "swing_cluster",
+                    "swing_count": len(group),
+                },
+            )
+        )
+    return candidates
+
+
+def dedupe_candidates(candidates: list[LiquidityPoolCandidate]) -> list[LiquidityPoolCandidate]:
+    exact_unique = _dedupe_exact_candidates(candidates)
+    return _merge_overlapping_candidates(exact_unique)
+
+
+def _dedupe_exact_candidates(candidates: list[LiquidityPoolCandidate]) -> list[LiquidityPoolCandidate]:
+    seen: set[tuple] = set()
+    unique: list[LiquidityPoolCandidate] = []
+    for candidate in candidates:
+        key = (
+            candidate.side,
+            candidate.pool_type,
+            str(candidate.price_low),
+            str(candidate.price_high),
+            tuple(candidate.reference_ids),
+        )
+        if key in seen:
+            continue
+        seen.add(key)
+        unique.append(candidate)
+    return unique
+
+
+def _merge_overlapping_candidates(candidates: list[LiquidityPoolCandidate]) -> list[LiquidityPoolCandidate]:
+    merged: list[LiquidityPoolCandidate] = []
+    by_side: dict[str, list[LiquidityPoolCandidate]] = {"buy_side": [], "sell_side": []}
+    for candidate in candidates:
+        by_side.setdefault(candidate.side, []).append(candidate)
+
+    for side_candidates in by_side.values():
+        ordered = sorted(side_candidates, key=lambda row: (Decimal(row.price_low), Decimal(row.price_high), row.created_ts))
+        for candidate in ordered:
+            if not merged:
+                merged.append(candidate)
+                continue
+            last = merged[-1]
+            if _can_merge_candidates(last, candidate):
+                merged[-1] = _merge_candidate_pair(last, candidate)
+            else:
+                merged.append(candidate)
+    return merged
+
+
+def _can_merge_candidates(left: LiquidityPoolCandidate, right: LiquidityPoolCandidate) -> bool:
+    if left.side != right.side:
+        return False
+    left_low = Decimal(left.price_low)
+    left_high = Decimal(left.price_high)
+    right_low = Decimal(right.price_low)
+    right_high = Decimal(right.price_high)
+    overlap = max(left_low, right_low) <= min(left_high, right_high)
+    if overlap:
+        return True
+    left_width = max(left_high - left_low, Decimal("0"))
+    right_width = max(right_high - right_low, Decimal("0"))
+    tolerance = max(left_width, right_width, Decimal("0.0000001"))
+    return abs(right_low - left_high) <= tolerance or abs(left_low - right_high) <= tolerance
+
+
+def _merge_candidate_pair(left: LiquidityPoolCandidate, right: LiquidityPoolCandidate) -> LiquidityPoolCandidate:
+    price_low = min(Decimal(left.price_low), Decimal(right.price_low))
+    price_high = max(Decimal(left.price_high), Decimal(right.price_high))
+    reference_ids = sorted(set(left.reference_ids + right.reference_ids))
+    merged_types = sorted(set(_pool_types(left) + _pool_types(right)))
+    source_types = sorted(set(_source_types(left) + _source_types(right)))
+    meta = {
+        **left.meta,
+        **right.meta,
+        "merged_pool_types": merged_types,
+        "source_pool_types": source_types,
+        "merged_reference_count": len(reference_ids),
+    }
+    return LiquidityPoolCandidate(
+        side=left.side,
+        pool_type=merged_types[0],
+        price_low=price_low,
+        price_high=price_high,
+        reference_ids=reference_ids,
+        created_ts=max(left.created_ts, right.created_ts),
+        meta=meta,
+    )
+
+
+def _pool_types(candidate: LiquidityPoolCandidate) -> list[str]:
+    merged = candidate.meta.get("merged_pool_types") if candidate.meta else None
+    if merged:
+        return list(merged)
+    return [candidate.pool_type]
+
+
+def _source_types(candidate: LiquidityPoolCandidate) -> list[str]:
+    source = candidate.meta.get("source_pool_types") if candidate.meta else None
+    if source:
+        return list(source)
+    return [candidate.pool_type]
diff --git a/src/services/market_data/__init__.py b/src/services/market_data/__init__.py
new file mode 100644
index 0000000..4befb32
--- /dev/null
+++ b/src/services/market_data/__init__.py
@@ -0,0 +1,6 @@
+"""Market data service package."""
+
+from src.services.market_data.normalizer import NormalizedCandle, normalize_okx_candles
+from src.services.market_data.okx_client import OKXCandle, OKXClient
+
+__all__ = ["NormalizedCandle", "normalize_okx_candles", "OKXCandle", "OKXClient"]
diff --git a/src/services/market_data/normalizer.py b/src/services/market_data/normalizer.py
new file mode 100644
index 0000000..0e612bf
--- /dev/null
+++ b/src/services/market_data/normalizer.py
@@ -0,0 +1,39 @@
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import Iterable
+
+from src.services.market_data.okx_client import OKXCandle
+
+
+@dataclass(frozen=True)
+class NormalizedCandle:
+    symbol: str
+    venue: str
+    timeframe: str
+    ts_open_ms: int
+    open: Decimal
+    high: Decimal
+    low: Decimal
+    close: Decimal
+    volume: Decimal
+    confirm: bool
+
+
+def normalize_okx_candles(symbol: str, venue: str, timeframe: str, candles: Iterable[OKXCandle]) -> list[NormalizedCandle]:
+    normalized: list[NormalizedCandle] = []
+    for candle in candles:
+        normalized.append(
+            NormalizedCandle(
+                symbol=symbol,
+                venue=venue,
+                timeframe=timeframe,
+                ts_open_ms=int(candle.ts),
+                open=Decimal(candle.open),
+                high=Decimal(candle.high),
+                low=Decimal(candle.low),
+                close=Decimal(candle.close),
+                volume=Decimal(candle.volume),
+                confirm=candle.confirm == "1",
+            )
+        )
+    return normalized
diff --git a/src/services/market_data/okx_client.py b/src/services/market_data/okx_client.py
new file mode 100644
index 0000000..61fe6d9
--- /dev/null
+++ b/src/services/market_data/okx_client.py
@@ -0,0 +1,72 @@
+from dataclasses import dataclass
+from typing import Any, Optional
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+from urllib.error import URLError, HTTPError
+from http.client import IncompleteRead
+import json
+import time
+
+from src.config.settings import settings
+
+
+@dataclass(frozen=True)
+class OKXCandle:
+    inst_id: str
+    bar: str
+    ts: str
+    open: str
+    high: str
+    low: str
+    close: str
+    volume: str
+    confirm: str
+
+
+class OKXClient:
+    def __init__(self, base_url: Optional[str] = None, timeout: Optional[int] = None) -> None:
+        self.base_url = base_url or settings.okx_base_url
+        self.timeout = timeout or settings.okx_timeout
+
+    def _get(self, path: str, params: dict[str, Any]) -> dict[str, Any]:
+        query = urlencode(params)
+        url = f"{self.base_url}{path}?{query}"
+        request = Request(url, headers={"User-Agent": "Mozilla/5.0"})
+        last_error: Optional[Exception] = None
+        for attempt in range(3):
+            try:
+                with urlopen(request, timeout=self.timeout) as response:
+                    payload = json.loads(response.read().decode("utf-8"))
+                if payload.get("code") not in ("0", 0, None):
+                    raise RuntimeError(f"OKX API error: {payload}")
+                return payload
+            except (IncompleteRead, URLError, HTTPError, TimeoutError, RuntimeError) as exc:
+                last_error = exc
+                if attempt == 2:
+                    raise
+                time.sleep(1 + attempt)
+        assert last_error is not None
+        raise last_error
+
+    def get_candles(self, inst_id: str, bar: str, limit: int = 100) -> list[OKXCandle]:
+        payload = self._get(
+            "/api/v5/market/history-candles",
+            {"instId": inst_id, "bar": bar, "limit": str(limit)},
+        )
+        rows = payload.get("data", [])
+        candles: list[OKXCandle] = []
+        for row in rows:
+            candles.append(
+                OKXCandle(
+                    inst_id=inst_id,
+                    bar=bar,
+                    ts=row[0],
+                    open=row[1],
+                    high=row[2],
+                    low=row[3],
+                    close=row[4],
+                    volume=row[5],
+                    confirm=row[8] if len(row) > 8 else "1",
+                )
+            )
+        return candles
diff --git a/src/services/ranges/__init__.py b/src/services/ranges/__init__.py
new file mode 100644
index 0000000..89e1540
--- /dev/null
+++ b/src/services/ranges/__init__.py
@@ -0,0 +1,5 @@
+"""Dealing range service package."""
+
+from src.services.ranges.dealing_range_service import DealingRangeService, RangeCandidate
+
+__all__ = ["DealingRangeService", "RangeCandidate"]
diff --git a/src/services/ranges/dealing_range_service.py b/src/services/ranges/dealing_range_service.py
new file mode 100644
index 0000000..d109360
--- /dev/null
+++ b/src/services/ranges/dealing_range_service.py
@@ -0,0 +1,60 @@
+from typing import Any, Optional, Union
+from dataclasses import dataclass
+from decimal import Decimal
+
+from src.repositories.dealing_range_repository import DealingRangeRepository
+
+
+@dataclass(frozen=True)
+class RangeCandidate:
+    high: Decimal
+    low: Decimal
+    equilibrium: Decimal
+    high_swing_id: int
+    low_swing_id: int
+    ts_start: object
+
+
+class DealingRangeService:
+    def __init__(self, repository: Optional[DealingRangeRepository] = None) -> None:
+        self.repository = repository or DealingRangeRepository()
+
+    def build_active_range(self, instrument_id: int, timeframe: str) -> Optional[RangeCandidate]:
+        swings = self.repository.fetch_recent_swings(instrument_id=instrument_id, timeframe=timeframe, limit=50)
+        highs = [row for row in swings if row["kind"] == "swing_high"]
+        lows = [row for row in swings if row["kind"] == "swing_low"]
+        if not highs or not lows:
+            return None
+
+        latest_high = max(highs, key=lambda row: row["ts"])
+        latest_low = max(lows, key=lambda row: row["ts"])
+        high_price = latest_high["price"]
+        low_price = latest_low["price"]
+        if high_price <= low_price:
+            return None
+        equilibrium = (high_price + low_price) / 2
+        ts_start = min(latest_high["ts"], latest_low["ts"])
+        return RangeCandidate(
+            high=high_price,
+            low=low_price,
+            equilibrium=equilibrium,
+            high_swing_id=latest_high["id"],
+            low_swing_id=latest_low["id"],
+            ts_start=ts_start,
+        )
+
+    def persist_active_range(self, instrument_id: int, timeframe: str, candidate: Optional[RangeCandidate]) -> int:
+        if candidate is None:
+            return 0
+        self.repository.upsert_range(
+            instrument_id=instrument_id,
+            timeframe=timeframe,
+            high=candidate.high,
+            low=candidate.low,
+            equilibrium=candidate.equilibrium,
+            high_swing_id=candidate.high_swing_id,
+            low_swing_id=candidate.low_swing_id,
+            ts_start=candidate.ts_start,
+            meta={},
+        )
+        return 1
diff --git a/src/services/reports/__init__.py b/src/services/reports/__init__.py
new file mode 100644
index 0000000..de05941
--- /dev/null
+++ b/src/services/reports/__init__.py
@@ -0,0 +1,13 @@
+"""Reporting service package."""
+
+from src.services.reports.backtest_report_service import BacktestReportService
+from src.services.reports.intraday_report_service import IntradayReportService
+from src.services.reports.post_trade_review_service import PostTradeReviewService
+from src.services.reports.pre_market_report_service import PreMarketReportService
+
+__all__ = [
+    "BacktestReportService",
+    "IntradayReportService",
+    "PostTradeReviewService",
+    "PreMarketReportService",
+]
diff --git a/src/services/reports/backtest_report_service.py b/src/services/reports/backtest_report_service.py
new file mode 100644
index 0000000..a717731
--- /dev/null
+++ b/src/services/reports/backtest_report_service.py
@@ -0,0 +1,6 @@
+from src.services.backtest import summarize_backtest_outcomes
+
+
+class BacktestReportService:
+    def build_summary(self, outcomes):
+        return summarize_backtest_outcomes(outcomes)
diff --git a/src/services/reports/intraday_report_service.py b/src/services/reports/intraday_report_service.py
new file mode 100644
index 0000000..6231f1c
--- /dev/null
+++ b/src/services/reports/intraday_report_service.py
@@ -0,0 +1,45 @@
+from typing import Optional
+
+
+class IntradayReportService:
+    def build_report(
+        self,
+        sweep_event: Optional[dict],
+        structure_event: Optional[dict],
+        fvg_zone: Optional[dict],
+        trade_signal: Optional[dict],
+    ) -> dict:
+        invalidations: list[str] = []
+        if trade_signal:
+            invalidations.extend(trade_signal.get("invalidations") or [])
+        if fvg_zone and (fvg_zone.get("status") in {"mitigated", "invalidated"} or (fvg_zone.get("meta") or {}).get("invalidated")):
+            invalidations.append("fvg_no_longer_actionable")
+        if structure_event and not structure_event.get("accepted", True):
+            invalidations.append("structure_not_accepted")
+
+        return {
+            "report_type": "intraday_explanation",
+            "sweep": {
+                "present": sweep_event is not None,
+                "side_swept": sweep_event.get("side_swept") if sweep_event else None,
+                "close_back_inside": sweep_event.get("close_back_inside") if sweep_event else None,
+            },
+            "structure": {
+                "event_type": structure_event.get("event_type") if structure_event else None,
+                "direction": structure_event.get("direction") if structure_event else None,
+                "accepted": structure_event.get("accepted") if structure_event else None,
+            },
+            "fvg": {
+                "direction": fvg_zone.get("direction") if fvg_zone else None,
+                "status": fvg_zone.get("status") if fvg_zone else None,
+                "fill_pct": float(fvg_zone.get("fill_pct") or 0.0) if fvg_zone else None,
+            },
+            "signal": {
+                "present": trade_signal is not None,
+                "status": trade_signal.get("status") if trade_signal else None,
+                "side": trade_signal.get("side") if trade_signal else None,
+                "session_code": trade_signal.get("session_code") if trade_signal else None,
+                "is_valid": trade_signal is not None and len(invalidations) == 0,
+            },
+            "invalidations": sorted(set(invalidations)),
+        }
diff --git a/src/services/reports/post_trade_review_service.py b/src/services/reports/post_trade_review_service.py
new file mode 100644
index 0000000..785eb49
--- /dev/null
+++ b/src/services/reports/post_trade_review_service.py
@@ -0,0 +1,50 @@
+from typing import Optional
+
+
+class PostTradeReviewService:
+    def build_report(
+        self,
+        trade_execution: Optional[dict],
+        trade_signal: Optional[dict],
+        backtest_result: Optional[dict],
+    ) -> dict:
+        rule_alignment = True
+        error_types: list[str] = []
+        improvement_notes: list[str] = []
+
+        if not trade_execution:
+            rule_alignment = False
+            error_types.append("missing_execution_record")
+        else:
+            if trade_execution.get("status") == "rejected":
+                rule_alignment = False
+                error_types.append("execution_rejected")
+            risk_checks = (trade_execution.get("meta") or {}).get("risk_checks") or []
+            if risk_checks:
+                rule_alignment = False
+                error_types.extend(risk_checks)
+
+        if trade_signal:
+            signal_invalidations = trade_signal.get("invalidations") or []
+            if signal_invalidations:
+                improvement_notes.append("review_signal_invalidations")
+            if trade_signal.get("status") != "awaiting_confirmation":
+                improvement_notes.append("prefer_confirmed_execution_window")
+
+        if backtest_result:
+            if backtest_result.get("outcome") == "loss":
+                improvement_notes.append("inspect_stop_and_structure_context")
+            if backtest_result.get("invalidated_before_entry"):
+                improvement_notes.append("avoid_expired_or_invalidated_signals")
+            if "same_candle_entry_exit_ambiguous" in (backtest_result.get("error_tags") or []):
+                improvement_notes.append("review_same_candle_ambiguity_cases")
+
+        return {
+            "report_type": "post_trade_review",
+            "rule_aligned": rule_alignment,
+            "execution_status": trade_execution.get("status") if trade_execution else None,
+            "signal_status": trade_signal.get("status") if trade_signal else None,
+            "backtest_outcome": backtest_result.get("outcome") if backtest_result else None,
+            "error_types": sorted(set(error_types)),
+            "improvement_notes": sorted(set(improvement_notes)),
+        }
diff --git a/src/services/reports/pre_market_report_service.py b/src/services/reports/pre_market_report_service.py
new file mode 100644
index 0000000..08cd04c
--- /dev/null
+++ b/src/services/reports/pre_market_report_service.py
@@ -0,0 +1,39 @@
+from typing import Optional
+
+
+def classify_range_location(price: Optional[float], dealing_range: Optional[dict]) -> Optional[str]:
+    if price is None or not dealing_range:
+        return None
+    equilibrium = float(dealing_range.get("equilibrium") or 0.0)
+    if price > equilibrium:
+        return "premium"
+    if price < equilibrium:
+        return "discount"
+    return "equilibrium"
+
+
+class PreMarketReportService:
+    def build_report(
+        self,
+        bias_snapshot: Optional[dict],
+        dealing_range: Optional[dict],
+        current_price: Optional[float],
+        session_code: Optional[str],
+    ) -> dict:
+        execution_permission = bool((bias_snapshot or {}).get("execution_intensity") in {"medium", "high"}) and session_code in {"LONDON", "NY_AM", "NY_PM"}
+        return {
+            "report_type": "pre_market_plan",
+            "daily_bias": (bias_snapshot or {}).get("daily_bias"),
+            "draw_side": (bias_snapshot or {}).get("draw_side"),
+            "execution_intensity": (bias_snapshot or {}).get("execution_intensity"),
+            "reason_codes": (bias_snapshot or {}).get("reason_codes") or [],
+            "session_code": session_code,
+            "execution_permission": execution_permission,
+            "working_range": {
+                "range_id": (dealing_range or {}).get("id"),
+                "high": float((dealing_range or {}).get("high") or 0.0) if dealing_range else None,
+                "low": float((dealing_range or {}).get("low") or 0.0) if dealing_range else None,
+                "equilibrium": float((dealing_range or {}).get("equilibrium") or 0.0) if dealing_range else None,
+                "location": classify_range_location(current_price, dealing_range),
+            },
+        }
diff --git a/src/services/sessions/__init__.py b/src/services/sessions/__init__.py
new file mode 100644
index 0000000..029611d
--- /dev/null
+++ b/src/services/sessions/__init__.py
@@ -0,0 +1,5 @@
+"""Session generation service package."""
+
+from src.services.sessions.session_generator import SessionGenerator, SessionRecord
+
+__all__ = ["SessionGenerator", "SessionRecord"]
diff --git a/src/services/sessions/session_generator.py b/src/services/sessions/session_generator.py
new file mode 100644
index 0000000..dfba66a
--- /dev/null
+++ b/src/services/sessions/session_generator.py
@@ -0,0 +1,71 @@
+from typing import Any, Optional, Union
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta
+from zoneinfo import ZoneInfo
+
+from src.config.sessions import SESSION_WINDOWS
+from src.config.settings import settings
+from src.repositories.market_session_repository import MarketSessionRepository
+
+
+@dataclass(frozen=True)
+class SessionRecord:
+    session_code: str
+    session_date: str
+    start_local: datetime
+    end_local: datetime
+
+
+class SessionGenerator:
+    def __init__(self, timezone_name: Optional[str] = None, repository: Optional[MarketSessionRepository] = None) -> None:
+        self.timezone_name = timezone_name or settings.session_timezone
+        self.timezone = ZoneInfo(self.timezone_name)
+        self.repository = repository or MarketSessionRepository()
+
+    def build_session_windows(self, session_date: datetime) -> list[SessionRecord]:
+        records: list[SessionRecord] = []
+        for window in SESSION_WINDOWS:
+            start_hour, start_minute = map(int, window.start.split(":"))
+            end_hour, end_minute = map(int, window.end.split(":"))
+            start_local = session_date.replace(hour=start_hour, minute=start_minute, second=0, microsecond=0)
+            end_local = session_date.replace(hour=end_hour, minute=end_minute, second=0, microsecond=0)
+            if end_local <= start_local:
+                end_local = end_local + timedelta(days=1)
+            records.append(
+                SessionRecord(
+                    session_code=window.code,
+                    session_date=start_local.date().isoformat(),
+                    start_local=start_local,
+                    end_local=end_local,
+                )
+            )
+        return records
+
+    def generate_for_date(self, instrument_id: int, timeframe: str, session_date: datetime) -> int:
+        records = self.build_session_windows(session_date)
+        written = 0
+        for record in records:
+            start_utc = record.start_local.astimezone(ZoneInfo("UTC"))
+            end_utc = record.end_local.astimezone(ZoneInfo("UTC"))
+            candles = self.repository.fetch_candles_for_window(instrument_id, timeframe, start_utc, end_utc)
+            highs = [row["high"] for row in candles if row.get("high") is not None]
+            lows = [row["low"] for row in candles if row.get("low") is not None]
+            high = max(highs) if highs else None
+            low = min(lows) if lows else None
+            midpoint = ((high + low) / 2) if high is not None and low is not None else None
+            status = "closed" if candles else "incomplete"
+            self.repository.upsert_session(
+                instrument_id=instrument_id,
+                session_date=date.fromisoformat(record.session_date),
+                timezone_name=self.timezone_name,
+                session_code=record.session_code,
+                start_ts=start_utc,
+                end_ts=end_utc,
+                high=high,
+                low=low,
+                midpoint=midpoint,
+                status=status,
+                meta={"candle_count": len(candles), "timeframe": timeframe},
+            )
+            written += 1
+        return written
diff --git a/src/services/signals/__init__.py b/src/services/signals/__init__.py
new file mode 100644
index 0000000..413bbb1
--- /dev/null
+++ b/src/services/signals/__init__.py
@@ -0,0 +1,17 @@
+"""Signal service package."""
+
+from src.services.signals.signal_service import (
+    SignalCandidate,
+    SignalService,
+    classify_session_for_signal,
+    trade_signal_matches_candidate,
+    validate_signal_context,
+)
+
+__all__ = [
+    "SignalCandidate",
+    "SignalService",
+    "classify_session_for_signal",
+    "trade_signal_matches_candidate",
+    "validate_signal_context",
+]
diff --git a/src/services/signals/signal_service.py b/src/services/signals/signal_service.py
new file mode 100644
index 0000000..9890960
--- /dev/null
+++ b/src/services/signals/signal_service.py
@@ -0,0 +1,188 @@
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+from src.repositories.signal_repository import SignalRepository
+
+
+@dataclass(frozen=True)
+class SignalCandidate:
+    side: str
+    status: str
+    entry_low: float
+    entry_high: float
+    stop_loss: float
+    tp1: float
+    tp2: float
+    rr_tp1: float
+    rr_tp2: float
+    session_code: Optional[str]
+    created_ts: object
+    expires_ts: object
+    invalidations: list[str]
+    evidence: dict
+    meta: dict
+
+
+class SignalService:
+    def __init__(self, repository: Optional[SignalRepository] = None) -> None:
+        self.repository = repository or SignalRepository()
+
+    def build_signal(self, instrument_id: int, setup_tf: str, trigger_tf: str) -> Optional[SignalCandidate]:
+        bias = self.repository.fetch_latest_bias_snapshot(instrument_id=instrument_id, setup_tf=setup_tf, trigger_tf=trigger_tf)
+        fvg = self.repository.fetch_latest_fvg(instrument_id=instrument_id, timeframe=trigger_tf)
+        mss = self.repository.fetch_latest_mss(instrument_id=instrument_id, timeframe=setup_tf)
+        if not bias or not fvg or not mss:
+            return None
+
+        structure_alignment = validate_signal_context(bias=bias, fvg=fvg, mss=mss)
+        if not structure_alignment['is_actionable']:
+            return None
+
+        side = structure_alignment['side']
+        entry_low = float(fvg['lower'])
+        entry_high = float(fvg['upper'])
+        if side == 'buy':
+            stop_loss = min(float(mss['broken_level']), entry_low) * 0.999
+            tp1 = entry_high * 1.001
+            tp2 = entry_high * 1.003
+        else:
+            stop_loss = max(float(mss['broken_level']), entry_high) * 1.001
+            tp1 = entry_low * 0.999
+            tp2 = entry_low * 0.997
+        risk = abs(((entry_low + entry_high) / 2) - stop_loss)
+        rr_tp1 = abs(tp1 - ((entry_low + entry_high) / 2)) / risk if risk else 0.0
+        rr_tp2 = abs(tp2 - ((entry_low + entry_high) / 2)) / risk if risk else 0.0
+        created_ts = datetime.now(timezone.utc)
+        expires_ts = created_ts + timedelta(hours=4)
+        session = self.repository.fetch_session_at(instrument_id=instrument_id, ts=created_ts)
+        session_code = session['session_code'] if session else 'OFF_HOURS'
+        session_decision = classify_session_for_signal(session_code)
+        invalidations = ['mss invalidated', 'fvg fully mitigated']
+        if not session_decision['execution_permission']:
+            invalidations.append('session_mismatch')
+        return SignalCandidate(
+            side=side,
+            status=session_decision['status'],
+            entry_low=entry_low,
+            entry_high=entry_high,
+            stop_loss=stop_loss,
+            tp1=tp1,
+            tp2=tp2,
+            rr_tp1=rr_tp1,
+            rr_tp2=rr_tp2,
+            session_code=session_code,
+            created_ts=created_ts,
+            expires_ts=expires_ts,
+            invalidations=invalidations,
+            evidence={
+                'bias_snapshot_id': bias['id'],
+                'fvg_id': fvg['id'],
+                'mss_id': mss['id'],
+            },
+            meta={
+                'session_filter': session_decision['reason'],
+                'execution_permission': session_decision['execution_permission'],
+                'structure_quality': structure_alignment['reason'],
+                'fvg_status': fvg['status'],
+                'fvg_fill_pct': float(fvg.get('fill_pct') or 0.0),
+                'mss_displacement_event_id': mss.get('displacement_event_id'),
+            },
+        )
+
+    def persist_signal(self, instrument_id: int, setup_tf: str, trigger_tf: str, candidate: Optional[SignalCandidate]) -> int:
+        if candidate is None:
+            return 0
+        bias = self.repository.fetch_latest_bias_snapshot(instrument_id=instrument_id, setup_tf=setup_tf, trigger_tf=trigger_tf)
+        if not bias:
+            return 0
+        latest = self.repository.fetch_latest_trade_signal(instrument_id=instrument_id, model_code='SWEEP_MSS_FVG')
+        if latest and trade_signal_matches_candidate(latest, candidate, bias['id']):
+            return 0
+        self.repository.insert_trade_signal(
+            instrument_id=instrument_id,
+            model_code='SWEEP_MSS_FVG',
+            side=candidate.side,
+            status=candidate.status,
+            bias_snapshot_id=bias['id'],
+            entry_type='limit',
+            entry_low=candidate.entry_low,
+            entry_high=candidate.entry_high,
+            stop_loss=candidate.stop_loss,
+            tp1=candidate.tp1,
+            tp2=candidate.tp2,
+            rr_tp1=candidate.rr_tp1,
+            rr_tp2=candidate.rr_tp2,
+            session_code=candidate.session_code,
+            created_ts=candidate.created_ts,
+            expires_ts=candidate.expires_ts,
+            invalidations=candidate.invalidations,
+            evidence=candidate.evidence,
+            meta=candidate.meta,
+        )
+        return 1
+
+
+def trade_signal_matches_candidate(signal: dict, candidate: SignalCandidate, bias_snapshot_id: int) -> bool:
+    return (
+        signal.get('side') == candidate.side
+        and signal.get('status') == candidate.status
+        and signal.get('bias_snapshot_id') == bias_snapshot_id
+        and signal.get('entry_type') == 'limit'
+        and float(signal.get('entry_low') or 0.0) == float(candidate.entry_low)
+        and float(signal.get('entry_high') or 0.0) == float(candidate.entry_high)
+        and float(signal.get('stop_loss') or 0.0) == float(candidate.stop_loss)
+        and float(signal.get('tp1') or 0.0) == float(candidate.tp1)
+        and float(signal.get('tp2') or 0.0) == float(candidate.tp2)
+        and float(signal.get('rr_tp1') or 0.0) == float(candidate.rr_tp1)
+        and float(signal.get('rr_tp2') or 0.0) == float(candidate.rr_tp2)
+        and signal.get('session_code') == candidate.session_code
+        and list(signal.get('invalidations') or []) == list(candidate.invalidations)
+        and dict(signal.get('evidence') or {}) == dict(candidate.evidence)
+        and dict(signal.get('meta') or {}) == dict(candidate.meta)
+    )
+
+
+def validate_signal_context(bias: dict, fvg: dict, mss: dict) -> dict[str, object]:
+    if not mss.get('accepted'):
+        return {'is_actionable': False, 'reason': 'mss_not_accepted'}
+
+    expected_side = 'buy' if mss['direction'] == 'bullish' else 'sell'
+    if fvg['direction'] != mss['direction']:
+        return {'is_actionable': False, 'reason': 'fvg_mss_direction_mismatch'}
+
+    draw_side = bias.get('draw_side')
+    if draw_side and ((expected_side == 'buy' and draw_side != 'buy_side') or (expected_side == 'sell' and draw_side != 'sell_side')):
+        return {'is_actionable': False, 'reason': 'bias_structure_mismatch'}
+
+    if fvg['status'] not in {'open', 'touched'}:
+        return {'is_actionable': False, 'reason': 'fvg_not_actionable'}
+
+    fvg_meta = fvg.get('meta') or {}
+    if fvg_meta.get('invalidated'):
+        return {'is_actionable': False, 'reason': 'fvg_invalidated'}
+
+    if mss.get('displacement_event_id') and fvg.get('related_displacement_id') and mss['displacement_event_id'] != fvg['related_displacement_id']:
+        return {'is_actionable': False, 'reason': 'displacement_context_mismatch'}
+
+    return {'is_actionable': True, 'reason': 'aligned', 'side': expected_side}
+
+
+def classify_session_for_signal(session_code: Optional[str]) -> dict[str, object]:
+    if session_code in {'LONDON', 'NY_AM', 'NY_PM'}:
+        return {
+            'status': 'awaiting_confirmation',
+            'execution_permission': True,
+            'reason': 'allowed_session',
+        }
+    if session_code in {'ASIA', 'NY_LUNCH'}:
+        return {
+            'status': 'awaiting_context',
+            'execution_permission': False,
+            'reason': 'observation_or_management_session',
+        }
+    return {
+        'status': 'awaiting_context',
+        'execution_permission': False,
+        'reason': 'off_hours',
+    }
diff --git a/src/services/structure/__init__.py b/src/services/structure/__init__.py
new file mode 100644
index 0000000..1d55a7a
--- /dev/null
+++ b/src/services/structure/__init__.py
@@ -0,0 +1,5 @@
+"""Structure service package."""
+
+from src.services.structure.mss_service import MSSCandidate, MSSService, detect_mss_candidates, evaluate_mss_acceptance
+
+__all__ = ["MSSCandidate", "MSSService", "detect_mss_candidates", "evaluate_mss_acceptance"]
diff --git a/src/services/structure/mss_service.py b/src/services/structure/mss_service.py
new file mode 100644
index 0000000..eb046ff
--- /dev/null
+++ b/src/services/structure/mss_service.py
@@ -0,0 +1,191 @@
+from dataclasses import dataclass
+from typing import Optional
+
+from src.config.constants import DEFAULT_MSS_ACCEPTANCE_WINDOW_CANDLES
+from src.repositories.structure_repository import StructureRepository
+
+
+@dataclass(frozen=True)
+class MSSCandidate:
+    direction: str
+    broken_level: float
+    reference_swing_id: int
+    displacement_event_id: int
+    accepted: bool
+    ts: object
+    meta: dict
+
+
+class MSSService:
+    def __init__(self, repository: Optional[StructureRepository] = None) -> None:
+        self.repository = repository or StructureRepository()
+
+    def detect_mss(self, instrument_id: int, timeframe: str) -> list[MSSCandidate]:
+        swings = self.repository.fetch_recent_swings(instrument_id=instrument_id, timeframe=timeframe, limit=50)
+        displacements = self.repository.fetch_recent_displacement(instrument_id=instrument_id, timeframe=timeframe, limit=20)
+        candles = self.repository.fetch_recent_candles(instrument_id=instrument_id, timeframe=timeframe, limit=200)
+        return detect_mss_candidates(
+            swings=swings,
+            displacements=displacements,
+            candles=candles,
+            acceptance_window=DEFAULT_MSS_ACCEPTANCE_WINDOW_CANDLES,
+        )
+
+    def persist_mss(self, instrument_id: int, timeframe: str, candidates: list[MSSCandidate]) -> int:
+        persisted = 0
+        for candidate in candidates:
+            if not candidate.accepted:
+                continue
+            self.repository.insert_mss_event(
+                instrument_id=instrument_id,
+                timeframe=timeframe,
+                direction=candidate.direction,
+                broken_level=candidate.broken_level,
+                reference_swing_id=candidate.reference_swing_id,
+                displacement_event_id=candidate.displacement_event_id,
+                accepted=candidate.accepted,
+                ts=candidate.ts,
+                meta=candidate.meta,
+            )
+            persisted += 1
+        return persisted
+
+
+def detect_mss_candidates(
+    swings: list[dict],
+    displacements: list[dict],
+    candles: list[dict],
+    acceptance_window: int = DEFAULT_MSS_ACCEPTANCE_WINDOW_CANDLES,
+) -> list[MSSCandidate]:
+    candidates: list[MSSCandidate] = []
+    if not swings or not displacements or not candles:
+        return candidates
+
+    swing_highs = sorted(
+        [s for s in swings if s['kind'] == 'swing_high' and s.get('price') is not None],
+        key=lambda row: row['ts'],
+    )
+    swing_lows = sorted(
+        [s for s in swings if s['kind'] == 'swing_low' and s.get('price') is not None],
+        key=lambda row: row['ts'],
+    )
+    ordered_candles = sorted(candles, key=lambda row: row['ts_open'])
+    candle_index_by_close = {row['ts_close']: idx for idx, row in enumerate(ordered_candles)}
+
+    for displacement in sorted(displacements, key=lambda row: row['end_ts'], reverse=True):
+        direction = displacement['direction']
+        if direction == 'bullish':
+            reference_swing = _latest_swing_before_ts(swing_highs, displacement['end_ts'])
+            if not reference_swing:
+                continue
+            candidate = _build_mss_candidate(
+                direction='bullish',
+                displacement=displacement,
+                reference_swing=reference_swing,
+                ordered_candles=ordered_candles,
+                candle_index_by_close=candle_index_by_close,
+                acceptance_window=acceptance_window,
+            )
+        else:
+            reference_swing = _latest_swing_before_ts(swing_lows, displacement['end_ts'])
+            if not reference_swing:
+                continue
+            candidate = _build_mss_candidate(
+                direction='bearish',
+                displacement=displacement,
+                reference_swing=reference_swing,
+                ordered_candles=ordered_candles,
+                candle_index_by_close=candle_index_by_close,
+                acceptance_window=acceptance_window,
+            )
+        if candidate and candidate.accepted:
+            candidates.append(candidate)
+            break
+    return candidates
+
+
+def _build_mss_candidate(
+    direction: str,
+    displacement: dict,
+    reference_swing: dict,
+    ordered_candles: list[dict],
+    candle_index_by_close: dict,
+    acceptance_window: int,
+) -> Optional[MSSCandidate]:
+    displacement_idx = candle_index_by_close.get(displacement['end_ts'])
+    if displacement_idx is None:
+        return None
+
+    broken_level = float(reference_swing['price'])
+    displacement_candle = ordered_candles[displacement_idx]
+    close_price = float(displacement_candle['close'])
+    if direction == 'bullish' and close_price <= broken_level:
+        return None
+    if direction == 'bearish' and close_price >= broken_level:
+        return None
+
+    retest_candles = ordered_candles[displacement_idx + 1 : displacement_idx + 1 + acceptance_window]
+    acceptance = evaluate_mss_acceptance(direction, broken_level, retest_candles)
+    if not acceptance['has_retest']:
+        return None
+
+    return MSSCandidate(
+        direction=direction,
+        broken_level=broken_level,
+        reference_swing_id=reference_swing['id'],
+        displacement_event_id=displacement['id'],
+        accepted=bool(acceptance['accepted']),
+        ts=displacement['end_ts'],
+        meta={
+            'acceptance_window_candles': acceptance_window,
+            'has_retest': acceptance['has_retest'],
+            'retest_count': acceptance['retest_count'],
+            'held_boundary': acceptance['held_boundary'],
+            'reclaimed_old_control': acceptance['reclaimed_old_control'],
+        },
+    )
+
+
+def evaluate_mss_acceptance(direction: str, broken_level: float, candles: list[dict]) -> dict[str, object]:
+    has_retest = False
+    reclaimed_old_control = False
+    held_boundary = True
+    retest_count = 0
+
+    for candle in candles:
+        low = float(candle['low'])
+        high = float(candle['high'])
+        close = float(candle['close'])
+        if direction == 'bullish':
+            touched_boundary = low <= broken_level
+            if touched_boundary:
+                has_retest = True
+                retest_count += 1
+            if close <= broken_level:
+                reclaimed_old_control = True
+                held_boundary = False
+                break
+        else:
+            touched_boundary = high >= broken_level
+            if touched_boundary:
+                has_retest = True
+                retest_count += 1
+            if close >= broken_level:
+                reclaimed_old_control = True
+                held_boundary = False
+                break
+
+    return {
+        'accepted': has_retest and held_boundary and not reclaimed_old_control,
+        'has_retest': has_retest,
+        'retest_count': retest_count,
+        'held_boundary': held_boundary,
+        'reclaimed_old_control': reclaimed_old_control,
+    }
+
+
+def _latest_swing_before_ts(swings: list[dict], ts) -> Optional[dict]:
+    eligible = [swing for swing in swings if swing['ts'] <= ts]
+    if not eligible:
+        return None
+    return eligible[-1]
diff --git a/src/services/sweeps/__init__.py b/src/services/sweeps/__init__.py
new file mode 100644
index 0000000..c8cf4b0
--- /dev/null
+++ b/src/services/sweeps/__init__.py
@@ -0,0 +1,5 @@
+"""Sweep service package."""
+
+from src.services.sweeps.sweep_service import SweepCandidate, SweepService
+
+__all__ = ["SweepCandidate", "SweepService"]
diff --git a/src/services/sweeps/sweep_service.py b/src/services/sweeps/sweep_service.py
new file mode 100644
index 0000000..0075ec2
--- /dev/null
+++ b/src/services/sweeps/sweep_service.py
@@ -0,0 +1,109 @@
+from typing import Any, Optional, Union
+from dataclasses import dataclass
+from datetime import date, datetime, time, timezone
+from decimal import Decimal
+
+from src.repositories.sweep_repository import SweepRepository
+
+
+@dataclass(frozen=True)
+class SweepCandidate:
+    side_swept: str
+    pool_id: int
+    sweep_high: Decimal
+    sweep_low: Decimal
+    sweep_ts: datetime
+    close_back_inside: bool
+    validation_level: str
+    status: str
+    meta: dict
+
+
+class SweepService:
+    def __init__(
+        self,
+        repository: Optional[SweepRepository] = None,
+        validation_window: int = 3,
+        candle_limit: int = 200,
+    ) -> None:
+        self.repository = repository or SweepRepository()
+        self.validation_window = validation_window
+        self.candle_limit = candle_limit
+
+    def detect_sweeps(self, instrument_id: int, timeframe: str) -> list[SweepCandidate]:
+        candidates: list[SweepCandidate] = []
+        pools = self.repository.fetch_active_pools(instrument_id=instrument_id, timeframe=timeframe)
+        for pool in pools:
+            created_ts = self._normalize_created_ts(pool["created_ts"])
+            candles = self.repository.fetch_candles_after_ts(
+                instrument_id=instrument_id,
+                timeframe=timeframe,
+                start_ts=created_ts,
+                limit=self.candle_limit,
+            )
+            candidate = self._build_candidate(pool, candles)
+            if candidate is not None:
+                candidates.append(candidate)
+        return candidates
+
+    def persist_sweeps(self, instrument_id: int, timeframe: str, candidates: list[SweepCandidate]) -> int:
+        for candidate in candidates:
+            self.repository.upsert_sweep(
+                instrument_id=instrument_id,
+                timeframe=timeframe,
+                side_swept=candidate.side_swept,
+                pool_id=candidate.pool_id,
+                sweep_high=candidate.sweep_high,
+                sweep_low=candidate.sweep_low,
+                sweep_ts=candidate.sweep_ts,
+                close_back_inside=candidate.close_back_inside,
+                validation_level=candidate.validation_level,
+                status=candidate.status,
+                meta=candidate.meta,
+            )
+            if candidate.status == "confirmed":
+                self.repository.mark_pool_swept(candidate.pool_id)
+        return len(candidates)
+
+    def _build_candidate(self, pool: dict, candles: list[dict]) -> Optional[SweepCandidate]:
+        for index, candle in enumerate(candles):
+            if not self._is_pool_breached(pool, candle):
+                continue
+            window = candles[index : index + self.validation_window]
+            close_back_inside = any(self._closes_back_inside(pool, item) for item in window)
+            validation_level = "validated" if close_back_inside else "weak"
+            status = "confirmed" if close_back_inside else "active"
+            return SweepCandidate(
+                side_swept=pool["side"],
+                pool_id=pool["id"],
+                sweep_high=candle["high"],
+                sweep_low=candle["low"],
+                sweep_ts=candle["ts_open"],
+                close_back_inside=close_back_inside,
+                validation_level=validation_level,
+                status=status,
+                meta={
+                    "pool_type": pool["pool_type"],
+                    "reference_ids": pool.get("reference_ids", []),
+                    "validation_window": self.validation_window,
+                    "breach_close": str(candle["close"]),
+                    "pool_price_low": str(pool["price_low"]),
+                    "pool_price_high": str(pool["price_high"]),
+                },
+            )
+        return None
+
+    def _is_pool_breached(self, pool: dict, candle: dict) -> bool:
+        if pool["side"] == "buy_side":
+            return candle["high"] > pool["price_high"]
+        return candle["low"] < pool["price_low"]
+
+    def _closes_back_inside(self, pool: dict, candle: dict) -> bool:
+        if pool["side"] == "buy_side":
+            return candle["close"] <= pool["price_high"]
+        return candle["close"] >= pool["price_low"]
+
+    def _normalize_created_ts(self, value: Union[datetime, date]) -> datetime:
+        if isinstance(value, datetime):
+            return value if value.tzinfo is not None else value.replace(tzinfo=timezone.utc)
+        return datetime.combine(value, time.min, tzinfo=timezone.utc)
diff --git a/src/services/swings/__init__.py b/src/services/swings/__init__.py
new file mode 100644
index 0000000..a8621b3
--- /dev/null
+++ b/src/services/swings/__init__.py
@@ -0,0 +1,5 @@
+"""Swing service package."""
+
+from src.services.swings.swing_service import SwingCandidate, SwingService
+
+__all__ = ["SwingCandidate", "SwingService"]
diff --git a/src/services/swings/swing_service.py b/src/services/swings/swing_service.py
new file mode 100644
index 0000000..bba5b64
--- /dev/null
+++ b/src/services/swings/swing_service.py
@@ -0,0 +1,80 @@
+from typing import Any, Optional, Union
+from dataclasses import dataclass
+from decimal import Decimal
+
+from src.repositories.swing_repository import SwingRepository
+
+
+@dataclass(frozen=True)
+class SwingCandidate:
+    kind: str
+    strength: str
+    price: Decimal
+    ts: object
+    left_bars: int
+    right_bars: int
+    confirmed: bool
+
+
+class SwingService:
+    def __init__(self, repository: Optional[SwingRepository] = None) -> None:
+        self.repository = repository or SwingRepository()
+
+    def detect_swings(self, instrument_id: int, timeframe: str, left_bars: int = 2, right_bars: int = 2, limit: int = 500) -> list[SwingCandidate]:
+        candles = self.repository.fetch_candles(instrument_id=instrument_id, timeframe=timeframe, limit=limit)
+        candidates: list[SwingCandidate] = []
+        if len(candles) < left_bars + right_bars + 1:
+            return candidates
+
+        for idx in range(left_bars, len(candles) - right_bars):
+            current = candles[idx]
+            left = candles[idx - left_bars: idx]
+            right = candles[idx + 1: idx + 1 + right_bars]
+
+            current_high = current["high"]
+            current_low = current["low"]
+
+            is_swing_high = all(current_high > item["high"] for item in left) and all(current_high > item["high"] for item in right)
+            is_swing_low = all(current_low < item["low"] for item in left) and all(current_low < item["low"] for item in right)
+
+            if is_swing_high:
+                candidates.append(
+                    SwingCandidate(
+                        kind="swing_high",
+                        strength="ST",
+                        price=current_high,
+                        ts=current["ts_open"],
+                        left_bars=left_bars,
+                        right_bars=right_bars,
+                        confirmed=True,
+                    )
+                )
+            if is_swing_low:
+                candidates.append(
+                    SwingCandidate(
+                        kind="swing_low",
+                        strength="ST",
+                        price=current_low,
+                        ts=current["ts_open"],
+                        left_bars=left_bars,
+                        right_bars=right_bars,
+                        confirmed=True,
+                    )
+                )
+        return candidates
+
+    def persist_swings(self, instrument_id: int, timeframe: str, candidates: list[SwingCandidate]) -> int:
+        for candidate in candidates:
+            self.repository.upsert_swing(
+                instrument_id=instrument_id,
+                timeframe=timeframe,
+                kind=candidate.kind,
+                strength=candidate.strength,
+                price=candidate.price,
+                ts=candidate.ts,
+                left_bars=candidate.left_bars,
+                right_bars=candidate.right_bars,
+                confirmed=candidate.confirmed,
+                meta={},
+            )
+        return len(candidates)
diff --git a/src/utils/__init__.py b/src/utils/__init__.py
new file mode 100644
index 0000000..f46a82a
--- /dev/null
+++ b/src/utils/__init__.py
@@ -0,0 +1 @@
+"""Shared utility helpers."""
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..ce8b775
--- /dev/null
+++ b/tests/__init__.py
@@ -0,0 +1 @@
+"""Test package for AI ICT."""
diff --git a/tests/fixtures/__init__.py b/tests/fixtures/__init__.py
new file mode 100644
index 0000000..d1b3395
--- /dev/null
+++ b/tests/fixtures/__init__.py
@@ -0,0 +1 @@
+"""Test fixtures package."""
diff --git a/tests/integration/__init__.py b/tests/integration/__init__.py
new file mode 100644
index 0000000..c66cd71
--- /dev/null
+++ b/tests/integration/__init__.py
@@ -0,0 +1 @@
+"""Integration tests package."""
diff --git a/tests/unit/__init__.py b/tests/unit/__init__.py
new file mode 100644
index 0000000..ea3f8b9
--- /dev/null
+++ b/tests/unit/__init__.py
@@ -0,0 +1 @@
+"""Unit tests package."""
diff --git a/tests/unit/test_api_and_main.py b/tests/unit/test_api_and_main.py
new file mode 100644
index 0000000..9c0a88e
--- /dev/null
+++ b/tests/unit/test_api_and_main.py
@@ -0,0 +1,206 @@
+import os
+import unittest
+from unittest.mock import patch
+
+os.environ.setdefault("DATABASE_URL", "postgresql+psycopg://user:pass@localhost:5432/ai_ict_test")
+
+from src.api import get_health
+from src.api.backtest import get_recent_backtest_summaries
+from src.api.signals import get_recent_signals
+from src.main import run_closed_loop
+
+
+class FakeResult:
+    def __init__(self, rows):
+        self._rows = rows
+
+    def mappings(self):
+        return self
+
+    def all(self):
+        return self._rows
+
+
+class FakeSession:
+    def __init__(self, rows):
+        self.rows = rows
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        return None
+
+    def execute(self, sql, params):
+        return FakeResult(self.rows)
+
+
+class ApiTests(unittest.TestCase):
+    def test_health_returns_expected_fields(self) -> None:
+        health = get_health()
+
+        self.assertEqual(health["app"], "ai-ict")
+        self.assertIn("database_configured", health)
+        self.assertIn("session_timezone", health)
+
+    def test_get_recent_signals_uses_session_query(self) -> None:
+        rows = [{"id": 1, "side": "buy", "status": "awaiting_confirmation"}]
+        with patch("src.api.signals.SessionLocal", return_value=FakeSession(rows)):
+            result = get_recent_signals(instrument_id=1, limit=1)
+
+        self.assertEqual(result, rows)
+
+    def test_get_recent_backtest_summaries_uses_session_query(self) -> None:
+        rows = [{"id": 10, "summary": {"total_signals": 3}}]
+        with patch("src.api.backtest.SessionLocal", return_value=FakeSession(rows)):
+            result = get_recent_backtest_summaries(instrument_id=1, limit=1)
+
+        self.assertEqual(result, rows)
+
+
+class FakeSessionGenerator:
+    timezone = __import__("datetime").timezone.utc
+
+    def generate_for_date(self, instrument_id, timeframe, session_date):
+        return 5
+
+
+class FakeSwingService:
+    def detect_swings(self, **kwargs):
+        return [type("Swing", (), {"kind": "swing_high", "price": 101.0, "ts": "t", "strength": "ST", "left_bars": 2, "right_bars": 2, "confirmed": True})()]
+
+    def persist_swings(self, **kwargs):
+        return 1
+
+
+class FakeRangeService:
+    def build_active_range(self, **kwargs):
+        return type("Range", (), {"high": 110.0, "low": 90.0, "equilibrium": 100.0, "high_swing_id": 1, "low_swing_id": 2, "ts_start": "t"})()
+
+    def persist_active_range(self, **kwargs):
+        return 1
+
+
+class FakeLiquidityService:
+    def build_candidates(self, **kwargs):
+        return [type("Pool", (), {"side": "buy_side", "pool_type": "prior_high", "price_low": 101.0, "price_high": 101.0, "reference_ids": [1], "created_ts": "t", "meta": {}})()]
+
+    def persist_candidates(self, **kwargs):
+        return 1
+
+
+class FakeSweepService:
+    def detect_sweeps(self, **kwargs):
+        return [type("Sweep", (), {"side_swept": "buy_side", "pool_id": 1, "sweep_high": 102.0, "sweep_low": 99.0, "sweep_ts": "t", "close_back_inside": True, "validation_level": "validated", "status": "confirmed", "meta": {}})()]
+
+    def persist_sweeps(self, **kwargs):
+        return 1
+
+
+class FakeDisplacementService:
+    def detect_displacement(self, **kwargs):
+        return [type("Disp", (), {"direction": "bullish", "start_ts": "t1", "end_ts": "t2", "strength_score": 0.8, "body_ratio": 2.0, "has_fvg": True, "is_valid": True})()]
+
+    def persist_displacement(self, **kwargs):
+        return 1
+
+
+class FakeMSSService:
+    def detect_mss(self, **kwargs):
+        return [type("MSS", (), {"direction": "bullish", "broken_level": 100.0, "reference_swing_id": 1, "displacement_event_id": 2, "accepted": True, "ts": "t", "meta": {}})()]
+
+    def persist_mss(self, **kwargs):
+        return 1
+
+
+class FakeFVGService:
+    def detect_fvg(self, **kwargs):
+        return [type("FVG", (), {"direction": "bullish", "upper": 103.0, "lower": 101.0, "start_ts": "t1", "end_ts": "t2", "fill_pct": 0.0, "status": "open", "related_displacement_id": 2, "meta": {}})()]
+
+    def persist_fvg(self, **kwargs):
+        return 1
+
+    def update_existing_fvgs(self, **kwargs):
+        return 1
+
+
+class FakeBiasService:
+    def build_bias(self, **kwargs):
+        return type("Bias", (), {"daily_bias": "bullish", "confidence": 0.7, "execution_intensity": "high", "narrative_code": "bullish_structure_shift", "draw_side": "buy_side", "range_id": 1, "reason_codes": ["latest_mss"], "snapshot_ts": "t"})()
+
+    def persist_bias(self, **kwargs):
+        return 11
+
+
+class FakeSignalService:
+    def build_signal(self, **kwargs):
+        return type("Signal", (), {"side": "buy", "status": "awaiting_confirmation", "entry_low": 101.0, "entry_high": 103.0, "stop_loss": 99.0, "tp1": 104.0, "tp2": 106.0, "rr_tp1": 1.0, "rr_tp2": 2.0, "session_code": "LONDON", "created_ts": "t", "expires_ts": "t2", "invalidations": [], "evidence": {}, "meta": {"execution_permission": True}})()
+
+    def persist_signal(self, **kwargs):
+        return 1
+
+
+class FakeExecutionService:
+    def create_execution(self, **kwargs):
+        return 99
+
+
+class FakeBacktestService:
+    def run_backtest(self, **kwargs):
+        outcome = type("Outcome", (), {"signal_id": 1, "outcome": "win", "mfe": 3.0, "mae": 1.0, "tp1_hit": True, "tp2_hit": True, "invalidated_before_entry": False, "error_tags": [], "meta": {"signal_side": "buy", "session_codes": ["LONDON"], "weekday": "Monday"}})()
+        return 55, [outcome]
+
+
+class FakePreMarketReportService:
+    def build_report(self, **kwargs):
+        return {"report_type": "pre_market_plan"}
+
+
+class FakeIntradayReportService:
+    def build_report(self, **kwargs):
+        return {"report_type": "intraday_explanation"}
+
+
+class FakePostTradeReviewService:
+    def build_report(self, **kwargs):
+        return {"report_type": "post_trade_review"}
+
+
+class ClosedLoopTests(unittest.TestCase):
+    def test_run_closed_loop_returns_summary_and_reports(self) -> None:
+        result = run_closed_loop(
+            instrument_id=1,
+            timeframe="1m",
+            backtest_limit=10,
+            run_execution=True,
+            dependencies={
+                "session_generator": FakeSessionGenerator(),
+                "swing_service": FakeSwingService(),
+                "range_service": FakeRangeService(),
+                "liquidity_service": FakeLiquidityService(),
+                "sweep_service": FakeSweepService(),
+                "displacement_service": FakeDisplacementService(),
+                "mss_service": FakeMSSService(),
+                "fvg_service": FakeFVGService(),
+                "bias_service": FakeBiasService(),
+                "signal_service": FakeSignalService(),
+                "execution_service": FakeExecutionService(),
+                "backtest_service": FakeBacktestService(),
+                "pre_market_report_service": FakePreMarketReportService(),
+                "intraday_report_service": FakeIntradayReportService(),
+                "post_trade_review_service": FakePostTradeReviewService(),
+                "get_recent_signals": lambda instrument_id, limit: [{"id": 1, "session_code": "LONDON", "status": "awaiting_confirmation", "side": "buy", "invalidations": []}],
+                "get_recent_backtest_summaries": lambda instrument_id, limit: [{"id": 55, "summary": {"total_signals": 1}}],
+            },
+        )
+
+        self.assertEqual(result["writes"]["sessions"], 5)
+        self.assertEqual(result["writes"]["execution_id"], 99)
+        self.assertEqual(result["writes"]["backtest_run_id"], 55)
+        self.assertEqual(result["reports"]["pre_market"]["report_type"], "pre_market_plan")
+        self.assertEqual(result["reports"]["intraday"]["report_type"], "intraday_explanation")
+        self.assertEqual(result["reports"]["post_trade"]["report_type"], "post_trade_review")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/unit/test_api_server.py b/tests/unit/test_api_server.py
new file mode 100644
index 0000000..d566a7c
--- /dev/null
+++ b/tests/unit/test_api_server.py
@@ -0,0 +1,90 @@
+import os
+import unittest
+
+os.environ.setdefault("DATABASE_URL", "postgresql+psycopg://user:pass@localhost:5432/ai_ict_test")
+
+from src.api import route_request
+
+
+class ApiServerRoutingTests(unittest.TestCase):
+    def test_routes_health(self) -> None:
+        status, payload = route_request(
+            "/health",
+            {},
+            dependencies={
+                "health": lambda: {"ok": True},
+                "candles": lambda **kwargs: [],
+                "sessions": lambda **kwargs: [],
+                "signals": lambda **kwargs: [],
+                "backtests": lambda **kwargs: [],
+            },
+        )
+
+        self.assertEqual(status, 200)
+        self.assertEqual(payload, {"ok": True})
+
+    def test_routes_signals_query(self) -> None:
+        status, payload = route_request(
+            "/signals",
+            {"instrument_id": ["1"], "limit": ["2"]},
+            dependencies={
+                "health": lambda: {"ok": True},
+                "candles": lambda **kwargs: [],
+                "sessions": lambda **kwargs: [],
+                "signals": lambda **kwargs: [{"id": 1}, {"id": 2}],
+                "backtests": lambda **kwargs: [],
+            },
+        )
+
+        self.assertEqual(status, 200)
+        self.assertEqual(payload["items"], [{"id": 1}, {"id": 2}])
+
+    def test_routes_backtests_without_instrument_filter(self) -> None:
+        status, payload = route_request(
+            "/backtests",
+            {"limit": ["1"]},
+            dependencies={
+                "health": lambda: {"ok": True},
+                "candles": lambda **kwargs: [],
+                "sessions": lambda **kwargs: [],
+                "signals": lambda **kwargs: [],
+                "backtests": lambda **kwargs: [{"id": 9}],
+            },
+        )
+
+        self.assertEqual(status, 200)
+        self.assertEqual(payload["items"], [{"id": 9}])
+
+    def test_rejects_missing_required_query_param(self) -> None:
+        with self.assertRaises(ValueError):
+            route_request(
+                "/signals",
+                {},
+                dependencies={
+                    "health": lambda: {"ok": True},
+                    "candles": lambda **kwargs: [],
+                    "sessions": lambda **kwargs: [],
+                    "signals": lambda **kwargs: [],
+                    "backtests": lambda **kwargs: [],
+                },
+            )
+
+    def test_returns_not_found_for_unknown_route(self) -> None:
+        status, payload = route_request(
+            "/unknown",
+            {},
+            dependencies={
+                "health": lambda: {"ok": True},
+                "candles": lambda **kwargs: [],
+                "sessions": lambda **kwargs: [],
+                "signals": lambda **kwargs: [],
+                "backtests": lambda **kwargs: [],
+            },
+        )
+
+        self.assertEqual(status, 404)
+        self.assertEqual(payload["error"], "not_found")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/unit/test_backtest_report_service.py b/tests/unit/test_backtest_report_service.py
new file mode 100644
index 0000000..80adef1
--- /dev/null
+++ b/tests/unit/test_backtest_report_service.py
@@ -0,0 +1,98 @@
+import os
+import unittest
+from datetime import datetime, timezone
+
+os.environ.setdefault("DATABASE_URL", "postgresql+psycopg://user:pass@localhost:5432/ai_ict_test")
+
+from src.services.backtest import BacktestOutcome, summarize_backtest_outcomes
+from src.services.reports import BacktestReportService
+
+
+class BacktestSummaryTests(unittest.TestCase):
+    def test_summarizes_outcomes_by_session_side_and_weekday(self) -> None:
+        outcomes = [
+            BacktestOutcome(
+                signal_id=1,
+                outcome="win",
+                mfe=4.0,
+                mae=1.0,
+                tp1_hit=True,
+                tp2_hit=True,
+                invalidated_before_entry=False,
+                error_tags=[],
+                meta={
+                    "signal_side": "buy",
+                    "session_codes": ["LONDON"],
+                    "weekday": "Monday",
+                },
+            ),
+            BacktestOutcome(
+                signal_id=2,
+                outcome="loss",
+                mfe=1.0,
+                mae=3.0,
+                tp1_hit=False,
+                tp2_hit=False,
+                invalidated_before_entry=False,
+                error_tags=["stopped_out"],
+                meta={
+                    "signal_side": "sell",
+                    "session_codes": ["NY_AM"],
+                    "weekday": "Monday",
+                },
+            ),
+            BacktestOutcome(
+                signal_id=3,
+                outcome="missed",
+                mfe=0.0,
+                mae=0.5,
+                tp1_hit=False,
+                tp2_hit=False,
+                invalidated_before_entry=True,
+                error_tags=["entry_not_triggered"],
+                meta={
+                    "signal_side": "buy",
+                    "session_codes": ["LONDON", "NY_AM"],
+                    "weekday": "Tuesday",
+                },
+            ),
+        ]
+
+        summary = summarize_backtest_outcomes(outcomes)
+
+        self.assertEqual(summary["total_signals"], 3)
+        self.assertEqual(summary["outcomes"]["win"], 1)
+        self.assertEqual(summary["outcomes"]["loss"], 1)
+        self.assertEqual(summary["outcomes"]["missed"], 1)
+        self.assertAlmostEqual(summary["win_rate"], 1 / 3)
+        self.assertEqual(summary["by_side"]["buy"]["count"], 2)
+        self.assertEqual(summary["by_side"]["sell"]["losses"], 1)
+        self.assertEqual(summary["by_session"]["LONDON"]["count"], 2)
+        self.assertEqual(summary["by_session"]["NY_AM"]["count"], 2)
+        self.assertEqual(summary["by_weekday"]["Monday"]["count"], 2)
+        self.assertEqual(summary["by_weekday"]["Tuesday"]["misses"], 1)
+
+    def test_report_service_reuses_backtest_summary(self) -> None:
+        outcomes = [
+            BacktestOutcome(
+                signal_id=9,
+                outcome="breakeven",
+                mfe=2.0,
+                mae=1.2,
+                tp1_hit=True,
+                tp2_hit=False,
+                invalidated_before_entry=False,
+                error_tags=[],
+                meta={"signal_side": "buy", "session_codes": ["NY_PM"], "weekday": "Friday"},
+            )
+        ]
+
+        service = BacktestReportService()
+        summary = service.build_summary(outcomes)
+
+        self.assertEqual(summary["by_session"]["NY_PM"]["breakevens"], 1)
+        self.assertEqual(summary["by_side"]["buy"]["count"], 1)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/unit/test_backtest_service.py b/tests/unit/test_backtest_service.py
new file mode 100644
index 0000000..aea523c
--- /dev/null
+++ b/tests/unit/test_backtest_service.py
@@ -0,0 +1,127 @@
+import os
+import unittest
+from datetime import datetime, timezone
+
+os.environ.setdefault("DATABASE_URL", "postgresql+psycopg://user:pass@localhost:5432/ai_ict_test")
+
+from src.services.backtest import BacktestSignal, evaluate_signal_outcome
+from src.repositories.backtest_repository import BacktestRepository
+
+
+class BacktestOutcomeTests(unittest.TestCase):
+    def test_buy_signal_uses_stop_first_when_entry_and_target_are_ambiguous(self) -> None:
+        signal = BacktestSignal(
+            signal_id=1,
+            side="buy",
+            entry_low=100.0,
+            entry_high=101.0,
+            stop_loss=99.0,
+            tp1=102.0,
+            tp2=104.0,
+        )
+        outcome = evaluate_signal_outcome(
+            signal,
+            [{"high": 105.0, "low": 98.0}],
+        )
+
+        self.assertEqual(outcome.outcome, "loss")
+        self.assertFalse(outcome.invalidated_before_entry)
+        self.assertIn("stopped_out", outcome.error_tags)
+        self.assertIn("same_candle_entry_exit_ambiguous", outcome.error_tags)
+        self.assertTrue(outcome.meta["same_candle_ambiguous"])
+        self.assertEqual(outcome.meta["same_candle_priority"], "stop_first")
+
+    def test_untriggered_entry_is_missed_without_invalidating_before_entry(self) -> None:
+        signal = BacktestSignal(
+            signal_id=2,
+            side="sell",
+            entry_low=100.0,
+            entry_high=101.0,
+            stop_loss=102.0,
+            tp1=99.0,
+            tp2=97.0,
+        )
+        outcome = evaluate_signal_outcome(
+            signal,
+            [{"high": 99.5, "low": 98.0}],
+        )
+
+        self.assertEqual(outcome.outcome, "missed")
+        self.assertFalse(outcome.invalidated_before_entry)
+        self.assertIn("entry_not_triggered", outcome.error_tags)
+        self.assertFalse(outcome.meta["entry_triggered"])
+
+    def test_sell_signal_can_reach_tp2(self) -> None:
+        signal = BacktestSignal(
+            signal_id=3,
+            side="sell",
+            entry_low=100.0,
+            entry_high=101.0,
+            stop_loss=103.0,
+            tp1=99.0,
+            tp2=97.0,
+        )
+        outcome = evaluate_signal_outcome(
+            signal,
+            [
+                {"high": 100.5, "low": 99.5},
+                {"high": 100.0, "low": 96.5},
+            ],
+        )
+
+        self.assertEqual(outcome.outcome, "win")
+        self.assertTrue(outcome.tp1_hit)
+        self.assertTrue(outcome.tp2_hit)
+        self.assertEqual(outcome.error_tags, [])
+
+
+class BacktestRepositorySerializationTests(unittest.TestCase):
+    def test_insert_backtest_result_serializes_datetime_in_meta(self) -> None:
+        payload = {
+            "signal_created_ts": datetime(2026, 4, 24, 12, 0, tzinfo=timezone.utc),
+            "weekday": "Friday",
+        }
+
+        class StubSession:
+            def __enter__(self):
+                return self
+
+            def __exit__(self, exc_type, exc, tb):
+                return False
+
+            def execute(self, _sql, params):
+                captured.update(params)
+
+        class StubBegin:
+            def __enter__(self):
+                return StubSession()
+
+            def __exit__(self, exc_type, exc, tb):
+                return False
+
+        captured: dict = {}
+        original_begin = BacktestRepository.insert_backtest_result.__globals__["SessionLocal"].begin
+        try:
+            BacktestRepository.insert_backtest_result.__globals__["SessionLocal"].begin = lambda: StubBegin()
+            repo = BacktestRepository()
+            repo.insert_backtest_result(
+                backtest_run_id=1,
+                signal_id=1,
+                outcome="missed",
+                mfe=0.0,
+                mae=0.0,
+                tp1_hit=False,
+                tp2_hit=False,
+                invalidated_before_entry=False,
+                error_tags=[],
+                meta=payload,
+            )
+        finally:
+            BacktestRepository.insert_backtest_result.__globals__["SessionLocal"].begin = original_begin
+
+        self.assertIn("meta", captured)
+        self.assertIn("2026-04-24 12:00:00+00:00", captured["meta"])
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/unit/test_execution_service.py b/tests/unit/test_execution_service.py
new file mode 100644
index 0000000..0f1bb57
--- /dev/null
+++ b/tests/unit/test_execution_service.py
@@ -0,0 +1,140 @@
+import os
+import unittest
+
+os.environ.setdefault("DATABASE_URL", "postgresql+psycopg://user:pass@localhost:5432/ai_ict_test")
+
+from src.services.execution import compute_entry_price, evaluate_execution_decision, trade_execution_matches_decision
+
+
+class ExecutionDecisionTests(unittest.TestCase):
+    def test_allows_paper_execution_for_valid_signal(self) -> None:
+        decision = evaluate_execution_decision(
+            signal={
+                "side": "buy",
+                "status": "awaiting_confirmation",
+                "entry_type": "limit",
+                "entry_low": 100.0,
+                "entry_high": 101.0,
+                "stop_loss": 99.0,
+                "tp1": 102.0,
+                "tp2": 104.0,
+                "session_code": "LONDON",
+                "execution_intensity": "medium",
+                "meta": {"execution_permission": True},
+            },
+            execution_mode="paper",
+            account_equity=10000.0,
+            risk_pct=0.01,
+        )
+
+        self.assertTrue(decision.allowed)
+        self.assertEqual(decision.status, "open")
+        self.assertEqual(decision.execution_mode, "paper")
+        self.assertGreater(decision.size, 0.0)
+        self.assertEqual(decision.reasons, [])
+
+    def test_semi_auto_uses_pending_status_when_allowed(self) -> None:
+        decision = evaluate_execution_decision(
+            signal={
+                "side": "sell",
+                "status": "awaiting_confirmation",
+                "entry_type": "limit",
+                "entry_low": 100.0,
+                "entry_high": 101.0,
+                "stop_loss": 102.0,
+                "tp1": 99.0,
+                "tp2": 97.0,
+                "session_code": "NY_AM",
+                "execution_intensity": "high",
+                "meta": {"execution_permission": True},
+            },
+            execution_mode="semi_auto",
+            account_equity=12000.0,
+            risk_pct=0.01,
+        )
+
+        self.assertTrue(decision.allowed)
+        self.assertEqual(decision.status, "pending")
+        self.assertEqual(decision.execution_mode, "semi_auto")
+
+    def test_rejects_signal_without_stop_or_allowed_session(self) -> None:
+        decision = evaluate_execution_decision(
+            signal={
+                "side": "buy",
+                "status": "awaiting_context",
+                "entry_type": "limit",
+                "entry_low": 100.0,
+                "entry_high": 101.0,
+                "stop_loss": None,
+                "tp1": 102.0,
+                "tp2": 104.0,
+                "session_code": "ASIA",
+                "execution_intensity": "low",
+                "meta": {"execution_permission": False},
+            },
+            execution_mode="paper",
+            account_equity=10000.0,
+            risk_pct=0.03,
+        )
+
+        self.assertFalse(decision.allowed)
+        self.assertEqual(decision.status, "rejected")
+        self.assertIn("missing_stop_loss", decision.reasons)
+        self.assertIn("session_not_allowed", decision.reasons)
+        self.assertIn("signal_not_executable", decision.reasons)
+        self.assertIn("signal_execution_permission_denied", decision.reasons)
+        self.assertIn("bias_execution_intensity_low", decision.reasons)
+        self.assertIn("risk_pct_out_of_bounds", decision.reasons)
+
+
+class ExecutionPricingTests(unittest.TestCase):
+    def test_entry_price_uses_midpoint_when_range_exists(self) -> None:
+        self.assertEqual(
+            compute_entry_price({"entry_low": 100.0, "entry_high": 102.0}),
+            101.0,
+        )
+
+    def test_entry_price_falls_back_to_single_bound(self) -> None:
+        self.assertEqual(compute_entry_price({"entry_low": 99.5, "entry_high": None}), 99.5)
+
+
+class ExecutionIdempotencyTests(unittest.TestCase):
+    def test_detects_equivalent_open_execution(self) -> None:
+        decision = evaluate_execution_decision(
+            signal={
+                "side": "buy",
+                "status": "awaiting_confirmation",
+                "entry_type": "limit",
+                "entry_low": 100.0,
+                "entry_high": 101.0,
+                "stop_loss": 99.0,
+                "tp1": 102.0,
+                "tp2": 104.0,
+                "session_code": "LONDON",
+                "execution_intensity": "medium",
+                "daily_bias": "bullish",
+                "draw_side": "buy_side",
+                "meta": {"execution_permission": True},
+            },
+            execution_mode="paper",
+            account_equity=10000.0,
+            risk_pct=0.01,
+        )
+        existing = {
+            "execution_mode": "paper",
+            "status": "open",
+            "side": "buy",
+            "entry_price": decision.entry_price,
+            "stop_loss": decision.meta["stop_loss"],
+            "take_profit_1": decision.meta["tp1"],
+            "take_profit_2": decision.meta["tp2"],
+            "size": decision.size,
+            "risk_pct": decision.risk_pct,
+            "meta": decision.meta,
+        }
+
+        self.assertTrue(trade_execution_matches_decision(existing, decision))
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/unit/test_fvg_service.py b/tests/unit/test_fvg_service.py
new file mode 100644
index 0000000..df3244a
--- /dev/null
+++ b/tests/unit/test_fvg_service.py
@@ -0,0 +1,62 @@
+from datetime import datetime, timezone
+import os
+import unittest
+
+os.environ.setdefault("DATABASE_URL", "postgresql+psycopg://user:pass@localhost:5432/ai_ict_test")
+
+from src.services.fvg import compute_fvg_fill_state
+
+
+class FVGStateTests(unittest.TestCase):
+    def test_marks_fvg_touched_when_partially_filled(self) -> None:
+        fill_pct, status, meta = compute_fvg_fill_state(
+            direction="bullish",
+            upper=105.0,
+            lower=100.0,
+            candles=[{"ts_open": 1, "high": 106.0, "low": 104.0, "close": 105.5}],
+        )
+
+        self.assertEqual(status, "touched")
+        self.assertAlmostEqual(fill_pct, 0.2)
+        self.assertEqual(meta["first_touch_ts"], 1)
+        self.assertFalse(meta["invalidated"])
+
+    def test_normalizes_datetime_touch_timestamp_for_meta(self) -> None:
+        fill_pct, status, meta = compute_fvg_fill_state(
+            direction="bullish",
+            upper=105.0,
+            lower=100.0,
+            candles=[{"ts_open": datetime(2026, 4, 24, 12, 0, tzinfo=timezone.utc), "high": 106.0, "low": 104.0, "close": 105.5}],
+        )
+
+        self.assertEqual(status, "touched")
+        self.assertAlmostEqual(fill_pct, 0.2)
+        self.assertEqual(meta["first_touch_ts"], "2026-04-24T12:00:00+00:00")
+
+    def test_marks_fvg_mitigated_when_fully_filled(self) -> None:
+        fill_pct, status, meta = compute_fvg_fill_state(
+            direction="bearish",
+            upper=110.0,
+            lower=100.0,
+            candles=[{"ts_open": 1, "high": 111.0, "low": 99.0, "close": 101.0}],
+        )
+
+        self.assertEqual(status, "mitigated")
+        self.assertEqual(fill_pct, 1.0)
+        self.assertFalse(meta["invalidated"])
+
+    def test_marks_fvg_invalidated_when_structure_breaks_through_zone(self) -> None:
+        fill_pct, status, meta = compute_fvg_fill_state(
+            direction="bullish",
+            upper=105.0,
+            lower=100.0,
+            candles=[{"ts_open": 1, "high": 103.0, "low": 99.0, "close": 99.5}],
+        )
+
+        self.assertEqual(status, "invalidated")
+        self.assertGreater(fill_pct, 0.0)
+        self.assertTrue(meta["invalidated"])
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/unit/test_liquidity_pool_service.py b/tests/unit/test_liquidity_pool_service.py
new file mode 100644
index 0000000..dec7db2
--- /dev/null
+++ b/tests/unit/test_liquidity_pool_service.py
@@ -0,0 +1,126 @@
+from decimal import Decimal
+import os
+import unittest
+
+os.environ.setdefault("DATABASE_URL", "postgresql+psycopg://user:pass@localhost:5432/ai_ict_test")
+
+from src.services.liquidity import LiquidityPoolCandidate, build_equal_pool_candidates, dedupe_candidates
+
+
+class EqualLiquidityPoolTests(unittest.TestCase):
+    def test_groups_equal_highs_within_threshold(self) -> None:
+        swings = [
+            {"id": 1, "kind": "swing_high", "price": Decimal("100.00"), "ts": "2026-04-21T00:00:00Z"},
+            {"id": 2, "kind": "swing_high", "price": Decimal("100.04"), "ts": "2026-04-21T00:05:00Z"},
+            {"id": 3, "kind": "swing_high", "price": Decimal("102.00"), "ts": "2026-04-21T00:10:00Z"},
+            {"id": 4, "kind": "swing_low", "price": Decimal("99.00"), "ts": "2026-04-21T00:15:00Z"},
+        ]
+
+        candidates = build_equal_pool_candidates(
+            swings=swings,
+            kind="swing_high",
+            side="buy_side",
+            pool_type="equal_highs",
+            threshold_pct=Decimal("0.0005"),
+        )
+
+        self.assertEqual(len(candidates), 1)
+        self.assertEqual(candidates[0].pool_type, "equal_highs")
+        self.assertEqual(candidates[0].price_low, Decimal("100.00"))
+        self.assertEqual(candidates[0].price_high, Decimal("100.04"))
+        self.assertEqual(candidates[0].reference_ids, [1, 2])
+        self.assertEqual(candidates[0].meta["swing_count"], 2)
+
+    def test_ignores_single_swing_clusters(self) -> None:
+        swings = [
+            {"id": 1, "kind": "swing_low", "price": Decimal("100.00"), "ts": "2026-04-21T00:00:00Z"},
+            {"id": 2, "kind": "swing_low", "price": Decimal("100.20"), "ts": "2026-04-21T00:05:00Z"},
+        ]
+
+        candidates = build_equal_pool_candidates(
+            swings=swings,
+            kind="swing_low",
+            side="sell_side",
+            pool_type="equal_lows",
+            threshold_pct=Decimal("0.0005"),
+        )
+
+        self.assertEqual(candidates, [])
+
+
+class LiquidityMergeTests(unittest.TestCase):
+    def test_merges_overlapping_same_side_pools(self) -> None:
+        candidates = [
+            LiquidityPoolCandidate(
+                side="buy_side",
+                pool_type="prior_high",
+                price_low=Decimal("100.00"),
+                price_high=Decimal("100.00"),
+                reference_ids=[1],
+                created_ts="2026-04-21T00:00:00Z",
+                meta={},
+            ),
+            LiquidityPoolCandidate(
+                side="buy_side",
+                pool_type="equal_highs",
+                price_low=Decimal("99.98"),
+                price_high=Decimal("100.02"),
+                reference_ids=[2, 3],
+                created_ts="2026-04-21T00:05:00Z",
+                meta={"source": "swing_cluster"},
+            ),
+        ]
+
+        deduped = dedupe_candidates(candidates)
+
+        self.assertEqual(len(deduped), 1)
+        self.assertEqual(deduped[0].price_low, Decimal("99.98"))
+        self.assertEqual(deduped[0].price_high, Decimal("100.02"))
+        self.assertEqual(deduped[0].reference_ids, [1, 2, 3])
+        self.assertIn("prior_high", deduped[0].meta["merged_pool_types"])
+        self.assertIn("equal_highs", deduped[0].meta["merged_pool_types"])
+
+    def test_keeps_distinct_sides_separate(self) -> None:
+        candidates = [
+            LiquidityPoolCandidate(
+                side="buy_side",
+                pool_type="session_high",
+                price_low=Decimal("100.00"),
+                price_high=Decimal("100.00"),
+                reference_ids=[1],
+                created_ts="2026-04-21T00:00:00Z",
+                meta={},
+            ),
+            LiquidityPoolCandidate(
+                side="sell_side",
+                pool_type="session_low",
+                price_low=Decimal("100.00"),
+                price_high=Decimal("100.00"),
+                reference_ids=[2],
+                created_ts="2026-04-21T00:05:00Z",
+                meta={},
+            ),
+        ]
+
+        deduped = dedupe_candidates(candidates)
+
+        self.assertEqual(len(deduped), 2)
+
+    def test_removes_exact_duplicates_before_merge(self) -> None:
+        candidate = LiquidityPoolCandidate(
+            side="sell_side",
+            pool_type="prior_low",
+            price_low=Decimal("95.00"),
+            price_high=Decimal("95.00"),
+            reference_ids=[5],
+            created_ts="2026-04-21T00:00:00Z",
+            meta={},
+        )
+
+        deduped = dedupe_candidates([candidate, candidate])
+
+        self.assertEqual(len(deduped), 1)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/unit/test_mss_service.py b/tests/unit/test_mss_service.py
new file mode 100644
index 0000000..7e98247
--- /dev/null
+++ b/tests/unit/test_mss_service.py
@@ -0,0 +1,66 @@
+import os
+import unittest
+
+os.environ.setdefault("DATABASE_URL", "postgresql+psycopg://user:pass@localhost:5432/ai_ict_test")
+
+from src.services.structure import detect_mss_candidates, evaluate_mss_acceptance
+
+
+class MSSAcceptanceTests(unittest.TestCase):
+    def test_bullish_acceptance_requires_retest_and_hold(self) -> None:
+        result = evaluate_mss_acceptance(
+            direction="bullish",
+            broken_level=100.0,
+            candles=[
+                {"low": 99.8, "high": 101.2, "close": 100.4},
+                {"low": 100.1, "high": 102.0, "close": 101.7},
+            ],
+        )
+
+        self.assertTrue(result["accepted"])
+        self.assertTrue(result["has_retest"])
+        self.assertTrue(result["held_boundary"])
+        self.assertFalse(result["reclaimed_old_control"])
+
+    def test_bearish_acceptance_fails_when_close_reclaims_old_control(self) -> None:
+        result = evaluate_mss_acceptance(
+            direction="bearish",
+            broken_level=100.0,
+            candles=[
+                {"low": 98.5, "high": 100.2, "close": 99.7},
+                {"low": 99.2, "high": 101.0, "close": 100.5},
+            ],
+        )
+
+        self.assertFalse(result["accepted"])
+        self.assertTrue(result["has_retest"])
+        self.assertFalse(result["held_boundary"])
+        self.assertTrue(result["reclaimed_old_control"])
+
+    def test_detect_mss_candidates_only_returns_confirmed_acceptance(self) -> None:
+        swings = [
+            {"id": 1, "kind": "swing_high", "price": 100.0, "ts": 2},
+            {"id": 2, "kind": "swing_low", "price": 95.0, "ts": 1},
+        ]
+        displacements = [
+            {"id": 9, "direction": "bullish", "end_ts": 5, "is_valid": True},
+        ]
+        candles = [
+            {"ts_open": 1, "ts_close": 2, "open": 97.0, "high": 100.0, "low": 96.0, "close": 98.0},
+            {"ts_open": 2, "ts_close": 3, "open": 98.0, "high": 99.0, "low": 95.0, "close": 96.0},
+            {"ts_open": 3, "ts_close": 4, "open": 96.0, "high": 102.0, "low": 95.5, "close": 101.3},
+            {"ts_open": 4, "ts_close": 5, "open": 101.3, "high": 103.0, "low": 100.5, "close": 102.2},
+            {"ts_open": 5, "ts_close": 6, "open": 102.2, "high": 102.8, "low": 99.9, "close": 100.4},
+            {"ts_open": 6, "ts_close": 7, "open": 100.4, "high": 103.5, "low": 100.2, "close": 103.0},
+        ]
+
+        candidates = detect_mss_candidates(swings=swings, displacements=displacements, candles=candles, acceptance_window=3)
+
+        self.assertEqual(len(candidates), 1)
+        self.assertTrue(candidates[0].accepted)
+        self.assertEqual(candidates[0].direction, "bullish")
+        self.assertEqual(candidates[0].meta["retest_count"], 1)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/unit/test_report_services.py b/tests/unit/test_report_services.py
new file mode 100644
index 0000000..76d4920
--- /dev/null
+++ b/tests/unit/test_report_services.py
@@ -0,0 +1,61 @@
+import os
+import unittest
+
+os.environ.setdefault("DATABASE_URL", "postgresql+psycopg://user:pass@localhost:5432/ai_ict_test")
+
+from src.services.reports import IntradayReportService, PostTradeReviewService, PreMarketReportService
+
+
+class PreMarketReportTests(unittest.TestCase):
+    def test_builds_pre_market_plan(self) -> None:
+        report = PreMarketReportService().build_report(
+            bias_snapshot={
+                "daily_bias": "bullish",
+                "draw_side": "buy_side",
+                "execution_intensity": "high",
+                "reason_codes": ["latest_mss", "active_range_available"],
+            },
+            dealing_range={"id": 1, "high": 110.0, "low": 90.0, "equilibrium": 100.0},
+            current_price=98.0,
+            session_code="LONDON",
+        )
+
+        self.assertEqual(report["report_type"], "pre_market_plan")
+        self.assertEqual(report["daily_bias"], "bullish")
+        self.assertEqual(report["working_range"]["location"], "discount")
+        self.assertTrue(report["execution_permission"])
+
+
+class IntradayReportTests(unittest.TestCase):
+    def test_builds_intraday_explanation_and_invalidations(self) -> None:
+        report = IntradayReportService().build_report(
+            sweep_event={"side_swept": "buy_side", "close_back_inside": True},
+            structure_event={"event_type": "MSS", "direction": "bearish", "accepted": True},
+            fvg_zone={"direction": "bearish", "status": "mitigated", "fill_pct": 1.0, "meta": {}},
+            trade_signal={"status": "awaiting_confirmation", "side": "sell", "session_code": "NY_AM", "invalidations": ["session_mismatch"]},
+        )
+
+        self.assertEqual(report["report_type"], "intraday_explanation")
+        self.assertFalse(report["signal"]["is_valid"])
+        self.assertIn("fvg_no_longer_actionable", report["invalidations"])
+        self.assertIn("session_mismatch", report["invalidations"])
+
+
+class PostTradeReviewTests(unittest.TestCase):
+    def test_builds_post_trade_review(self) -> None:
+        report = PostTradeReviewService().build_report(
+            trade_execution={"status": "rejected", "meta": {"risk_checks": ["session_not_allowed"]}},
+            trade_signal={"status": "awaiting_context", "invalidations": ["session_mismatch"]},
+            backtest_result={"outcome": "loss", "invalidated_before_entry": False, "error_tags": ["same_candle_entry_exit_ambiguous"]},
+        )
+
+        self.assertEqual(report["report_type"], "post_trade_review")
+        self.assertFalse(report["rule_aligned"])
+        self.assertIn("execution_rejected", report["error_types"])
+        self.assertIn("session_not_allowed", report["error_types"])
+        self.assertIn("inspect_stop_and_structure_context", report["improvement_notes"])
+        self.assertIn("review_same_candle_ambiguity_cases", report["improvement_notes"])
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/unit/test_signal_service.py b/tests/unit/test_signal_service.py
new file mode 100644
index 0000000..996c6c4
--- /dev/null
+++ b/tests/unit/test_signal_service.py
@@ -0,0 +1,112 @@
+import os
+import unittest
+
+os.environ.setdefault("DATABASE_URL", "postgresql+psycopg://user:pass@localhost:5432/ai_ict_test")
+
+from src.services.signals import classify_session_for_signal, trade_signal_matches_candidate, validate_signal_context
+from src.services.signals.signal_service import SignalCandidate
+
+
+class SignalSessionFilterTests(unittest.TestCase):
+    def test_london_allows_confirmation(self) -> None:
+        decision = classify_session_for_signal("LONDON")
+
+        self.assertEqual(decision["status"], "awaiting_confirmation")
+        self.assertTrue(decision["execution_permission"])
+        self.assertEqual(decision["reason"], "allowed_session")
+
+    def test_lunch_is_downgraded_to_context(self) -> None:
+        decision = classify_session_for_signal("NY_LUNCH")
+
+        self.assertEqual(decision["status"], "awaiting_context")
+        self.assertFalse(decision["execution_permission"])
+        self.assertEqual(decision["reason"], "observation_or_management_session")
+
+    def test_missing_session_is_off_hours(self) -> None:
+        decision = classify_session_for_signal(None)
+
+        self.assertEqual(decision["status"], "awaiting_context")
+        self.assertFalse(decision["execution_permission"])
+        self.assertEqual(decision["reason"], "off_hours")
+
+
+class SignalStructureAlignmentTests(unittest.TestCase):
+    def test_rejects_unaccepted_mss(self) -> None:
+        result = validate_signal_context(
+            bias={"draw_side": "buy_side"},
+            fvg={"direction": "bullish", "status": "open", "meta": {}},
+            mss={"direction": "bullish", "accepted": False},
+        )
+
+        self.assertFalse(result["is_actionable"])
+        self.assertEqual(result["reason"], "mss_not_accepted")
+
+    def test_rejects_mitigated_or_invalidated_fvg(self) -> None:
+        mitigated = validate_signal_context(
+            bias={"draw_side": "buy_side"},
+            fvg={"direction": "bullish", "status": "mitigated", "meta": {}},
+            mss={"direction": "bullish", "accepted": True},
+        )
+        invalidated = validate_signal_context(
+            bias={"draw_side": "buy_side"},
+            fvg={"direction": "bullish", "status": "touched", "meta": {"invalidated": True}},
+            mss={"direction": "bullish", "accepted": True},
+        )
+
+        self.assertEqual(mitigated["reason"], "fvg_not_actionable")
+        self.assertEqual(invalidated["reason"], "fvg_invalidated")
+
+    def test_accepts_aligned_structure(self) -> None:
+        result = validate_signal_context(
+            bias={"draw_side": "sell_side"},
+            fvg={"direction": "bearish", "status": "touched", "meta": {}, "related_displacement_id": 7},
+            mss={"direction": "bearish", "accepted": True, "displacement_event_id": 7},
+        )
+
+        self.assertTrue(result["is_actionable"])
+        self.assertEqual(result["side"], "sell")
+        self.assertEqual(result["reason"], "aligned")
+
+
+class SignalIdempotencyTests(unittest.TestCase):
+    def test_detects_equivalent_trade_signal(self) -> None:
+        candidate = SignalCandidate(
+            side="buy",
+            status="awaiting_confirmation",
+            entry_low=100.0,
+            entry_high=101.0,
+            stop_loss=99.0,
+            tp1=102.0,
+            tp2=104.0,
+            rr_tp1=1.0,
+            rr_tp2=2.0,
+            session_code="LONDON",
+            created_ts="now",
+            expires_ts="later",
+            invalidations=["mss invalidated"],
+            evidence={"bias_snapshot_id": 1, "fvg_id": 2, "mss_id": 3},
+            meta={"execution_permission": True},
+        )
+        latest = {
+            "side": "buy",
+            "status": "awaiting_confirmation",
+            "bias_snapshot_id": 9,
+            "entry_type": "limit",
+            "entry_low": 100.0,
+            "entry_high": 101.0,
+            "stop_loss": 99.0,
+            "tp1": 102.0,
+            "tp2": 104.0,
+            "rr_tp1": 1.0,
+            "rr_tp2": 2.0,
+            "session_code": "LONDON",
+            "invalidations": ["mss invalidated"],
+            "evidence": {"bias_snapshot_id": 1, "fvg_id": 2, "mss_id": 3},
+            "meta": {"execution_permission": True},
+        }
+
+        self.assertTrue(trade_signal_matches_candidate(latest, candidate, bias_snapshot_id=9))
+
+
+if __name__ == "__main__":
+    unittest.main()