futu_cache/trd_cache/

types.rs

// 交易缓存数据模型。

use futu_core::account_locator::AccountCardRecord;

/// 账户 key: acc_id
pub type AccKey = u64;

/// 缓存的账户信息
#[derive(Debug, Clone, Default)]
pub struct CachedTrdAcc {
    /// 账户 ID
    pub acc_id: u64,
    /// 后端/mobile native intra account id (C++ `Ndt_Trd_AccItem.nIntraAccID`).
    ///
    /// 公开 FTAPI `acc_id` 与 backend 查询 body 里的 `account_id` 不是同一层
    /// 语义。需要发 backend native account_id 的 handler 应优先用这个字段，
    /// 不要从公开 `acc_id` 低 32 位反推。
    pub intra_acc_id: Option<u64>,
    /// 交易环境（0=Simulate / 1=Real）
    pub trd_env: i32,
    /// 该账户有权限访问的交易市场列表
    pub trd_market_auth_list: Vec<i32>,
    /// 账户类型（Cash / Margin / Derivative / ...）
    pub acc_type: Option<i32>,
    /// 账户卡号（后段数字，仅用于显示识别）
    pub card_num: Option<String>,
    /// 账户所属 broker（FutuHK=1 / FutuUS=2 / ...）
    pub security_firm: Option<i32>,
    /// 模拟账户子类型
    pub sim_acc_type: Option<i32>,
    /// 统一卡号（跨市场账户聚合标识）
    pub uni_card_num: Option<String>,
    /// 账户状态码（正常 / 冻结 / ...）
    pub acc_status: Option<i32>,
    /// Backend raw `FTUsrTrdAcc::Account.state`.
    ///
    /// C++ API layer keeps this distinct from public `TrdAccStatus`:
    /// `OPENED(1)` is returned as Active, `CLOSED(2)` is returned in the
    /// disabled-real tail, while `OPENING(0)` is skipped by
    /// `APIServer_Trd_GetAccList.cpp:109-115`. Do not derive this back from
    /// `acc_status`, because both CLOSED and OPENING are non-active.
    pub acc_open_state: Option<i32>,
    /// 账户角色（主账户 / 子账户 / 顾问）
    pub acc_role: Option<i32>,
    /// Daemon-derived user-visible account label.
    ///
    /// Some opened business accounts are not representable by
    /// `Trd_Common.TrdMarket` (for example crypto) or overload protocol role
    /// values (for example equity-incentive / IPO route). The bridge derives a
    /// label from backend account metadata and stores it here so public account
    /// discovery does not rely on numeric market allowlists.
    pub acc_label: Option<String>,
    /// 日本账户附加类型标签
    pub jp_acc_type: Vec<i32>,
    // --- 以下为审计补全的字段 ---
    /// 账户所有者 UID
    pub owner_uid: Option<u64>,
    /// 账户操作者 UID
    pub opr_uid: Option<u64>,
    /// 混合状态 (C++ enAccState / MixedState)
    pub mixed_state: Option<i32>,
    /// IRA 类型 (CA: TFSA=1, RRSP=2, SRRSP=3)
    pub ira_type: Option<i32>,
    /// 授权状态 (GrantState)
    pub grant_state: Option<i32>,
    /// 口座类型 (JP: Cash=1, Margin=2, Derivative=3)
    pub kouza_type: Option<i32>,
    /// 交易市场 (Account.market, 单个值)
    pub trd_market: Option<i32>,
    /// 关联账户 ID (基金账户绑定)
    pub association_acc_id: Option<u64>,
    /// 综合账户子账户标志 (0=非子账户)
    pub acc_flag: Option<i32>,
    /// 原始顺序索引 (用于保持后端返回的自然顺序)
    pub order_index: usize,
    /// C++ 排序 key: (BrokerID << 48) | (TrdMkt << 32) | IntraAccID
    pub sort_key: u64,
}

impl AccountCardRecord for CachedTrdAcc {
    fn acc_id(&self) -> u64 {
        self.acc_id
    }

    fn card_num(&self) -> Option<&str> {
        self.card_num.as_deref()
    }

    fn uni_card_num(&self) -> Option<&str> {
        self.uni_card_num.as_deref()
    }
}

impl CachedTrdAcc {
    /// v1.4.108: identify crypto from bridge-derived backend metadata label.
    ///
    /// Account discovery must not hide opened crypto accounts, but `Trd_Common`
    /// has no public `TrdMarket_Crypto` variant. The bridge therefore derives
    /// `acc_label=crypto` from `FTUsrTrdAcc.AccountMarket::Crypto` /
    /// `TradingCapability::NaCrypto`; cache consumers should read that label
    /// rather than re-hardcoding market numbers.
    pub fn is_crypto_account(&self) -> bool {
        self.acc_label.as_deref() == Some("crypto")
    }

