ek_ui/

state.rs

//! 共享观测状态:`UiPlugin`(总线面)写、`render_body`(窗口面)读。
//!
//! 线程形貌:总线侧在**插件 worker 线程**写;窗口侧在 **eframe 主线程**读;
//! 锁粒度 = 每次 `lock().clone()/snapshot()`,不跨帧持锁。

use std::collections::{BTreeMap, HashSet, VecDeque};
use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU32, AtomicU64, AtomicUsize, Ordering};
use std::sync::{Arc, Mutex};

use ek_data::bar::BarData;
use ek_dm::wire::BarsFrame;
use ek_station::wire::PlugRow;

/// 日志环形容量(A/D 裁定 2026-10-28:E15 实证 512 被一次 506 行的状态洪水
/// 灌满 → 启动链日志被挤出,T5 假红。显示窗抬到 4096(与 K线格同哲学:
/// 够看 + 有界);**全量事实由溢出落盘兜住**([`LogRing`] spilling 面,
/// 每所一笔一行,追加写,永不回环 —— 见 `LogRing::push` 的 spill 分支)。
pub const RING_CAP: usize = 4096;

/// 展示面统一时区:UTC+08(固定偏移,不依赖本机时区设置)。
/// 0.2.27 起从 render 侧提到 state(原 `render.rs` 那份随之删除):日志时间戳
/// 在入环时就要打,而打戳与表格时间列(`fmt_dt`)必须是同一个口径,
/// 不能一边 +08 一边本机时区。
pub(crate) fn beijing_tz() -> chrono::FixedOffset {
    chrono::FixedOffset::east_opt(8 * 3600).expect("+08 offset is always valid")
}

/// 一行日志(BD-UI-41:Python 侧 LogMonitor 是带「时间/信息/接口」表头的表格
/// (`widget.py:1167-1180`),我们原来只存正文串、渲染侧没有时间可排)。
/// 时间戳在入环那一刻打,北京墙钟 `%H:%M:%S`(与 `fmt_dt` 同口径)。
#[derive(Debug, Clone)]
pub struct LogEntry {
    /// 北京墙钟 `HH:MM:SS`。
    pub at: String,
    /// 正文。
    pub text: String,
}

/// 环形日志:push 满则挤掉最旧一条,溢出计数单调(页面显示"已丢弃 N 条")。
/// spilling 面(A/D 裁定):**进环的每一笔都追加写盘**(`%APPDATA%\ek\logs\`
/// 按天文件;`EK_UI_LOG_DIR` 可重定向)—— 显示有界,事实全量,回去翻盘不翻环。
#[derive(Debug)]
pub struct LogRing {
    lines: VecDeque<LogEntry>,
    cap: usize,
    spilled: u64,
    spill_dir: Option<std::path::PathBuf>,
}

/// 缺省落盘目录(可用 `EK_UI_LOG_DIR` 重定向;测试用例自设临时目录)。
pub(crate) fn default_spill_dir() -> std::path::PathBuf {
    if let Ok(d) = std::env::var("EK_UI_LOG_DIR")
        && !d.trim().is_empty()
    {
        return std::path::PathBuf::from(d);
    }
    std::env::var("APPDATA")
        .map(|r| std::path::PathBuf::from(r).join("ek").join("logs"))
        .unwrap_or_else(|_| std::path::PathBuf::from(".ek-logs"))
}

impl Default for LogRing {
    fn default() -> Self {
        Self::new_spilling(RING_CAP, default_spill_dir())
    }
}

impl LogRing {
    /// 定容环形(纯显示,不落盘;测试可传小容量逼溢出)。
    pub fn new(cap: usize) -> Self {
        Self {
            lines: VecDeque::with_capacity(cap),
            cap,
            spilled: 0,
            spill_dir: None,
        }
    }

    /// 定容环形 + **全量落盘**(A/D 裁定):进环事件每一笔都追加写
    /// `{dir}\ekapp-{YYYYMMDD}.log`(北京墙钟打戳;写失败静默降级 ——
    /// 磁盘/权限问题不得影响界面,计数面照旧有 `spilled`)。
    pub fn new_spilling(cap: usize, dir: std::path::PathBuf) -> Self {
        Self {
            lines: VecDeque::with_capacity(cap),
            cap,
            spilled: 0,
            spill_dir: Some(dir),
        }
    }

    /// 落盘写(每笔一行:`{at} | {text}`;失败忽略)。
    fn spill_write(&self, entry: &LogEntry) {
        let Some(dir) = self.spill_dir.as_ref() else {
            return;
        };
        let day = chrono::Local::now().format("%Y%m%d");
        let path = dir.join(format!("ekapp-{day}.log"));
        let _ = std::fs::create_dir_all(dir);
        if let Ok(mut f) = std::fs::OpenOptions::new()
            .append(true)
            .create(true)
            .open(&path)
        {
            use std::io::Write as _;
            let _ = writeln!(f, "{} | {}", entry.at, entry.text);
        }
    }

    /// 追加一行;满则挤旧 + spilled+1;spilling 环下每笔同步写盘。
    pub fn push(&mut self, line: impl Into<String>) {
        let at = chrono::Utc::now()
            .with_timezone(&beijing_tz())
            .format("%H:%M:%S")
            .to_string();
        let entry = LogEntry {
            at,
            text: line.into(),
        };
        if self.spill_dir.is_some() {
            self.spill_write(&entry);
        }
        if self.cap == 0 {
            self.spilled += 1;
            return;
        }
        if self.lines.len() == self.cap {
            self.lines.pop_front();
            self.spilled += 1;
        }
        self.lines.push_back(entry);
    }

    /// 当前长度。
    pub fn len(&self) -> usize {
        self.lines.len()
    }

    /// 是否空行。
    pub fn is_empty(&self) -> bool {
        self.lines.is_empty()
    }

    /// 累计已丢弃条数(只有溢出才涨)。
    pub fn spilled(&self) -> u64 {
        self.spilled
    }

    /// 只读快照(正文;测试与巡回取证用它,不关心时间)。
    pub fn snapshot(&self) -> Vec<String> {
        self.lines.iter().map(|e| e.text.clone()).collect()
    }

    /// 带时间戳的快照(渲染侧表格用:时间列 + 正文列)。
    pub fn entries(&self) -> Vec<LogEntry> {
        self.lines.iter().cloned().collect()
    }

    /// 全清;spilled 保留(历史溢出事实不抹)。
    pub fn clear(&mut self) {
        self.lines.clear();
    }
}

/// 一次 eTimer 拉取的服务/插件快照(渲染直接可用)。
#[derive(Debug, Clone, Default)]
pub struct BusSnap {
    /// svctl.list 全行(svctl 独裁班;状态原文)。
    pub rows: Vec<PlugRow>,
    /// 逐插件服务目录(id 清单;无服务为空)。
    pub services: Vec<(String, Vec<String>)>,
}

/// UI 操作指令(窗口面 → 总线面;eTimer 节拍被 ui 插件请辞)。
#[derive(Debug, Clone, PartialEq)]
pub enum UiCmd {
    /// svctl.start(工厂名 + 实例注册名;`name` 空 = 旧行为,工厂名即注册名)。
    /// 多账号面:`factory="ctp"` + `name=ctp_<broker>_<账号>` 建第 N 个网关实例。
    Start { factory: String, name: String },
    /// svctl.remove(插件名)。
    Remove { name: String },
    /// dm.reload 回灌(S4;push=true 逐条广播,行情面板实时见 Rows)。
    Reload {
        interval: i64,
        symbol: String,
        bars: Vec<BarData>,
    },
    /// 下单(S5;网关受理即 SUBMITTING 单上总线)。
    /// S6 起网关可选(`gateway.send_order`,空 = ctp)。
    /// 0.1.1(BD-UI-30):改走 `oms.submit_order` 五段管线(拆单/风控/逐腿
    /// 发送/记账,parent 聚合);`mode` = 拆单四态(勾选「自动开平」= Auto,
    /// 取消勾选 = None 原样旁路)。
    SendOrder {
        req: ek_data::order_request::OrderRequest,
        gateway: String,
        mode: ek_oms::LockMode,
    },
    /// 撤单(S5;携三段号所需的 orderid;S6 起网关同选)。
    /// 0.1.1(BD-UI-30):改走 `oms.cancel_order`(守卫 4000 不可绕过;
    /// symbol/exchange 由 oms 订单缓存解,不再随令携带)。
    CancelOrder { orderid: String, gateway: String },
    /// `{gw}.configure` 账户配置(多账号面:网关名随令携带,不再硬编码 `ctp`;
    /// 出队时 `to_configure_req` 抬成线上契约)。
    /// 0.2.18 起界面侧不再用它装配账户(装配走 `Connect`);保留作低层口与测试面。
    CtpConfigure { gateway: String, form: CtpForm },
    /// **四态分离的「连接」(0.2.18,规划裁定:添加 ≠ 连接)**:
    /// 一次做完 `svctl.start(factory=ctp)` + `{gw}.configure`,结果回写账户行
    /// (`Assembling → Assembled / AssembleFailed`)。界面『连接』『重试』钮走这一条,
    /// 『添加账户』只写清册(不再一键装配 → 失败不会留下"注定被拒"的半死行)。
    Connect { gateway: String, form: CtpForm },
    /// `{gw}.subscribe` 订阅行情(多账号面:一律路由到**行情元账号**,
    /// 从账号没有 MD 会话,发给它只会静默成功 —— 见规划 §5.C / §9.4-21)。
    CtpSubscribe {
        gateway: String,
        symbols: Vec<String>,
    },
    /// **`{gw}.disconnect` 停会话(0.2.19,规划裁定 1:断开 ≠ 移除)**:
    /// 网关实例、账号配置、订阅集、状态计数全保留,『连接/重试』可恢复(重登自动重订阅)。
    /// 『移除』走的 `UiCmd::Remove`(svctl.remove)才是停实例 —— 两个动作不得混成一个。
    Disconnect { gateway: String },
    /// 配置托底:段目录刷新(`cfg.list`;0.6.0 环节8,BD-CFG-17 零值面)。
    CfgList,
    /// 配置托底:清段(`cfg.delete`,`ns` + 空整段语义;运维窗操作,与文件回缺省)
    CfgDelete { ns: String },
    /// 配置托底:重存段(`cfg.save`;从明面重读 → serialize → store,
    /// **值不变** —— 修 rev/格式,持久挂久节奏验证面;0.6.0 环节8)。
    CfgResave { ns: String },

    // ---------------- 策略交易(0.9.47;统一「一插件多实例」表) ----------------
    /// 添加策略(弹窗提交)。
    StratAdd {
        /// 策略类名。
        class_name: String,
        /// 实例名。
        name: String,
        /// 参数(键 → 编码串)。
        params: Vec<(String, String)>,
    },
    /// 初始化。
    StratInit { name: String },
    /// 启动。
    StratStart { name: String },
    /// 暂停。
    StratPause { name: String },
    /// 恢复(暂停后继续)。
    StratResume { name: String },
    /// 停止(内部先全撤)。
    StratStop { name: String },
    /// 改参数(仅非运行/非暂停)。
    StratEdit {
        /// 实例名。
        name: String,
        /// 新参数(键 → 编码串)。
        params: Vec<(String, String)>,
    },
    /// 移除。
    StratRemove { name: String },
    /// 全部启动(只启已初始化的)。
    StratStartAll,
    /// 全部停止。
    StratStopAll,
    /// 重推一次全量快照(界面表异常时的兜底)。
    StratResync,
    /// 查一次当前参数值(编辑弹窗打开时)。
    StratSettings { name: String },
    /// 查一次最新价(弹窗预填)。
    StratPrice { symbol: String },
    /// 补一次类元数据:**仅当缓存为空**才真的 ask(s32a/s32b)。
    StratMetaSync,
    /// 设默认交易/行情网关(设置面提交;空串 = 自动解析)。
    StratSetEngine {
        /// 交易网关。
        trade_gateway: String,
        /// 行情网关。
        md_gateway: String,
    },
}

/// 策略命令的回执(`add` / `edit` 这类"窗内要看到结果"的命令用这一条回带)。
///
/// 纪律:命令线程 ask 完把回执放进 [`UiShared`] 的单槽,渲染线程**取走即清** ——
/// 窗内不 ask、也不轮询,只读这一格。
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StratFeedback {
    /// 动作:`"add"` / `"edit"`。
    pub op: &'static str,
    /// 目标实例名。
    pub name: String,
    /// 引擎是否受理。
    pub ok: bool,
    /// 中文消息(失败必非空)。
    pub msg: String,
}

/// 行情缓存单格容量(防涨;丢头保尾,bar 流单调)。
pub const KLINE_CELL_CAP: usize = 4096;

/// 账户软上限(0.2.18 落地既有开放项:达上限『添加账户』入口禁用并提示,
/// 界面侧不再无限长行)。
/// 账户数**防御性顶**(0.9.10 用户裁定「我们从来没有限制过账户数」):
/// 业务侧无限制,这条只挡荒谬状态(误操作连击/异常脚本),顶到 64 = 事实上摸不到。
pub const MAX_ACCOUNTS: usize = 64;

/// 「查询断供」判据之一:资金/持仓查询**连续**被拒达此数(规划 Q10)。
///
/// 阈值住在界面,不住在网关:ek-ctp 只给 `td_query_reject_streak` 这个原料,
/// 「连续几次算断供」是界面口径(它才知道自己多久刷一次)。
pub const QUERY_REJECT_STREAK_LIMIT: u32 = 3;

/// 「查询断供」判据之二:距最后一次**资金回报**超过这么多秒(规划 Q10)。
///
/// 阈值对照的是 ek-ctp 0.9.8 的轮询密度:1 秒闸 + 秒针抖动 → 资金与持仓每路 2~4 秒一次,
/// 30 秒 = 最坏也有 7 次机会没见到资金,足够避开「刚登录还没轮到」与「合约阶段内本来不问
/// 资金」的正常空窗,又不至于把 F2 那种断供拖很久才显形。
pub const ACCOUNT_STALE_SECS: i64 = 30;

/// 链状态行的前缀(0.5.0,用户定「链进行的状态改为事件日志推送」)—— **单源:引用网关那一份**。
///
/// 前缀的唯一出处是 ek-ctp 0.9.8 的 `ek_ctp::driver::CHAIN_STATE_PREFIX`(驱动落每一条 `[链] `
/// 状态行、插件落会话复位行,用的都是它)。本 crate 0.5.0 抬 pin 到 0.9.8,就不再自己抄一份 ——
/// 抄一份 = 网关改前缀而界面静默不认。测试钉 `u4i` 读的是这个再导出。
pub use ek_ctp::driver::CHAIN_STATE_PREFIX;

/// 管制面快照(`svctl.list`)轮询节拍(0.5 M3:事件驱动后唯一保留的拍级轮询)。
///
/// 4 拍 ≈ 4 秒(第一拍必问,界面刚起来不该空着):这一口给的是「谁在场 + 服务目录 +
/// 邮箱溢出计数」,不是交易数据。0.4 之前它每拍一次,是因为交易四表搭在同一拍上;
/// 四表改吃推送后,它降到自己那一档。
pub const LIST_POLL_TICKS: u32 = 4;

/// `{gw}.status` 每拍最多问几个账户(0.5 M3:状态轮询摊平)。
///
/// 摊平而不是降拍:8 个账户同拍全问,单拍上限就是 8 × 2s;每拍只问 2 个,单拍上限
/// 就是 4s,而 8 个账户 4 拍走完一轮 —— 与快照节拍同档,且不随账户数线性长。
pub const STATUS_ASKS_PER_TICK: usize = 2;

/// 成交账本上限(0.5 偏离基线③,用户裁定接)。
///
/// 基线的成交表只插不删、无上限(`widget.py:1242/1267` 的 `data_key = ""`);长跑一天
/// CTP 成交可上万行,而渲染每帧要把它们喂进表。触顶丢最旧,并在第一次触顶时弹一次告警。
pub const TRADE_CAP: usize = 5000;

/// 水位阈下限(0.7.0 背压刀):积压越过软顶的 1/16 且不少于此数 → 黄。
pub const PENDING_WARN_FLOOR: u64 = 4_096;
/// 水位阈下限(0.7.0 背压刀):积压越过软顶的 1/4 且不少于此数 → 红。
pub const PENDING_CRIT_FLOOR: u64 = 32_768;

/// 某插件的水位阈(0.7.0:**吃这一行自己的软顶**,比例 + 下限)。
///
/// 0.5 M6 时代界面自带一张「谁覆写了容量」的登记表(`mailbox_cap_of`)——
/// ek-station 0.4.0 起 `PlugRow.soft_cap` 把这条事实随快照带到界面上,
/// 登记表就是第二份事实源(两处会飘),**退役**。
/// 阈值口径:比例随软顶缩放(1/16 黄、1/4 红),下限取旧口径的定数
/// (4096 / 32768),避免小软顶的插件刚起步就满屏红。
#[must_use]
pub fn pending_thresholds(soft_cap: u64) -> (u64, u64) {
    let warn = (soft_cap / 16).max(PENDING_WARN_FLOOR);
    let crit = (soft_cap / 4).max(PENDING_CRIT_FLOOR);
    (warn.min(soft_cap.max(1)), crit.min(soft_cap.max(1)))
}

/// 二次确认步进:Armed = 首点待确认;Fired = 同名二点已发令;Switched = 目标迁移。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ConfirmStep {
    Armed,
    Fired,
    Switched,
}

/// 隔离态判定(svctl.list 状态原文含 Quarantin → 红;ePlugQDown.<名> 是定向
/// 广播,未知名无法预订阅 —— 快照行扫描是唯一闭环面,BD-UI-17)。
#[must_use]
pub fn is_quarantined(state: &str) -> bool {
    state.contains("Quarantin")
}

// ================= S4:行情库(eBar./eBarUpdate. 上屏地面) =================

/// K线历史补数单(fen 请求形态;tq 桥消费)。
#[derive(Debug, Clone)]
pub struct KlineFetch {
    pub symbol: String,
    pub interval_secs: i64,
}

/// 单格 = (symbol, interval) → bar 升序序列(丢头保尾;datetime 单调)。
#[derive(Debug, Default)]
pub struct MarketStore {
    cells: Mutex<BTreeMap<(String, i64), Vec<BarData>>>,
    /// eBar. 帧接收计数(帧统计,刷新不丢帧观感面)。
    frames: AtomicU64,
    /// eBarUpdate. 接收计数。
    updates: AtomicU64,
    /// dm.reload 成功计数(回灌确认面)。
    reloads: AtomicU64,
}

/// 一格的可读视图(渲染/测试用)。
#[derive(Debug, Clone, PartialEq)]
pub struct CellView {
    pub symbol: String,
    pub interval: i64,
    pub bars: Vec<BarData>,
}

impl MarketStore {
    /// eBar. 收帧:逐 bar 并格(同 dt 替尾;更旧丢弃;更晚追加,溢出丢头)。
    pub fn on_frame(&self, frame: &BarsFrame) {
        let mut cells = self.cells.lock().unwrap();
        for b in &frame.bars {
            let key = (b.symbol.clone(), frame.interval);
            let cell = cells.entry(key).or_default();
            match cell.last() {
                Some(last) if b.datetime < last.datetime => continue,
                Some(last) if b.datetime == last.datetime => {
                    let slot = cell.last_mut().expect("len>1");
                    *slot = b.clone();
                }
                _ => {
                    cell.push(b.clone());
                    if cell.len() > KLINE_CELL_CAP {
                        cell.remove(0);
                    }
                }
            }
        }
        self.frames.fetch_add(1, Ordering::AcqRel);
    }

