futu_gateway_core/bridge/

reload.rs

use super::*;

/// v1.4.106 codex 0554 F3 [P2]: ms 精度的 unix wall clock — `last_reload_refresh`
/// 写 `started_ms` / `finished_ms` 用. 用 `SystemTime::UNIX_EPOCH` 直接派生,
/// 不走 bridge server-clock runtime（reload 是真实墙钟事件 + status snapshot 给 ops 看,
/// 不是 backend-time-aligned 业务路径, 不需 svr_time_offset 修正）.
fn now_ms() -> u64 {
    crate::bridge::clock::wall_clock_since_unix_epoch_or_zero("admin reload refresh").as_millis()
        as u64
}

/// v1.4.106 codex 0554 F3 [P2]: 后台 refresh 任务的纯逻辑 (剥离自 `reload()`),
/// 便于单测. 不持 `&self`, 只接 `reload_state` clone (None = offline mode 无凭据).
///
/// 返回值是终态 (`Succeeded` / `Failed` / `Skipped` / `NotApplicable`) — caller
/// 用 `*last_reload_refresh.write() = ...` 写回 RwLock.
async fn run_reload_refresh_task(reload_state: Option<ReloadState>) -> ReloadRefreshStatus {
    let Some(state) = reload_state else {
        // offline mode 启动: 没有 reload_state, refresh 跳过
        let finished_ms = now_ms();
        let reason = "no reload_state (daemon started in offline mode); cipher \
                      cache cleared but tgtgt not refreshable"
            .to_string();
        tracing::warn!(reason, "admin reload (async phase): refresh skipped");
        return ReloadRefreshStatus::Skipped {
            finished_ms,
            reason,
        };
    };

    match auth::refresh_credentials_on_disk(
        &state.http,
        &state.account,
        &state.device_id,
        state.client_type,
        state.region_code.as_deref(),
        state.attribution,
    )
    .await
    {
        Ok(report) => {
            let finished_ms = now_ms();
            if report.credentials_refreshed {
                tracing::info!(
                    "admin reload (async phase): credentials refreshed on disk \
                     (new tgtgt picked up by next Platform reconnect)"
                );
                ReloadRefreshStatus::Succeeded {
                    finished_ms,
                    refreshed: true,
                }
            } else {
                // refresh helper 报"already fresh" — 不算失败也不算"做了"
                tracing::info!(
                    "admin reload (async phase): credentials already fresh, \
                     no refresh needed"
                );
                ReloadRefreshStatus::NotApplicable { finished_ms }
            }
        }
        Err(e) => {
            let finished_ms = now_ms();
            // v1.4.42 (external reviewer v1.4.40 报告 P3.4 修): 专门针对 "no cached
            // credentials" 场景加更 actionable 的 hint.
            let err_str = format!("{e}");
            let hinted = if err_str.contains("no cached credentials") {
                format!(
                    "{err_str}\n\
                     【hint】如果这是 moomoo 账户，credentials 文件可能没被首登流程 \
                     save (v1.4.42 已知 bug，根因待 raw response 分析)。workaround:\n\
                     1. ./futu-opend --reset-device --setup-only \
                        --login-account <account> --login-pwd <pwd> --platform moomoo\n\
                     2. 走完 SMS 流程，daemon 早退出 (凭据已写盘)\n\
                     3. 正式启 daemon; admin/reload 后应可正常 refresh"
                )
            } else {
                err_str
            };
            tracing::warn!(
                error = %hinted,
                "admin reload (async phase): credentials refresh failed \
                 (cipher cache still cleared; shutdown + restart opend if \
                 Platform conn is stuck)"
            );
            ReloadRefreshStatus::Failed {
                finished_ms,
                error: hinted,
            }
        }
    }
}

