教學

Typed 資料結構遷移

本頁內容8

FinLab 的交易資料結構正從隱式的 dict／list 改為正式的 typed 介面。這一頁列出新的資料結構與 API、和舊寫法的相容策略，以及 deprecation policy。舊介面都還能用，typed 與 dict 介面可以並存，所以可以逐步遷移。

遷移步驟

把資料模型改為 `finlab.schemas` 的 dataclass

持倉、委託、投資組合改用下方的新資料結構。

逐步切換到 typed API

例如 from_entries、generate_order_entries、get_data_typed，一次換一個地方。

保留 dict fallback

上層的 UI、DB、排程全數完成遷移前，先保留 dict 介面。

新的資料結構

以下 dataclass 都可由 finlab.schemas 匯入，並且都提供 from_dict()／to_dict()：

from finlab.schemas import (
    OrderEntry,
    PortfolioConfigData,
    PortfolioData,
    PositionEntry,
    StrategyPositionData,
)

持倉：Position

方法	說明
`Position.from_entries(entries)`	從 entry 清單建立 `Position`
`Position.to_entries()`	轉成 entry 清單

from finlab.online.order_executor import Position

position = Position({'2330': 1, '1101': 1})

entries = position.to_entries()
position = Position.from_entries(entries)

rows = position.to_list()  # 舊介面仍可使用

舊有的 from_list()／to_list() 仍可使用；typed 與 dict 介面可並存，方便逐步遷移。

產生委託：OrderExecutor

方法	說明
`OrderExecutor.generate_orders(..., as_entries=False, quantity_type='decimal')`	預設行為不變，仍回傳 `list[dict]`
`OrderExecutor.generate_order_entries(..., quantity_type='decimal')`	回傳 typed entry

quantity_type 支援 decimal（預設）、float、string。

投資組合同步：PortfolioSyncManager

方法	說明
`get_data(typed=False)`	讀取資料
`set_data(data, typed=False)`	寫入資料
`get_data_typed()`	讀取 typed 資料
`set_data_typed(data)`	寫入 typed 資料

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

策略報告：CloudReport 與 ReportExecution

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

成員	說明
`CloudReport.from_dict(report_dict, execution_dict)`	從 dict 建立
`CloudReport.position_info2()`	取得持倉資訊
`CloudReport.position_schedulers`	排程與權重

ReportExecution 封裝回測的執行設定：

成員	說明
`ReportExecution.from_dict(d)`／`.to_dict()`	與 dict 互轉
`.weights`	當前持倉權重（`pd.Series`）
`.next_weights`	下期持倉權重
`.actions`	停損停利等動作
`.config`	回測設定（`resample`、`stopLoss`、`takeProfit` 等）
`.current_rebalance_date`／`.next_rebalance_date`	換倉日期

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

下一步

下單：單一策略用 Position 與 OrderExecutor 把策略持倉送到券商。
下單：多策略用 PortfolioSyncManager 管理多個策略的投資組合。
finlab.online 下單模組的完整 API。
finlab.portfolio 投資組合模組的完整 API。

這一頁有幫到你嗎？