    /// eBarUpdate. 收单 bar 快照(实时门;同 dt 替尾,新 dt 追加 = in-flight bar)。
    pub fn on_update(&self, b: &BarData) {
        let mut cells = self.cells.lock().unwrap();
        let iv = b
            .interval
            .unwrap_or(ek_data::constant::Interval::MINUTE)
            .seconds();
        let key = (b.symbol.clone(), iv);
        let cell = cells.entry(key).or_default();
        match cell.last() {
            Some(last) if b.datetime == last.datetime => {
                let slot = cell.last_mut().expect("len>1");
                *slot = b.clone();
            }
            Some(last) if b.datetime < last.datetime => {}
            _ => {
                cell.push(b.clone());
                if cell.len() > KLINE_CELL_CAP {
                    cell.remove(0);
                }
            }
        }
        self.updates.fetch_add(1, Ordering::AcqRel);
    }

    /// `{gw}.klines` 历史回包并格(I2 第一刀)。
    ///
    /// 与 on_frame 不同:**回填补数比现有尾巴更旧是常态**,走全格
    /// 「升序合并 + 同 dt 去重 + 超限丢头(保最新 KLINE_CELL_CAP 根)」。
    /// 请求方负责 error/truncated 显形;这里纯数据并格。
    pub fn note_history(&self, symbol: &str, iv_secs: i64, bars: &[BarData]) {
        let mut cells = self.cells.lock().unwrap();
        let cell = cells.entry((symbol.to_string(), iv_secs)).or_default();
        cell.extend(bars.iter().cloned());
        cell.sort_unstable_by_key(|b| b.datetime);
        cell.dedup_by(|a, b| a.datetime == b.datetime);
        if cell.len() > KLINE_CELL_CAP {
            let excess = cell.len() - KLINE_CELL_CAP;
            cell.drain(0..excess);
        }
        self.frames.fetch_add(1, Ordering::AcqRel);
    }

    /// dm.reload 回灌登记(RELOAD OK 计数;dm 侧行为独立)。
    pub fn note_reload(&self) {
        self.reloads.fetch_add(1, Ordering::AcqRel);
    }

    /// 全格只读快照(键序 = BTreeMap 序,symbol/interval 稳定)。
    pub fn cells(&self) -> Vec<CellView> {
        self.cells
            .lock()
            .unwrap()
            .iter()
            .map(|((sym, iv), bars)| CellView {
                symbol: sym.clone(),
                interval: *iv,
                bars: bars.clone(),
            })
            .collect()
    }

    /// K线窗查找键面(F1 键统一,0.9.9):窗键 = 视觉裸符号(如 `rb2605`),格键 =
    /// **带交易所前缀**(note_history 的生命线,如 `SHFE.rb2605`)。
    /// 查找 = 精确命中 or **同码剥前缀命中**(`X.{sym}` 收尾即认)——
    /// 修实时病:E15 波前窗永远找不到前缀格,历史画不出。
    pub fn find_cell(&self, sym: &str) -> Option<CellView> {
        self.cells()
            .into_iter()
            .find(|c| c.symbol == sym || c.symbol.ends_with(&format!(".{sym}")))
    }

    /// 计算(Ai) 帧统计。
    pub fn counts(&self) -> (u64, u64, u64) {
        (
            self.frames.load(Ordering::Acquire),
            self.updates.load(Ordering::Acquire),
            self.reloads.load(Ordering::Acquire),
        )
    }
}

/// 回灌表单(v4:界面面已退役,总线口 `UiCmd::Reload` 保留;解析器留作
/// 测试与脚本面)。
#[derive(Debug, Default, Clone, PartialEq)]
pub struct ReloadForm {
    pub interval: String,
    pub symbol: String,
    pub csv: String,
}

/// 票据网关选择子解析(多账号面)。
///
/// 0.2.15 起**不再兜底成字面量 `"ctp"`**:多账号下"空网关"必须显式落到
/// `fallback`(= [`UiShared::default_gateway`] 的阶梯:行级带入 → 上次选择 →
/// 第一个已连接账户);一个账户都没有时回 `Err`,界面据此禁用下单钮。
/// 单账号旧行为仍成立(fallback 就是那个账户的派生名)。
pub fn parse_gateway(raw: &str, fallback: Option<&str>) -> Result<String, String> {
    let g = raw.trim();
    if !g.is_empty() {
        if g.chars().any(|c| c.is_whitespace()) {
            return Err(format!("网关解析: 含空白:{raw:?}"));
        }
        return Ok(g.to_string());
    }
    match fallback.map(|f| f.trim()).filter(|f| !f.is_empty()) {
        Some(f) => Ok(f.to_string()),
        None => Err("网关解析: 未选择账户(先在账户面板添加账户)".to_string()),
    }
}

/// CTP 网关配置表单(S6 测试面;界面手工输入源 → UiCmd::CtpConfigure →
/// ask `ctp.configure`。零配置口径:界面不读文件,值全部人敲;密码位掩码)。
#[derive(Debug, Clone, PartialEq)]
pub struct CtpForm {
    pub broker_id: String,
    pub td_addr: String,
    pub td_user: String,
    pub td_password: String,
    pub td_auth_code: String,
    pub td_app_id: String,
    pub md_addr: String,
    pub md_user: String,
    pub md_password: String,
    /// 订阅标的(逗号分隔;`订阅行情` 钮解析)。
    pub symbols: String,
    /// 收录勾选(ek-ctp 0.6.0 D-PC-FILTER):网关收录哪些产品类。
    /// 缺省只勾期货 —— 期权默认不勾,因为默认口径与改动前一致(只期货上抛)。
    pub accept_futures: bool,
    pub accept_options: bool,
}

/// 手写 `Default`(不能 derive:`accept_futures` 必须为 `true`,derive 会给 `false`,
/// 而两个都 false 在语义上是「什么都不收录」)。
impl Default for CtpForm {
    fn default() -> Self {
        Self {
            broker_id: String::new(),
            td_addr: String::new(),
            td_user: String::new(),
            td_password: String::new(),
            td_auth_code: String::new(),
            td_app_id: String::new(),
            md_addr: String::new(),
            md_user: String::new(),
            md_password: String::new(),
            symbols: String::new(),
            accept_futures: true,
            accept_options: false,
        }
    }
}

impl CtpForm {
    /// 勾选 → CTP 产品类码表(期货 `'1'`、期权 `'2'`)。
    /// 两个都不勾交空表给插件:插件侧归一化一律回落默认期货 —— **空不等于全丢**
    /// (共享合约表为空会让网关的持仓查询整条被跳过)。
    #[must_use]
    pub fn product_classes(&self) -> Vec<String> {
        let mut codes = Vec::new();
        if self.accept_futures {
            codes.push("1".to_string());
        }
        if self.accept_options {
            codes.push("2".to_string());
        }
        codes
    }

    /// 表单 → 线上契约(字段直映;md 回落由插件侧裁决,表单不预处理)。
    pub fn to_configure_req(&self) -> ek_ctp::plugin::ConfigureReq {
        ek_ctp::plugin::ConfigureReq {
            broker_id: self.broker_id.trim().to_string(),
            td_addr: self.td_addr.trim().to_string(),
            td_user: self.td_user.trim().to_string(),
            td_password: self.td_password.clone().into(),
            td_auth_code: self.td_auth_code.trim().to_string(),
            td_app_id: self.td_app_id.trim().to_string(),
            md_addr: self.md_addr.trim().to_string(),
            md_user: self.md_user.trim().to_string(),
            md_password: self.md_password.clone().into(),
            product_classes: self.product_classes(),
        }
    }

    /// 订阅位解析(逗号/空白分隔;空表 = Err)。
    pub fn parse_symbols(&self) -> Result<Vec<String>, String> {
        let list: Vec<String> = self
            .symbols
            .split([',', '，', ' '])
            .map(|s| s.trim().to_string())
            .filter(|s| !s.is_empty())
            .collect();
        if list.is_empty() {
            return Err("订阅解析: 标的位空".to_string());
        }
        Ok(list)
    }

    /// 添加/连接前的形制校验(规划 U7:旧口径是"前置为空照样建账户并下发两令")。
    ///
    /// 判据:`tcp://host:port` 形制(host 非空、端口为 1..=65535 的十进制)、
    /// broker/账号非空、AppID/AuthCode 非空(CTP 登录必需,空值只会换来一次注定失败的登录)。
    /// **md 前置允许为空** = 纯 TD 账户(单源纪律:非行情源不建 MD 会话)。
    ///
    /// 返回 `Err(第一条原因)` —— 界面红字呈现,不当『添加』按钮的硬拦截前置条件之外的东西
    /// (校验只在『添加』『连接』两条入口上跑,低层口 `add_account` 不重复校验)。
    pub fn validate(&self) -> Result<(), String> {
        fn front(name: &str, v: &str) -> Result<(), String> {
            let v = v.trim();
            let Some(rest) = v.strip_prefix("tcp://") else {
                return Err(format!("{name} 形制应为 tcp://host:port(当前 {:?})", v));
            };
            let Some((host, port)) = rest.rsplit_once(':') else {
                return Err(format!("{name} 缺端口:{name} {:?}", v));
            };
            if host.trim().is_empty() {
                return Err(format!("{name} 主机位空:{}", v));
            }
            let port: u32 = port
                .parse()
                .map_err(|_| format!("{name} 端口不是数字:{}", v))?;
            if port == 0 || port > 65535 {
                return Err(format!("{name} 端口越界(1..=65535):{}", v));
            }
            Ok(())
        }
        if self.broker_id.trim().is_empty() {
            return Err("broker 位空".to_string());
        }
        if self.td_user.trim().is_empty() {
            return Err("交易账号位空".to_string());
        }
        front("td 前置", &self.td_addr)?;
        if !self.md_addr.trim().is_empty() {
            front("md 前置", &self.md_addr)?;
        }
        if self.td_app_id.trim().is_empty() {
            return Err("AppID 位空(CTP 登录必需)".to_string());
        }
        if self.td_auth_code.trim().is_empty() {
            return Err("AuthCode 位空(CTP 登录必需)".to_string());
        }
        Ok(())
    }
}

/// 账户装配四态(0.2.18,规划 §3.3「添加 ≠ 连接 ≠ 断开 ≠ 移除」)。
///
/// 口径边界(诚实):这一层只说**实例装配**,不说登录 —— 登录成败/掉线 ek-ctp 无状态口
/// 可查(开放项 `ctp.status`,规划裁定 3:状态机等终态口,不做 eLog 自建过渡)。
/// 因此 `Assembled` 的界面文案必须是「已装配·登录态未知」(短形:状态列宽有限,
/// 长文案会被 Grid 挤成竖排 —— s39 快照实锤过),不得写成「已连接」。
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum AccountStage {
    /// 未装配:添加后未连接、实例已摘、或装配失败后未重试。
    #[default]
    NotAssembled,
    /// 装配中:`UiCmd::Connect` 已入列,svctl 还没把这个注册名带回在场表。
    Assembling,
    /// 实例已装配(登录态未知)。
    Assembled,
    /// 装配失败:`svctl.start` 被拒/超时,或 `{gw}.configure` 被拒。可重试。
    AssembleFailed,
}

impl AccountStage {
    /// 界面文案(状态列 / 徽标)。
    #[must_use]
    pub fn label(self) -> &'static str {
        match self {
            AccountStage::NotAssembled => "未装配",
            AccountStage::Assembling => "装配中…",
            // 规划 §3.5 缓解:不让「已装配」被读成「在线」。
            // (文案长度有实测约束:账户面板是 Grid,状态列文案过长会被挤成竖排换行。)
            AccountStage::Assembled => "已装配·登录态未知",
            AccountStage::AssembleFailed => "装配失败",
        }
    }
}

/// 登录态(0.2.19;事实源 = ek-ctp 0.9.0 `{gw}.status`,规划 P3 / 裁定 3)。
///
/// 与 [`AccountStage`] 是**两件事**:stage 说「实例在不在」,这一档说「会话活着没有」。
/// 状态列把两者拼起来(`AccountRow::status_label`)。
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum LoginState {
    /// 还没读到读数,或读到了但没有任何登录证据。
    ///
    /// 网关的「句柄已建」(**`td_handle_up`**)**不等于在线** —— 掉线时它仍是真
    /// (ek-ctp DESIGN D-STATUS ①),所以没有 `logged_in` 就只有这一档,不得显示「在线」。
    #[default]
    Unknown,
    /// 网关回报 `td_logged_in`(纯行情账户看 `md_logged_in`)—— 在线的唯一硬证据。
    Online,
    /// 最近一次登录失败(网关在成功后会清零这一位,所以它显形 = 现在就是登不上)。
    LoginFailed,
    /// 柜台断过线且当前未登录(`td_disconnects > 0`;计数跨重连保留)。
    FrontDown,
    /// 登录着但查询连续被拒 / 资金回报超时(规划 Q10 两判据,阈值在界面)。
    QueryStarved,
    /// 用户主动『断开』(规划裁定 1):会话已停,实例与订阅还在,『连接』可恢复。
    Stopped,
}

impl LoginState {
    /// 状态列短文案(账户面板是 Grid,长文案会被挤成竖排 —— s39 快照实锤过)。
    #[must_use]
    pub fn label(self) -> &'static str {
        match self {
            LoginState::Unknown => "登录态未知",
            LoginState::Online => "在线",
            LoginState::LoginFailed => "登录失败",
            LoginState::FrontDown => "掉线",
            LoginState::QueryStarved => "查询断供",
            LoginState::Stopped => "已断开",
        }
    }

    /// 这一档要不要在状态列上着色(红/橙)。
    #[must_use]
    pub fn is_alarm(self) -> bool {
        matches!(self, LoginState::LoginFailed | LoginState::FrontDown)
    }
}

/// 「掉线 N 次」这类细节:N = 0 回 `None` —— 没有发生过就不该占状态列的位置。
fn count_note(label: &str, n: u32) -> Option<String> {
    (n > 0).then(|| format!("{label} {n} 次"))
}

/// 柜台错误原句 → **短原因**(账户行状态列用)。原句形状照 ek-ctp `map::error_text`
/// (`map.rs:332-333`)= `{消息}，代码：{id}，信息：{正文}`。
///
/// 取「信息」的正文(去掉 CTP 侧的 `CTP:` 前缀)并把代码括在后面 = `不合法的登录(3)`。
/// 形状对不上(网关没回带原因、或不是这条格式)就回 `None` —— 状态列宁可只写「登录失败」,
/// 也不编一个原因出来。
fn brief_counter_reason(full: &str) -> Option<String> {
    let tail = full.rfind("信息：").map(|i| &full[i + "信息：".len()..])?;
    let body = tail.trim().trim_start_matches("CTP:").trim();
    if body.is_empty() {
        return None;
    }
    let code = full
        .rfind("代码：")
        .map(|i| {
            let rest = &full[i + "代码：".len()..];
            let end = rest.find('，').unwrap_or(rest.len());
            rest[..end].trim().to_string()
        })
        .filter(|c| !c.is_empty() && c.parse::<i64>().is_ok());
    Some(match code {
        Some(c) => format!("{body}({c})"),
        None => body.to_string(),
    })
}

/// 账户行(多账号面;规划 §5.B + 0.2.18 四态)。
///
/// 界面是账户清单的**唯一事实源**(不新增"账户注册表"插件):
/// 网关实例的在场由 `svctl.list` 回填,身份与凭据留在这一行,**每账户一份 form**
/// (旧「全界面共享一张表单」已退役 → 消 U4 凭据串味 / U6 取消编辑不清空)。
#[derive(Debug, Clone, PartialEq, Default)]
pub struct AccountRow {
    /// 派生注册名(`ctp_<broker>_<账号>`;**寻址唯一用这个**,别名不参与)。
    pub gateway: String,
    /// 用户别名(显示用,可空 = 回退账号;唯一性由 `add_account` 校验,规划 Q3)。
    pub alias: String,
    pub broker_id: String,
    pub account: String,
    /// 是否行情元账号(**全局单源**——用户裁定"单数据源";已装配后锁定,规划 D3)。
    pub md_source: bool,
    /// 该账户自己的表单留档(编辑弹窗回填用;密码只存内存,裁定 2:不持久化)。
    pub form: CtpForm,
    /// **档案复原标(0.9.0)**:这一行来自启动清点(`%APPDATA%\ek\cfg` 的存档段),
    /// 不是本次会话手输的。呈现面:行上「档案」徽标 + 编辑弹窗密码位显示
    /// 「密库引用,不回显」;行为面:「连接」= `UiCmd::Start`(存档直连),
    /// **不走表单 configure** —— 存档的密码在密库,不在表单里,发空表单只会把
    /// 空密码受理下去(这就是复原行必须走 svctl.start 的唯一理由)。
    pub restored: bool,
    /// **自动连接勾选(0.9.0)**:手点才置位 + 落盘标记;**只存 ui 段**
    /// (账户行为面归界面档案,不进网关段 —— 2026-10-28 用户裁定「编排归
    /// station/界面层,网关只当哑网关」的落点)。消费方:守护复原(ek-station
    /// boot 清点 = 开则起连)与桌面启动清点(不复原 spawn,行列出后手点「连接」)。
    pub auto_connect: bool,
    /// **密码密库引用在位**(0.9.0;只读元信息,来自存档段的 `Field::secret`
    /// 引用行)。呈现面:复原行密码位显示「密库引用 ✓」;它**不是**密码本身,
    /// 也不参与任何连接判据(实例 on_start 才解密,ek-ctp BD-CFG-16)。
    /// 手输行恒为 `false`(受理受理面另有实况档位口 `credentials_state`)。
    pub password_ref: bool,
    /// 装配四态(规划 §3.3)。
    pub stage: AccountStage,
    /// 装配失败原因(`AssembleFailed` 时留显形;成功即清空)。
    pub fail_note: Option<String>,
    /// **网关实际收录回带值**(`ConfigureReply.product_classes`,规划 U9)。
    ///
    /// 与 `form.accept_*`(用户勾选)并排显示:勾选是意图,这一栏是事实。
    /// 空 = 尚未装配过或旧版网关未回带。
    pub effective_classes: Vec<String>,
    /// **入向异常计数(0.9.34 交易网关表)**:`{gw}.status` 回带的 `td_anomalies.total` /
    /// `md_anomalies.total`(ek-ctp 0.12.0「入向零丢弃」波的显形面)。
    ///
    /// 语义:柜台报文里有**认不出**的交易所码 / 状态码 / 时间戳 / 方向 / 缺委托号的成交 …
    /// 网关不丢包,一律折算成可读值并把次数记在这里;`0` = 没遇到过异常。
    /// 与 `login` 正交:异常多不代表掉线,但**非零就要有人看**(数据可能被折算)。
    pub td_anomaly: u32,
    /// 行情侧入向异常计数(同上,`md_anomalies.total`)。
    pub md_anomaly: u32,
    /// 在场位(由 `svctl.list` 快照回填:该注册名在不在 = 实例已装配)。
    /// 0.2.19 起登录成败另有事实源(`{gw}.status` → `login`),这一位只管实例。
    pub connected: bool,
    /// **登录态(0.2.19)**:`{gw}.status` 读数折出来的,与 `stage`/`connected` 正交。
    ///
    /// 默认 `Unknown`:装配成功本身不构成任何登录证据(ek-ctp D-STATUS ①)。
    pub login: LoginState,
    /// 状态细节(「掉线 2 次」「查询连续被拒 3 次」「资金回报已 45s 未更新」)。
    /// `None` = 没有可说的细节(不是「一切正常」——一切正常由 `login` 说)。
    pub status_note: Option<String>,
    /// **柜台原因的短标签(0.4.1 十期 BD-UI-63)**:登录失败/掉线时从 `td_last_error` 里
    /// 抠出「代码：N」与「信息：」的正文,给账户行的状态列用(红字后面直接跟着原因)。
    ///
    /// 为什么不直接把整句塞进状态列:柜台原句是「交易服务器登录失败，代码：3，信息：CTP:不
    /// 合法的登录」这种长句,Grid 状态列被它挤宽就会把别的列顶窄(s39 那口径)。整句留在
    /// `status_note` 里,窗下方「状态细节」那一行照旧给全。
    pub login_brief: Option<String>,
    /// **链状态(0.5.0,用户定「链进行的状态改为事件日志推送」)**:该网关最近一条 `[链] `
    /// 状态行的正文(去掉前缀)。
    ///
    /// 事实源是 ek-ctp 0.9.8 推送的日志(前置已连接 / 授权通过 / 登录成功 / 结算单已确认 /
    /// 查询合约 第N次 / 合约已到手开始轮询 / 合约未到手本轮已停止 / 会话已复位),不是轮询读数。
    /// `None` = 这一条会话还没推过状态行(显示「—」)。**它只是显示**:不参与 `apply_status`
    /// 那套在线/断供判据,也不参与任何下单判据。
    pub chain_note: Option<String>,
}