    pub fn is_encrypted(&self) -> bool {
        self.is_crypto_account()
    }

    /// v1.4.97 J-Acc-Q3 + v1.4.98 T2-6: derived `acc_label` for
    /// `/api/accounts` REST response.
    ///
    /// **Priority order**:
    /// 1. bridge-derived backend label (`crypto`, `equity_incentive`,
    ///    `ipo_route`, ...);
    /// 2. `"paper_trade"` — `trd_env==0 (Simulate)` (v1.4.98).
    ///
    /// Returns `None` for "no special label" (default Margin / regular Cash).
    ///
    /// **Spec**: REST-only enrichment (no proto change for gRPC clients —
    /// gRPC 不看 proto extension field, 只看 /api/accounts REST output).
    /// Clients should `treat unknown labels as opaque strings` for forward
    /// compatibility; new labels may appear when backend account categories are
    /// surfaced through the bridge.
    ///
    /// Labels are opaque strings for clients. Unknown labels should be rendered
    /// as-is rather than treated as an error.
    pub fn derive_acc_label(&self) -> Option<&str> {
        if let Some(label) = self.acc_label.as_deref() {
            return Some(label);
        }
        if self.trd_env == 0 {
            return Some("paper_trade");
        }
        None
    }
}

/// 缓存的资金 (对齐 C++ Ndt_Trd_AccFund 全字段)
#[derive(Debug, Clone, Default)]
pub struct CachedFunds {
    pub power: f64,                      // 最大做多购买力
    pub total_assets: f64,               // 资产净值
    pub cash: f64,                       // 现金
    pub market_val: f64,                 // 证券市值
    pub frozen_cash: f64,                // 冻结资金
    pub debt_cash: f64,                  // 欠款金额
    pub avl_withdrawal_cash: f64,        // 可提金额
    pub currency: Option<i32>,           // 货币类型
    pub available_funds: Option<f64>,    // 可用资金 (期货)
    pub unrealized_pl: Option<f64>,      // 未实现盈亏 (期货)
    pub realized_pl: Option<f64>,        // 已实现盈亏 (期货)
    pub risk_level: Option<i32>,         // 风险等级
    pub initial_margin: Option<f64>,     // 初始保证金
    pub maintenance_margin: Option<f64>, // 维持保证金
    pub max_power_short: Option<f64>,    // 最大做空购买力
    pub net_cash_power: Option<f64>,     // 现金购买力
    pub long_mv: Option<f64>,            // 多头市值
    pub short_mv: Option<f64>,           // 空头市值
    pub pending_asset: Option<f64>,      // 在途资产
    pub max_withdrawal: Option<f64>,     // 最大可提
    pub risk_status: Option<i32>,        // 风险状态码
    pub margin_call_margin: Option<f64>, // margin call 保证金
    pub securities_assets: Option<f64>,  // 证券资产
    pub fund_assets: Option<f64>,        // 基金资产
    pub bond_assets: Option<f64>,        // 债券资产
    pub crypto_mv: Option<f64>,          // 数字货币市值
    pub exposure_level: Option<i32>,     // 数字货币风险等级
    pub exposure_limit: Option<f64>,     // 数字货币持仓限额
    pub used_limit: Option<f64>,         // 数字货币已用限额
    pub remaining_limit: Option<f64>,    // 数字货币剩余额度

    // v1.4.98 T1-4 (mobile-source-audit Phase 2): US PDT (Pattern Day
    // Trader) 6 字段. proto/Trd_Common.proto:377-382 字段 24-29.
    // 仅富途证券(美国)账户适用. mobile App 账户首页"日内交易"卡片直接显示.
    // futu-trd::Funds 已读 5 字段 (缺 beginning_dtbp), CachedFunds 之前
    // 6 字段全漏 → cache-only path silent drop.
    /// 是否 PDT 账户 (Pattern Day Trader, 仅 US)
    pub is_pdt: Option<bool>,
    /// 剩余日内交易次数 (string 表示, mobile UI 直接显示)
    pub pdt_seq: Option<String>,
    /// 初始日内交易购买力 (DTBP)
    pub beginning_dtbp: Option<f64>,
    /// 剩余日内交易购买力 (DTBP)
    pub remaining_dtbp: Option<f64>,
    /// 日内交易待缴金额 (DT Call)
    pub dt_call_amount: Option<f64>,
    /// 日内交易限制状态 (DTStatus enum)
    pub dt_status: Option<i32>,

    /// 分币种现金信息: (currency, cash, avl_withdrawal, net_cash_power)
    pub cash_info_list: Vec<CachedCashInfo>,
    /// 分市场资产信息: (trd_market, assets)
    pub market_info_list: Vec<CachedMarketInfo>,
}

