跳轉到

Typed Data Interfaces Migration

本文整理 FinLab 交易資料結構從隱式 dict/list 轉為正式 typed 介面的使用方式，包含相容策略與 deprecation policy。

1. 新增的正式資料結構

可由 finlab.schemas 匯入：

  • PositionEntry
  • OrderEntry
  • StrategyPositionData
  • PortfolioConfigData
  • PortfolioData

以上 dataclass 均提供 from_dict() / to_dict()。

2. Position typed API

  • Position.from_entries(entries)
  • Position.to_entries()

說明： - 舊有 from_list() / to_list() 仍可使用。 - typed 與 dict 介面可並存，方便逐步遷移。

3. OrderExecutor typed API

  • OrderExecutor.generate_orders(..., as_entries=False, quantity_type='decimal')
  • OrderExecutor.generate_order_entries(..., quantity_type='decimal')

quantity_type 支援： - decimal（預設） - float - string

預設行為維持不變：generate_orders() 仍回傳 list[dict]。

4. PortfolioSyncManager typed API

  • get_data(typed=False)
  • set_data(data, typed=False)
  • get_data_typed()
  • set_data_typed(data)

說明： - self.data 內部儲存格式仍為既有 dict shape。 - typed getter/setter 只在邊界做轉換，確保既有序列化路徑（to_path / to_local / to_cloud）相容。

5. symbol / stock_id 相容與未來政策

目前政策： - symbol 為 canonical 欄位。 - stock_id 仍保留為向後相容 alias。 - 兩欄同時存在且值衝突時，會拋出錯誤（避免資料歧義）。

建議： - 新程式碼請優先使用 symbol。 - 第三方整合請保留 stock_id 讀取相容，直到 major 版本公告移除時程。

規劃（暫定）： - 1.x: stock_id fully supported (alias mode) - 2.x (not earlier than): 再評估是否改為 warning-only 或移除 alias

6. Report Typed API

CloudReport 提供 typed 介面存取策略報告：

  • CloudReport.from_dict(report_dict, execution_dict) — 從 dict 建立
  • CloudReport.position_info2() — 取得持倉資訊
  • CloudReport.position_schedulers — 排程與權重

ReportExecution 封裝回測執行設定：

  • ReportExecution.from_dict(d) / .to_dict()
  • .weights — 當前持倉權重（pd.Series）
  • .next_weights — 下期持倉權重
  • .actions — 停損停利等動作
  • .config — 回測設定（resample、stopLoss、takeProfit 等）
  • .current_rebalance_date / .next_rebalance_date — 換倉日期

7. 遷移建議順序

  1. 先把資料模型改為 finlab.schemas dataclass。
  2. 逐步切換為 typed API（from_entries / generate_order_entries / get_data_typed）。
  3. 保留 dict fallback，直到上層 UI/DB/排程全數完成遷移。