futu_qot/

types.rs

// 行情域通用类型
// 从 proto 结构体转换为 Rust 友好的类型。

/// 股票标识
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct Security {
    /// 所属市场（HK / US / SH / SZ / SG / JP / ...）
    pub market: QotMarket,
    /// 市场内的原始代码（如 HK `"00700"` / US `"NVDA"` / 期权 `"NVDA261219C150000"`）
    pub code: String,
}

impl Security {
    /// 构造 Security，`code` 支持 `&str` / `String` / 任何 `Into<String>`。
    pub fn new(market: QotMarket, code: impl Into<String>) -> Self {
        Self {
            market,
            code: code.into(),
        }
    }

    /// 从 proto Security 转换
    pub fn from_proto(s: &futu_proto::qot_common::Security) -> Self {
        Self {
            market: QotMarket::from_i32(s.market),
            code: s.code.clone(),
        }
    }

    /// 转换为 proto Security
    pub fn to_proto(&self) -> futu_proto::qot_common::Security {
        futu_proto::qot_common::Security {
            market: self.market as i32,
            code: self.code.clone(),
        }
    }
}

/// 市场类型
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(i32)]
#[non_exhaustive]
pub enum QotMarket {
    Unknown = 0,
    HkSecurity = 1,
    HkFuture = 2,
    UsSecurity = 11,
    CnshSecurity = 21,
    CnszSecurity = 22,
    SgSecurity = 31,
    JpSecurity = 41,
    AuSecurity = 51,
    MySecurity = 61,
    CaSecurity = 71,
    FxSecurity = 81,
    // Ref: proto/Qot_Common.proto:22 `QotMarket_CC_Security = 91`.
    // Public QOT crypto market; crypto trade still requires account/broker
    // context and static-cache metadata before write-path routing.
    Crypto = 91,
}

impl QotMarket {
    /// 从 proto i32 值还原；未知值返 [`Self::Unknown`]。
    pub fn from_i32(v: i32) -> Self {
        match v {
            1 => Self::HkSecurity,
            2 => Self::HkFuture,
            11 => Self::UsSecurity,
            21 => Self::CnshSecurity,
            22 => Self::CnszSecurity,
            31 => Self::SgSecurity,
            41 => Self::JpSecurity,
            51 => Self::AuSecurity,
            61 => Self::MySecurity,
            71 => Self::CaSecurity,
            81 => Self::FxSecurity,
            91 => Self::Crypto,
            _ => Self::Unknown,
        }
    }
}

/// 订阅类型
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(i32)]
#[non_exhaustive]
pub enum SubType {
    None = 0,
    Basic = 1,
    OrderBook = 2,
    Ticker = 4,
    RT = 5,
    KLDay = 6,
    KL5Min = 7,
    KL15Min = 8,
    KL30Min = 9,
    KL60Min = 10,
    KL1Min = 11,
    KLWeek = 12,
    KLMonth = 13,
    Broker = 14,
    KLQuarter = 15,
    KLYear = 16,
    KL3Min = 17,
    OrderDetail = 18,
}

/// K 线类型
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(i32)]
#[non_exhaustive]
pub enum KLType {
    Unknown = 0,
    Min1 = 1,
    Day = 2,
    Week = 3,
    Month = 4,
    Year = 5,
    Min5 = 6,
    Min15 = 7,
    Min30 = 8,
    Min60 = 9,
    Min3 = 10,
    Quarter = 11,
}

/// 复权类型
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(i32)]
#[non_exhaustive]
pub enum RehabType {
    None = 0,
    Forward = 1,
    Backward = 2,
}

/// K 线数据点
#[derive(Debug, Clone)]
pub struct KLine {
    /// 所属 K 线时间（字符串表示，如 `"2026-04-21 09:30:00"`）
    pub time: String,
    /// 是否为空白 K 线（该时间点无成交）
    pub is_blank: bool,
    /// 最高价
    pub high_price: f64,
    /// 开盘价
    pub open_price: f64,
    /// 最低价
    pub low_price: f64,
    /// 收盘价
    pub close_price: f64,
    /// 昨收价
    pub last_close_price: f64,
    /// 成交量（股 / 手 / 合约数，视产品而定）
    pub volume: i64,
    /// 成交额
    pub turnover: f64,
    /// 换手率（百分比）
    pub turnover_rate: f64,
    /// 市盈率
    pub pe: f64,
    /// 涨跌幅（百分比，含正负）
    pub change_rate: f64,
    /// Unix 秒时间戳（用于排序 / 对齐 tz）
    pub timestamp: f64,
}

impl KLine {
    pub fn from_proto(k: &futu_proto::qot_common::KLine) -> Self {
        Self {
            time: k.time.clone(),
            is_blank: k.is_blank,
            high_price: k.high_price.unwrap_or(0.0),
            open_price: k.open_price.unwrap_or(0.0),
            low_price: k.low_price.unwrap_or(0.0),
            close_price: k.close_price.unwrap_or(0.0),
            last_close_price: k.last_close_price.unwrap_or(0.0),
            volume: k.volume.unwrap_or(0),
            turnover: k.turnover.unwrap_or(0.0),
            turnover_rate: k.turnover_rate.unwrap_or(0.0),
            pe: k.pe.unwrap_or(0.0),
            change_rate: k.change_rate.unwrap_or(0.0),
            timestamp: k.timestamp.unwrap_or(0.0),
        }
    }
}