/// 分币种现金信息
#[derive(Debug, Clone, Default)]
pub struct CachedCashInfo {
    /// 币种（对齐 proto `TrdCommon.Currency`）
    pub currency: i32,
    /// 该币种现金
    pub cash: f64,
    /// 该币种可用余额
    pub available_balance: f64,
    /// 该币种净购买力（无杠杆）
    pub net_cash_power: f64,
}

/// 分市场资产信息
#[derive(Debug, Clone, Default)]
pub struct CachedMarketInfo {
    /// 所属交易市场（对齐 proto `TrdCommon.TrdMarket`）
    pub trd_market: i32,
    /// 该市场资产总值
    pub assets: f64,
}

/// 缓存的持仓 (对齐 C++ Ndt_Trd_AccPosition 全字段)
#[derive(Debug, Clone, Default)]
pub struct CachedPosition {
    pub position_id: u64,
    /// Backend business position id used by JP combo close/order paths.
    ///
    /// C++ `NNProto_Trd_AccReal.cpp:262-269` stores
    /// `asset_query.AccPstnInfo.business_position_id` as
    /// `Ndt_Trd_AccPosition.sBusinessPositionID` and, for FutuJP, exposes
    /// `Position.positionID = HashStrToU64(sBusinessPositionID)`. Combo
    /// trade-write paths must reverse that mapping before sending backend
    /// CMD2297/CMD4701.
    pub business_position_id: Option<String>,
    /// C++ `Ndt_Trd_AccPosition.nPositionAccID`; used by JP combo legs as
    /// backend `pos_account_id`.
    pub position_acc_id: Option<u64>,
    /// C++ `Ndt_Trd_AccPosition.nSubAccountID`; used by JP combo legs as
    /// backend `pos_sub_account_id`.
    pub sub_account_id: Option<u64>,
    pub position_side: i32, // 0=多仓, 1=空仓
    pub code: String,
    pub name: String,
    pub qty: f64,
    pub can_sell_qty: f64,
    pub price: f64,                      // 当前价
    pub cost_price: f64,                 // 摊薄成本价
    pub val: f64,                        // 市值
    pub pl_val: f64,                     // 盈亏金额
    pub pl_ratio: Option<f64>,           // 盈亏比例
    pub sec_market: Option<i32>,         // 证券市场
    pub td_pl_val: Option<f64>,          // 今日盈亏
    pub td_trd_val: Option<f64>,         // 今日成交额
    pub td_buy_val: Option<f64>,         // 今日买入金额
    pub td_buy_qty: Option<f64>,         // 今日买入数量
    pub td_sell_val: Option<f64>,        // 今日卖出金额
    pub td_sell_qty: Option<f64>,        // 今日卖出数量
    pub unrealized_pl: Option<f64>,      // 未实现盈亏 (期货)
    pub realized_pl: Option<f64>,        // 已实现盈亏 (期货)
    pub currency: Option<i32>,           // 货币
    pub trd_market: Option<i32>,         // 交易市场
    pub diluted_cost_price: Option<f64>, // 摊薄成本
    pub average_cost_price: Option<f64>, // 平均成本
    pub average_pl_ratio: Option<f64>,   // 平均盈亏比例
    /// C++ 10.7 `Ndt_Trd_AccPosition.nComboIDHash`, projected as
    /// `Trd_Common.Position.comboID` only for combo summary/leg rows.
    pub combo_id: Option<u64>,
    /// Backend asset-system combo id string (`Ndt_Trd_AccPosition.sComboIDSvr`).
    ///
    /// Public `comboID` is a hash, but C++ JP combo close/order paths write the
    /// original string back to backend `OrderNewReq.combo_id`; keep both
    /// representations so public projection and backend write paths do not
    /// fight each other.
    pub business_combo_id: Option<String>,
    /// C++ 10.7 option strategy type after backend `combo_identify` ->
    /// NN -> public `Qot_Common.OptionStrategyType` mapping.
    pub strategy_type: Option<i32>,
    /// C++ 10.7 `NN_PositionType`, projected as public
    /// `Trd_Common.PositionType` (`Combined=1`, `Leg=2`).
    pub position_type: Option<i32>,
    /// C++ 10.7 position account id. JP sub-account rows may use a different
    /// long account id; otherwise the handler falls back to request acc_id.
    pub acc_id: Option<u64>,
    /// C++ 10.7 JP sub-account type.
    pub jp_acc_type: Option<i32>,
    /// v1.4.42 (external reviewer v1.4.40 roadmap #2 + P2.3): 期权持仓到期日距今天数。
    /// backend 不返，daemon 按 code 推导（option code 才有值）。
    pub expiry_date_distance: Option<i32>,
}

