跳轉到

重構指南

這一頁不是教你怎麼「改幾個檔案」，而是站在架構層面說：

  • 如果今天要重做這個系統
  • 哪些概念一定要保留
  • 哪些邊界應該先畫清楚
  • 哪些是目前的技術債

先講結論

如果要重構這個專案，最好的思路不是從 API 開始，而是從核心模型開始。

建議依序拆解：

  1. 市場資料模型
  2. 回測執行模型
  3. 策略介面
  4. 參數系統
  5. 分析系統
  6. 任務系統
  7. API / UI

你真正要保留的核心概念

1. 資料核心

必須保留：

  • OHLCV
  • DataFeed
  • IndicatorStore

這三者是策略與回測引擎的共同語言。

2. 執行核心

必須保留：

  • BacktestBot
  • Broker
  • Strategy

可簡化成：

DataFeed -> Strategy -> Orders -> Broker -> State

3. 結果核心

必須保留：

  • state
  • order history
  • analysis metrics

因為：

  • 一般回測
  • 最佳化
  • 訓練
  • 報表

其實都圍繞這些結果資料。

現在的技術債在哪裡

1. app.py 太胖

它現在同時做：

  • API
  • 全域狀態
  • 回測 orchestration
  • task 管理
  • 訓練管理
  • 備註管理

重構時應優先拆成：

  • services/backtest_service.py
  • services/optimization_service.py
  • services/training_service.py
  • services/notes_service.py

2. 全域狀態過多

目前有：

  • ticker
  • current_strategy_name
  • current_timeframe_minutes
  • current_start_time
  • current_end_time

這對單人操作很方便，但對：

  • 測試
  • 多使用者
  • 多 session
  • 正式部署

都不太友善。

重構時建議：

  • 把這些改成 request-scoped input
  • 或做成可持久化的 user/session state

3. 舊路徑與新路徑共存

目前存在：

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

若要重構，應先決定：

  • 哪條是正式主路
  • 哪條是待淘汰 / 待重寫

4. migration 不正式

正式重構後，建議：

  • 導入 Alembic
  • 所有 schema 變更版本化

如果今天重做，我建議的目錄結構

src/
  domain/
    market_data.py
    strategy.py
    broker.py
    backtest.py
    analysis.py

  infrastructure/
    quote/
      shioaji_provider.py
      databento_provider.py
    db/
      models.py
      repository.py
      migrations/

  application/
    backtest_service.py
    optimization_service.py
    training_service.py
    notes_service.py

  interfaces/
    api/
      routes/
      schemas/

Quote Adapter 應該先正式化

目前 quote adapter 是隱性規格。
重構時建議第一批抽象出：

  • QuoteProvider
  • get_data(ticker, start_time, end_time) -> pd.DataFrame

並明確規範 DataFrame 欄位。

策略系統應該拆三層

以 Bollinger 系列來說，重構時建議拆成：

1. 指標層

  • 布林帶計算
  • TEMA
  • slope
  • ATR

2. 訊號狀態機層

  • 做多 / 做空型態形成
  • 進場條件
  • 觀望 / squeeze
  • 截斷與重置

3. 交易決策層

  • 開倉
  • 平倉
  • 反手
  • 止損
  • 中線停利 / 止損

這樣會比把所有邏輯都塞在單一策略 class 中更容易測試。

參數系統的重構原則

現在已經做對的一件事是：

  • 參數依 (ticker, timeframe, strategy_name) 隔離

未來重構時，應保留這個原則。

可以再加強的地方是：

  • 參數 schema 與實際策略欄位自動對齊
  • 每個策略獨立 schema
  • 參數版本化

任務系統的重構原則

最佳化任務目前很實用，但仍是同步執行 API。

若要正式化，建議：

  • API 只負責建立任務
  • 真正執行改成 background worker
  • 進度與結果查詢保留

也就是拆成：

  • task create
  • task enqueue
  • task execute
  • task query

什麼是這個系統最值得保留的

如果你最後真的整套重做，最值得保留的是：

  • 明確的策略註冊中心
  • DataFeed / OHLCV 的資料核心
  • 參數依策略隔離
  • 最佳化結果查詢與分頁
  • 前端可用的策略清單控制

什麼是最值得優先重寫的

如果只能先重寫一部分，我會排序：

  1. app.py service 化
  2. quote adapter 正式 interface 化
  3. multi_params 與主流程統一策略維度
  4. migration 正式化
  5. 啟動副作用移除

最後建議

若你的目標是「任何人看完文件都能重做出來」，那最重要的不是一開始就把每支 API 記滿，而是把以下三件事講清楚：

  1. 資料怎麼流
  2. 狀態怎麼變
  3. 模組邊界在哪裡

這份文件站目前已經把這三件事作為主軸。
之後若要再往更完整的規格文件前進，最值得補的是：

  • 策略逐條邏輯規格
  • API request/response 全量範例
  • DB schema 與 migration 版本史