impl AccountRow {
    /// 派生入口(兼容 1 参 = 在场清单空;多前置判定见 `derive_with`)。
    pub fn derive(form: &CtpForm) -> Result<Self, String> {
        Self::derive_with(form, &[])
    }

    /// 由表单派生账户行(派生名唯一入口 = `appconfig::unique_gw_name`,0.9.10)。
    ///
    /// `taken` = 在场清单 `(gw, broker, 账号, td 前置)`:
    /// - 三处全同 = `Err`(同前置不重复登记);
    /// - 同 broker+账号 而 td 前置不同 = 自动后缀 `_2/_3…`(用户裁定「一账号多套
    ///   前置,别名备注切换」,IP 相同端口不同也算两套)。
    ///
    /// 返回 `Err(原因)` = broker/账号非法、派生名超 32 字符或重复;
    /// 界面须红字呈现,**不得静默替换**(规划 §3)。
    pub fn derive_with(
        form: &CtpForm,
        taken: &[(String, String, String, String)],
    ) -> Result<Self, String> {
        let broker = form.broker_id.trim();
        let account = form.td_user.trim();
        let gateway =
            crate::appconfig::unique_gw_name(taken, broker, account, form.td_addr.trim())?;
        Ok(Self {
            gateway,
            alias: String::new(),
            broker_id: broker.to_string(),
            account: account.to_string(),
            md_source: false,
            form: form.clone(),
            stage: AccountStage::NotAssembled,
            fail_note: None,
            effective_classes: Vec::new(),
            td_anomaly: 0,
            md_anomaly: 0,
            connected: false,
            login: LoginState::Unknown,
            status_note: None,
            login_brief: None,
            chain_note: None,
            // 本次会话手输/派生的行:非档案、非自动连接(0.9.0;复原行的两标
            // 在 `restore_saved_accounts_from` 里置位)。
            restored: false,
            auto_connect: false,
            password_ref: false,
        })
    }

    /// 状态列文案(装配态 + 登录态拼一起)。
    ///
    /// 「已装配」后面必须跟着登录态,不能光写「已装配」——0.2.18 那条「不得读成在线」
    /// 的口径(规划 U5)现在有了真读数才真正立住:没有证据时写「已装配·登录态未知」。
    /// 装配段一律走 `AccountStage::label()`,不在这里重抄一遍文案(两处不同式就是坑)。
    #[must_use]
    pub fn status_label(&self) -> String {
        if self.stage == AccountStage::Assembled {
            match self.login {
                LoginState::Unknown => "已装配·登录态未知".to_string(),
                other => format!("已装配·{}", other.label()),
            }
        } else {
            self.stage.label().to_string()
        }
    }

    /// 把 `{gw}.status` 读数折成界面登录态 + 细节(0.2.19;规划 P3 / Q10)。
    ///
    /// 判据顺序写明(每条都有理由):
    /// 1. **登录失败先判** —— 网关在登录成功后会清零 `td_login_failed`,所以它显形就是现在登不上;
    /// 2. **登录着** → 才谈「查询断供」,三条判据:连续被拒达阈 / 距最后一次资金回报超时 /
    ///    **登录后资金回报从未到手且已超过同一个 stale 阈值**(0.2.21,实连 S15f 逼出来的第三条);
    ///    都没中 = 在线;
    /// 3. **没登录** → 用户主动『断开』优先(那是自己按的钮,比柜台掉线计数更贴近用户意图),
    ///    其次才是柜台掉线(`disconnects > 0`),最后才是「未知」;
    /// 4. **纯行情账户**(td 前置留档为空)看 MD 半边 —— 看 TD 半边永远是「未知」,那是假信息。
    ///
    /// 「从未发生」= `None` 不当 0 用:网关没回报过资金时刻 ≠ 「0 秒前刚回报过」。
    pub fn apply_status(
        &mut self,
        st: &ek_ctp::plugin::GatewayStatus,
        now_ms: i64,
        reject_limit: u32,
        stale_secs: i64,
    ) {
        // 入向异常计数(0.9.34):读数口直取,不参与 login 判定 —— 只显形。
        self.td_anomaly = st.td_anomalies.total;
        self.md_anomaly = st.md_anomalies.total;
        let td_side = !self.form.td_addr.trim().is_empty();
        let (login, note) = if td_side {
            if st.td_login_failed && !st.td_logged_in {
                (
                    LoginState::LoginFailed,
                    st.td_last_error
                        .clone()
                        .or_else(|| Some("登录失败(网关未回带原因)".to_string())),
                )
            } else if st.td_logged_in {
                if st.td_query_reject_streak >= reject_limit {
                    (
                        LoginState::QueryStarved,
                        Some(format!("查询连续被拒 {} 次", st.td_query_reject_streak)),
                    )
                } else if let Some(last) = st.td_last_account_ms {
                    let idle_ms = now_ms.saturating_sub(last);
                    if idle_ms > stale_secs.saturating_mul(1_000) {
                        (
                            LoginState::QueryStarved,
                            Some(format!("资金回报已 {}s 未更新", idle_ms / 1_000)),
                        )
                    } else {
                        (LoginState::Online, count_note("掉线", st.td_disconnects))
                    }
                } else {
                    // 登录成功但资金一次都没到手。轮转第一拍本就要 2~6 秒(ek-ctp 0.7.0 口径),
                    // 所以刚登录那几秒只算「尚未到手」不算断供;但**"从未到手"不能永远算在线** ——
                    // 2026-10-22 实连 S15f 实测:账户 B `logged_in=true`、查询被拒 0 次、
                    // 资金时刻 `None` 持续 390 秒以上,界面上却一直显示「在线 + 资金回报尚未到手」。
                    // 超过同一个 stale 阈值就翻「查询断供」:判据原料齐了(登录时刻 + 读数时刻),
                    // 不需要网关多给任何东西。
                    let since_login_ms = st.td_last_login_ok_ms.map(|ok| now_ms.saturating_sub(ok));
                    match since_login_ms {
                        Some(ms) if ms > stale_secs.saturating_mul(1_000) => (
                            LoginState::QueryStarved,
                            Some(format!("资金回报从未到手(登录已 {}s)", ms / 1_000)),
                        ),
                        _ => (LoginState::Online, Some("资金回报尚未到手".to_string())),
                    }
                }
            } else if self.login == LoginState::Stopped {
                let extra = if st.td_disconnects > 0 {
                    format!("(此前掉线 {} 次)", st.td_disconnects)
                } else {
                    String::new()
                };
                (
                    LoginState::Stopped,
                    Some(format!("会话已停{extra};『连接』可恢复")),
                )
            } else if st.td_disconnects > 0 {
                (
                    LoginState::FrontDown,
                    Some(format!("掉线 {} 次", st.td_disconnects)),
                )
            } else {
                (LoginState::Unknown, st.td_last_error.clone())
            }
        } else if st.md_logged_in {
            (
                LoginState::Online,
                count_note("掉线", st.md_disconnects)
                    .or_else(|| Some("纯行情账户(无 TD 会话)".to_string())),
            )
        } else if self.login == LoginState::Stopped {
            (
                LoginState::Stopped,
                Some("会话已停;『连接』可恢复".to_string()),
            )
        } else if st.md_disconnects > 0 {
            (
                LoginState::FrontDown,
                Some(format!("掉线 {} 次", st.md_disconnects)),
            )
        } else {
            (LoginState::Unknown, st.md_last_error.clone())
        };
        // 0.9.1 分项接上(随 ek-ctp 0.9.1):总数与连续串**不分路**(消费侧要的是
        // 「查询这条路连续被拒几次」),但用户要知道被拒的是哪一路 —— 合约一条没到手时,
        // 下一笔单会被 ContractGate 以 `contract:unknown` 拒掉,而状态列只写「在线」
        // 就是假信息。加在句尾而不是另开一行:Grid 列宽会被长文案挤成竖排(s39 实锤)。
        let note = if td_side && st.td_instrument_rejects > 0 {
            let add = format!("合约查询被拒 {} 次", st.td_instrument_rejects);
            match note {
                // 已经点名过合约查询的句子不重复加。
                Some(base) if base.contains("合约查询被拒") => Some(base),
                Some(base) => Some(format!("{base};{add}")),
                None => Some(add),
            }
        } else {
            note
        };
        self.login = login;
        self.status_note = note;
        // 告警态(登录失败 / 掉线)才配「柜台原因」短标签:在线、未知、已断开都不占状态列。
        // 这一位是账户行红字后面那段原因的**唯一来源**(BD-UI-63)。
        self.login_brief = if login.is_alarm() {
            st.td_last_error
                .as_deref()
                .or(st.md_last_error.as_deref())
                .and_then(brief_counter_reason)
        } else {
            None
        };
    }

    /// 显示名:别名优先,空则回退账号(寻址仍只用 `gateway`,规划 Q3)。
    #[must_use]
    pub fn display_name(&self) -> String {
        let a = self.alias.trim();
        if a.is_empty() {
            self.account.clone()
        } else {
            a.to_string()
        }
    }
}

/// 交易监控快照(渲染侧读的那一份;0.5 起它是四本 keyed 账的缓存视图,
/// 不再是「eTimer 拍 ask oms 全量查询组帧」的产物)。
#[derive(Debug, Clone, PartialEq, Default)]
pub struct TradeSnap {
    pub orders: Vec<ek_data::order::OrderData>,
    pub trades: Vec<ek_data::trade::TradeData>,
    pub positions: Vec<ek_data::position::PositionData>,
    /// 资金帧(oms.get_all_accounts;CTP configure 登录后有数)。
    pub accounts: Vec<ek_data::account::AccountData>,
}

/// CSV(每行 `dt,open,high,low,close,volume`;dt 为 epoch 秒)→ BarData 批。
/// 错行报行号;空 csv = Err;升序不强制(dm.reload 自会逐行入窗)。
pub fn parse_reload_csv(form: &ReloadForm) -> Result<(i64, String, Vec<BarData>), String> {
    let interval: i64 = form
        .interval
        .trim()
        .parse()
        .map_err(|_| format!("回灌 解析: interval 非整数:{:?}", form.interval))?;
    let symbol = form.symbol.trim().to_string();
    if symbol.is_empty() {
        return Err("回灌解析: symbol 空".to_string());
    }
    if form.csv.trim().is_empty() {
        return Err("回灌解析: csv 空".to_string());
    }
    let mut bars = Vec::new();
    for (i, raw) in form.csv.lines().enumerate() {
        let line = raw.trim();
        if line.is_empty() || line.starts_with('#') {
            continue;
        }
        let parts: Vec<&str> = line.split(',').map(str::trim).collect();
        if parts.len() != 6 {
            return Err(format!("回灌解析: 第 {} 列数 ≠ 6", i + 1));
        }
        let num = |s: &str| -> Result<f64, String> {
            s.parse::<f64>()
                .map_err(|_| format!("回灌解析: 第 {} 列数值坏:{:?}", i + 1, s))
        };
        let dt_s: i64 = parts[0]
            .parse()
            .map_err(|_| format!("回灌解析: 第 {} 列 dt 坏:{:?}", i + 1, parts[0]))?;
        bars.push(BarData {
            symbol: symbol.clone(),
            datetime: dt_s * 1_000_000_000,
            interval: Some(
                ek_dm::wire::interval_of_seconds(interval)
                    .unwrap_or(ek_data::constant::Interval::MINUTE),
            ),
            open_price: num(parts[1])?,
            high_price: num(parts[2])?,
            low_price: num(parts[3])?,
            close_price: num(parts[4])?,
            volume: num(parts[5])?,
            // ── CSV 只有六列(ts,o,h,l,c,v),其余字段显式给值,不靠 `..Default` ──
            // 回灌的 K 线来自文件、不属于任何网关,所以网关名留空。
            gateway_name: String::new(),
            // 也同样不知道是哪个交易所,给 UNKNOWN 而不是猜一个(猜错比留空危险)。
            exchange: ek_data::constant::Exchange::UNKNOWN,
            // 成交额/持仓量/涨跌幅 **CSV 里没有**。写 0 有歧义(0 可能是真 0,
            // 也可能是没数据);根治要改成 Option<f64>,属于 ek-data 破坏性变更,
            // 单独决策后再动。此处先显式写出来,至少不再是"靠默认悄悄变 0"。
            turnover: 0.0,
            open_interest: 0.0,
            pct_change: 0.0,
        });
    }
    if bars.is_empty() {
        return Err("回灌解析: 无有效行".to_string());
    }
    Ok((interval, symbol, bars))
}

// ================= v4 布局面(带/组 tab / tick 库 / 下单表单;docs/ek-ui-layout-v2-plan.md) =================

/// 左上组 tab(Python [委托|未成交];审计修正:行情是带不是 tab,K线/运维/CTP
/// 是弹窗不是 tab,故不设全局 10 值 UiTab——那是 v2 残影)。
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum TopLeftTab {
    #[default]
    Orders,
    Active,
}

impl TopLeftTab {
    pub fn label(self) -> &'static str {
        match self {
            Self::Orders => "委托",
            Self::Active => "未成交",
        }
    }
}

/// 右下组 tab(Python [资金|日志])。
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum BottomRightTab {
    #[default]
    Account,
    Logs,
}

impl BottomRightTab {
    pub fn label(self) -> &'static str {
        match self {
            Self::Account => "资金",
            Self::Logs => "日志",
        }
    }
}

/// 数据区两刀的份额(0.4.1 BD-UI-54)。Python `right_splitter` = vertical 50:50,
/// 我们的左右刀与之正交;两值都夹在 `crate::splitters::clamp_frac` 界内。
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct DataSplit {
    /// 左右刀:左列占比(委托|未成交 在左)。
    pub col: f32,
    /// 上下刀:上行占比(委托/成交 在上)。
    pub row: f32,
}

impl Default for DataSplit {
    fn default() -> Self {
        Self {
            col: crate::splitters::DATA_SPLIT_DEFAULT,
            row: crate::splitters::DATA_SPLIT_DEFAULT,
        }
    }
}

/// 行情带六所固定 tab 序(0.4.1 BD-UI-54:六所各一格 = 用户裁定「每个交易所
/// 都要一个」;原 `crate::dock::MARKET_ORDER` 随 dock 拆除,常量原样搬到这里)。
pub const MARKET_ORDER: [ek_data::constant::Exchange; 6] = [
    ek_data::constant::Exchange::SHFE,
    ek_data::constant::Exchange::DCE,
    ek_data::constant::Exchange::CZCE,
    ek_data::constant::Exchange::CFFEX,
    ek_data::constant::Exchange::INE,
    ek_data::constant::Exchange::GFEX,
];

// 0.2.30(BD-UI-46,裁定 8):主题面整块删除 —— 只保留一套主题(当时 = Qt深色
// qdarkstyle 3.2.3 复刻;0.4.1 四期 BD-UI-57 换成 shadcn Nova 深色,「只有一套」这条
// 裁定不变,换的是值),视觉规格搬进 `crate::tokens`。原来的 `Theme` 五变体枚举、
// `label()`、`next()` 循环、`UiShared::theme()/set_theme()/cycle_theme()`、菜单循环钮
// 全部退役。这是一次**有意的公共面收缩**:`ek_ui::state::Theme` 不再存在。外部没有任何
// crate 依赖 ek-ui,所以收缩不触发联动;但它不可逆,记在 CHANGELOG 0.2.30。

/// tick 库(v2 行情 tab 唯一数据源):symbol → 最新 tick,逐 symbol 覆盖,
/// 有界 = 订阅面(ek-ctp 只发已订阅合约;无 bar 回落,用户裁定)。
#[derive(Debug, Default)]
pub struct TickStore {
    ticks: BTreeMap<String, ek_data::tick::TickData>,
}

impl TickStore {
    /// 逐合约覆盖(审计修正:键 = en_symbol「交易所.合约」,防跨所同码相撞;
    /// 交易所分组取 tick 自带 exchange)。
    pub fn put(&mut self, t: &ek_data::tick::TickData) {
        self.ticks
            .insert(format!("{}.{}", t.exchange.as_str(), t.symbol), t.clone());
    }

    /// 只读视图(交易所 → 合约排序,tab 分组顺序稳定)。
    pub fn rows(&self) -> Vec<ek_data::tick::TickData> {
        let mut v: Vec<ek_data::tick::TickData> = self.ticks.values().cloned().collect();
        v.sort_by(|a, b| {
            (a.exchange.as_str().to_string(), a.symbol.clone())
                .cmp(&(b.exchange.as_str().to_string(), b.symbol.clone()))
        });
        v
    }

    /// 按交易所分组(tab 键只列有 tick 的所,不预置全枚举)。
    pub fn groups(&self) -> Vec<(String, Vec<ek_data::tick::TickData>)> {
        let mut out: Vec<(String, Vec<ek_data::tick::TickData>)> = Vec::new();
        for t in self.rows() {
            let ex = t.exchange.as_str().to_string();
            match out.last_mut() {
                Some((e, v)) if *e == ex => v.push(t),
                _ => out.push((ex, vec![t])),
            }
        }
        out
    }

    pub fn len(&self) -> usize {
        self.ticks.len()
    }

    pub fn is_empty(&self) -> bool {
        self.ticks.is_empty()
    }
}

/// 下单面板表单(v2 常驻右侧;Python TradingWidget 字段面等价;操作面非配置面)。
#[derive(Debug, Clone, PartialEq)]
pub struct OrderForm {
    /// 交易所代码(下拉;from_str 抬成枚举)
    pub exchange: String,
    /// 合约代码(纯 symbol,不带前缀)
    pub symbol: String,
    pub direction: ek_data::constant::Direction,
    pub offset: ek_data::constant::Offset,
    pub order_type: ek_data::constant::OrderType,
    /// 输入面保持字符串(同 Python QLineEdit),委托时解析
    pub price: String,
    pub volume: String,
    /// 网关(下拉源 = trade_snap gateway 去重集 ∪ CTP 表单现值)
    pub gateway: String,
    /// 价格随行情勾选(勾选时价格框随选中合约最新 tick)
    pub follow_price: bool,
    /// 「自动开平」勾选(0.1.1 BD-UI-30;默认开 = LockMode::Auto 走拆单器,
    /// 关 = LockMode::None 原样旁路——守卫不可绕,拆单可逐请求旁路)
    pub auto_split: bool,
}

impl Default for OrderForm {
    fn default() -> Self {
        Self {
            exchange: "SHFE".to_string(),
            symbol: String::new(),
            direction: ek_data::constant::Direction::LONG,
            offset: ek_data::constant::Offset::OPEN,
            order_type: ek_data::constant::OrderType::LIMIT,
            price: String::new(),
            volume: "1".to_string(),
            gateway: String::new(),
            follow_price: true,
            auto_split: true,
        }
    }
}

