跳轉到

系統架構

本專案目前是一個單一後端入口 + 多模組回測核心 + 外部資料 adapter + DB repository 的結構。

架構總覽

flowchart LR
    UI[前端 / 文件 / 儀表板] --> API[FastAPI app.py]
    API --> Quote[Quote Adapters]
    API --> PM[ParameterManager]
    API --> DB[Repository / SQLAlchemy]
    API --> Core[Backtest Core]
    Core --> Strategy[Strategies]
    Core --> Broker[FuturesBroker]
    Core --> Analysis[Analytics]

主要模組

app.py

這是目前的後端 composition root，也就是：

  • API 路由入口
  • 全域狀態容器
  • quote adapter 注入點
  • 回測 orchestration 中心
  • 最佳化任務與訓練功能的整合入口

換句話說，app.py 不只是 router，它同時承擔了：

  • application service
  • runtime state
  • 回測流程協調器

src/strategy/

策略實作與策略註冊中心：

  • base_strategy.py
  • strategy_registry.py
  • bollinger_atr_strategy.py
  • bollinger_atr_strategy_v2.py
  • bollinger_atr_strategy_v3.py
  • bollinger_atr_strategy_v4.py
  • bollinger_atr_strategy_opt.py
  • ma_cross_strategy.py

這一層決定：

  • 使用哪個策略類別
  • 該策略需要什麼參數
  • 每根 K 棒來時如何更新訊號

src/trade/

回測核心：

  • tradebot.py
  • broker.py

其中：

  • BacktestBot 管理回測主迴圈
  • FuturesBroker 管理持倉、保證金、成交與損益

src/type.py

底層型別：

  • OHLCV
  • DataFeed
  • IndicatorStore

它定義了策略和回測引擎共同依賴的資料結構。

src/quote/

外部資料來源 adapter：

  • shioaji_quote.py
  • databento_quote.py

這些 adapter 的責任是把外部 API 的資料轉成內部可接受的 DataFrame 結構，再交給資料流工具轉為 DataFeed。

src/datafeed/

utils.py 是 adapter 與回測核心的橋樑：

  • aggregate_dataframe()
  • data_feed_from_dataframe()
  • data_feed_from_dataframe_with_timeframe()

src/api/db/

資料庫層：

  • config.py：決定 SQLite / PostgreSQL
  • engine.py：建立 SQLAlchemy engine / session
  • orm_models.py：資料表結構
  • repository.py：DB access 封裝

src/analytics/

分析層：

  • backtest_analysis.py
  • universal_analyzer.py

前者偏 API / 最佳化共用的輕量統計，後者偏離線分析與報表。

目前的資料持久化邊界

記憶體

  • CacheManager.cache
  • 一般回測 state cache
  • 多區段回測 cache

JSON 檔

  • backtest_history.json

DB

  • strategy_params
  • training_param_ranges
  • trading_notes
  • backtest_segments
  • optimization_tasks
  • optimization_saved_results

重要架構觀察

1. app.py 偏胖

目前很多邏輯都還在 app.py：

  • 全域狀態
  • API
  • 回測 orchestration
  • 最佳化執行
  • 訓練 / 備註 / 歷史紀錄

如果未來要重構，第一步通常會是把這些流程拆成 service layer。

2. 一般回測與舊回測腳本共存

目前專案內有兩條路徑：

  • 新主流程：app.py + strategy_registry + param_manager
  • 舊流程：simple_backtest.py + multi_period_backtest.py

因此文件與重構時要分清楚：

  • 哪些 API 已 strategy-aware
  • 哪些舊腳本仍是歷史包袱

3. 文件要以實作為準

專案內已有部分舊 Markdown 文件，但其中有一些內容已與現況不同。
這份文件站以目前程式碼為主要規格來源。