v0.2.0 - Expose yd_offset_quantity and yd_remaining_quantity

Feat: Expose yd_offset_quantity and yd_remaining_quantity on StockPosition

list_positions() callers can now read both how much of yesterday's stock
position has been closed today and how much remains, without reaching into
internal sync state. The two values are now first-class fields on the
public StockPosition model.

Changes

• StockPosition.yd_offset_quantity: new int field — amount of
  yd_quantity already offset by today's opposite-direction trades
  (accumulates intraday).
• StockPosition.yd_remaining_quantity: Pydantic v2 @computed_field
  — equals yd_quantity - yd_offset_quantity. Appears in
  model_dump() / JSON; ignored if passed to the constructor;
  does not participate in __eq__.
• _get_local_positions() now returns pos.model_copy() snapshots so
  callers cannot mutate the internal cache and a held snapshot does not
  shift when the deal-callback path mutates cached objects in place.
• _convert_api_positions() (stable-period API path) derives
  yd_offset_quantity from today's filled trades via
  _load_and_sum_today_trades + _calculate_yd_offset_for_position,
  removing the previous misleading yd_offset_quantity = 0 fallback
  for positions not yet present in local state.
• Internal StockPositionInner class removed; _convert_to_public_stock_position
  helper deleted. Both were redundant once the field was promoted.
• README.md / README.zh-TW.md updated with the new StockPosition
  shape and notes on the computed-field semantics.

Migration

For most users this is additive — existing reads of yd_quantity /
quantity / cond etc. are unchanged, and model_dump() now contains
two extra keys (yd_offset_quantity, yd_remaining_quantity).

If you imported StockPositionInner directly (it was never documented
as public), import StockPosition instead — the two are now identical.

📦 Installation

pip install sj-sync==0.2.0

Or with uv:

uv add sj-sync==0.2.0

📊 Test Coverage

• 133 tests passing across Python 3.9–3.13
• 91.36% total code coverage
• CI green across the full 3.9–3.13 matrix ✅

🔗 Links

• English README
• 繁體中文 README

---

功能：在 StockPosition 公開 yd_offset_quantity 與 yd_remaining_quantity

呼叫 list_positions() 的使用者現在不需要去翻內部狀態，就能直接讀到
「今天用掉了多少昨日庫存」以及「昨日還剩多少」。這兩個值已成為公開
StockPosition 上的 first-class 欄位。

變更內容

• StockPosition.yd_offset_quantity：新增 int 欄位 — 今日已被反向交易
  沖掉的昨日庫存量（盤中累計）。
• StockPosition.yd_remaining_quantity：Pydantic v2 @computed_field
  — 等於 yd_quantity - yd_offset_quantity。會出現在 model_dump() /
  JSON；傳給 constructor 會被靜默忽略；不會參與 __eq__。
• _get_local_positions() 改回傳 pos.model_copy() 快照，避免外部
  mutate 內部 cache，也避免使用者抓到的 list 在後續 deal callback
  原地修改快取物件時值跟著改變。
• _convert_api_positions()（stable-period API 路徑）改用
  _load_and_sum_today_trades + _calculate_yd_offset_for_position
  從今日成交直接計算 yd_offset_quantity，移除原本「local 沒有就回 0」
  會誤導的 fallback。
• 移除內部 StockPositionInner class 與 _convert_to_public_stock_position
  helper（欄位變成公開後兩者都成冗餘）。
• 更新 README.md / README.zh-TW.md 反映新的 StockPosition 結構與
  computed-field 語意。

遷移說明

對大多數使用者這是純擴增變更 — yd_quantity / quantity /
cond 等既有讀取路徑不變，model_dump() 多兩個鍵
（yd_offset_quantity、yd_remaining_quantity）。

如果你曾直接 import StockPositionInner（雖然 docstring 從來沒把它寫成
public），請改 import StockPosition — 兩者現在等價。

📦 安裝

pip install sj-sync==0.2.0

或使用 uv：

uv add sj-sync==0.2.0

📊 測試涵蓋率

• 133 個測試在 Python 3.9–3.13 通過
• 91.36% 總程式碼涵蓋率
• 完整 3.9–3.13 矩陣 CI 全綠 ✅

🔗 相關連結

• English README
• 繁體中文 README

---

Full Changelog: v0.1.11...v0.2.0