impl OrderForm {
    /// 表单 → OrderRequest(与票据解析同一出口;错误红字就地,不进总线)。
    pub fn to_request(&self) -> Result<ek_data::order_request::OrderRequest, String> {
        use std::str::FromStr;
        let symbol = self.symbol.trim();
        if symbol.is_empty() {
            return Err("下单: 代码为空".to_string());
        }
        if symbol.contains('.') {
            return Err("下单: 代码不带交易所前缀(交易所走下拉)".to_string());
        }
        let exchange = ek_data::constant::Exchange::from_str(self.exchange.trim())
            .map_err(|e| format!("下单: {e}"))?;
        let price: f64 = self
            .price
            .trim()
            .parse()
            .map_err(|_| format!("下单: 价格无效 {:?}", self.price))?;
        let volume: f64 = self
            .volume
            .trim()
            .parse()
            .map_err(|_| format!("下单: 数量无效 {:?}", self.volume))?;
        if self.order_type != ek_data::constant::OrderType::MARKET && price <= 0.0 {
            return Err("下单: 限价单价格须为正".to_string());
        }
        if volume <= 0.0 {
            return Err("下单: 数量须为正".to_string());
        }
        Ok(ek_data::order_request::OrderRequest {
            symbol: symbol.to_string(),
            exchange,
            direction: self.direction,
            order_type: self.order_type,
            volume,
            price,
            offset: self.offset,
            ..ek_data::order_request::OrderRequest::default()
        })
    }
}

/// 合约库(v4 查询合约窗数据源):en_symbol → ContractData。
///
/// 数据面 = ek-ctp 登录后自动 reqQryInstrument 回流(`eContract.` 裸键逐条 +
/// `eContractFinish` 完成线,driver.rs:779)——**无 ask 口,UI 只收不催**
/// (用户裁定:订阅不在网关配置定死,查询窗勾选订阅 / 下单代码回车)。
#[derive(Debug, Default)]
pub struct ContractStore {
    contracts: BTreeMap<String, ek_data::contract::ContractData>,
}

impl ContractStore {
    pub fn put(&mut self, c: &ek_data::contract::ContractData) {
        self.contracts
            .insert(format!("{}.{}", c.exchange.as_str(), c.symbol), c.clone());
    }

    /// Python ContractManager 查询口径:代码/交易所/名称模糊,留空 = 全部。
    pub fn query(&self, pattern: &str) -> Vec<ek_data::contract::ContractData> {
        let p = pattern.trim();
        self.contracts
            .values()
            .filter(|c| {
                p.is_empty()
                    || c.symbol.contains(p)
                    || c.exchange.as_str().eq_ignore_ascii_case(p)
                    || c.name.contains(p)
            })
            .cloned()
            .collect()
    }

    pub fn len(&self) -> usize {
        self.contracts.len()
    }

    pub fn is_empty(&self) -> bool {
        self.contracts.is_empty()
    }
}

/// 插件面板与宿主观察线程共用的观测状态。
#[derive(Debug, Default)]
pub struct UiShared {
    /// 0.9.37:当前是否「配置相」(起跑前)。相内**不画**「下发指令」的钮 ——
    /// 消费指令的 ui-cmd 线程只在 ui 插件起跑后存在,点了没反应会让人以为按钮坏了。
    setup_phase: std::sync::atomic::AtomicBool,
    /// 档案根读不动的显形条(0.9.39;空表必须能自证原因)。
    store_err: Mutex<Option<String>>,
    /// 0.9.45:当前帧被真渲染过的模块窗 id(有头判据/取证用;每帧窗口循环开头清)。
    window_visible: Mutex<HashSet<String>>,
    logs: Mutex<LogRing>,
    snap: Mutex<Arc<BusSnap>>,
    market: MarketStore,
    ctp_form: Mutex<CtpForm>,
    /// 交易四本账(0.5 M1:事件驱动后的唯一事实源;键 = 基线 `data_key`)。
    /// 值带行序 `u64` —— 基线 `insert_new_row` 是 `insertRow(0)`(新事件在前)。
    trade_orders: Mutex<BTreeMap<String, (u64, ek_data::order::OrderData)>>,
    trade_trades: Mutex<VecDeque<(u64, ek_data::trade::TradeData)>>,
    /// 成交去重集(键 `en_tradeid` = `{网关}.{成交号}`)。
    ///
    /// 口径来自基线**引擎层** `BaseTradeEngine.trades_filter_dict`(`engine.py:1072-1080`,
    /// 注释写明它是为「账户重连时柜台重推同一笔成交」准备的),与 `ek-oms` 的
    /// `trades_filter`(`oms.rs:203 / 260-264`)同键同口径。成交表本身没有 `data_key`
    /// (基线 `TradeMonitor` :1267 只插不改),所以去重只能靠这张集,不能靠行键。
    /// 它跟着账本走:触顶被挤掉的行同时出集(那笔再推就还能上屏),摘网关时同网关一起清。
    trade_ids: Mutex<HashSet<String>>,
    trade_positions: Mutex<BTreeMap<String, (u64, ek_data::position::PositionData)>>,
    trade_funds: Mutex<BTreeMap<String, (u64, ek_data::account::AccountData)>>,
    /// 行序计数器(每次入账递增;快照按它降序排 = 新事件在前)。
    trade_seq: AtomicU64,
    /// 成交账本触顶丢弃计数(0.5 偏离③;>0 说明更早的成交已被丢掉)。
    trade_dropped: AtomicU64,
    /// 四本账 → 快照的重建标记(入账置真,`trade_snap()` 消费)。
    trade_dirty: AtomicBool,
    /// 渲染侧读的交易快照 = 四本账的缓存视图(脏时按帧重建一次)。
    trade_snap: Mutex<Arc<TradeSnap>>,
    tick_store: Mutex<TickStore>,
    order_form: Mutex<OrderForm>,
    /// 数据区 2×2 两刀的份额(0.4.1 BD-UI-54:拆 dock 后归薄 QSplitter;
    /// col = 左右刀的左占比,row = 上下刀的上占比,缺省 = Python right_splitter 50:50)。
    data_split: Mutex<DataSplit>,
    /// 行情带当前 tab(按所;六所固定 tab 条,谁在前台就是谁)。
    selected_exchange: Mutex<String>,
    /// 委托|未成交 组的当前 tab。
    topleft_tab: Mutex<TopLeftTab>,
    /// 资金|日志 组的当前 tab。
    bottomright_tab: Mutex<BottomRightTab>,
    ops_window: AtomicBool,
    /// 账户面板(多账号面;取代旧单账号 CTP 配置窗的入口 —— 旧窗已退役,
    /// 旧 `ctp_window` 位随之删除,不留死状态)。
    ///
    /// 0.9.34:开合搬到 [`crate::mount::Registry`](窗口 = 模块窗),本字段退役。
    contracts_window: AtomicBool,
    contract_store: Mutex<ContractStore>,
    contract_query: Mutex<String>,
    contract_selected: Mutex<Vec<String>>,
    kline_windows: Mutex<Vec<String>>,
    /// K线历史补数队列(I2 第一刀:开窗入队一次;命令线程消费走 tq `{gw}.klines`)。
    kline_fetches: Mutex<Vec<KlineFetch>>,
    /// 已补数集(同 (symbol,秒) 只补一次;开新窗/重开不重复拉)。
    kline_fetched: Mutex<HashSet<(String, i64)>>,
    rev: AtomicU64,
    /// 关窗/测试结束信号(窗口面置位,宿主观察线程消费)。
    stop: AtomicBool,
    /// svctl 操作指令队列(窗口面入,ui 插件 eTimer 出)。
    cmds: Mutex<VecDeque<UiCmd>>,
    /// 待二次确认的移除目标(单槽;再次同名点 = 发令)。
    pending_confirm: Mutex<Option<String>>,
    /// 账户清单(多账号面;界面唯一事实源)。
    accounts: Mutex<Vec<AccountRow>>,
    /// 账户配置弹窗开合(0.2.18 Commit B:『添加』与『编辑』同一弹窗两种模式)。
    account_edit_window: AtomicBool,
    /// 弹窗模式:`Some(派生名)` = 编辑该账户;**`None` = 添加新账户**(草稿位仍是 `ctp_form`)。
    editing_account: Mutex<Option<String>>,
    /// 弹窗里的别名草稿(『保存』时才写回账户行)。
    edit_alias: Mutex<String>,
    /// 弹窗内的拦截原因(校验不过 / 装配被拒):弹窗**不关**,原因上屏(规划 U3 / Q26)。
    edit_error: Mutex<Option<String>>,
    /// 行情元账号的注册名(空 = 未选;连接后锁定,规划 D3)。
    md_source: Mutex<String>,
    /// 订阅集(裸代码;断开重连后按它重放订阅,规划 §5.C)。
    subscriptions: Mutex<Vec<String>>,
    /// 表格行选中(BD-UI-31):表 id → 选中行键(每表一行;键由渲染侧构造,
    /// 纯界面态,不发指令;悬停跳色是渲染侧即时判断,不入状态)。
    row_sel: Mutex<BTreeMap<String, String>>,
    /// 0.3.1(Wave D,BD-UI-49)表格排序键:`表 id -> Some((列序, 升序))`,`None` = 不排序。
    /// 排序键住在界面状态,不进数据模型(W2 的判据就是这条 -- Python `widget.py:396-419`
    /// 那个「更新途中重排」的病,根因是排序作用在正在被喂的模型上)。
    table_sorts: Mutex<BTreeMap<String, Option<(usize, bool)>>>,
    /// 「列边界可拖」的开关(0.3.1 右键菜单「调整列宽」)已在 0.4.1 五期(BD-UI-58)退役:
    /// 可拖 + 列线是全部表的固定形制,不再是可开关的东西 → 字段与访问器一并删。
    /// 状态轮询游标(0.5 M3 摊平:每拍从游标起环形取 `STATUS_ASKS_PER_TICK` 个)。
    /// 0.7.0 第3刀:周期轮询退役(状态改吃 `eStatus.` 推送),这里只服务
    /// 「网关上线后的一次性播种」(每网关运行期至多一次 ask)。
    status_cursor: AtomicUsize,
    /// 一次性状态播种队列(0.7.0 第3刀):网关上线 → 问一次 `{gw}.status` 拿初始快照,
    /// 之后常态全靠 `eStatus.` 推送(界面零轮询)。
    status_seed: Mutex<Vec<String>>,
    /// `svctl.list` 轮询节拍计数(每 `LIST_POLL_TICKS` 拍一次)。
    list_tick: AtomicU32,
    /// 管制面快照的「现在就问」标记(0.5 执行核查补的洞):插件上/下线与 svctl 起停
    /// 之后必须立刻重问一次,否则在场位与运维窗那一行最多要等 4 拍才动 —— 0.4 是每拍
    /// 一次,这一档降下来就把「点了移除、行 4 秒不动」变成了常态。
    list_due: AtomicBool,
    /// 「重播种一次四张表」标记(0.5 执行核查补的第三处):网关或 oms 上线之后重问一次
    /// 四口。摘除一个网关账户会作废它名下的委托 / 成交行,而 oms 那边那些行还在 ——
    /// 重新添加时不重问一次,界面就永久少了一段历史。消费方是命令线程,不是 eTimer 拍。
    seed_due: AtomicBool,
    /// `oms.pipeline_status` 待问标记(0.5 M3:改事件触发 —— 启动 / oms 上线 / 手动刷新钮)。
    pipeline_due: AtomicBool,
    /// 配置托底段目录待问标记(0.6.0 环节8;启用 = 运维窗「刷新段落目录」钮)。
    cfg_due: AtomicBool,
    /// 配置托底段目录读数(0.6.0;`None` = 没问过 → 运维窗按句提示,不是空表;
    /// `Some(vec)`:零值面,`NsBrief` 只有 key/形态标志,BD-CFG-17/18)。
    cfg_briefs: Mutex<Option<Vec<ek_cfg::wire::NsBrief>>>,
    /// 清段二次确认臂(0.6.0;防误触,与 svctl 移除的 ConfirmStep 同形但独立)。
    cfg_delete_arm: Mutex<Option<String>>,
    /// **当前界面档(0.8.0 配色双档,BD-UI-61)**:`0 = Dark`(缺省)、`1 = Light`。
    /// 缺省 = 深色(裁定 B:没点过切换钮时现行为零变化)。AtomicU8 而不是 `Mutex<Theme>`:
    /// 渲染线程每帧读、命令线程偶发读,`Acquire/Release` 就够,不给每帧加锁。
    theme: AtomicU8,
    /// 主题落盘请求(0.8.0;只有**用户手点**切换钮才置位,照参考站「只有点击才存」)。
    /// 消费方是**命令线程**(写 ek-cfg 存储根 `ns="ui" key="theme"`)—— 渲染线程零文件 IO。
    theme_persist_due: AtomicBool,
    /// 自动连接落盘请求(0.9.0):**手点**「自动连接」勾选才置位;消费方 = 命令线程
    /// 把全部行的勾选态写进 `ns="ui"`(键 `auto_connect.<网关名>`,移除行清键)。
    /// 与主题同一支纪律:渲染线程零文件 IO,写档只在命令线程 eTimer 拍上。
    auto_connect_persist_due: AtomicBool,
    /// 别名落盘请求(0.9.10,用户裁定 2026-10-28「仿真/24小时 标签要能选」):
    /// 保存/改别名/摘行时置位;消费方 = 命令线程写 `ns="ui"` 键 `alias.<网关名>`
    /// (空别名 = 清键;摘户行清键)。与自动连接同一支纪律:渲染线程零文件 IO。
    alias_persist_due: AtomicBool,
    /// 档案抹除待办(0.9.10,用户实锤「删了的账户下次启动又显示」):摘行 = 内存清册
    /// 摘除 + 档案段 `ctp.{gw}` 也要抹(启动清点扫 `ctp.*` 段,档案不抹 = 账户复活)。
    /// 渲染线程只入队(零文件 IO),消费方 = 命令线程 `purge_account_archive`。
    archive_purge: Mutex<Vec<String>>,
    /// 推送线载荷类型异常的计数(0.5 M1:线名 → 次数)。不静默丢。
    bad_payload: Mutex<BTreeMap<String, u64>>,
    /// oms 装配显形的最新读数(`pipeline_status()` 的字符串行)。
    /// 空 = 没问到 / oms 不在场 → 运维窗整节不画(不是「画一个空表」)。
    pipeline_lines: Mutex<Vec<String>>,
    /// 「查询断供」阈值覆盖 `Some((连续被拒次数, 资金超时秒))`;`None` = 用缺省常量。
    /// 阈值住在界面不在网关(ek-ctp D-STATUS),覆盖位是给测试与后续配置面留的口子。
    status_thresholds: Mutex<Option<(u32, i64)>>,
    /// 0.3.2(Wave E,BD-UI-50)攒着待灌进 toast 队列的告警(界面层产生,渲染帧收口)。
    pending_alerts: Mutex<Vec<(crate::toast::AlertLevel, String)>>,
    /// 常驻 toast 队列(住在界面状态,不是 render 的局部变量 —— 否则 8 秒自动关与
    /// 同屏上限都没有意义)。`None` = 还没按我们的口径建过。
    toasts: crate::toast::ToastsCell,
    /// 已经弹过 toast 的告警键(去重:同一账户同一状态只弹一次,照 Python AlertEngine 的去重)。
    alerted: Mutex<std::collections::BTreeSet<String>>,
    /// 0.3.1(Wave D,BD-UI-49)退出确认窗是否开着(照 Python `closeEvent`:关窗先问一句)。
    exit_confirm_open: AtomicBool,
    /// 用户已在确认窗里点过「确认退出」—— 之后不再拦关闭(否则确认完也关不掉)。
    exit_confirmed: AtomicBool,
    /// 装配锁(0.9.5 阶段机):启动全成功后 = 装配面**只可看不可动**。
    /// 纯界面层旗(用户裁定「底层不写死」):svctl/插件本体不读它,只有界面认它。
    assembly_locked: AtomicBool,
    /// 引擎弱引用(0.9.34「一模块一菜单」波):模块窗要按实例名取插件句柄
    /// (`get_typed`) 才能渲染,但 `UiShared` 也被插件持有 —— 存 `Weak` 断环,
    /// 主循环每帧 `upgrade`,引擎不在场(None)= 窗口画「未就绪」。
    engine: Mutex<std::sync::Weak<ek_core::main_engine::MainEngine>>,
    /// 模块挂载表(0.9.34):一模块一菜单一窗;`svctl.start/remove` 后 `remount_modules`。
    modules: Mutex<crate::mount::Registry>,
    // ---------------- 策略交易(0.9.47) ----------------
    /// 策略行表:`实例名 → 行`。**单源是 ek-strategy 的推送** ——
    /// 界面不查、不推、不缓存第二份事实(渲染只读这里)。
    strategies: Mutex<BTreeMap<String, ek_strategy::contract::StrategyRow>>,
    /// 策略类元数据(「添加策略」弹窗的数据源;UI 上线时插件推一次全量)。
    strategy_metas: Mutex<Vec<ek_strategy::strategy::StrategyMeta>>,
    /// 编辑弹窗回填的参数(命令线程问 `strategy.get_settings` 后落到这里)。
    strategy_settings: Mutex<BTreeMap<String, Vec<(String, String)>>>,
    /// 弹窗预填用的最新价缓存(`symbol → price`)。
    strategy_prices: Mutex<BTreeMap<String, f64>>,
    /// 策略命令回执单槽(`add`/`edit` 用;渲染线程取走即清)。
    strategy_feedback: Mutex<std::collections::VecDeque<StratFeedback>>,
}

impl UiShared {
    // ---- 引擎 / 模块挂载(0.9.34) ----

    /// 记下引擎弱引用(runtime 装配完成后调一次)。
    pub fn install_engine(&self, engine: &std::sync::Arc<ek_core::main_engine::MainEngine>) {
        *self.engine.lock().unwrap() = std::sync::Arc::downgrade(engine);
    }

    /// 取引擎(主循环每帧;引擎已散 = None)。
    #[must_use]
    pub fn engine_arc(&self) -> Option<std::sync::Arc<ek_core::main_engine::MainEngine>> {
        self.engine.lock().unwrap().upgrade()
    }