/// 缓存的订单 (对齐 C++ Ndt_Trd_Order 全字段)
#[derive(Debug, Clone, Default)]
pub struct CachedOrder {
    pub order_id: u64,
    pub order_id_ex: String, // 服务端订单 ID 字符串
    pub code: String,
    pub name: String,
    pub trd_side: i32,
    pub order_type: i32,
    pub order_status: i32,
    pub qty: f64,
    pub price: f64,
    pub fill_qty: f64,
    pub fill_avg_price: f64,
    pub create_time: String,
    pub update_time: String,
    pub last_err_msg: Option<String>,   // 最后错误信息
    pub sec_market: Option<i32>,        // 证券市场
    pub create_timestamp: Option<f64>,  // 创建时间戳
    pub update_timestamp: Option<f64>,  // 更新时间戳
    pub remark: Option<String>,         // 备注
    pub time_in_force: Option<i32>,     // 有效期类型
    pub fill_outside_rth: Option<bool>, // 是否允许盘前盘后成交
    pub aux_price: Option<f64>,         // 触发价格
    pub trail_type: Option<i32>,        // 跟踪类型
    pub trail_value: Option<f64>,       // 跟踪值
    pub trail_spread: Option<f64>,      // 跟踪价差
    pub currency: Option<i32>,          // 货币
    pub trd_market: Option<i32>,        // 交易市场

    /// v1.4.106 codex 0219 Finding 4 / 0226 F7: backend snapshot 字段集合.
    ///
    /// PlaceOrder ack 后 backend 返 `OrderNewRsp.order_id` (= `szOrderID`,
    /// 服务端真实订单 id, alphanumeric 字符串). FTAPI `Trd_PlaceOrder.S2C.order_id`
    /// 是这个 string 的 hash (`HashStrToU64` 结果, 见 `trade_query::hash_str_to_u64`).
    ///
    /// **必填语义**: ModifyOrder / CancelOrder backend req 的 `order_id` 字段
    /// **必须**填 backend `szOrderID`, 不是 hash. 反模式 (v1.4.105 及以前):
    /// 没有 orderIDEx 时直接 `order_id_ex.parse().unwrap_or(0)` 把 hash 当
    /// backend id 发 — backend 拒错或匹配失败.
    ///
    /// 修法 (v1.4.106 Finding 1+4): cache 存 `backend_order_id` (= szOrderID)
    /// 字段; trade-write handler 通过 `find_order_for_trade_write` lookup 拿到
    /// `ResolvedOrderContext { backend_order_id, version, exchange, exchange_code,
    /// security_type, ... }` 后再发 backend req.
    pub backend_order_id: String,

    /// v1.4.106 codex 0219 Finding 4: backend `Order.version` (proto field 21).
    ///
    /// ModifyOrder backend `OrderReplaceReq.order_version` 必填 — 让 backend
    /// 能拒接收已经被其他客户端改过版本的旧请求. C++ `FillModifyOrderReq:736`:
    /// `req.set_order_version((u32_t)order.nVersion)`.
    pub order_version: i32,

    /// v1.4.106 codex 0219 Finding 4: backend `Order.exchange_code` (proto field 37).
    ///
    /// 期货所属交易所代码 (e.g. `1` = HKEX, `2` = NYSE 之类, 取值参考
    /// `NN_QotMarket`). ModifyOrder / CancelOrder backend 必填 (期货必填,
    /// 股票为 0). C++ `FillModifyOrderReq:773`:
    /// `req.set_exchange_code((u32_t)order.enMktID)`.
    pub exchange_code: i32,

    /// v1.4.106 codex 0219 Finding 4: backend `Order.exchange` (proto field 49).
    ///
    /// 股票所属交易所字符串 (e.g. "SEHK", "NYSE", "NASDAQ"). ModifyOrder /
    /// CancelOrder backend 必填. C++ `FillModifyOrderReq:774`:
    /// `req.set_exchange(order.szExchange)`.
    pub exchange: String,

    /// v1.4.106 codex 0219 Finding 4: backend `Order.security_type` (proto field 29).
    ///
    /// 取值参考 backend `odr_sys_cmn::SecurityType`
    /// (1=COMMON, 2=OPTION, 4=FUTURES, 5=BOND).
    /// CancelOrder single 必填 (`req.add_security_type(GetSecurityType(...))`,
    /// C++ `FillCancelOrderReq:817`).
    pub security_type: i32,

    /// v1.4.98 T1-8 (mobile-source-audit): 美股盘前/盘中/盘后 session 标识.
    /// proto/Trd_Common.proto:455 字段 27. 同 time_in_force / fill_outside_rth
    /// 系列, 美股 RTH/Pre-Market/After-Hours order routing 显示用.
    pub session: Option<i32>,

