futu_cache/trd_cache/

snapshots.rs

use super::*;
use futu_domain_trade_account::{
    TradeFundsSnapshotKeyPlan, TradePositionsSnapshotKeyPlan, plan_combo_position_lookup_like_cpp,
    plan_funds_lookup_keys_like_cpp, plan_funds_write_key_like_cpp,
    plan_funds_write_key_with_returned_currency_like_cpp, plan_positions_currency_key_like_cpp,
    plan_positions_key_like_cpp,
};

use super::freshness::insert_newer_snapshot;

impl TrdCache {
    /// **v1.4.106 Finding A** (legacy compat): 不带 currency 维度的 update.
    /// 用 `FundsCacheKey::legacy(acc_id)` 作 key. 适用于:
    /// - 现有 caller 还没改 signature 的 (背景: backend push 不一定知 currency)
    /// - SingleCurrency / sim / Crypto / Forex 账户 (本来就单币种)
    ///
    /// **新 caller 应优先用 [`Self::update_funds_per_currency`]** 显式标
    /// currency 维度, 让 Universal/Futures 账户能存独立 snapshot per currency.
    pub fn update_funds(&self, acc_id: u64, funds: CachedFunds) {
        let key = funds_cache_key(plan_funds_write_key_like_cpp(acc_id, 0, None));
        let snapshot = self.snapshot_freshness.stamp(funds);
        insert_newer_snapshot(&self.funds, key, snapshot);
    }

    /// **v1.4.106 Finding A** (preferred for Universal/Futures): 带 currency
    /// 维度的 update. backend push 时若知 funds 的实际 currency (从 `f.currency`
    /// 字段或 push context 派生), 应该用这个 helper 让多币种 snapshot 不互相覆盖.
    ///
    /// 对齐 C++ `INNData_Trd_Acc::SetAccFund(stKey, enCurrency, ...)`.
    pub fn update_funds_per_currency(
        &self,
        acc_id: u64,
        currency: Option<i32>,
        funds: CachedFunds,
    ) {
        let key = funds_cache_key(plan_funds_write_key_like_cpp(acc_id, 0, currency));
        let snapshot = self.snapshot_freshness.stamp(funds);
        insert_newer_snapshot(&self.funds, key, snapshot);
    }

    /// Currency + asset-category aware funds update.
    ///
    /// JP derivative accounts use `asset_category` as part of the C++ asset key.
    /// Non-JP/legacy callers should pass `asset_category=0`, which preserves the
    /// existing legacy/per-currency key shape.
    pub fn update_funds_scoped(
        &self,
        acc_id: u64,
        asset_category: i32,
        currency: Option<i32>,
        funds: CachedFunds,
    ) {
        let key = funds_cache_key(plan_funds_write_key_like_cpp(
            acc_id,
            asset_category,
            currency,
        ));
        let snapshot = self.snapshot_freshness.stamp(funds);
        insert_newer_snapshot(&self.funds, key, snapshot);
    }

    /// Update the requested funds bucket and also mirror the returned backend
    /// currency bucket when it is known.
    ///
    /// C++ stores `Ndt_Trd_AccFund` under `accFund.enCurrency`
    /// (`INNData_Trd_Acc.cpp::SetAccFund`). A Rust caller may request CMD3020
    /// with `currency=None` because the daemon derived the backend default, but
    /// REST/CLI later read the same account through an explicit effective
    /// currency bucket. Mirroring prevents an older per-currency snapshot from
    /// masking a fresher default refresh.
    pub fn update_funds_scoped_with_returned_currency(
        &self,
        acc_id: u64,
        asset_category: i32,
        requested_currency: Option<i32>,
        funds: CachedFunds,
    ) {
        let write_plan = plan_funds_write_key_with_returned_currency_like_cpp(
            acc_id,
            asset_category,
            requested_currency,
            funds.currency,
        );
        let requested_snapshot = self.snapshot_freshness.stamp(funds.clone());
        insert_newer_snapshot(
            &self.funds,
            funds_cache_key(write_plan.requested),
            requested_snapshot,
        );

        if let Some(mirror_key) = write_plan.returned_currency_mirror {
            let mirror_snapshot = self.snapshot_freshness.stamp(funds);
            insert_newer_snapshot(&self.funds, funds_cache_key(mirror_key), mirror_snapshot);
        }
    }

    /// **v1.4.106 Finding A**: cache lookup with C++-equivalent fallback.
    ///
    /// 对齐 C++ `INNData_Trd_Acc::GetAccFund(stKey, enCurrency, pAccFund)`:
    /// 先试 requested currency, 找不到则 fallback 到 latest/first available
    /// currency, **返 false** (caller 应看 boolean 决定是否 trust).
    ///
    /// 输入 `currency`:
    /// - `Some(c)`: Universal/Futures 路径, 优先 match per-currency snapshot
    /// - `None`: SingleCurrency 路径, 直接 match `legacy(acc_id)` snapshot
    ///
    /// 输出 `(funds, currency_match)`:
    /// - `(Some(funds), true)`: 精确命中 requested currency snapshot
    /// - `(Some(funds), false)`: 命中 fallback (legacy 或不同 currency 的
    ///   snapshot — caller 应**不要 silent trust**, 至少 log warn 或 surface
    ///   currency mismatch)
    /// - `(None, _)`: 完全 cache miss
    #[must_use]
    pub fn get_funds(&self, acc_id: u64, currency: Option<i32>) -> (Option<CachedFunds>, bool) {
        self.get_funds_scoped(acc_id, 0, currency)
    }