/// 基本行情数据
#[derive(Debug, Clone)]
pub struct BasicQot {
    /// 对应证券
    pub security: Security,
    /// 是否停牌
    pub is_suspended: bool,
    /// 上市日期
    pub list_time: String,
    /// 价位（最小变动价，spread）
    pub price_spread: f64,
    /// 最新报价更新时间（`"YYYY-MM-DD HH:MM:SS"`）
    pub update_time: String,
    /// 今日最高价
    pub high_price: f64,
    /// 今日开盘价
    pub open_price: f64,
    /// 今日最低价
    pub low_price: f64,
    /// 现价（最新成交价）
    pub cur_price: f64,
    /// 昨收价
    pub last_close_price: f64,
    /// 成交量
    pub volume: i64,
    /// 成交额
    pub turnover: f64,
    /// 换手率（百分比）
    pub turnover_rate: f64,
    /// 振幅（`(high - low) / last_close`，百分比）
    pub amplitude: f64,
}

impl BasicQot {
    pub fn from_proto(q: &futu_proto::qot_common::BasicQot) -> Self {
        Self {
            security: Security::from_proto(&q.security),
            is_suspended: q.is_suspended,
            list_time: q.list_time.clone(),
            price_spread: q.price_spread,
            update_time: q.update_time.clone(),
            high_price: q.high_price,
            open_price: q.open_price,
            low_price: q.low_price,
            cur_price: q.cur_price,
            last_close_price: q.last_close_price,
            volume: q.volume,
            turnover: q.turnover,
            turnover_rate: q.turnover_rate,
            amplitude: q.amplitude,
        }
    }
}

/// 摆盘数据项
#[derive(Debug, Clone)]
pub struct OrderBookEntry {
    /// 档位价格
    pub price: f64,
    /// 该档位合计挂单量
    pub volume: i64,
    /// 该档位挂单笔数
    pub order_count: i32,
}

impl OrderBookEntry {
    pub fn from_proto(ob: &futu_proto::qot_common::OrderBook) -> Self {
        Self {
            price: ob.price,
            volume: ob.volume,
            order_count: ob.oreder_count, // proto 中拼写为 oreder_count
        }
    }
}

/// 摆盘数据
#[derive(Debug, Clone)]
pub struct OrderBookData {
    /// 对应证券
    pub security: Security,
    /// 卖档列表（升序，index 0 为卖一）
    pub ask_list: Vec<OrderBookEntry>,
    /// 买档列表（降序，index 0 为买一）
    pub bid_list: Vec<OrderBookEntry>,
}

/// `Qot_Common.QotMarketState` enum → 人读 label。
///
/// 严格对齐 `proto/Qot_Common.proto:83-124` 的 QotMarketState 枚举（含夜市 /
/// 期货日市 / HkCas 港股收盘竞价 / 美股夜盘等）。
///
/// 历史：v1.4.25 加 `market-state` 命令时把 label 写错了（`Closed=6` 被叫
/// 成 `ClosedToday` 等），v1.4.30 严格按 proto 重写。v1.4.31 从 futucli 抽
/// 到这里统一维护，避免两处拷贝再次漂移。
pub fn market_state_label(s: i32) -> &'static str {
    match s {
        0 => "None",                  // 无交易
        1 => "Auction",               // 竞价
        2 => "WaitingOpen",           // 早盘前等待开盘
        3 => "Morning",               // 早盘
        4 => "Rest",                  // 午间休市
        5 => "Afternoon",             // 午盘
        6 => "Closed",                // 收盘
        8 => "PreMarketBegin",        // 盘前
        9 => "PreMarketEnd",          // 盘前结束
        10 => "AfterHoursBegin",      // 盘后
        11 => "AfterHoursEnd",        // 盘后结束
        12 => "FutuSwitchDate",       // 切换日
        13 => "NightOpen",            // 夜市开盘
        14 => "NightEnd",             // 夜市收盘
        15 => "FutureDayOpen",        // 期货日市开盘
        16 => "FutureDayBreak",       // 期货日市休市
        17 => "FutureDayClose",       // 期货日市收盘
        18 => "FutureDayWaitForOpen", // 期货日市等待开盘
        19 => "HkCas",                // 港股收盘竞价
        20 => "FutureNightWait",      // 夜市等待开盘（已废弃）
        21 => "FutureAfternoon",      // 期货下午开盘（已废弃）
        22 => "FutureSwitchDate",     // 期货切交易日（已废弃）
        23 => "FutureOpen",           // 期货开盘
        24 => "FutureBreak",          // 期货中盘休息
        25 => "FutureBreakOver",      // 期货休息后开盘
        26 => "FutureClose",          // 期货收盘
        27 => "StibAfterHoursWait",   // 科创板盘后撮合等待（已废弃）
        28 => "StibAfterHoursBegin",  // 科创板盘后交易开始（已废弃）
        29 => "StibAfterHoursEnd",    // 科创板盘后交易结束（已废弃）
        30 => "CloseAuction",         // 收市竞价
        31 => "AfternoonEnd",         // 已收盘
        32 => "Night",                // 交易中
        33 => "OvernightBegin",       // 夜盘开始
        34 => "OvernightEnd",         // 夜盘结束
        35 => "TradeAtLast",          // 收盘前成交
        36 => "TradeAuction",         // 收盘前竞价
        37 => "Overnight",            // 美股夜盘交易时段
        _ => "Unknown",
    }
}

#[cfg(test)]
mod tests;