    /// Backend `odr_sys_cmn.Order.order_trade_time_type` / C++ `order.enOrderTradeTimeType`.
    ///
    /// `GetMaxTrdQtys` real option IM side request (CMD5004) mirrors C++
    /// `NNProto_Trd_MaxQty::QueryOptionIM`: when querying max qty for a
    /// modification order, the side request forwards the cached backend order's
    /// trade-time type if it is not UNSET.
    pub order_trade_time_type: Option<u32>,

    /// v1.4.98 T1-8 (mobile-source-audit): 日本子账户类型 (security_firm=7
    /// FutuJP 时填充). proto/Trd_Common.proto:456 字段 28.
    /// 8 enum 值: GENERAL/TOKUTEI/NISA_GENERAL/NISA_TSUMITATE 等
    /// (per docs/reference/rest-api.md D6).
    pub jp_acc_type: Option<i32>,

    /// v1.4.90 S BUG-e4da-009: stub 标志。
    ///
    /// PlaceOrder/CancelOrder handler 成功响应后**立刻** upsert 一个 stub
    /// `CachedOrder`（v1.4.82 A2 / `place_order.rs:427`），让 `/api/orders`
    /// 0ms 可见。`is_stub=true` 标记此条尚未被 backend 权威列表 ack。
    ///
    /// 后续 backend `query_orders` 返回包含同 `order_id` 的 enriched 数据时，
    /// 经 `merge_preserving_stubs` 合并 → `is_stub=false`。
    ///
    /// 历史坑：v1.4.73 A1 PlaceOrder 后 spawn refresh 直接 `orders.insert`
    /// **整覆盖**，把刚 upsert 的 stub 抹掉（race 22ms 内即清零）。
    /// 跨 v1.4.73 → v1.4.89 7 版未真修。本字段是根因修法的一部分。
    pub is_stub: bool,

    /// C++ `Ndt_Trd_Order.bIsLocalOrder` equivalent.
    ///
    /// C++ `UpdateOrderList` replaces the backend list, then re-inserts rows
    /// returned by `INNData_Trd_Order::GetLocalOrderList` where
    /// `bIsLocalOrder=true`.
    ///
    /// Refs:
    /// - `FutuOpenD/Src/NNProtoCenter/Trade/_NNProto_Trd_Comm.cpp:345-359`
    /// - `FutuOpenD/Src/NNDataCenter/Trade/INNData_Trd_Order.cpp:13-31`
    /// - `FutuOpenD/Src/NNProtoCenter/Trade/Operate/NNProto_Trd_OrderOpBase.cpp:95`
    ///
    /// Rust uses this narrowly for local terminal rows that C++ keeps visible
    /// after backend refresh, notably DeleteFailOrder success -> Deleted(23).
    /// It is intentionally distinct from `is_stub`: stubs expire by TTL, while
    /// local Deleted rows are C++ list state and must survive an empty backend
    /// refresh until a backend row with the same id replaces them.
    pub is_local_order: bool,

    /// v1.4.90 S BUG-e4da-009: stub 插入时间（unix epoch ms）。
    ///
    /// `merge_preserving_stubs` 用于 evict 老 stub：backend 如果连续多次
    /// 不返某 stub `order_id` 且 stub 已超过 `STUB_TTL_MS` (30s) → evict。
    /// 防止 stub 因 backend 拒单（never appear in list）永久滞留。
    ///
    /// `0` 表示非 stub（与 `is_stub=false` 配套）。
    pub stub_inserted_at_ms: u64,

    /// v1.4.105 BUG-v1.4.104-001 (P0): broker 异步 confirm 标志.
    ///
    /// PlaceOrder backend 同步 ack (CMD 4701 result=0) 仅说明 backend 收到请求,
    /// **不**代表 broker 真的接受订单. C++ `OnOMEvent_Reply_PlaceOrder`
    /// (`APIServer_Trd_PlaceOrder.cpp:794`) 是**异步 event handler** — broker
    /// 真 confirm 后才 fire `set_orderid(nOrderIDHash)`. backend `OrderNewRsp.
    /// need_op_confirm` (proto field 6, default=true) 即表示 "真 broker confirm
    /// 还在路上, 等 OMEvent push (notice_type 4/5/8/100)".
    ///
    /// **历史坑 (external reviewer BUG-v1.4.104-001 实锤)**: v1.4.82-104 stub 上 cache 时直接
    /// 视为已确认, 没有 broker async confirm 等待 → 三次不同订单返同 order_id_ex
    /// 时客户端看 success → 误以为生效 → 加仓重下 → 风控 auto-cancel error 10003.
    ///
    /// **语义**:
    /// - `true`: backend 已 ack 但 broker 未确认 — `is_stub=true` 时 stub 不进
    ///   `/api/orders` 响应 (filter), 等 push notice_type=4/5/8/100 confirm 后翻
    ///   `false` 才 expose. 30s 内未 confirm → cleanup task 删 stub + warn.
    /// - `false`: backend 权威 / broker 已 confirm — 正常 expose 给 client.
    ///   query_orders 返的所有 order 都是 `false` (backend list 是 broker-confirmed
    ///   的权威列表).
    ///
    /// **与 `is_stub` 关系**:
    /// - `is_stub=true && is_pending_broker_confirm=true`: 刚 PlaceOrder ack, 还没
    ///   push confirm. **client 不可见** (Layer 4 filter).
    /// - `is_stub=true && is_pending_broker_confirm=false`: backend `need_op_confirm=
    ///   false` 路径 (sim 账户 / 立即生效场景). client 可见.
    /// - `is_stub=false`: backend authoritative (query_orders 返 / push merge 后).
    ///   `is_pending_broker_confirm` 必为 false. client 可见.
    pub is_pending_broker_confirm: bool,
}