    /// Funds lookup using the same `(acc_id, asset_category, currency)` dimensions
    /// as [`Self::update_funds_scoped`].
    ///
    /// For `asset_category != 0` we require an exact scoped hit. Falling back to a
    /// legacy or another asset-category snapshot would mix JP derivative asset
    /// buckets and silently return the wrong funds.
    #[must_use]
    pub fn get_funds_scoped(
        &self,
        acc_id: u64,
        asset_category: i32,
        currency: Option<i32>,
    ) -> (Option<CachedFunds>, bool) {
        let lookup = self.get_funds_scoped_with_freshness(acc_id, asset_category, currency);
        (lookup.funds, lookup.currency_match)
    }

    #[must_use]
    pub fn get_funds_scoped_with_freshness(
        &self,
        acc_id: u64,
        asset_category: i32,
        currency: Option<i32>,
    ) -> FundsSnapshotLookup {
        let lookup_plan = plan_funds_lookup_keys_like_cpp(acc_id, asset_category, currency);
        let exact_key = funds_cache_key(lookup_plan.exact);
        if let Some(snapshot) = self.funds.get(&exact_key) {
            return funds_lookup(&self.snapshot_freshness, exact_key, snapshot.value(), true);
        }
        // Step 2: fallback to legacy(acc_id) — backend 不带 currency context
        // push 时落进 legacy key
        if let Some(legacy_fallback) = lookup_plan.legacy_fallback
            && let legacy_key = funds_cache_key(legacy_fallback)
            && let Some(snapshot) = self.funds.get(&legacy_key)
        {
            return funds_lookup(
                &self.snapshot_freshness,
                legacy_key,
                snapshot.value(),
                false,
            );
        }
        // Step 3: fallback to ANY snapshot for this acc_id (latest available
        // currency, 等价于 C++ "first available")
        if let Some(scan_acc_id) = lookup_plan.scan_acc_id {
            for entry in self.funds.iter() {
                if entry.key().acc_id == scan_acc_id {
                    return funds_lookup(
                        &self.snapshot_freshness,
                        *entry.key(),
                        entry.value(),
                        false,
                    );
                }
            }
        }
        FundsSnapshotLookup {
            funds: None,
            currency_match: false,
            freshness: self.snapshot_freshness.freshness(
                PositionsCacheKey::scoped(acc_id, asset_category),
                None::<&StampedTradeSnapshot<CachedFunds>>,
            ),
        }
    }

    pub fn update_positions(&self, acc_id: u64, positions: Vec<CachedPosition>) {
        self.update_positions_scoped(acc_id, 0, positions);
    }

    pub fn update_positions_scoped(
        &self,
        acc_id: u64,
        asset_category: i32,
        positions: Vec<CachedPosition>,
    ) {
        let key = positions_cache_key(plan_positions_key_like_cpp(acc_id, asset_category));
        let snapshot = self.snapshot_freshness.stamp(positions);
        insert_newer_snapshot(&self.positions, key, snapshot);
    }

    pub fn update_positions_currency_scoped(
        &self,
        acc_id: u64,
        asset_category: i32,
        currency: i32,
        positions: Vec<CachedPosition>,
    ) {
        let key = positions_cache_key(plan_positions_currency_key_like_cpp(
            acc_id,
            asset_category,
            currency,
        ));
        let snapshot = self.snapshot_freshness.stamp(positions);
        insert_newer_snapshot(&self.positions, key, snapshot);
    }

    pub fn update_combo_positions_scoped(
        &self,
        acc_id: u64,
        asset_category: i32,
        positions: Vec<CachedPosition>,
    ) {
        let key = positions_cache_key(plan_positions_key_like_cpp(acc_id, asset_category));
        let snapshot = self.snapshot_freshness.stamp(positions);
        insert_newer_snapshot(&self.combo_positions, key, snapshot);
    }

    #[must_use]
    pub fn get_positions_scoped(
        &self,
        acc_id: u64,
        asset_category: i32,
    ) -> Option<Vec<CachedPosition>> {
        self.get_positions_scoped_with_freshness(acc_id, asset_category)
            .positions
    }

    #[must_use]
    pub fn get_positions_currency_scoped(
        &self,
        acc_id: u64,
        asset_category: i32,
        currency: i32,
    ) -> Option<Vec<CachedPosition>> {
        self.get_positions_currency_scoped_with_freshness(acc_id, asset_category, currency)
            .positions
    }