impl GatewayBridge {
    /// v1.4.32+ 只读健康状态快照。
    ///
    /// 走 REST `/api/admin/status`（见 `futu_rest::routes::admin`），CLI 用
    /// `futucli daemon-status` 查。不 mutate 任何 Bridge 状态，可任意时刻调。
    ///
    /// 暴露哪些字段由"运维真实想知道什么"决定：
    /// - login: 登录是否成功、uid、归属地域（判断 auth 状态）
    /// - platform: Platform 通道 connected 吗
    /// - brokers: 每个 broker_id 的名字 + 是否已建 conn + 登录目标 addr
    ///   + keep_alive（判断是不是某个 broker 掉线）
    /// - cache: 是否解锁过、cipher 和 account 数（判断下单链路就绪度）
    pub fn snapshot_status(&self) -> StatusSnapshot {
        let auth_result = self.auth_runtime().auth_result();
        let login_state = self.caches().login_cache.get_login_state();
        let credential = login_state
            .as_ref()
            .and_then(|state| auth::credential_ticket_status(&state.login_account))
            .map(|status| LoginCredentialStatus {
                saved_at: status.saved_at,
                age_days: status.age_days,
                expires_in_days: status.expires_in_days,
                expiry_warning: status.expiry_warning,
            });
        let auth_refresh = self.auth_runtime().client_sig_refresh_status();
        let login = match &auth_result {
            Some(auth) => LoginStatus {
                online: true,
                user_id: Some(auth.user_id),
                // UserAttribution 已经 derive Debug（variant 名就是 "Cn"/"Hk"/...），
                // 直接格式化成两字母 code，和 CLAUDE.md 里的 attribution 表一致。
                attribution: Some(format!("{:?}", auth.user_attribution)),
                credential,
                auth_refresh: auth_refresh.clone(),
            },
            None => LoginStatus {
                online: false,
                user_id: None,
                attribution: None,
                credential: None,
                auth_refresh,
            },
        };

        let platform_connected = self.broker_runtime().platform_connected();
        let platform = PlatformStatus {
            connected: platform_connected,
        };

        // brokers 按 broker_id 排序输出。只列出有活动 conn 的（brokers map 里的），
        // 加上 conn_meta 里的元数据（登录地址 + keep_alive）
        let brokers = self.broker_runtime().broker_statuses();

        let cipher_count = self.caches().trd_cache.ciphers.len();
        let account_count = self.caches().trd_cache.get_accounts().len();
        let stock_list_status = self.caches().static_cache.stock_list_sync_status();
        let security_count = self.caches().static_cache.security_info_count();
        let cache = CacheStats {
            trade_unlocked: cipher_count > 0,
            cached_cipher_count: cipher_count,
            cached_account_count: account_count,
            static_data: StaticCacheStats {
                security_count,
                stock_list_readiness: stock_list_status
                    .readiness_for_security_count(security_count)
                    .as_str(),
                stock_list_first_sync_done: stock_list_status.first_sync_done,
                stock_list_converged: stock_list_status.converged,
                stock_list_sync_started_total: stock_list_status.started_total,
                stock_list_sync_finished_total: stock_list_status.finished_total,
                stock_list_sync_failed_total: stock_list_status.failed_total,
                stock_list_sync_recoverable_retry_total: stock_list_status.recoverable_retry_total,
                stock_list_zero_delta_total: stock_list_status.zero_delta_total,
                stock_list_last_version: stock_list_status.last_version,
                stock_list_last_total_stocks: stock_list_status.last_total_stocks,
                stock_list_last_cached_count: stock_list_status.last_cached_count,
                stock_list_last_finished_ms: stock_list_status.last_finished_ms,
            },
        };

        // v1.4.106 codex 0554 F3 [P2]: clone last_reload_refresh status
        // (RwLock guard 短生命周期, clone 出去避免锁住 snapshot).
        let last_reload_refresh = self.auth_runtime().last_reload_refresh().read().clone();

        StatusSnapshot {
            version: env!("CARGO_PKG_VERSION"),
            login,
            platform,
            brokers,
            cache,
            last_reload_refresh,
        }
    }