/// v1.4.106 codex 0219 Finding 1+4: trade-write resolution snapshot.
///
/// 用于 ModifyOrder / CancelOrder handler 把 cached order 字段一次性
/// 拿出来构造 backend req. **不在 hot path 改 CachedOrder**, 而是返一个
/// 只读 snapshot 防 caller mutate cache.
///
/// 字段 1:1 映射 backend `OrderReplaceReq` / `OrderCancelReq` 必填项 +
/// modify validation 用到的 (`order_type` / `trd_side` / `qty` /
/// `price` / `order_status`).
#[derive(Debug, Clone, Default, PartialEq)]
pub struct CachedOrderSnapshot {
    /// = backend `szOrderID` (alphanumeric 字符串, 服务端真实 id).
    pub backend_order_id: String,
    /// = backend `Order.version`.
    pub order_version: i32,
    /// = backend `Order.exchange_code` (期货所属交易所代码, e.g. NN_QotMarket).
    pub exchange_code: i32,
    /// = backend `Order.exchange` (股票所属交易所字符串, e.g. "SEHK").
    pub exchange: String,
    /// = backend `Order.security_type` (1=COMMON, 2=OPTION, 4=FUTURES, 5=BOND).
    pub security_type: i32,
    /// FTAPI `OrderType` (modify validation 按原 order_type 决定 price /
    /// aux_price / trail* 是否必填).
    pub order_type: i32,
    /// FTAPI `TrdSide` (1=Buy / 2=Sell / 3=SellShort / 4=BuyBack).
    /// trailing modify 计算 sign 用.
    pub trd_side: i32,
    /// FTAPI `OrderStatus` (`IsNotSupportOrderOp` 检查用).
    pub order_status: i32,
    /// FTAPI `TrdMarket` (modify validation 中 sec_type futures 路径用).
    pub trd_market: Option<i32>,
    /// FTAPI `Order.qty` (历史值, 仅 modify validation 引用).
    pub qty: f64,
    /// FTAPI `Order.price` (历史值, 仅 modify validation 引用).
    pub price: f64,
    /// FTAPI `Order.code` (用于错误提示 + log 关联).
    pub code: String,
    /// PlaceOrder stub 标记. PlaceOrder ack 时插入的 stub `is_stub=true` +
    /// `order_version=0`. ModifyOrder 按 C++ 本地回显订单 `nVersion=-1`
    /// 映射为 backend wire `u32::MAX`; CancelOrder 不依赖 order_version.
    pub is_stub: bool,
    /// PlaceOrder stub 是否仍在等待 broker/backend 权威确认.
    ///
    /// Real write handlers use this to avoid reporting success against a local
    /// optimistic echo when the authoritative order list has not accepted the
    /// order yet.
    pub is_pending_broker_confirm: bool,
}

impl CachedOrderSnapshot {
    /// 从 `CachedOrder` 抽出 trade-write resolution 用到的字段子集.
    pub fn from_order(o: &CachedOrder) -> Self {
        Self {
            backend_order_id: o.backend_order_id.clone(),
            order_version: o.order_version,
            exchange_code: o.exchange_code,
            exchange: o.exchange.clone(),
            security_type: o.security_type,
            order_type: o.order_type,
            trd_side: o.trd_side,
            order_status: o.order_status,
            trd_market: o.trd_market,
            qty: o.qty,
            price: o.price,
            code: o.code.clone(),
            is_stub: o.is_stub,
            is_pending_broker_confirm: o.is_pending_broker_confirm,
        }
    }
}