    #[must_use]
    pub fn get_combo_positions_scoped(
        &self,
        acc_id: u64,
        asset_category: i32,
    ) -> Option<Vec<CachedPosition>> {
        self.get_combo_positions_scoped_with_freshness(acc_id, asset_category)
            .positions
    }

    #[must_use]
    pub fn get_positions_scoped_with_freshness(
        &self,
        acc_id: u64,
        asset_category: i32,
    ) -> PositionsSnapshotLookup {
        let key = positions_cache_key(plan_positions_key_like_cpp(acc_id, asset_category));
        positions_lookup(&self.snapshot_freshness, key, self.positions.get(&key))
    }

    #[must_use]
    pub fn get_positions_currency_scoped_with_freshness(
        &self,
        acc_id: u64,
        asset_category: i32,
        currency: i32,
    ) -> PositionsSnapshotLookup {
        let key = positions_cache_key(plan_positions_currency_key_like_cpp(
            acc_id,
            asset_category,
            currency,
        ));
        positions_lookup(&self.snapshot_freshness, key, self.positions.get(&key))
    }

    #[must_use]
    pub fn get_combo_positions_scoped_with_freshness(
        &self,
        acc_id: u64,
        asset_category: i32,
    ) -> PositionsSnapshotLookup {
        let key = positions_cache_key(plan_positions_key_like_cpp(acc_id, asset_category));
        positions_lookup(
            &self.snapshot_freshness,
            key,
            self.combo_positions.get(&key),
        )
    }

    #[must_use]
    pub fn has_positions_scoped(&self, acc_id: u64, asset_category: i32) -> bool {
        let key = positions_cache_key(plan_positions_key_like_cpp(acc_id, asset_category));
        self.positions.contains_key(&key)
    }

    /// C++ `INNData_Trd_Acc::GetComboPositionItem(nAccID, Unknown, nPositionID)`.
    ///
    /// Combo trade-write paths receive public FTAPI `positionID` (a hash). The
    /// backend requires the original `business_position_id` string plus the
    /// position's long account/sub-account ids. Search the combo-position view
    /// for the account and return the cached row instead of guessing.
    #[must_use]
    pub fn find_combo_position_item(
        &self,
        acc_id: u64,
        position_id: u64,
    ) -> Option<CachedPosition> {
        let lookup_plan = plan_combo_position_lookup_like_cpp(acc_id, position_id);
        let legacy_plan = lookup_plan.legacy_key?;
        let legacy_key = positions_cache_key(legacy_plan);
        if let Some(positions) = self.combo_positions.get(&legacy_key)
            && let Some(position) = positions
                .value()
                .value()
                .iter()
                .find(|position| position.position_id == position_id)
        {
            return Some(position.clone());
        }
        if let Some(scan_acc_id) = lookup_plan.scan_remaining_account_buckets {
            for entry in self.combo_positions.iter() {
                if entry.key().acc_id != scan_acc_id || *entry.key() == legacy_key {
                    continue;
                }
                if let Some(position) = entry
                    .value()
                    .value()
                    .iter()
                    .find(|position| position.position_id == position_id)
                {
                    return Some(position.clone());
                }
            }
        }
        None
    }
}

fn funds_lookup(
    freshness_store: &super::freshness::TradeSnapshotFreshnessStore,
    key: FundsCacheKey,
    snapshot: &StampedTradeSnapshot<CachedFunds>,
    currency_match: bool,
) -> FundsSnapshotLookup {
    FundsSnapshotLookup {
        funds: Some(snapshot.value().clone()),
        currency_match,
        freshness: freshness_store.freshness(
            PositionsCacheKey::scoped(key.acc_id, key.asset_category),
            Some(snapshot),
        ),
    }
}

fn positions_lookup(
    freshness_store: &super::freshness::TradeSnapshotFreshnessStore,
    key: PositionsCacheKey,
    snapshot: Option<
        dashmap::mapref::one::Ref<'_, PositionsCacheKey, StampedTradeSnapshot<Vec<CachedPosition>>>,
    >,
) -> PositionsSnapshotLookup {
    let freshness = freshness_store.freshness(key.asset_scope(), snapshot.as_deref());
    PositionsSnapshotLookup {
        positions: snapshot.map(|snapshot| snapshot.value().value().clone()),
        freshness,
    }
}

fn funds_cache_key(plan: TradeFundsSnapshotKeyPlan) -> FundsCacheKey {
    if plan.asset_category != 0 {
        FundsCacheKey::full(plan.acc_id, plan.asset_category, plan.currency)
    } else {
        match plan.currency {
            Some(currency) => FundsCacheKey::per_currency(plan.acc_id, currency),
            None => FundsCacheKey::legacy(plan.acc_id),
        }
    }
}

fn positions_cache_key(plan: TradePositionsSnapshotKeyPlan) -> PositionsCacheKey {
    PositionsCacheKey::full(plan.acc_id, plan.asset_category, plan.currency)
}