    /// 模块挂载表(渲染/菜单用)。
    pub fn modules(&self) -> std::sync::MutexGuard<'_, crate::mount::Registry> {
        self.modules.lock().unwrap()
    }

    // ---- 策略交易(0.9.47) ----

    /// 吃一条策略推送并落进行表(`bump` 让下一帧重画)。
    ///
    /// 三条语义与插件侧严格对齐:
    /// - `Upsert` = 整行替换(不是字段合并);
    /// - `Removed` = 摘掉一行;
    /// - `Snapshot` = **整体替换**(UI 上线/重连后的重播,不能与旧行并存)。
    pub fn apply_strategy_event(&self, ev: &ek_strategy::contract::StrategyEvent) {
        use ek_strategy::contract::StrategyEvent as Ev;
        {
            let mut map = self.strategies.lock().unwrap();
            match ev {
                Ev::Upsert(row) => {
                    map.insert(row.name.clone(), (**row).clone());
                }
                Ev::Removed { name } => {
                    map.remove(name);
                }
                Ev::Snapshot(rows) => {
                    map.clear();
                    for r in rows {
                        map.insert(r.name.clone(), r.clone());
                    }
                }
            }
        }
        self.bump();
    }

    /// 策略类元数据(添加弹窗)。
    pub fn set_strategy_metas(&self, metas: Vec<ek_strategy::strategy::StrategyMeta>) {
        *self.strategy_metas.lock().unwrap() = metas;
        self.bump();
    }

    /// 策略类元数据(只读克隆;弹窗每帧要它)。
    #[must_use]
    pub fn strategy_metas(&self) -> Vec<ek_strategy::strategy::StrategyMeta> {
        self.strategy_metas.lock().unwrap().clone()
    }

    /// 全部行(按实例名有序,表序稳定)。
    #[must_use]
    pub fn strategy_rows(&self) -> Vec<ek_strategy::contract::StrategyRow> {
        self.strategies.lock().unwrap().values().cloned().collect()
    }

    /// 单行。
    #[must_use]
    pub fn strategy_row(&self, name: &str) -> Option<ek_strategy::contract::StrategyRow> {
        self.strategies.lock().unwrap().get(name).cloned()
    }

    /// 行数(`0` = 空态)。
    #[must_use]
    pub fn strategy_count(&self) -> usize {
        self.strategies.lock().unwrap().len()
    }

    /// 落一份参数回填(编辑弹窗)。
    pub fn set_strategy_settings(&self, name: &str, params: Vec<(String, String)>) {
        self.strategy_settings
            .lock()
            .unwrap()
            .insert(name.to_string(), params);
        self.bump();
    }

    /// 取参数回填(**取走即清**;弹窗只吃一次)。
    pub fn take_strategy_settings(&self, name: &str) -> Option<Vec<(String, String)>> {
        self.strategy_settings.lock().unwrap().remove(name)
    }

    /// 落一个最新价(弹窗预填)。
    pub fn set_strategy_price(&self, symbol: &str, price: f64) {
        self.strategy_prices
            .lock()
            .unwrap()
            .insert(symbol.to_string(), price);
        self.bump();
    }

    /// 取最新价。
    #[must_use]
    pub fn strategy_price(&self, symbol: &str) -> Option<f64> {
        self.strategy_prices.lock().unwrap().get(symbol).copied()
    }

    /// 队列上限:回执是"给用户看结果"的,不承载业务事实;爆了丢最老的。
    ///
    /// 2026-11-03 由单槽改队列:命令线程可能连发几条(启动/暂停/停止),
    /// 单槽会让前一条被后一条顶掉 —— 丢掉恰好是失败那条时,用户看到的就是"点了没反应"。
    pub const STRAT_FEEDBACK_CAP: usize = 32;

    /// 落一条命令回执(命令线程调)。
    pub fn set_strategy_feedback(&self, fb: StratFeedback) {
        {
            let mut q = self.strategy_feedback.lock().unwrap();
            if q.len() >= Self::STRAT_FEEDBACK_CAP {
                q.pop_front();
            }
            q.push_back(fb);
        }
        self.bump();
    }

    /// 把回执放回**队首**(渲染线程"这条不是给我的"用:顺序不能乱)。
    pub fn push_strategy_feedback_front(&self, fb: StratFeedback) {
        self.strategy_feedback.lock().unwrap().push_front(fb);
        self.bump();
    }

    /// 取走一条命令回执(渲染线程;取走即清,只消费一次)。
    pub fn take_strategy_feedback(&self) -> Option<StratFeedback> {
        self.strategy_feedback.lock().unwrap().pop_front()
    }

    /// 档案根读不动的**显形条**(0.9.39;`Some` = 网关窗顶部挂橙条,空表不再无声)。
    pub fn set_store_err(&self, msg: Option<String>) {
        *self.store_err.lock().unwrap() = msg;
        self.bump();
    }

    /// 读显形条(`None` = 档案清点正常)。
    #[must_use]
    pub fn store_err(&self) -> Option<String> {
        self.store_err.lock().unwrap().clone()
    }

    // ---- 0.9.45 窗可见性取证(有头 H12/H13 判据) ----

    /// 帧开头:清窗口可见集(`Registry::windows` 每帧调用)。
    pub fn begin_window_frame(&self) {
        self.window_visible.lock().unwrap().clear();
    }
    /// 某窗本帧被真渲染过(不是 set_open 的记账,是**真的走完渲染**)。
    pub fn note_window_visible(&self, id: &str) {
        self.window_visible.lock().unwrap().insert(id.to_string());
    }
    /// 判据问口:某窗最近一帧在不在屏。
    #[must_use]
    pub fn window_was_visible(&self, id: &str) -> bool {
        self.window_visible.lock().unwrap().contains(id)
    }
    /// 记「当前在配置相」(0.9.37;`StageApp` 构造时开,起跑时关)。
    pub fn set_setup_phase(&self, on: bool) {
        self.setup_phase
            .store(on, std::sync::atomic::Ordering::Release);
        self.bump();
    }

    /// 是否还在配置相(起跑前)。配置相里**不发**任何下发指令。
    #[must_use]
    pub fn in_setup(&self) -> bool {
        self.setup_phase.load(std::sync::atomic::Ordering::Acquire)
    }

    /// 重建挂载表(装配完成 / 起停插件后调;已有窗的开合与窗内态保留)。
    ///
    /// 0.9.40(用户实测「界面点击死卡」):**引擎扫描在锁外做完**。旧写法是持着
    /// 挂载表锁去扫引擎,而引擎在插件起停时会短暂持锁(装配 2~4 秒)→ 主界面
    /// 点菜单/开窗就跟着卡住。现在先扫(锁外)、再进锁写表(纯内存,微秒级)。
    pub fn remount_modules(&self) {
        let groups = crate::mount::scan_groups(self);
        let mut reg = self.modules.lock().unwrap();
        reg.sync_groups(&groups);
    }

    /// 空状态(快照空、日志空、rev 0)。
    pub fn new() -> Self {
        Self {
            // `always` 模块(交易网关)先建好 —— 没引擎、没装配也要能管账户档案。
            window_visible: Mutex::new(HashSet::new()),
            modules: Mutex::new(crate::mount::Registry::with_always()),
            ..Self::default()
        }
    }

    // ---- v2 布局面访问器(tick 库 / 表单 / 选中 / tab) ----

    /// 落一条 tick(eTick. 裸键上屏;逐 symbol 覆盖)。
    pub fn update_tick(&self, t: &ek_data::tick::TickData) {
        self.tick_store.lock().unwrap().put(t);
        self.bump();
    }

    /// tick 只读视图(排序后)。
    pub fn tick_rows(&self) -> Vec<ek_data::tick::TickData> {
        self.tick_store.lock().unwrap().rows()
    }

    /// tick 按交易所分组(行情 tab 二级 tab 键表)。
    pub fn tick_groups(&self) -> Vec<(String, Vec<ek_data::tick::TickData>)> {
        self.tick_store.lock().unwrap().groups()
    }

    /// tick 库格数。
    pub fn tick_count(&self) -> usize {
        self.tick_store.lock().unwrap().len()
    }

    /// 下单表单只读快照。
    pub fn order_form(&self) -> OrderForm {
        self.order_form.lock().unwrap().clone()
    }

    /// 下单表单写(渲染侧每控件改动即写)。
    pub fn set_order_form(&self, f: OrderForm) {
        *self.order_form.lock().unwrap() = f;
        self.bump();
    }

    /// 选中交易所(行情带当前 tab;不在六所内的取值由本口夹回首所 —— 空/脏值
    /// 都落到 SHFE,调用方永远拿到一个可用的 tab 名;行情行单击只带入下单面板,
    /// tab 归 tab 条管)。
    pub fn selected_exchange(&self) -> String {
        let s = self.selected_exchange.lock().unwrap().clone();
        if MARKET_ORDER.iter().any(|e| e.as_str() == s) {
            s
        } else {
            MARKET_ORDER[0].as_str().to_string()
        }
    }

    /// 选中交易所写。
    pub fn set_selected_exchange(&self, s: impl Into<String>) {
        *self.selected_exchange.lock().unwrap() = s.into();
        self.bump();
    }

    /// 左上组当前 tab。
    pub fn topleft_tab(&self) -> TopLeftTab {
        *self.topleft_tab.lock().unwrap()
    }

    /// 左上组 tab 写。
    pub fn set_topleft_tab(&self, t: TopLeftTab) {
        *self.topleft_tab.lock().unwrap() = t;
        self.bump();
    }

    /// 右下组当前 tab。
    pub fn bottomright_tab(&self) -> BottomRightTab {
        *self.bottomright_tab.lock().unwrap()
    }

    /// 右下组 tab 写。
    pub fn set_bottomright_tab(&self, t: BottomRightTab) {
        *self.bottomright_tab.lock().unwrap() = t;
        self.bump();
    }

    /// 数据区分刀份额读(渲染期)。
    pub fn data_split(&self) -> DataSplit {
        *self.data_split.lock().unwrap()
    }

    /// 数据区分刀份额写(分隔条拖拽回调;写入前就地夹取到可用区,QSplitter
    /// minimumSize 语义 —— 调用方传多少都不出界)。
    pub fn set_data_split(&self, s: DataSplit) {
        let s = DataSplit {
            col: crate::splitters::clamp_frac(s.col),
            row: crate::splitters::clamp_frac(s.row),
        };
        let mut g = self.data_split.lock().unwrap();
        if g.col != s.col || g.row != s.row {
            *g = s;
            self.bump();
        }
    }

    /// 「恢复布局」:数据区分刀回 Python right_splitter 口径(两刀各半),
    /// 三个 tab 态回缺省。dock 时代的「整树替换」不再存在 —— 布局骨架本来就是
    /// Python 等价的原生面板,没有树可换。
    pub fn reset_layout(&self) {
        *self.data_split.lock().unwrap() = DataSplit::default();
        *self.selected_exchange.lock().unwrap() = String::new();
        *self.topleft_tab.lock().unwrap() = TopLeftTab::default();
        *self.bottomright_tab.lock().unwrap() = BottomRightTab::default();
        self.bump();
    }

    // ---- v4 弹窗面(egui::Window 开关;kittest 可断言) ----

    /// 运维窗开合。
    pub fn ops_window_open(&self) -> bool {
        self.ops_window.load(Ordering::Acquire)
    }

    /// 运维窗开合写。
    /// 某张表当前的排序键(`None` = 按数据源原序)。
    pub fn table_sort(&self, table: &str) -> Option<(usize, bool)> {
        self.table_sorts
            .lock()
            .unwrap()
            .get(table)
            .copied()
            .flatten()
    }

    /// 表头点击:同列再点 = 翻向;异列 = 新列升序(与 Python QTableView 单击表头同口径)。
    pub fn toggle_table_sort(&self, table: &str, col: usize) {
        let mut m = self.table_sorts.lock().unwrap();
        let asc = match m.get(table).copied().flatten() {
            Some((c, a)) if c == col => !a,
            _ => true,
        };
        m.insert(table.to_string(), Some((col, asc)));
    }

    pub fn set_ops_window_open(&self, v: bool) {
        self.ops_window.store(v, Ordering::Release);
        self.bump();
    }

    // ---- 多账号面(规划 §5.B / §5.C) ----

    /// 账户面板开合(**0.9.34 起 = 「交易网关」模块窗的开合**,单一事实源在挂载表)。
    ///
    /// 保留旧名是因为 `render`/测试/示例都以它为入口语义(「把账户面打开」);
    /// 实现改走 [`crate::mount::Registry`],不再有独立的 `AtomicBool`。
    pub fn accounts_window_open(&self) -> bool {
        self.modules().is_open("ctp")
    }

    /// 账户面板开合写(→ `交易网关` 模块窗)。
    pub fn set_accounts_window_open(&self, v: bool) {
        self.modules().set_open("ctp", v);
        self.bump();
    }

    /// 账户配置弹窗开合(0.2.18 Commit B)。
    pub fn account_edit_open(&self) -> bool {
        self.account_edit_window.load(Ordering::Acquire)
    }

    /// 当前弹窗模式:`Some(派生名)` = 编辑;`None` = 添加。
    pub fn editing_account(&self) -> Option<String> {
        self.editing_account.lock().unwrap().clone()
    }

    /// 打开配置弹窗并载入草稿:`Some(派生名)` = 编辑模式(草稿 = 该账户留档);
    /// `None` = 添加模式(草稿 = `draft_from_existing()`,凭据位空)。
    /// 账户不在清册 = `false`(不开一个编辑不存在账户的窗)。
    pub fn begin_account_edit(&self, gateway: Option<&str>) -> bool {
        match gateway {
            Some(gw) => {
                let Some(row) = self.account(gw) else {
                    return false;
                };
                *self.editing_account.lock().unwrap() = Some(gw.to_string());
                *self.edit_alias.lock().unwrap() = row.alias.clone();
                self.set_ctp_form(row.form.clone());
            }
            None => {
                *self.editing_account.lock().unwrap() = None;
                *self.edit_alias.lock().unwrap() = String::new();
                let draft = self.draft_from_existing();
                self.set_ctp_form(draft);
            }
        }
        *self.edit_error.lock().unwrap() = None;
        self.account_edit_window.store(true, Ordering::Release);
        self.bump();
        true
    }

    /// 关闭配置弹窗 = **放弃未保存**(规划 Q24:绝不静默写入清册留档)。
    pub fn end_account_edit(&self) {
        *self.editing_account.lock().unwrap() = None;
        *self.edit_alias.lock().unwrap() = String::new();
        *self.edit_error.lock().unwrap() = None;
        self.account_edit_window.store(false, Ordering::Release);
        let draft = self.draft_from_existing();
        self.set_ctp_form(draft);
        self.bump();
    }

    /// 摘除一行账户时的连带口径:若这行正被配置弹窗**编辑**,立即关弹窗放弃。
    ///
    /// 不这么做的话:弹窗是非 modal 的,用户可以在弹窗开着时点同一行的『移除』——
    /// 编辑目标消失后弹窗会静默退化成「添加模式」(只读句消失、字段全部可编辑),
    /// 此时点『保存』会拿旧凭据建出一个**新账户**。这是执行核查抓到的坑。
    pub fn end_account_edit_if_editing(&self, gateway: &str) {
        if self.editing_account().as_deref() == Some(gateway) {
            self.end_account_edit();
        }
    }

    /// 弹窗别名草稿读。
    pub fn edit_alias(&self) -> String {
        self.edit_alias.lock().unwrap().clone()
    }

    /// 弹窗别名草稿写。
    pub fn set_edit_alias(&self, v: impl Into<String>) {
        *self.edit_alias.lock().unwrap() = v.into();
        self.bump();
    }

    /// 弹窗拦截原因读(`None` = 无)。
    pub fn edit_error(&self) -> Option<String> {
        self.edit_error.lock().unwrap().clone()
    }

    /// 弹窗拦截原因写(`None` = 清)。
    pub fn set_edit_error(&self, e: Option<String>) {
        *self.edit_error.lock().unwrap() = e;
        self.bump();
    }

    /// 弹窗草稿与该账户留档是否不一致(dirty;添加模式恒为"有内容待保存")。
    pub fn account_edit_dirty(&self) -> bool {
        let editing = self.editing_account();
        let draft = self.ctp_form();
        match editing {
            Some(gw) => self.account(&gw).map(|a| a.form != draft).unwrap_or(false),
            None => draft != CtpForm::default() && !draft.td_user.trim().is_empty(),
        }
    }

    /// 账户清单只读视图(注册序)。
    pub fn accounts(&self) -> Vec<AccountRow> {
        self.accounts.lock().unwrap().clone()
    }

    /// 单行账户查询。
    pub fn account(&self, gateway: &str) -> Option<AccountRow> {
        self.accounts
            .lock()
            .unwrap()
            .iter()
            .find(|a| a.gateway == gateway)
            .cloned()
    }

    /// 新增一行账户(**只写清册,不装配** —— 规划裁定「添加 ≠ 连接」)。
    ///
    /// `Err(原因)` 三种:派生名已存在(同 broker+账号重复添加)、别名重名(规划 Q3)、
    /// 达账户软上限 `MAX_ACCOUNTS`。宿主侧还有第二道 `Duplicate` 守卫;界面侧先拦是为了
    /// 不建出一个"注定被拒"的请求。
    pub fn add_account(&self, row: AccountRow) -> Result<(), String> {
        let mut acc = self.accounts.lock().unwrap();
        if acc.iter().any(|a| a.gateway == row.gateway) {
            return Err(format!("账户 {} 已存在(同 broker + 账号)", row.gateway));
        }
        let alias = row.alias.trim();
        if !alias.is_empty()
            && acc
                .iter()
                .any(|a| a.alias.trim().eq_ignore_ascii_case(alias))
        {
            return Err(format!("别名 {alias:?} 已被其他账户占用(别名须唯一)"));
        }
        if acc.len() >= MAX_ACCOUNTS {
            return Err(format!(
                "账户已达软上限 {MAX_ACCOUNTS} 个(先移除一个再添加)"
            ));
        }
        let has_alias = !row.alias.trim().is_empty();
        acc.push(row);
        drop(acc);
        if has_alias {
            // 带别名入册 → 立落盘标记(键 alias.<网关名> 要进 ui 段;空别名无键可写,不动标记)。
            self.alias_persist_due.store(true, Ordering::Release);
        }
        self.bump();
        Ok(())
    }

    /// 是否还能添加账户。
    #[must_use]
    pub fn can_add_account(&self) -> bool {
        self.accounts.lock().unwrap().len() < MAX_ACCOUNTS
    }

    /// 改一行账户的别名(按 gateway 主键;不存在 = false)。
    ///
    /// 别名只用于显示与选择,**不参与寻址**(寻址恒用派生注册名,规划 Q3)。
    /// 别名须**唯一**(与 `add_account` 同一守卫):空别名 = 不设别名(合法);
    /// 与他人重名 = false(调用方须显形,不得静默改成重名别名)。
    pub fn set_account_alias(&self, gateway: &str, alias: &str) -> bool {
        let alias = alias.trim().to_string();
        let mut acc = self.accounts.lock().unwrap();
        if !alias.is_empty()
            && acc
                .iter()
                .any(|a| a.gateway != gateway && a.alias.eq_ignore_ascii_case(&alias))
        {
            return false;
        }
        match acc.iter_mut().find(|a| a.gateway == gateway) {
            Some(a) => {
                a.alias = alias;
                drop(acc);
                self.alias_persist_due.store(true, Ordering::Release);
                self.bump();
                true
            }
            None => false,
        }
    }

    /// `UiCmd::Connect` 已入列 → 四态置「装配中」并清掉上一次的失败原因。
    ///
    /// 登录态一并退回 `Unknown`(0.2.19):新一轮装配开始时,上一轮的「在线/掉线」
    /// 不再是这一轮的事实 —— 留着会让用户在重连过程中看到「在线」。
    pub fn note_connect_sent(&self, gateway: &str) {
        let mut acc = self.accounts.lock().unwrap();
        if let Some(a) = acc.iter_mut().find(|a| a.gateway == gateway) {
            a.stage = AccountStage::Assembling;
            a.fail_note = None;
            a.login = LoginState::Unknown;
            a.status_note = None;
            a.login_brief = None;
            // 链状态同理作废(0.5.0):上一轮会话的「查询合约中」不是这一轮的事实。
            a.chain_note = None;
            drop(acc);
            self.bump();
        }
    }

    /// 装配结果回写:`Ok(())` → 「实例已装配」;`Err(原因)` → 「装配失败」+ 原因留显形。
    ///
    /// 失败**不回滚清册行**(规划 U3 定盘:行留着,给『重试』;旧口径"必须先移除才能重试"作废)。
    pub fn note_connect_result(&self, gateway: &str, result: Result<(), String>) {
        let mut acc = self.accounts.lock().unwrap();
        if let Some(a) = acc.iter_mut().find(|a| a.gateway == gateway) {
            match result {
                Ok(()) => {
                    a.stage = AccountStage::Assembled;
                    a.fail_note = None;
                }
                Err(e) => {
                    a.stage = AccountStage::AssembleFailed;
                    a.fail_note = Some(e);
                }
            }
            drop(acc);
            self.bump();
        }
    }

    /// 记录网关实际收录的产品类(`ConfigureReply.product_classes` 回带,规划 U9)。
    ///
    /// 只存不改用户勾选:勾选是意图,这一栏是事实,两者并排显示。
    pub fn note_effective_product_classes(&self, gateway: &str, classes: &[String]) {
        let mut acc = self.accounts.lock().unwrap();
        if let Some(a) = acc.iter_mut().find(|a| a.gateway == gateway) {
            a.effective_classes = classes.to_vec();
            drop(acc);
            self.bump();
        }
    }

    /// 链状态行落账(0.5.0,用户定):`note` = `[链] ` 前缀之后的正文,账户表「阶段」列显示它。
    ///
    /// 只认 ek-ctp 推的状态行(调用点在 `plugin.rs` 的 eLog 分支按前缀筛),普通日志不动这一栏。
    /// 没有对应账户行 = 什么都不做(网关还没进清册,状态行先到是正常时序)。
    pub fn note_chain(&self, gateway: &str, note: &str) {
        let mut acc = self.accounts.lock().unwrap();
        if let Some(a) = acc.iter_mut().find(|a| a.gateway == gateway) {
            if a.chain_note.as_deref() == Some(note) {
                return; // 同一条状态重复推(例如重连时同一阶段再来一次)不 bump、不刷帧
            }
            a.chain_note = Some(note.to_string());
            drop(acc);
            self.bump();
        }
    }

    // ---- 0.2.19 状态面(`{gw}.status` 轮询结果落账;规划 P3 / 裁定 3) ----

    /// 当前生效的「查询断供」阈值:`(连续被拒次数, 资金回报超时秒)`。
    #[must_use]
    pub fn status_thresholds(&self) -> (u32, i64) {
        self.status_thresholds
            .lock()
            .unwrap()
            .unwrap_or((QUERY_REJECT_STREAK_LIMIT, ACCOUNT_STALE_SECS))
    }

    /// 覆盖阈值(测试夹具把两判据收紧到「1 次 / 0 秒」,才好在没有真柜台的用例里显形)。
    pub fn set_status_thresholds(&self, reject_limit: u32, stale_secs: i64) {
        *self.status_thresholds.lock().unwrap() = Some((reject_limit, stale_secs));
        self.bump();
    }

    /// 管制面快照的轮询节拍:eTimer 每拍调一次。
    ///
    /// 三个条件任一为真就问:① 被标记(插件上/下线、svctl 起停);② 第一拍(界面刚
    /// 起来不该空着等 4 秒);③ 每 `LIST_POLL_TICKS` 拍一次。
    pub fn list_poll_due(&self) -> bool {
        let n = self.list_tick.fetch_add(1, Ordering::Relaxed) + 1;
        self.list_due.swap(false, Ordering::AcqRel) || n == 1 || n.is_multiple_of(LIST_POLL_TICKS)
    }

    /// 置「下一拍就重问管制面」(插件上下线、svctl 起停回执之后)。
    pub fn request_list_refresh(&self) {
        self.list_due.store(true, Ordering::Release);
    }

    /// 置「重播种一次四张表」(网关或 oms 上线之后)。消费方 = 命令线程。
    pub fn request_trade_reseed(&self) {
        self.seed_due.store(true, Ordering::Release);
    }

    /// 取走「重播种」标记(消费性,不是一档状态)。
    pub fn take_trade_reseed(&self) -> bool {
        self.seed_due.swap(false, Ordering::AcqRel)
    }

    /// 这一拍该问哪几个账户的 `{gw}.status`(0.5 M3 摊平)。
    ///
    /// 入参 = 当前「已装配且在场」的网关名;返回不超过 `STATUS_ASKS_PER_TICK` 个,
    /// 从游标起环形取 —— 8 个账户 4 拍走完一轮,单拍 ask 上限恒定。
    pub fn status_batch(&self, present: &[String]) -> Vec<String> {
        // 先按名去重:账户清册允许两行共用同一个网关(第二行 `svctl.start` 回「已在场」
        // 而行仍在清册里),而 `{gw}.status` 是按网关寻址的同一个服务口 —— 不去重就是
        // 同一拍里白问两次,而且把环形节律打乱(两个格子问同一个网关,别的网关没人问)。
        let mut uniq: Vec<String> = Vec::with_capacity(present.len());
        for gw in present {
            if !uniq.iter().any(|u| u == gw) {
                uniq.push(gw.clone());
            }
        }
        let n = uniq.len();
        if n == 0 {
            return Vec::new();
        }
        let start = self.status_cursor.fetch_add(1, Ordering::Relaxed) % n;
        let take = STATUS_ASKS_PER_TICK.min(n);
        let mut out = Vec::with_capacity(take);
        for i in 0..take {
            out.push(uniq[(start + i) % n].clone());
        }
        out
    }

    /// 记「该给这个网关播种一次状态」(0.7.0 第3刀;按名去重:同一网关只排一次)。
    pub fn request_status_seed(&self, gateway: &str) {
        let mut q = self.status_seed.lock().unwrap();
        if !q.iter().any(|g| g == gateway) {
            q.push(gateway.to_string());
        }
    }

    /// 取走全部待播种网关(排空;消费方是 eTimer 那一拍的 `seed_status`)。
    pub fn take_status_seeds(&self) -> Vec<String> {
        let mut q = self.status_seed.lock().unwrap();
        std::mem::take(&mut *q)
    }

    /// 状态变化事件入账(0.7.0 第3刀;`eStatus.` 一次到货三件事)。
    ///
    /// 1. **文案逐字进日志环**:文本由生产者(ek-ctp `describe()`)生成,界面不拼句子;
    /// 2. **状态列回写**:整份快照直接喂 `note_gateway_status`(在线/掉线/断供判据
    ///    吃的是同一份事实,不再回查);
    /// 3. **去重告警**:失败类六款(断开/认证失败/登录失败/查询停止/查询被拒/订阅被拒)
    ///    各弹一次;去重键带**会话标记**(`td_disconnects` / `md_disconnects`),
    ///    重连后的同一款算新事件(旧会话的账不替新会话挡告警)。成功类不弹(降噪:
    ///    文案与状态列已经说话)。
    pub fn note_status_event(&self, ev: &ek_ctp::GatewayStatusEvent) {
        let gw = ev.gateway.as_str();
        let text = ev.describe();
        self.log_line(format!("[INFO][{gw}] {text}"));
        let note = text
            .strip_prefix(CHAIN_STATE_PREFIX)
            .map(|s| s.trim().to_string())
            .unwrap_or_else(|| text.clone());
        self.note_chain(gw, &note);
        self.note_gateway_status(gw, &ev.status);
        let alarm_kind = matches!(
            ev.change,
            ek_ctp::GatewayChange::TdDisconnected
                | ek_ctp::GatewayChange::TdAuthFailed
                | ek_ctp::GatewayChange::TdLoginFailed
                | ek_ctp::GatewayChange::ContractQueryStopped
                | ek_ctp::GatewayChange::QueryRejected
                | ek_ctp::GatewayChange::MdDisconnected
                | ek_ctp::GatewayChange::MdLoginFailed
                | ek_ctp::GatewayChange::SubscribeRejected
        );
        if alarm_kind {
            // 会话标记:TD 侧款看 td 断开数,MD 侧款看 md 断开数(重连 → 数变 → 新事件)
            let session = if ev.change.kind().starts_with("md-") {
                ev.status.md_disconnects
            } else {
                ev.status.td_disconnects
            };
            let key = format!("estatus:{gw}:{}:{session}", ev.change.kind());
            if self.alert_once(key) {
                self.push_alert(
                    crate::toast::AlertLevel::Warning,
                    format!("账户 {gw}:{}", note.trim()),
                );
            }
        }
    }

    /// 置「该问一次 oms 装配」(0.5 M3:事件触发而不是节拍)。
    pub fn request_pipeline_refresh(&self) {
        self.pipeline_due.store(true, Ordering::Release);
    }
    /// 消费「该问一次 oms 装配」标记(取一次即清)。
    pub fn take_pipeline_due(&self) -> bool {
        self.pipeline_due.swap(false, Ordering::AcqRel)
    }

    /// 置「该问一次段落目录」(0.6.0 环节8;运维窗钮)。
    pub fn request_cfg_refresh(&self) {
        self.cfg_due.store(true, Ordering::Release);
    }

    /// 消费「该问一次段落目录」标记(取一次即清)。
    pub fn take_cfg_due(&self) -> bool {
        self.cfg_due.swap(false, Ordering::AcqRel)
    }

    /// 当前界面档(0.8.0 配色双档;缺省 = 深色)。
    pub fn theme(&self) -> crate::tokens::Theme {
        crate::tokens::Theme::from_u8(self.theme.load(Ordering::Acquire))
    }

    /// 装档(0.8.0)。**不置落盘标记** —— 启动读盘、夹具显式设档走这一支,
    /// 用户手点才走 `toggle_theme`(只有手点才落盘,照参考站口径)。
    pub fn set_theme(&self, theme: crate::tokens::Theme) {
        self.theme.store(theme.as_u8(), Ordering::Release);
        self.bump();
    }

    /// 用户点切换钮(0.8.0):切到另一档 + 立落盘标记,返回新档。
    pub fn toggle_theme(&self) -> crate::tokens::Theme {
        let next = self.theme().flipped();
        self.theme.store(next.as_u8(), Ordering::Release);
        self.theme_persist_due.store(true, Ordering::Release);
        self.bump();
        next
    }

    /// 消费「该把当前档落盘」标记(命令线程用;渲染线程零文件 IO)。
    pub fn take_theme_persist_due(&self) -> bool {
        self.theme_persist_due.swap(false, Ordering::AcqRel)
    }

    /// 用户手点「自动连接」勾选(0.9.0):更新行标 + 立落盘标记(手点才写 ui 段)。
    ///
    /// 守卫口径与既有账户面一致:行不在清册 = `Err`(不静默)。
    pub fn set_auto_connect(&self, gateway: &str, on: bool) -> Result<(), String> {
        {
            let mut acc = self.accounts.lock().unwrap();
            match acc.iter_mut().find(|a| a.gateway == gateway) {
                Some(a) => {
                    if a.auto_connect != on {
                        a.auto_connect = on;
                        self.auto_connect_persist_due.store(true, Ordering::Release);
                        self.bump();
                    }
                }
                None => return Err(format!("账户 {gateway} 不在清册")),
            }
        }
        Ok(())
    }

    /// 消费「该把自动连接勾选态落盘 ui 段」标记(命令线程用;手点才真写文件)。
    pub fn take_auto_connect_persist_due(&self) -> bool {
        self.auto_connect_persist_due.swap(false, Ordering::AcqRel)
    }

    /// 消费「该把别名表落盘」标记(命令线程用;渲染线程零文件 IO)。
    pub fn take_alias_persist_due(&self) -> bool {
        self.alias_persist_due.swap(false, Ordering::AcqRel)
    }

    /// 取走并清空档案抹除待办(命令线程落盘拍消费;见 `archive_purge` 字段注释)。
    pub fn take_archive_purges(&self) -> Vec<String> {
        let mut q = self.archive_purge.lock().unwrap();
        std::mem::take(&mut *q)
    }

    /// **启动清点 → 账户清单复原**(0.9.0)。
    ///
    /// 清点范围 = 该存档根里的 `ctp.*` 段(名单与连接参数的源);
    /// 每行是否「自动连接」= `ui` 段里的键 `auto_connect.<网关名>`("1" = 开;
    /// 键缺 = **关**,不善意)。密码**绝不进表单**:存档段里的密码是密库引用,
    /// `Field::secret` 键在这里只被读成「引用在位」的元信息(密码显示位用),
    /// 解密在实例 on_start 的 worker 时机(ek-ctp BD-CFG-16),与本函数无关。
    ///
    /// 复原行口径:`restored = true`、`auto_connect` 取档案值、
    /// `stage = NotAssembled`(实例只在「连接」/守护 auto_connect 时 spawn)。
    /// 已在清册的同名行**(手输先于复活的撞名)**跳过并显形 —— 清册行为唯一事实源,
    /// 清点不覆盖人手建的行。
    ///
    /// 返回:本次真正入库的复原行名(测试/首启说明用)。
    pub fn restore_saved_accounts_from(&self, store: &ek_cfg::Store) -> Vec<String> {
        // ui 段先读一次(缺 = 冷启动,全行 auto_connect = 关;别名键同理缺省无)。
        let mut flags: std::collections::BTreeMap<String, bool> = Default::default();
        let mut aliases: std::collections::BTreeMap<String, String> = Default::default();
        match store.load(crate::plugin::THEME_NS) {
            Ok(ek_cfg::LoadOutcome::Loaded { map, .. }) => {
                for (k, _f) in map.iter() {
                    if let Some(gw) = k.strip_prefix("auto_connect.") {
                        flags.insert(gw.to_string(), map.get_plain(k) == Some("1"));
                    }
                    if let Some(gw) = k.strip_prefix("alias.")
                        && let Some(v) = map.get_plain(k)
                    {
                        let v = v.trim();
                        if !v.is_empty() {
                            aliases.insert(gw.to_string(), v.to_string());
                        }
                    }
                }
            }
            Ok(_) => {}  // 冷启动:ui 段不在,零标志
            Err(_) => {} // ui 段存在但读不动(BD-CFG-4 应已兜底):标志照缺省关,显形下面统一出
        }
        let mut restored: Vec<String> = Vec::new();
        let ns_list = match store.list_namespaces() {
            Ok(v) => v,
            Err(e) => {
                // 0.9.39(用户实测「账户登录上去也没有了」):**显形**,不许静默空表。
                // 这一句同时进日志、进网关窗顶部(橙条)—— 空表要能自证"是读不出,不是丢了"。
                let msg = format!(
                    "档案清点失败:{e} —— 账户表会是空的,但**档案没丢**。\
                     多半是安全软件拦了本程序写 %APPDATA%\\ek\\cfg(放行后重启即恢复)"
                );
                self.log_line(format!("[ui] {msg}"));
                self.set_store_err(Some(msg));
                return restored;
            }
        };
        // 读通了 = 显形条撤掉(上一次失败留下的橙条不许赖着)。
        self.set_store_err(None);
        for ns in ns_list {
            let Some(gw) = ns.strip_prefix("ctp.") else {
                continue;
            };
            if self.account(gw).is_some() {
                self.log_line(format!(
                    "[ui] 档案 {ns} 与在册同名行撞名,清点不覆盖(清册行为唯一事实源)"
                ));
                continue;
            }
            let map = match store.load(&ns) {
                Ok(ek_cfg::LoadOutcome::Loaded { map, .. }) => map,
                Ok(_) => {
                    self.log_line(format!("[ui] 档案 {ns} 一段也读不出(跳过)"));
                    continue;
                }
                Err(e) => {
                    self.log_line(format!("[ui] 档案 {ns} 读不了:{e:?}(跳过)"));
                    continue;
                }
            };
            // 密码佈位:引用在位 = 表单的「密库引用」徽标依据(只读元信息)。
            let password_ref = map
                .get_secret_key("td_password")
                .is_some_and(|k| !k.is_empty());
            let mut form = CtpForm {
                broker_id: map.get_plain("broker_id").unwrap_or_default().to_owned(),
                td_addr: map.get_plain("td_addr").unwrap_or_default().to_owned(),
                td_user: map.get_plain("td_user").unwrap_or_default().to_owned(),
                td_password: String::new(),
                td_auth_code: map.get_plain("td_auth_code").unwrap_or_default().to_owned(),
                td_app_id: map.get_plain("td_app_id").unwrap_or_default().to_owned(),
                md_addr: map.get_plain("md_addr").unwrap_or_default().to_owned(),
                md_user: String::new(),
                md_password: String::new(),
                symbols: String::new(),
                accept_futures: false,
                accept_options: false,
            };
            // 2026-10-28 收录面裁定:期权全线退役;旧档里的 "1,2" 仍按**只期货**复原
            // (呈现层宁可收窄,不在复原时悄悄重开期权)。
            for c in map
                .get_plain("product_classes")
                .unwrap_or_default()
                .split(',')
            {
                if c.trim() == "1" {
                    form.accept_futures = true;
                }
            }
            let Ok(mut row) = AccountRow::derive(&form) else {
                self.log_line(format!(
                    "[ui] 档案 {ns} 无法派生(账号/前置非法别名冲突?),跳过 —— 界面手输重配更省心"
                ));
                continue;
            };
            // 注册名以**档案名**为准(0.9.10 多前置):档案段带 `_2` 后缀的行,
            // 派生基名与档案名不同 —— 复原跟着档案名走,否则同账号两套前置会撞回一行。
            row.gateway = gw.to_string();
            row.restored = true;
            row.auto_connect = flags.get(gw).copied().unwrap_or(false);
            row.password_ref = password_ref;
            // 别名标签(0.9.10):ui 段 alias.<网关名> 读回;撞名不硬塞(清册唯一性
            // 守卫优先),显形一句,行照复原 —— 标签是显示面,不该把行挡在门外。
            if let Some(a) = aliases.get(gw) {
                let taken = self
                    .accounts
                    .lock()
                    .unwrap()
                    .iter()
                    .any(|x| x.alias.trim().eq_ignore_ascii_case(a));
                if taken {
                    self.log_line(format!(
                        "[ui] 档案别名 {a:?} 已被在册行占用,{gw} 不带标签复原(账户面板改别名即可)"
                    ));
                } else {
                    row.alias = a.clone();
                }
            }
            restored.push(row.gateway.clone());
            self.add_account(row).ok();
        }
        if !restored.is_empty() {
            self.log_line(format!(
                "[ui] 账户档案清点复原 {} 行(手点「连接」直连存档;自动连接按行上勾选)",
                restored.len()
            ));
            // **行情源默认(0.9.10 用户裁定)**:默认 = **第一个勾选自动连接的账户**
            // (清册顺序);全没勾 = 不设默认(用户自己选);用户已指定(源非空) = 以指定为主。
            if self.md_source.lock().unwrap().is_empty() {
                let first = self
                    .accounts
                    .lock()
                    .unwrap()
                    .iter()
                    .find(|a| a.auto_connect)
                    .map(|a| a.gateway.clone());
                if let Some(gw) = first
                    && self.set_md_source(&gw).is_ok()
                {
                    self.log_line(format!("[账户] 行情源(默认=第一个勾选自动连接的)= {gw}"));
                }
            }
            self.bump();
        }
        restored
    }

    /// 复原入口(桌面端;生态缺省根)。根不可用 = 空表 + 显形(不落临时目录)。
    pub fn restore_saved_accounts(&self) -> Vec<String> {
        match ek_cfg::Store::eco() {
            Ok(store) => self.restore_saved_accounts_from(&store),
            Err(_) => {
                self.log_line(
                    "[ui] 档案清点跳过:config_dir() 不可用(BD-CFG-20;配置根异常该显形)".to_string(),
                );
                Vec::new()
            }
        }
    }

    /// 段落目录回写(0.6.0)。
    pub fn set_cfg_briefs(&self, b: Vec<ek_cfg::wire::NsBrief>) {
        *self.cfg_briefs.lock().unwrap() = Some(b);
        self.bump();
    }
    /// 段落目录只读视图(0.6.0;`None` = 从未问过)。
    pub fn cfg_briefs(&self) -> Option<Vec<ek_cfg::wire::NsBrief>> {
        self.cfg_briefs.lock().unwrap().clone()
    }

    /// 清段二次确认臂(0.6.0;`Some(ns)` = 已点过一次,下一帧再点同一行才真发)。
    pub fn cfg_delete_armed(&self) -> Option<String> {
        self.cfg_delete_arm.lock().unwrap().clone()
    }
    pub fn arm_cfg_delete(&self, ns: Option<String>) {
        *self.cfg_delete_arm.lock().unwrap() = ns;
        self.bump();
    }

    /// `oms.pipeline_status` 读数回写(装配事实,不是业务事实)。
    pub fn set_pipeline_lines(&self, lines: Vec<String>) {
        *self.pipeline_lines.lock().unwrap() = lines;
        self.bump();
    }

    /// 最新一次的 oms 装配显形读数(空 = 运维窗不画这一节)。
    pub fn pipeline_lines(&self) -> Vec<String> {
        self.pipeline_lines.lock().unwrap().clone()
    }

    /// 某条推送线的载荷类型不对(0.5 M1)。
    ///
    /// 链上这几条线的载荷类型不是编译期保证:`ePosition.` 的载荷「由广发方确定」
    /// (ek-oms plugin.rs:329 同样只能 downcast 试)。收不进去就计数,并在**第一次**
    /// 显形一条日志 —— 静默丢等于「界面少了一路数据而没人知道」。
    pub fn note_bad_payload(&self, line: &str) {
        let mut book = self.bad_payload.lock().unwrap();
        let n = book.entry(line.to_string()).or_insert(0);
        *n += 1;
        if *n == 1 {
            self.log_line(format!(
                "[ui] {line} 载荷类型异常(第一次):这一路的行进不了账本"
            ));
        }
    }

    /// 某条推送线累计收不进去多少条(测试判据)。
    #[must_use]
    pub fn bad_payload_count(&self, line: &str) -> u64 {
        self.bad_payload
            .lock()
            .unwrap()
            .get(line)
            .copied()
            .unwrap_or(0)
    }

    /// 插件邮箱**水位与触顶**的显形(0.4.5 P7d 首发;0.7.0 背压刀改口径)。
    ///
    /// 新口径(随 ek-core 0.5.0):邮箱**无界默认不丢** → `spilled` 只在触到
    /// 该插件自己的**软顶**时才涨,所以「spilled > 0」不再意味着「丢过几条行情」,
    /// 而是**已经触顶**——一件红色大事。默认不丢之后,现场真正要看的是
    /// **积压多深**(消费侧滞后 = 刷新慢),所以这里从 0.5 的"溢出告警"扩成
    /// 三段读数,全部走快照逐行(数据源 = ek-station 0.4.0 的 `pending/peak/soft_cap`):
    /// - 积压越黄阈(软顶 1/16,下限 4096)→ Warning;
    /// - 积压越红阈(软顶 1/4,下限 32768)→ Error:再涨就要丢新帧了;
    /// - `spilled > 0`(已触顶)→ Error:此刻起每多一条就丢一条**新到**的事件。
    ///
    /// 去重口径照旧(告警是状态事实,不是渲染帧的副作用):每个插件每一级只弹一次,
    /// 持续状态由运维窗那一列**常显**(告警负责"发生",窗口负责"一直在")。
    pub fn note_plugin_spill(&self, rows: &[ek_station::wire::PlugRow]) {
        for r in rows {
            let (warn, crit) = pending_thresholds(r.soft_cap);
            if r.pending >= warn && self.alert_once(format!("pend-warn:{}", r.name)) {
                self.push_alert(
                    crate::toast::AlertLevel::Warning,
                    format!(
                        "插件 {}：邮箱积压 {} 帧(峰值 {};该插件软顶 {})——它的 worker 消化不过来,刷新会变慢",
                        r.name, r.pending, r.peak, r.soft_cap
                    ),
                );
            }
            if r.pending >= crit && self.alert_once(format!("pend-crit:{}", r.name)) {
                self.push_alert(
                    crate::toast::AlertLevel::Error,
                    format!(
                        "插件 {}：邮箱积压 {} 帧,越过软顶 {} 的四分之一——再涨就开始丢新到的事件",
                        r.name, r.pending, r.soft_cap
                    ),
                );
            }
            if r.spilled > 0 && self.alert_once(format!("spill:{}", r.name)) {
                self.push_alert(
                    crate::toast::AlertLevel::Error,
                    format!(
                        "插件 {}：已触软顶 {} 并丢弃新到事件累计 {} 条(峰值 {})——它的消化速度跟不上生产速度",
                        r.name, r.soft_cap, r.spilled, r.peak
                    ),
                );
            }
        }
    }

    /// `{gw}.status` 读数回写 → 该行登录态与细节重算。
    ///
    /// 0.3.2(Wave E,BD-UI-50)这里同时是**告警的唯一产生口**:轮询一拍问出告警态就灌 toast。
    /// 为什么住这儿而不是账户面板的渲染里(Python `AlertEngine` 的对照口径):
    /// 告警是「状态口问出来的事实」,不是「某张窗画出来的东西」——账户窗没开也必须知道掉线了。
    /// 去重键 = 网关 + 登录态:同一状态只弹一次,状态变了才算新告警(否则每轮轮询一条,
    /// 8 秒自动关与同屏上限 3 都没有意义)。
    pub fn note_gateway_status(&self, gateway: &str, st: &ek_ctp::plugin::GatewayStatus) {
        let (limit, stale) = self.status_thresholds();
        let now = ek_ctp::map::now_epoch_ms();
        // 先在账户锁里把「这一拍是不是告警态」读出来,出锁再发 toast
        // (accounts / alerted / pending_alerts 是三颗独立的锁,不嵌套持有)。
        let mut alarm: Option<(LoginState, String)> = None;
        let mut found = false;
        {
            let mut acc = self.accounts.lock().unwrap();
            if let Some(a) = acc.iter_mut().find(|a| a.gateway == gateway) {
                found = true;
                a.apply_status(st, now, limit, stale);
                if a.login.is_alarm() || a.login == LoginState::QueryStarved {
                    alarm = Some((
                        a.login,
                        a.status_note
                            .clone()
                            .unwrap_or_else(|| a.login.label().to_string()),
                    ));
                }
            }
        }
        if found {
            self.bump();
        }
        if let Some((login, note)) = alarm
            && self.alert_once(format!("{gateway}|{}", login.label()))
        {
            self.push_alert(
                crate::toast::AlertLevel::Error,
                format!("账户 {gateway}：{note}"),
            );
        }
    }

    /// 状态口问不到(网关不在场 / ask 超时):登录态退回 `Unknown` 并写明原因。
    ///
    /// **不得保留上一轮的「在线」**:问不到就是没有证据,留着旧读数等于替网关谎称在线。
    pub fn note_status_unreachable(&self, gateway: &str, why: &str) {
        let mut acc = self.accounts.lock().unwrap();
        if let Some(a) = acc.iter_mut().find(|a| a.gateway == gateway) {
            a.login = LoginState::Unknown;
            a.status_note = Some(format!("状态口问不到:{why}"));
            a.login_brief = None;
            drop(acc);
            self.bump();
        }
    }

    /// 『断开』已发令 → 该行立刻显形「已断开」(不等下一轮轮询;用户按了就该马上看到)。
    pub fn mark_account_stopped(&self, gateway: &str) {
        let mut acc = self.accounts.lock().unwrap();
        if let Some(a) = acc.iter_mut().find(|a| a.gateway == gateway) {
            a.login = LoginState::Stopped;
            a.status_note = Some("会话已停;『连接』可恢复".to_string());
            a.login_brief = None;
            drop(acc);
            self.bump();
        }
    }

    /// 装配前把表单落到该账户留档,并按**全局单源纪律**裁决 md 位:
    /// 非行情源账户 → `md_addr` 就地清空(**留档与下发同一份**,消 U4 的"只清下发不清留档")。
    pub fn prepare_connect_form(&self, gateway: &str, form: CtpForm) -> CtpForm {
        let source = self.md_source();
        let mut f = form;
        if source.as_str() != gateway {
            f.md_addr.clear();
            f.md_user.clear();
            f.md_password.clear();
        }
        self.update_account_form(gateway, f.clone());
        f
    }

    /// 『添加账户』弹窗的草稿位:沿用当前在场账户的**非凭据字段**
    /// (broker / AppID / AuthCode / 收录勾选),凭据位(账号、密码、前置)一律清空
    /// (规划 Q20 的零风险缓解:少敲几遍,但绝不把上一家的密码带进下一家)。
    #[must_use]
    pub fn draft_from_existing(&self) -> CtpForm {
        let acc = self.accounts.lock().unwrap();
        let mut draft = CtpForm::default();
        if let Some(a) = acc.last() {
            draft.broker_id = a.form.broker_id.clone();
            draft.td_auth_code = a.form.td_auth_code.clone();
            draft.td_app_id = a.form.td_app_id.clone();
            draft.accept_futures = a.form.accept_futures;
            draft.accept_options = a.form.accept_options;
        }
        draft
    }

    /// 更新一行账户的表单留档(按 gateway 主键;不存在 = false)。
    pub fn update_account_form(&self, gateway: &str, form: CtpForm) -> bool {
        let mut acc = self.accounts.lock().unwrap();
        match acc.iter_mut().find(|a| a.gateway == gateway) {
            Some(a) => {
                a.form = form;
                drop(acc);
                self.bump();
                true
            }
            None => false,
        }
    }

    /// 摘除一行账户(界面侧清册;网关实例由 `UiCmd::Remove` 走 svctl 摘)。
    pub fn remove_account(&self, gateway: &str) -> bool {
        let mut acc = self.accounts.lock().unwrap();
        let before = acc.len();
        acc.retain(|a| a.gateway != gateway);
        let removed = acc.len() != before;
        if removed {
            // 元账号被摘 → 源位清空(等用户重新指定);订阅集保留(规划 §5.C)。
            let mut md = self.md_source.lock().unwrap();
            if md.as_str() == gateway {
                md.clear();
            }
            drop(acc);
            // 摘行 → 别名键也要跟着清(不留魂;同 auto_connect 的摘户纪律)。
            self.alias_persist_due.store(true, Ordering::Release);
            // 摘行 → 档案段入抹除待办(不抹 = 下次启动清点复活,用户实锤病根)。
            self.archive_purge.lock().unwrap().push(gateway.to_string());
            self.bump();
        }
        removed
    }

    /// 用 svctl 快照回填账户在场位与四态;回带**本轮新装配**的网关名(订阅重放用)。
    ///
    /// 四态口径:svctl 带回这个名字 = 实例已装配(清掉失败原因);
    /// 名字不在场且原先记着「已装配」= 回到「未装配」(被摘/宿主崩了);
    /// 「装配中」与「装配失败」是界面侧记的,**不被在场表覆盖**。
    ///
    /// 0.2.19 附带一条:实例不在场时**登录态读数一并作废** —— 会话读数属于那个实例,
    /// 实例没了还留着「在线/掉线 2 次」,就是在替一个不存在的会话说话。
    pub fn sync_accounts_connected(&self, rows: &[PlugRow]) -> Vec<String> {
        let mut newly = Vec::new();
        {
            let mut acc = self.accounts.lock().unwrap();
            for a in acc.iter_mut() {
                let up = rows.iter().any(|r| r.name == a.gateway);
                if up && !a.connected {
                    newly.push(a.gateway.clone());
                }
                a.connected = up;
                if up {
                    a.stage = AccountStage::Assembled;
                    a.fail_note = None;
                } else {
                    // 实例不在场 = 这一条会话没了:链状态同理作废(0.5.0「阶段」栏)。
                    // 留着就是替一个不存在的会话说话(与上面「登录态读数一并作废」同一条理由)。
                    a.chain_note = None;
                    if a.stage == AccountStage::Assembled {
                        a.stage = AccountStage::NotAssembled;
                        a.login = LoginState::Unknown;
                        a.status_note = None;
                        a.login_brief = None;
                    }
                }
            }
        }
        if !newly.is_empty() {
            self.bump();
        }
        newly
    }

    /// 行情元账号注册名(空 = 未选)。
    pub fn md_source(&self) -> String {
        self.md_source.lock().unwrap().clone()
    }

    /// 是否已有账户装配 —— 元账号锁定判定(规划 D3:连接后不允许切换)。
    pub fn accounts_locked(&self) -> bool {
        self.accounts.lock().unwrap().iter().any(|a| a.connected)
    }

    /// 指定行情元账号(仅配置阶段;任何账户已连接 = 拒,界面须提示"先断开")。
    pub fn set_md_source(&self, gateway: &str) -> Result<(), String> {
        {
            let acc = self.accounts.lock().unwrap();
            if acc.iter().any(|a| a.connected) {
                return Err("元账号已锁定:有账户在线,切换行情源需先断开该账户".to_string());
            }
            if !acc.iter().any(|a| a.gateway == gateway) {
                return Err(format!("账户 {gateway} 不在清册"));
            }
        }
        let mut acc = self.accounts.lock().unwrap();
        for a in acc.iter_mut() {
            a.md_source = a.gateway == gateway;
        }
        drop(acc);
        let mut md = self.md_source.lock().unwrap();
        *md = gateway.to_string();
        self.bump();
        Ok(())
    }

    /// 订阅集只读视图。
    pub fn subscriptions(&self) -> Vec<String> {
        self.subscriptions.lock().unwrap().clone()
    }

    /// 登记订阅(去重保序;断开重连后按它重放)。
    pub fn note_subscriptions(&self, symbols: &[String]) {
        {
            let mut subs = self.subscriptions.lock().unwrap();
            for s in symbols {
                let s = s.trim();
                if !s.is_empty() && !subs.iter().any(|x| x == s) {
                    subs.push(s.to_string());
                }
            }
        }
        self.bump();
    }

    /// 下单默认账户阶梯(替代旧"空 → 字面量 ctp"兜底,规划 §5.B;
    /// **0.2.18 四态后修正,规划 Q4**):
    /// 上次手动选择(须仍在清册且已装配)→ 第一个已装配账户;
    /// **未装配账户不得进默认** —— 旧阶梯的"退到第一个账户"会把只添加了还没连接的
    /// 账户选成下单归属,发出去只会撞 `unknown:gateway`。
    /// 一个都没有 = `None`(界面据此禁用下单钮)。
    pub fn default_gateway(&self) -> Option<String> {
        let chosen = {
            let f = self.order_form.lock().unwrap();
            f.gateway.trim().to_string()
        };
        if !chosen.is_empty() && self.account(&chosen).is_some_and(|a| a.connected) {
            return Some(chosen);
        }
        let acc = self.accounts.lock().unwrap();
        acc.iter().find(|a| a.connected).map(|a| a.gateway.clone())
    }

    /// 已开 K线窗合约表(多开,去重)。
    pub fn kline_symbols(&self) -> Vec<String> {
        self.kline_windows.lock().unwrap().clone()
    }

    /// 开 K线窗(去重;日志留痕可断言)。
    pub fn open_kline(&self, symbol: impl Into<String>) {
        let s = symbol.into();
        let mut v = self.kline_windows.lock().unwrap();
        if !v.contains(&s) {
            v.push(s.clone());
        }
        drop(v);
        self.log_line(format!("[kline] 打开 K线窗 {s}"));
        // I2 第一刀:开窗即入队一次历史补数(tq 桥;周期跟 dm 缺省 1 分钟档,
        // 符号没带交易所前缀就用当前行情 tab 的所补齐成 en_symbol)。
        let fq = if s.contains('.') {
            s.clone()
        } else {
            format!("{}.{}", self.selected_exchange(), s)
        };
        const KLINE_INTERVAL_SECS: i64 = 60;
        {
            let mut fetched = self.kline_fetched.lock().unwrap();
            if fetched.contains(&(fq.clone(), KLINE_INTERVAL_SECS)) {
                return;
            }
            fetched.insert((fq.clone(), KLINE_INTERVAL_SECS));
        }
        self.kline_fetches.lock().unwrap().push(KlineFetch {
            symbol: fq,
            interval_secs: KLINE_INTERVAL_SECS,
        });
        self.log_line(format!("[kline] 入队历史补数 {s}(1min×300,tq 桥)"));
    }

    /// 补数队列出口(命令线程 catch;非阻塞读,取走即清)。
    pub fn take_kline_fetches(&self) -> Vec<KlineFetch> {
        std::mem::take(&mut self.kline_fetches.lock().unwrap())
    }

    /// 命令线程路由位:有补数单待发。
    pub fn kline_fetch_pending(&self) -> bool {
        !self.kline_fetches.lock().unwrap().is_empty()
    }

    /// 关 K线窗(窗关闭钮 → 出表)。
    pub fn close_kline(&self, symbol: &str) {
        self.kline_windows.lock().unwrap().retain(|s| s != symbol);
        self.bump();
    }

    // ---- v4 查询合约窗面(合约库 / 查询串 / 勾选集) ----

    /// 查询合约窗开合。
    pub fn contracts_window_open(&self) -> bool {
        self.contracts_window.load(Ordering::Acquire)
    }

    /// 查询合约窗开合写。
    pub fn set_contracts_window_open(&self, v: bool) {
        self.contracts_window.store(v, Ordering::Release);
        self.bump();
    }

    /// 落一条合约(`eContract.` 裸键上屏),并**回补已有行的名称**。
    ///
    /// 时序决定了这一步必须有:登录即上账的委托/成交回报**先于合约到手**(柜台在
    /// 登录后立刻回放当日回报,而合约查询要走完查询链),网关发它们时合约表还空着,
    /// 名字补不上(0.11.0 第5刀现场实测:委托 2/27、成交 1/14)。合约到货之后
    /// 把同名行补齐 —— 只补空名字,**已有名字不覆盖**;补名不改行序、不新增行。
    pub fn update_contract(&self, c: &ek_data::contract::ContractData) {
        self.contract_store.lock().unwrap().put(c);
        if !c.name.is_empty() {
            self.backfill_names(&c.symbol, &c.name);
        }
        self.bump();
    }

    /// 名称回补(0.11.0 第5刀 R6):按代码补委托 / 成交 / 持仓三本账里的空名行。
    ///
    /// 名称是**交易所层面的合约属性**(与网关无关),所以跨网关按代码补;
    /// 补的是显示事实,不参与任何判据(在线/断供/归属守卫都不看这一栏)。
    fn backfill_names(&self, symbol: &str, name: &str) {
        let mut touched = false;
        {
            let mut rows = self.trade_orders.lock().unwrap();
            for (_, (_, o)) in rows.iter_mut() {
                if o.symbol == symbol && o.name.is_empty() {
                    o.name = name.to_string();
                    touched = true;
                }
            }
        }
        {
            let mut rows = self.trade_trades.lock().unwrap();
            for (_, t) in rows.iter_mut() {
                if t.symbol == symbol && t.name.is_empty() {
                    t.name = name.to_string();
                    touched = true;
                }
            }
        }
        {
            let mut rows = self.trade_positions.lock().unwrap();
            for (_, (_, p)) in rows.iter_mut() {
                if p.symbol == symbol && p.name.is_empty() {
                    p.name = name.to_string();
                    touched = true;
                }
            }
        }
        if touched {
            // 快照缓存要跟着作废(否则屏幕上还是旧名字)
            self.trade_dirty.store(true, Ordering::Release);
        }
    }

    /// 合约查询(Python ContractManager 口径:留空 = 全部)。
    pub fn contracts(&self, pattern: &str) -> Vec<ek_data::contract::ContractData> {
        self.contract_store.lock().unwrap().query(pattern)
    }

    /// 合约库格数。
    pub fn contract_count(&self) -> usize {
        self.contract_store.lock().unwrap().len()
    }

    /// 按代码查合约名(0.11.0 第5刀 R6 的补名口;查不到 = `None`,不编名字)。
    fn contract_name_of(&self, symbol: &str) -> Option<String> {
        self.contract_store
            .lock()
            .unwrap()
            .query(symbol)
            .into_iter()
            .find(|c| c.symbol == symbol && !c.name.is_empty())
            .map(|c| c.name)
    }

    /// 查询串读写。
    pub fn contract_query(&self) -> String {
        self.contract_query.lock().unwrap().clone()
    }

    /// 查询串写。
    pub fn set_contract_query(&self, q: impl Into<String>) {
        *self.contract_query.lock().unwrap() = q.into();
        self.bump();
    }

    /// 勾选翻转(en_symbol)。
    pub fn toggle_contract_selection(&self, en_symbol: &str) {
        let mut v = self.contract_selected.lock().unwrap();
        match v.iter().position(|s| s == en_symbol) {
            Some(i) => {
                v.remove(i);
            }
            None => v.push(en_symbol.to_string()),
        }
        self.bump();
    }

    /// 当前勾选集。
    pub fn selected_contracts(&self) -> Vec<String> {
        self.contract_selected.lock().unwrap().clone()
    }

    /// 撤单拒因翻译(0.11.0 第6刀 R7):机器码 → 人话,**原文照留**。
    ///
    /// oms 的拒因是结构化机器码(判据/日志吃它,不能改),屏幕上要给一句人话。
    /// 这一条住在状态层(不是渲染层),与告警同一口径:事实的产生口说什么,
    /// 屏幕上就说什么,渲染不参与翻译。
    #[must_use]
    pub fn cancel_reject_note(msg: &str) -> String {
        let head = msg.split(' ').next().unwrap_or(msg);
        let note = if head.starts_with("unknown:order") {
            "这台网关的账本里没有这笔委托(登录前的旧单,或不属于这个账户)"
        } else if head.starts_with("mismatch:gateway") {
            "该委托不属于这个账户(归属守卫挡住,不会撤到别人头上)"
        } else if head.starts_with("terminal:status") {
            "这笔委托已经到终态(已成交/已撤/已拒),撤不了了"
        } else if head.starts_with("limit:cancel-guard") {
            "撤单尝试次数已到上限(每单有上限,防连点打爆柜台)"
        } else {
            ""
        };
        if note.is_empty() {
            // 认不出的机器码:照原文,不编故事
            format!("撤单被拒:{msg}")
        } else {
            format!("撤单被拒:{note}(机器码:{msg})")
        }
    }

    /// 追加一行日志(总线面/宿主观察线程写)。
    pub fn log_line(&self, line: impl Into<String>) {
        self.logs.lock().unwrap().push(line);
        self.bump();
    }

    /// 清空日志(渲染"清空日志"按钮 / 测试)。
    pub fn clear_logs(&self) {
        self.logs.lock().unwrap().clear();
        self.bump();
    }

    /// 日志只读快照 + 溢出计数。
    pub fn logs_snapshot(&self) -> (Vec<String>, u64) {
        let r = self.logs.lock().unwrap();
        (r.snapshot(), r.spilled())
    }

    /// 带时间戳的日志快照(BD-UI-41 渲染侧:日志表格的「时间」列)。
    pub fn logs_entries(&self) -> (Vec<LogEntry>, u64) {
        let r = self.logs.lock().unwrap();
        (r.entries(), r.spilled())
    }

    /// 日志当前长度(kittest 断言用)。
    pub fn logs_len(&self) -> usize {
        self.logs.lock().unwrap().len()
    }

    /// 落一次服务快照(eTimer 节流回调)。
    pub fn set_snapshot(&self, snap: BusSnap) {
        *self.snap.lock().unwrap() = Arc::new(snap);
        self.bump();
    }

    /// 当前快照(Arc 克隆,零拷贝走锁)。
    pub fn snapshot(&self) -> Arc<BusSnap> {
        Arc::clone(&self.snap.lock().unwrap())
    }

    /// revision:任何写入 +1(插件面 ePlug 事件也用;测试判定"有事件进来过")。
    pub fn rev(&self) -> u64 {
        self.rev.load(Ordering::Acquire)
    }

    /// 手动推一次 revision(总线面 ePlugUp/Down 记账用)。
    pub fn bump(&self) {
        self.rev.fetch_add(1, Ordering::AcqRel);
    }

    /// 置关窗信号(eframe App 关窗钩子调用)。
    pub fn request_stop(&self) {
        self.stop.store(true, Ordering::Release);
    }

    /// 观察线程轮询用。
    /// 0.3.2(Wave E,BD-UI-50)告警入口:界面层调它,渲染帧灌进 toast 队列。
    pub fn push_alert(&self, level: crate::toast::AlertLevel, text: impl Into<String>) {
        self.pending_alerts
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .push((level, text.into()));
    }

    /// 取走待灌的告警(render 每帧一次)。
    pub(crate) fn take_alerts(&self) -> Vec<(crate::toast::AlertLevel, String)> {
        let mut q = self
            .pending_alerts
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        std::mem::take(&mut *q)
    }

    /// 常驻 toast 队列。
    pub(crate) fn toasts(&self) -> std::sync::MutexGuard<'_, Option<egui_notify::Toasts>> {
        self.toasts.lock()
    }

    /// 去重:这条告警第一次出现返回 true(同一键不再重复弹)。
    pub fn alert_once(&self, key: impl Into<String>) -> bool {
        let key = key.into();
        self.alerted
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .insert(key)
    }

    /// 待灌进 toast 的告警条数(状态层判据用;灌进队列由渲染帧收口)。
    #[must_use]
    pub fn pending_alert_count(&self) -> usize {
        self.pending_alerts
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .len()
    }

    /// 已弹过的告警键数(去重账本;判据用它核「同一状态不重复弹」)。
    #[must_use]
    pub fn alerted_count(&self) -> usize {
        self.alerted
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .len()
    }

    /// 退出确认窗:开 / 关 / 是否已确认放行(0.3.1 BD-UI-49)。
    pub fn exit_confirm_open(&self) -> bool {
        self.exit_confirm_open
            .load(std::sync::atomic::Ordering::Relaxed)
    }

    pub fn open_exit_confirm(&self) {
        self.exit_confirm_open
            .store(true, std::sync::atomic::Ordering::Relaxed);
    }

    pub fn close_exit_confirm(&self) {
        self.exit_confirm_open
            .store(false, std::sync::atomic::Ordering::Relaxed);
    }

    pub fn exit_confirmed(&self) -> bool {
        self.exit_confirmed
            .load(std::sync::atomic::Ordering::Relaxed)
    }

    pub fn confirm_exit(&self) {
        self.exit_confirmed
            .store(true, std::sync::atomic::Ordering::Relaxed);
    }

    pub fn is_stop(&self) -> bool {
        self.stop.load(Ordering::Acquire)
    }

    /// 装配锁是否在位(0.9.5 阶段机;只被界面读)。
    #[must_use]
    pub fn assembly_locked(&self) -> bool {
        self.assembly_locked.load(Ordering::Relaxed)
    }

    /// 置装配锁(0.9.5;启动全成功 → true,失败 → 保持 false 留修路)。
    pub fn set_assembly_locked(&self, on: bool) {
        self.assembly_locked.store(on, Ordering::Relaxed);
    }

    // ---- svctl 操作面(S2) ----

    /// 入一条操作指令(窗口面离场动作唯一通道;左位不直调)。
    pub fn push_cmd(&self, cmd: UiCmd) {
        self.cmds.lock().unwrap().push_back(cmd);
        self.bump();
    }

    /// 取走全部指令(0.5 M5:命令线程辞行)。
    pub fn drain_cmds(&self) -> Vec<UiCmd> {
        self.cmds.lock().unwrap().drain(..).collect()
    }

    /// 队列里是否有待执行指令(命令线程的「有没有活」判据,不消费)。
    #[must_use]
    pub fn cmd_pending(&self) -> bool {
        !self.cmds.lock().unwrap().is_empty()
    }

    /// 当前待二次确认目标(Some = 二次确认中)。
    pub fn pending_confirm(&self) -> Option<String> {
        self.pending_confirm.lock().unwrap().clone()
    }

    /// 确认步进:同名二点 = 发令(Fired),异名 = 迁移(Switched),首点 = 进入待确认。
    pub fn confirm_step(&self, name: &str) -> ConfirmStep {
        let mut g = self.pending_confirm.lock().unwrap();
        match g.take() {
            Some(p) if p == name => ConfirmStep::Fired,
            Some(_) => {
                *g = Some(name.to_string());
                ConfirmStep::Switched
            }
            None => {
                *g = Some(name.to_string());
                ConfirmStep::Armed
            }
        }
    }

    /// 清除待确认(取消钮)。
    pub fn confirm_cancel(&self) {
        *self.pending_confirm.lock().unwrap() = None;
        self.bump();
    }

    // ---- S4 行情面 ----

    /// 行情库直读(读写两用:worker 写,渲染读)。
    pub fn market(&self) -> &MarketStore {
        &self.market
    }

    // ---- S5 交易面 ----

    /// 全量播种四本账(**测试夹具的入口**;0.5 起生产侧不再走这一条 —— 启动一次四问
    /// 走 `note_*` 合并式播种,见 `plugin.rs::reconcile_trade`)。
    ///
    /// 与 `note_*` 的分工:这一条是「把已有的一份账交给界面」(先清后灌),`note_*` 是
    /// 「一批新事件进来」。行序按入参**反序**赋 seq,正是为了让重建后的 `trade_snap()`
    /// 与喂进来的顺序一致 —— 播种不是「一批新事件」,只有新事件才走「在前」。
    pub fn seed_trade_snap(&self, ts: TradeSnap) {
        // 0.11.0 第5刀 R6:播种面同样补名(oms 账本里那些"发的时候合约表还空着"的
        // 行,进界面这一刻合约早就在手了)
        let named = |symbol: &str, name: String| -> String {
            if name.is_empty() {
                self.contract_name_of(symbol).unwrap_or(name)
            } else {
                name
            }
        };
        {
            let mut book = self.trade_orders.lock().unwrap();
            book.clear();
            for mut o in ts.orders.into_iter().rev() {
                o.name = named(&o.symbol, o.name);
                let seq = self.trade_seq.fetch_add(1, Ordering::Relaxed) + 1;
                book.insert(o.en_orderid(), (seq, o));
            }
        }
        {
            let mut book = self.trade_trades.lock().unwrap();
            book.clear();
            let mut ids = self.trade_ids.lock().unwrap();
            ids.clear();
            for mut t in ts.trades.into_iter().rev() {
                t.name = named(&t.symbol, t.name);
                let seq = self.trade_seq.fetch_add(1, Ordering::Relaxed) + 1;
                ids.insert(t.en_tradeid());
                book.push_front((seq, t));
            }
        }
        {
            let mut book = self.trade_positions.lock().unwrap();
            book.clear();
            for mut p in ts.positions.into_iter().rev() {
                p.name = named(&p.symbol, p.name);
                let seq = self.trade_seq.fetch_add(1, Ordering::Relaxed) + 1;
                book.insert(p.en_positionid(), (seq, p));
            }
        }
        {
            let mut book = self.trade_funds.lock().unwrap();
            book.clear();
            for a in ts.accounts.into_iter().rev() {
                let seq = self.trade_seq.fetch_add(1, Ordering::Relaxed) + 1;
                book.insert(a.en_accountid(), (seq, a));
            }
        }
        self.trade_dirty.store(true, Ordering::Release);
        self.bump();
    }

    /// 一笔委托入账(基线 OrderMonitor:有 `en_orderid` 就更新可变列,否则新行)。
    ///
    /// 可变列口径照基线 `widget.py:1341-1357` 的 `update` 标记:随回报走的是
    /// `name / traded / traded_price / status / status_msg / datetime`;`symbol /
    /// exchange / type / direction / offset / price / volume / orderid / reference /
    /// gateway_name` 插入后不再被后续回报改写 —— CTP 的后续回报里这些字段可能给空,
    /// 整行覆盖会把「总量」写成 0(`BaseCell.set_content` 的 `if self.is_update` 挡的就是这个)。
    pub fn note_order(&self, o: &ek_data::order::OrderData) {
        let key = o.en_orderid();
        {
            let mut book = self.trade_orders.lock().unwrap();
            match book.get_mut(&key) {
                Some((_, cur)) => {
                    cur.name.clone_from(&o.name);
                    cur.traded = o.traded;
                    cur.traded_price = o.traded_price;
                    cur.status = o.status;
                    cur.status_msg.clone_from(&o.status_msg);
                    cur.datetime = o.datetime;
                }
                None => {
                    let seq = self.trade_seq.fetch_add(1, Ordering::Relaxed) + 1;
                    book.insert(key, (seq, o.clone()));
                }
            }
        }
        self.trade_dirty.store(true, Ordering::Release);
        self.bump();
    }

    /// 一笔成交入账(0.5 裁定:按 `en_tradeid` 去重,新成交在前)。
    ///
    /// 基线的两层口径在这里合成一条:表格层 `TradeMonitor.data_key = ""`(:1267,只插不改、
    /// 不按键更新),引擎层 `trades_filter_dict`(`engine.py:1072-1080`,同一笔成交只算一次,
    /// 注释写明防的是账户重连时柜台重推)。我们的成交表就是用户看到的那本账,而它现在有两个
    /// 事件源(网关推送 + 启动 / 上线播种),所以引擎层那一条必须落到这里,否则同一笔会出两行
    /// —— 实连演示里量出来了:摘账户再重加之后,元账号 3 行成交变 4 行、纯 TD 账号 3 行变 6 行。
    pub fn note_trade(&self, t: &ek_data::trade::TradeData) {
        let id = t.en_tradeid();
        if self.trade_ids.lock().unwrap().contains(&id) {
            return;
        }
        let seq = self.trade_seq.fetch_add(1, Ordering::Relaxed) + 1;
        let dropped = {
            let mut book = self.trade_trades.lock().unwrap();
            book.push_front((seq, t.clone()));
            self.trade_ids.lock().unwrap().insert(id);
            let over = book.len().saturating_sub(TRADE_CAP);
            for _ in 0..over {
                // 挤掉最旧一行同时把它出集:那笔之后再推,还能上屏(去重集不许比账本大)。
                if let Some((_, old)) = book.pop_back() {
                    self.trade_ids.lock().unwrap().remove(&old.en_tradeid());
                }
            }
            over
        };
        if dropped > 0 {
            let total = self
                .trade_dropped
                .fetch_add(dropped as u64, Ordering::AcqRel)
                + dropped as u64;
            // 只在第一次触顶弹一次:触顶之后每笔都丢,弹下去就是刷屏。
            if total == dropped as u64 {
                self.push_alert(
                    crate::toast::AlertLevel::Warning,
                    format!("成交表已达 {TRADE_CAP} 行上限:更早的成交不再显示"),
                );
            }
        }
        self.trade_dirty.store(true, Ordering::Release);
        self.bump();
    }

    /// 一笔持仓入账(基线 PositionMonitor:键 `en_positionid`,可变列照 :1480-1497)。
    ///
    /// 「平仓后残留」由渲染侧处理(基线 :1514-1517 的 `volume == 0 → hideRow`):
    /// 账本留着这一行、把 volume 写成 0,不删行。
    pub fn note_position(&self, p: &ek_data::position::PositionData) {
        let key = p.en_positionid();
        {
            let mut book = self.trade_positions.lock().unwrap();
            match book.get_mut(&key) {
                Some((_, cur)) => {
                    cur.volume = p.volume;
                    cur.yd_volume = p.yd_volume;
                    cur.can_use_volume = p.can_use_volume;
                    cur.frozen = p.frozen;
                    cur.on_road_volume = p.on_road_volume;
                    cur.market_value = p.market_value;
                    cur.avg_price = p.avg_price;
                    cur.price = p.price;
                    cur.last_price = p.last_price;
                    cur.pnl = p.pnl;
                    cur.profit_rate = p.profit_rate;
                    cur.name.clone_from(&p.name);
                }
                None => {
                    let seq = self.trade_seq.fetch_add(1, Ordering::Relaxed) + 1;
                    book.insert(key, (seq, p.clone()));
                }
            }
        }
        self.trade_dirty.store(true, Ordering::Release);
        self.bump();
    }

    /// 一笔资金入账(基线 AccountMonitor:键 `en_accountid`,可变列 balance / frozen)。
    pub fn note_funds(&self, a: &ek_data::account::AccountData) {
        let key = a.en_accountid();
        {
            let mut book = self.trade_funds.lock().unwrap();
            match book.get_mut(&key) {
                Some((_, cur)) => {
                    cur.balance = a.balance;
                    cur.frozen = a.frozen;
                }
                None => {
                    let seq = self.trade_seq.fetch_add(1, Ordering::Relaxed) + 1;
                    book.insert(key, (seq, a.clone()));
                }
            }
        }
        self.trade_dirty.store(true, Ordering::Release);
        self.bump();
    }

    /// 某网关的行全部作废(0.5 M1:摘除 / 下线后不留旧委托旧仓)。返回清掉的行数。
    pub fn clear_gateway_rows(&self, gateway: &str) -> usize {
        let mut removed = 0usize;
        {
            let mut book = self.trade_orders.lock().unwrap();
            let before = book.len();
            book.retain(|_, (_, o)| o.gateway_name != gateway);
            removed += before - book.len();
        }
        {
            let mut book = self.trade_trades.lock().unwrap();
            let before = book.len();
            book.retain(|(_, t)| t.gateway_name != gateway);
            removed += before - book.len();
            // 去重集跟着账本清:这个网关之后再推同一笔成交,还能上屏。
            // 前缀带点(`en_tradeid` = `{网关}.{成交号}`)→ 名字互为前缀的两个网关不会误清。
            let prefix = format!("{gateway}.");
            self.trade_ids
                .lock()
                .unwrap()
                .retain(|id| !id.starts_with(&prefix));
        }
        {
            let mut book = self.trade_positions.lock().unwrap();
            let before = book.len();
            book.retain(|_, (_, p)| p.gateway_name != gateway);
            removed += before - book.len();
        }
        {
            let mut book = self.trade_funds.lock().unwrap();
            let before = book.len();
            book.retain(|_, (_, a)| a.gateway_name != gateway);
            removed += before - book.len();
        }
        if removed > 0 {
            self.trade_dirty.store(true, Ordering::Release);
            self.bump();
        }
        removed
    }

    /// 成交账本触顶丢弃计数(0.5 偏离③;0 = 从没丢过)。
    #[must_use]
    pub fn trade_dropped(&self) -> u64 {
        self.trade_dropped.load(Ordering::Acquire)
    }

    /// 交易监控快照读(渲染):四本账的缓存视图,脏时按帧重建一次。
    ///
    /// 脏标记由入账置真、这里消费 —— 回报潮里一百条事件也只重建一次(每帧一次),
    /// 不是每条事件一次。锁序:先缓存后账本;入账侧只持账本锁,不反向。
    pub fn trade_snap(&self) -> Arc<TradeSnap> {
        let mut cache = self.trade_snap.lock().unwrap();
        if self.trade_dirty.swap(false, Ordering::AcqRel) {
            *cache = Arc::new(self.build_trade_snap());
        }
        Arc::clone(&cache)
    }

    /// 四本账 → 快照。行序 = seq 降序(基线 `insertRow(0)` 的新事件在前),
    /// 同 seq 用键升序兜底,保证可断言。
    fn build_trade_snap(&self) -> TradeSnap {
        fn by_seq<T>(rows: &BTreeMap<String, (u64, T)>) -> Vec<T>
        where
            T: Clone,
        {
            let mut v: Vec<(u64, &String, &T)> =
                rows.iter().map(|(k, (s, v))| (*s, k, v)).collect();
            v.sort_by(|a, b| b.0.cmp(&a.0).then_with(|| a.1.cmp(b.1)));
            v.into_iter().map(|(_, _, v)| v.clone()).collect()
        }
        TradeSnap {
            orders: by_seq(&self.trade_orders.lock().unwrap()),
            trades: self
                .trade_trades
                .lock()
                .unwrap()
                .iter()
                .map(|(_, t)| t.clone())
                .collect(),
            positions: by_seq(&self.trade_positions.lock().unwrap()),
            accounts: by_seq(&self.trade_funds.lock().unwrap()),
        }
    }

    // ---- S6 CTP 配置面 ----

    /// CTP 配置表单读(渲染克隆面)。
    pub fn ctp_form(&self) -> CtpForm {
        self.ctp_form.lock().unwrap().clone()
    }

    /// CTP 配置表单写。
    pub fn set_ctp_form(&self, f: CtpForm) {
        *self.ctp_form.lock().unwrap() = f;
        self.bump();
    }

    // ---- BD-UI-31 表格行选中面 ----

    /// 该行是否为所属表的选中行(渲染判断;无键 = 未选)。
    pub fn row_selected(&self, table: &str, key: &str) -> bool {
        self.row_sel
            .lock()
            .unwrap()
            .get(table)
            .is_some_and(|k| k == key)
    }

    /// 设所属表的选中行(每表一行;同键重复点 = 保持)。
    pub fn select_row(&self, table: &str, key: &str) {
        self.row_sel
            .lock()
            .unwrap()
            .insert(table.to_string(), key.to_string());
    }
}