/// v1.4.106 codex 0219 Finding 1: ResolveOrderError 区分三种 cache miss 形态.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ResolveOrderError {
    /// 同时缺 `order_id` 和 `order_id_ex`. caller 必须早期 reject.
    InvalidInput,
    /// `(acc_id, order_id)` 在 cache 找不到. 提示用户先刷新 `/api/orders`
    /// 或传 orderIDEx.
    CacheMiss,
    /// cache 命中但 `backend_order_id` 字段空 (老版本 cache entry).
    /// 提示用户先刷新 `/api/orders` 或传 orderIDEx.
    MissingBackendId,
}

impl std::fmt::Display for ResolveOrderError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::InvalidInput => f.write_str(
                "modify/cancel: 必须传 order_id 或 order_id_ex (orderIDEx 优先)",
            ),
            Self::CacheMiss => f.write_str(
                "modify/cancel: 订单不在本地缓存. 请先调 /api/orders 刷新, 或在请求里传 orderIDEx (= backend szOrderID).",
            ),
            Self::MissingBackendId => f.write_str(
                "modify/cancel: 本地缓存缺 backend orderIDEx (老版本 daemon 写入的 cache). 请先调 /api/orders 刷新, 或在请求里传 orderIDEx.",
            ),
        }
    }
}

impl std::error::Error for ResolveOrderError {}

/// **v1.4.106 Finding A** (codex source audit 2026-05-01): funds cache currency-aware key.
///
/// 对齐 C++ `INNData_Trd_Acc.cpp::m_mapAccFund`:
///   `m_mapAccFund: NN_AssetKey -> NN_TrdCurrency -> Ndt_Trd_AccFund`
///
/// Universal/Futures 账户对**不同 currency** 有独立 funds snapshot, 之前 Rust
/// 用 `DashMap<AccKey, CachedFunds>` (1 acc_id → 1 snapshot) 会被 backend
/// pushed snapshots **互相覆盖** — 用户传 `currency=USD` 拿到的可能是 stale
/// CAD 数据, 客户端无法察觉.
///
/// 字段语义:
/// - `acc_id`: 账户 (主 key)
/// - `asset_category`: `Trd_Common.proto::AssetCategory` enum (0=Default 等),
///   对齐 C++ NN_AssetKey 子集. 若 client 传 `c2s.asset_category=None`, 用 0.
/// - `currency`: `Some(c)` 表示 per-currency snapshot (Futures/Universal 路径);
///   `None` 表示 legacy 单币种账户 native (无 per-currency 概念). C++ 等价于
///   "first available currency" snapshot.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct FundsCacheKey {
    pub acc_id: u64,
    pub asset_category: i32,
    pub currency: Option<i32>,
}

impl FundsCacheKey {
    /// Legacy single-account snapshot key (acc_id only, no per-currency / no
    /// per-asset_category dimension). 用于 SingleCurrency 账户 / 无 currency
    /// context 的 cache write.
    #[must_use]
    pub const fn legacy(acc_id: u64) -> Self {
        Self {
            acc_id,
            asset_category: 0,
            currency: None,
        }
    }

    /// Per-currency snapshot key (Universal/Futures 路径).
    #[must_use]
    pub const fn per_currency(acc_id: u64, currency: i32) -> Self {
        Self {
            acc_id,
            asset_category: 0,
            currency: Some(currency),
        }
    }

    /// Per-asset-category + per-currency snapshot key (full path, asset_category
    /// 非 0 时用).
    #[must_use]
    pub const fn full(acc_id: u64, asset_category: i32, currency: Option<i32>) -> Self {
        Self {
            acc_id,
            asset_category,
            currency,
        }
    }
}

/// **v1.4.107 PositionList asset-category key**.
///
/// C++ `APIServer_Trd_GetPositionList.cpp::FillPositionList` reads positions
/// by `NN_AssetKey { accid, enCategory }`. FutuJP margin / derivative accounts
/// therefore need independent position snapshots per asset category, just like
/// funds. Category 0 keeps the legacy single-bucket behavior for non-JP and sim
/// accounts.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct PositionsCacheKey {
    pub acc_id: u64,
    pub asset_category: i32,
}

impl PositionsCacheKey {
    #[must_use]
    pub const fn legacy(acc_id: u64) -> Self {
        Self {
            acc_id,
            asset_category: 0,
        }
    }

    #[must_use]
    pub const fn scoped(acc_id: u64, asset_category: i32) -> Self {
        Self {
            acc_id,
            asset_category,
        }
    }
}

