Summary
新版 shioaji 目前有多個 response/data object 的公開欄位與 shioaji==1.3.3 不一致，可能造成既有使用者升級後程式碼不相容。
這份 issue 先整理目前觀察到的差異，後續可逐項補 alias、wrapper 或相容 model。
Scope
比對目標：
- Baseline:
shioaji==1.3.3
- Current: current HEAD
主要影響範圍：
- Stream callback / receiver data types
- Order / Trade response
- Reserve API response
- Portfolio response
- Contract / ComboBase
1. Stream Data Types
目前 stream callback / receiver data type 有多處欄位與 shioaji==1.3.3 不一致。以下只列有變動的欄位。
1.1 TickSTKv1 / QuoteSTKv1
這兩個 class 都有以下欄位 rename：
shioaji==1.3.3 欄位 |
目前欄位 |
total_amount |
amount_sum |
total_volume |
vol_sum |
chg_type |
diff_type |
price_chg |
diff_price |
pct_chg |
diff_rate |
bid_side_total_vol |
trade_bid_vol_sum |
ask_side_total_vol |
trade_ask_vol_sum |
bid_side_total_cnt |
trade_bid_cnt |
ask_side_total_cnt |
trade_ask_cnt |
fixed_trade_vol |
fixed_trade_volume |
新增欄位：
TickSTKv1: exchange, date, time, closing_oddlot_close, closing_oddlot_amount, closing_oddlot_bid_price, closing_oddlot_ask_price, fixed_trade_amountQuoteSTKv1: exchange, date, time
1.2 TickFOPv1
欄位 rename：
shioaji==1.3.3 欄位 |
目前欄位 |
underlying_price |
target_kind_price |
total_amount |
amount_sum |
total_volume |
vol_sum |
chg_type |
diff_type |
price_chg |
diff_price |
pct_chg |
diff_rate |
bid_side_total_vol |
trade_bid_vol_sum |
ask_side_total_vol |
trade_ask_vol_sum |
新增欄位：
1.3 QuoteFOPv1
欄位 rename：
shioaji==1.3.3 欄位 |
目前欄位 |
underlying_price |
target_kind_price |
total_amount |
amount_sum |
total_volume |
vol_sum |
chg_type |
diff_type |
price_chg |
diff_price |
pct_chg |
diff_rate |
bid_side_total_vol |
trade_bid_vol_sum |
ask_side_total_vol |
trade_ask_vol_sum |
bid_side_total_cnt |
trade_bid_cnt |
ask_side_total_cnt |
trade_ask_cnt |
first_derived_bid_vol |
first_derived_bid_volume |
first_derived_ask_vol |
first_derived_ask_volume |
新增欄位：
1.4 BidAskSTKv1
欄位差異：
1.3.3 有 datetime，目前 public stub 沒有看到- 目前新增
exchange, date, time
1.5 BidAskFOPv1
1.3.3 有、目前 Python-facing optimized BidAskFOPv1 沒看到的欄位：
datetimebid_total_volask_total_voldiff_bid_voldiff_ask_volfirst_derived_bid_pricefirst_derived_ask_pricefirst_derived_bid_volfirst_derived_ask_volunderlying_price
新增欄位：
2. Order / Trade Response
2.1 OrderStatus 語意改變
在 1.3.3，OrderStatus 是 response data model，欄位包含：
idstatusstatus_codeweb_idorder_datetimemsgmodified_timemodified_priceorder_quantitydeal_quantitycancel_quantitydeals
目前版本：
OrderStatus 是 enum- 原本的 data model 改名為
OrderStatusInfo
Trade.status 指向 OrderStatusInfo
這可能會影響 import 或 type checking，例如：
from shioaji.order import OrderStatus
2.2 Order object 欄位不同
在 1.3.3，StockOrder, FuturesOrder, ComboOrder 都繼承 BaseOrder，因此包含：
目前下單用的 order input object 沒有這些欄位，回傳資料改由 OrderResult 表示。
2.3 Deal 多了欄位
目前 Deal 額外 expose：
這是 additive change，應該相對安全。
3. Reserve API Response
1.3.3 reserve APIs 回傳 wrapper objects：
ReserveStocksSummaryResponseReserveStocksDetailResponseReserveStockResponseEarmarkStocksDetailResponseReserveEarmarkingResponse
每個 wrapper 有：
目前 API 看起來直接回傳內層 object，例如：
ReserveStocksSummaryReserveStocksDetailReserveOrderRespEarmarkingOrderResp
這會讓原本寫法不相容：
resp = api.reserve_stock(...)
resp.response
resp.error
4. Portfolio Response
在 1.3.3，繼承 LazyModel 的 models 會 expose status。
相關 models 包含：
SettlementAccountBalanceProfitLossSummaryTotalMarginTradingLimits
目前版本看起來已保留 status：
但以下 public stub 沒有看到 status：
SettlementTradingLimitsProfitLossSummaryTotal
5. Contract / ComboBase
5.1 BaseContract
目前 BaseContract 多了：
這是 additive change。
5.2 ComboBase
在 1.3.3，ComboBase 繼承 Contract，所以有完整 contract field surface。
目前 ComboBase 只 expose combo leg 需要的欄位，少了多個 1.3.3 欄位，例如：
namecurrencydelivery_dateunderlying_kindunderlying_codeunitmultiplierlimit_uplimit_downreferenceupdate_datemargin_trading_balanceshort_selling_balanceday_trade
Expected Behavior
如果目標是維持與 shioaji==1.3.3 的 Python API compatibility，既有 response/data object 欄位應該仍可使用，可以是 canonical fields，也可以是 compatibility aliases。
Suggested Direction
- 為 stream data fields 補上
1.3.3 相容 alias。
- 恢復或 shim 舊版
OrderStatus data model surface。
- 內部可以保留
OrderStatusInfo，但 shioaji.order.OrderStatus 應盡量維持舊版相容。
- 恢復 reserve response wrappers，或提供含
response / error 的 compatibility wrapper。
- 補回 portfolio response models 缺少的
status property。
- 檢查
ComboBase 是否需要 expose 完整 Contract 相容欄位。
Summary
新版 shioaji 目前有多個 response/data object 的公開欄位與
shioaji==1.3.3不一致，可能造成既有使用者升級後程式碼不相容。這份 issue 先整理目前觀察到的差異，後續可逐項補 alias、wrapper 或相容 model。
Scope
比對目標：
shioaji==1.3.3主要影響範圍：
1. Stream Data Types
目前 stream callback / receiver data type 有多處欄位與
shioaji==1.3.3不一致。以下只列有變動的欄位。1.1
TickSTKv1/QuoteSTKv1這兩個 class 都有以下欄位 rename：
shioaji==1.3.3欄位total_amountamount_sumtotal_volumevol_sumchg_typediff_typeprice_chgdiff_pricepct_chgdiff_ratebid_side_total_voltrade_bid_vol_sumask_side_total_voltrade_ask_vol_sumbid_side_total_cnttrade_bid_cntask_side_total_cnttrade_ask_cntfixed_trade_volfixed_trade_volume新增欄位：
TickSTKv1:exchange,date,time,closing_oddlot_close,closing_oddlot_amount,closing_oddlot_bid_price,closing_oddlot_ask_price,fixed_trade_amountQuoteSTKv1:exchange,date,time1.2
TickFOPv1欄位 rename：
shioaji==1.3.3欄位underlying_pricetarget_kind_pricetotal_amountamount_sumtotal_volumevol_sumchg_typediff_typeprice_chgdiff_pricepct_chgdiff_ratebid_side_total_voltrade_bid_vol_sumask_side_total_voltrade_ask_vol_sum新增欄位：
exchangedatetime1.3
QuoteFOPv1欄位 rename：
shioaji==1.3.3欄位underlying_pricetarget_kind_pricetotal_amountamount_sumtotal_volumevol_sumchg_typediff_typeprice_chgdiff_pricepct_chgdiff_ratebid_side_total_voltrade_bid_vol_sumask_side_total_voltrade_ask_vol_sumbid_side_total_cnttrade_bid_cntask_side_total_cnttrade_ask_cntfirst_derived_bid_volfirst_derived_bid_volumefirst_derived_ask_volfirst_derived_ask_volume新增欄位：
exchangedatetime1.4
BidAskSTKv1欄位差異：
1.3.3有datetime，目前 public stub 沒有看到exchange,date,time1.5
BidAskFOPv11.3.3有、目前 Python-facing optimizedBidAskFOPv1沒看到的欄位：datetimebid_total_volask_total_voldiff_bid_voldiff_ask_volfirst_derived_bid_pricefirst_derived_ask_pricefirst_derived_bid_volfirst_derived_ask_volunderlying_price新增欄位：
exchangedatetime2. Order / Trade Response
2.1
OrderStatus語意改變在
1.3.3，OrderStatus是 response data model，欄位包含：idstatusstatus_codeweb_idorder_datetimemsgmodified_timemodified_priceorder_quantitydeal_quantitycancel_quantitydeals目前版本：
OrderStatus是 enumOrderStatusInfoTrade.status指向OrderStatusInfo這可能會影響 import 或 type checking，例如：
2.2 Order object 欄位不同
在
1.3.3，StockOrder,FuturesOrder,ComboOrder都繼承BaseOrder，因此包含：idseqnoordnoca目前下單用的 order input object 沒有這些欄位，回傳資料改由
OrderResult表示。2.3
Deal多了欄位目前
Deal額外 expose：datetime這是 additive change，應該相對安全。
3. Reserve API Response
1.3.3reserve APIs 回傳 wrapper objects：ReserveStocksSummaryResponseReserveStocksDetailResponseReserveStockResponseEarmarkStocksDetailResponseReserveEarmarkingResponse每個 wrapper 有：
responseerror目前 API 看起來直接回傳內層 object，例如：
ReserveStocksSummaryReserveStocksDetailReserveOrderRespEarmarkingOrderResp這會讓原本寫法不相容：
4. Portfolio Response
在
1.3.3，繼承LazyModel的 models 會 exposestatus。相關 models 包含：
SettlementAccountBalanceProfitLossSummaryTotalMarginTradingLimits目前版本看起來已保留
status：AccountBalanceMargin但以下 public stub 沒有看到
status：SettlementTradingLimitsProfitLossSummaryTotal5. Contract / ComboBase
5.1
BaseContract目前
BaseContract多了：target_code這是 additive change。
5.2
ComboBase在
1.3.3，ComboBase繼承Contract，所以有完整 contract field surface。目前
ComboBase只 expose combo leg 需要的欄位，少了多個1.3.3欄位，例如：namecurrencydelivery_dateunderlying_kindunderlying_codeunitmultiplierlimit_uplimit_downreferenceupdate_datemargin_trading_balanceshort_selling_balanceday_tradeExpected Behavior
如果目標是維持與
shioaji==1.3.3的 Python API compatibility，既有 response/data object 欄位應該仍可使用，可以是 canonical fields，也可以是 compatibility aliases。Suggested Direction
1.3.3相容 alias。OrderStatusdata model surface。OrderStatusInfo，但shioaji.order.OrderStatus應盡量維持舊版相容。response/error的 compatibility wrapper。statusproperty。ComboBase是否需要 expose 完整Contract相容欄位。