    /// v1.4.32+ 重置 trade cipher 缓存（`/api/admin/reload`）。
    ///
    /// 当前 scope 故意小：**只清 cipher cache + 后台刷 credentials**，
    /// 不重跑 HTTP auth 也不重建 broker TCP 连接。理由见
    /// `routes/admin.rs::admin_reload` 的文档。
    ///
    /// 调用后（同步阶段, response return 前已生效）：
    /// - `cache.trade_unlocked` 变 false（cipher 全清）
    /// - 各账户的 `cipher_state_version` 已 bump（v1.4.73 BUG-008 idem
    ///   cache 失效）
    /// - 客户端必须重新 `/api/unlock-trade` 才能下单
    /// - broker TCP / Platform TCP / auth_result 全保持
    ///
    /// 后台阶段（spawn 跑, response return 后异步）：
    /// - v1.4.34: 跑一次 `remember_login` 刷新磁盘 credentials 文件
    ///   tgtgt，下次 Platform 断线重连时自动用新 tgtgt。不动内存
    ///   auth_result（不碰 Bridge 字段可变性，不主动断 TCP）。
    /// - 状态写 auth runtime last-reload status，`/api/admin/status` 暴露
    ///   `Running`/`Succeeded`/`Failed`/`Skipped`/`NotApplicable` 给 ops。
    ///
    /// **v1.4.106 codex 0554 F3 [P2] 拆两阶段**:
    ///
    /// 之前 `reload()` 整段 `await refresh_credentials_on_disk(...)`,
    /// 网络 I/O 几秒, axum admin handler hang 期间 client 不知 cipher 已
    /// 清没. 现在 sync clear 完立刻 return, ops 通过 `/api/admin/status`
    /// 看 last_reload_refresh 进度. cipher 已清是 sync 保证, refresh 是
    /// best-effort fallback (失败也不阻塞 reload 主目的).
    pub fn reload(&self) -> ReloadReport {
        // ── 同步阶段 (sync clear + bump) ──
        // v1.4.106 codex 0554 F1 [P1]: 走 cache helper 同步清 cipher + bump
        // 每个被清账户的 `cipher_state_version`，复用 v1.4.73 A2 BUG-008 的
        // idem cache 失效语义。
        //
        // 之前直接清 `self.caches().trd_cache.ciphers` 会 silent skip bump →
        // reload 后客户端再调 unlock-trade 同 body 时 idempotency cache 命中返
        // stale "cached success" → cipher 仍空 → place-order `-401`。
        //
        // 禁止后续再用 `cache.ciphers.clear()` 直接清；所有 control-plane
        // 路径必须走 helper 保证 bump。
        let (ciphers_dropped, bumped_versions) = self
            .caches()
            .trd_cache
            .clear_all_ciphers_and_bump_versions();
        tracing::warn!(
            ciphers_dropped,
            ?bumped_versions,
            "admin reload (sync phase): trade cipher cache cleared + \
             cipher_state_version bumped (BUG-008 idem cache invalidation); \
             clients must re-unlock"
        );

        // ── 后台阶段 (spawn refresh) ──
        // 把状态置 Running, 然后 spawn 异步 task 跑 refresh_credentials_on_disk.
        let started_ms = now_ms();
        let last_status = self.auth_runtime().last_reload_refresh();
        *last_status.write() = ReloadRefreshStatus::Running { started_ms };

        let reload_state = self.auth_runtime().reload_state();
        self.background_runtime().track(tokio::spawn(async move {
            let final_status = run_reload_refresh_task(reload_state).await;
            *last_status.write() = final_status;
        }));

        // 同步阶段已成 → 立即返
        let message = if ciphers_dropped == 0 {
            "no ciphers to drop; credentials refresh dispatched in background \
             (see /api/admin/status → last_reload_refresh)"
                .to_string()
        } else {
            format!(
                "dropped {ciphers_dropped} trade cipher(s); credentials refresh \
                 dispatched in background (see /api/admin/status → \
                 last_reload_refresh); call /api/unlock-trade again to re-enable \
                 order placement"
            )
        };

        ReloadReport {
            ok: true,
            ciphers_dropped,
            // v1.4.106 拆两阶段后, 同步路径不知道 refresh 结果. 留 None,
            // 真值在 last_reload_refresh 里 ops 自己查 (向后兼容旧 client
            // 期望存在 — 字段保留, 但语义变 "未知 / pending"). 历史 reviewer
            // 写脚本读这两字段时也不会崩 (None 仍合法 JSON).
            credentials_refreshed: false,
            credentials_refresh_error: Some(
                "refresh dispatched in background; query /api/admin/status \
                 (last_reload_refresh) for outcome"
                    .to_string(),
            ),
            message,
        }
    }
}

#[cfg(test)]
mod reload_tests;