/// v1.4.106 codex 0226 F1+F2: PlaceOrder 阶段 backend 返回 `OrderNewRsp.action`
/// (CltAction.type == ORDER_CONFIRM=5) 时, 携带 `CltActionOrderConfirm` 二次
/// 确认上下文 — 客户端需把这些字段透传给 backend `OrderConfirmReq` (cmd 4728).
///
/// 来源 (proto-internal/odr_sys_cmn.proto:883-893):
/// ```text
/// message CltActionOrderConfirm {
///     optional string order_id = 1;             // 订单 id (= backend 真实
///                                                //  szOrderID, alphanumeric)
///     optional string title = 2;                // 弹窗标题文案
///     optional string content = 3;              // 弹窗内容文案
///     optional string confirm_button_title = 4;
///     optional string cancel_button_title = 5;
///     optional uint32 confirm_type = 6;         // 必传给 OrderConfirmReq
///     optional uint32 exchange_code = 7;        // 期货上游交易所代码
///     optional string exchange = 8;             // 股票所属交易所
/// }
/// ```
///
/// daemon 在 PlaceOrder ack 路径里 capture 此 context, 然后在
/// `Trd_ReconfirmOrder` 收到客户端确认请求时按 (acc_id, ftapi_order_id) 取出来
/// 构造 backend `OrderConfirmReq`. 缺 context = backend 不需要二次确认 (e.g.
/// HK 高买低卖未触发 / sim 路径) → ReconfirmOrder handler 早 reject loud.
///
/// **来源 cmd_id**: `CS_CMDID_TRADE_ORDER_CONFIRM_ORDER = 4728`
/// (`moomoo/Moomoo/Include/FTTrade/TradeCmdDefine.h:132`).
#[derive(Debug, Clone, PartialEq, Eq, Hash, Default)]
pub struct OrderConfirmContext {
    /// backend 真实 szOrderID (alphanumeric); 写到 `OrderConfirmReq.order_id`.
    pub backend_order_id: String,
    /// `CltActionOrderConfirm.confirm_type` (来自 OrderConfirmType enum).
    /// **必传** (backend 用此值校验客户端确实看到了对应弹窗).
    pub confirm_type: u32,
    /// `CltActionOrderConfirm.exchange_code` (期货必传).
    pub exchange_code: u32,
    /// `CltActionOrderConfirm.exchange` (股票必传).
    pub exchange: String,
    /// 弹窗 title (用于 daemon 日志, 客户端可参考).
    pub title: String,
    /// 弹窗 content (用于 daemon 日志, 客户端可参考).
    pub content: String,
    /// confirm_button / cancel_button title 透传 (UX, 不影响 backend).
    pub confirm_button_title: String,
    pub cancel_button_title: String,
    /// 写入时间 (unix epoch ms), TTL 用. PlaceOrder 与 ReconfirmOrder 之间通常
    /// <60s, 远超 60s 视为 stale → handler 拒绝.
    pub inserted_at_ms: u64,
}

/// v1.4.106 codex 0226 F1+F2: pending OrderConfirm cache key.
///
/// `(acc_id, ftapi_order_id)` 而不是 `(acc_id, backend_order_id)`, 因为 FTAPI
/// 客户端发 ReconfirmOrder 用的是 PlaceOrder 返的 `s2c.order_id` (FTAPI u64,
/// 由 `hash_backend_id_to_u64` 派生). FTAPI 客户端**不**直接看到 backend
/// alphanumeric szOrderID; daemon 必须按 FTAPI order_id 反查 context.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct OrderConfirmKey {
    pub acc_id: u64,
    /// FTAPI order_id (= `hash_backend_id_to_u64(backend.order_id)`).
    pub ftapi_order_id: u64,
}

impl OrderConfirmKey {
    pub fn new(acc_id: u64, ftapi_order_id: u64) -> Self {
        Self {
            acc_id,
            ftapi_order_id,
        }
    }
}

/// C++ `m_mapReqIDOrderID` key, scoped by account to avoid cross-account
/// collisions in the shared Rust trade cache.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct OrderOpReqKey {
    pub acc_id: u64,
    pub req_id: String,
}

impl OrderOpReqKey {
    pub fn new(acc_id: u64, req_id: String) -> Self {
        Self { acc_id, req_id }
    }
}

/// C++ `FindOrderIDByReqID` clears the helper map once it reaches 512 entries.
pub const ORDER_OP_REQ_ORDER_MAP_CLEAR_LIMIT: usize = 512;

/// v1.4.106 codex 0226 F1+F2: pending order confirm context TTL (ms).
///
/// PlaceOrder → ReconfirmOrder 通常 <60s (用户看到弹窗后立即点确认). 超过 60s
/// 视为弹窗已被忽略 / 用户 abandon → daemon 不允许 reconfirm (backend 也会拒绝
/// 因为 confirm_type 已过期). 当前选 5min (300_000 ms) 作宽松 TTL — 给真机用户
/// 更多缓冲, 同时防内存泄漏.
pub const ORDER_CONFIRM_CONTEXT_TTL_MS: u64 = 300_000;