ek-ctp 0.11.11

//! CTP 码值映射与 MySQL 时间换算(逐字对照 `enkeep_ctp/gateway/ctp_gateway.py`
//! 顶部映射表 66-128 行)。
//!
//! 码值常量带线值引用(`api/ctp_constant.py` 行号);错配翻译策略:能 `Option`
//! 的全 `Option`,由调用方按原稿行为处置(合约行静默丢/委托行 info 日志丢/
//! 撤单 parse 失败 console 级特价)。

use crate::wire::{
    DepthMarketData, ErrorField, InputOrderAction, InstrumentField, InvestorPositionField,
    OrderField, TradeField, TradingAccountField,
};
use ek_data::account::AccountData;
use ek_data::constant::{Asset, Direction, Exchange, Offset, OrderType, Status};
use ek_data::contract::ContractData;
use ek_data::order::OrderData;
use ek_data::tick::TickData;
use ek_data::time::DtNs;
use ek_data::trade::TradeData;
use std::time::{SystemTime, UNIX_EPOCH};

// ================ CTP 码值(原稿 `constants` 表;线值取 api/ctp_constant.py) ================

/// 浮点极值标识(原稿 127 行 `MAX_FLOAT = sys.float_info.max`;
/// IEEE-754 与 Rust `f64::MAX` 同值)。
pub const MAX_FLOAT: f64 = f64::MAX;

/// 委托状态码(常量 120-128):`'0'`全成交/`'1'`部分成交尚在队列/`'3'`未成交尚在队列/
/// `'5'`已撤销/`'a'`未知;原稿 STATUS_CTP2VT 只登记这五键(67-73)。
const OST_ALL_TRADED: &str = "0";
const OST_PART_TRADED_Q: &str = "1";
const OST_NO_TRADE_Q: &str = "3";
const OST_CANCELED: &str = "5";
const OST_UNKNOWN: &str = "a";

/// 报单方向/持仓方向码(常量 163-169):买 `'0'`/卖 `'1'`/净 `'1'`/多 `'2'`/空 `'3'`;
/// 原稿 DIRECTION_CTP2VT 把 D_Buy/D_Sell 与 PD_Long/PD_Short 合并一表(80-82)。
const D_BUY: &str = "0";
const D_SELL: &str = "1";
/// 持仓方向码:净 `'1'`(槽位带说明,不参表——注意 CTP 码值冲突:PD_Net 与
/// D_Sell 都是 `'1'`,原稿 dict 同冲突,`'1'` 一律解析为 SHORT,行为逐字保留)。
#[allow(dead_code)]
const PD_NET: &str = "1";
const PD_LONG: &str = "2";
const PD_SHORT: &str = "3";

/// 开平标志码(常量 206-212 / OFEN 变体 1118-1124):开 `'0'`/平 `'1'`/平今 `'3'`/
/// 平昨 `'4'`;原稿用 OFEN_* 线值(94-100)。
const OFEN_OPEN: &str = "0";
const OFEN_CLOSE: &str = "1";
const OFEN_CLOSE_TODAY: &str = "3";
const OFEN_CLOSE_YESTERDAY: &str = "4";

/// 报单价格类型码(190-192):市价 `'1'`/限价 `'2'`。
const OPT_ANY_PRICE: &str = "1";
const OPT_LIMIT_PRICE: &str = "2";

/// 有效期类型码(233/235):IOC `'1'`/GFD `'3'`。
const TC_IOC: &str = "1";
const TC_GFD: &str = "3";

/// 成交量类型码(239/241):任意量 `'1'`/全部量 `'3'`。
const VC_AV: &str = "1";
const VC_CV: &str = "3";

/// 产品类码(143-149):期货 `'1'`/期权 `'2'`/组合 `'3'`/现货期权 `'6'`;
/// 原稿 PRODUCT_CTP2VT 这四键(113-118)。
const PC_FUTURES: &str = "1";
const PC_OPTIONS: &str = "2";
/// 产品类码(143-149):期货 `'1'`/期权 `'2'`/组合 `'3'`/现货期权 `'6'`;
/// 原稿 PRODUCT_CTP2VT 这四键(113-118)。组合键仅存档(D-PC,ek-data 无 SPREAD)。
#[allow(dead_code)]
const PC_COMBINATION: &str = "3";
const PC_SPOT_OPTION: &str = "6";

// ================ 产品类白名单(网关勾选) ================

/// 网关收录的产品类白名单(CTP 单字符码 `THOST_FTDC_PC_*`)。
///
/// 语义(D-PC-FILTER,DESIGN.md):**查询侧不过滤**(原稿 `reqQryInstrument({})` 全量,
/// 且实测三个查询口都无法按类型过滤),**收录侧严格丢弃** —— 不在名单内的合约行
/// 既不进共享合约表,也不上抛 `eContract`。
///
/// 空名单**绝不等于「全丢」**:一律回落默认(期货)。理由不是便利,是守卫 ——
/// `contracts` 为空会让持仓查询整条被跳过(driver.rs 的 `contracts.is_empty()` 守卫),
/// 一次误配置就把持仓数据关掉。
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct ProductClasses(pub Vec<String>);

impl ProductClasses {
    /// 默认勾选:只有期货。
    pub fn default_classes() -> Vec<String> {
        vec![PC_FUTURES.to_string()]
    }

    /// 归一化:去首尾空白、去重、丢弃非法码(CTP 产品类码是单字符),
    /// 结果为空则回落 [`ProductClasses::default_classes`]。返回有序去重表。
    pub fn normalize(&self) -> Vec<String> {
        let mut out: Vec<String> = self
            .0
            .iter()
            .map(|c| c.trim().to_string())
            .filter(|c| c.chars().count() == 1 && !c.is_empty())
            .collect();
        out.sort();
        out.dedup();
        if out.is_empty() {
            return Self::default_classes();
        }
        out
    }

    /// 该产品类码是否收录。
    pub fn accepts(&self, product_class: &str) -> bool {
        self.normalize().iter().any(|c| c == product_class)
    }
}

// ================ 枚举翻译 ================

/// 交易所代码 → [`Exchange`](原稿 EXCHANGE_CTP2VT 103-110 的**内联 match**
/// 六键,不依赖 ek-data `Exchange::ALL` 变体顺序,避免跨 crate 耦合;miss → `None`)。
pub fn exchange_of(exchange_id: &str) -> Option<Exchange> {
    match exchange_id {
        "CFFEX" => Some(Exchange::CFFEX),
        "SHFE" => Some(Exchange::SHFE),
        "CZCE" => Some(Exchange::CZCE),
        "DCE" => Some(Exchange::DCE),
        "INE" => Some(Exchange::INE),
        "GFEX" => Some(Exchange::GFEX),
        _ => None,
    }
}

/// 产品类码 → [`Asset`](原稿 PRODUCT_CTP2VT;miss → `None`)。
///
/// 偏差记录(D-PC,DESIGN.md):原稿把 PC_Combination('3') 映到 `Asset.SPREAD`
/// —— ek-data 0.2.2 的 `Asset` 无 SPREAD 变体(组合面在 InstrumentType 正交),
/// 故本表组合类返回 None → 合约行告警跳过。
pub fn asset_from(product_class: &str) -> Option<Asset> {
    match product_class {
        PC_FUTURES => Some(Asset::FUTURES),
        PC_OPTIONS | PC_SPOT_OPTION => Some(Asset::OPTION),
        // D-PC:原稿 SPREAD 目标在本数据面缺失 → None(skip+告警)
        _ => None,
    }
}

/// 委托状态码 → [`Status`](原稿 STATUS_CTP2VT 五键;miss → `None`,
/// 原稿行为 = `write_log` 后丢弃该行)。
pub fn status_of(code: &str) -> Option<Status> {
    match code {
        OST_NO_TRADE_Q => Some(Status::NOTTRADED),
        OST_PART_TRADED_Q => Some(Status::PARTTRADED),
        OST_ALL_TRADED => Some(Status::ALLTRADED),
        OST_CANCELED => Some(Status::CANCELLED),
        OST_UNKNOWN => Some(Status::SUBMITTING),
        _ => None,
    }
}

/// 方向码 → [`Direction`](D_* 与 PD_* 合并表,原稿 80-82)。
pub fn direction_from(code: &str) -> Option<Direction> {
    match code {
        D_BUY | PD_LONG => Some(Direction::LONG),
        D_SELL | PD_SHORT => Some(Direction::SHORT),
        _ => None,
    }
}

/// 开平码(OFEN_*)→ [`Offset`]。
pub fn offset_from(code: &str) -> Option<Offset> {
    match code {
        OFEN_OPEN => Some(Offset::OPEN),
        OFEN_CLOSE => Some(Offset::CLOSE),
        OFEN_CLOSE_TODAY => Some(Offset::CLOSETODAY),
        OFEN_CLOSE_YESTERDAY => Some(Offset::CLOSEYESTERDAY),
        _ => None,
    }
}

/// (价格类型, 有效期, 成交量类型)三元组 → [`OrderType`](原稿 ORDERTYPE_VT2CTP
/// 85-90 反演;misse → `None`,原稿 write_log 后丢行)。
pub fn order_type_from(price_type: &str, time_cond: &str, volume_cond: &str) -> Option<OrderType> {
    match (price_type, time_cond, volume_cond) {
        (OPT_LIMIT_PRICE, TC_GFD, VC_AV) => Some(OrderType::LIMIT),
        (OPT_ANY_PRICE, TC_GFD, VC_AV) => Some(OrderType::MARKET),
        (OPT_LIMIT_PRICE, TC_IOC, VC_AV) => Some(OrderType::FAK),
        (OPT_LIMIT_PRICE, TC_IOC, VC_CV) => Some(OrderType::FOK),
        _ => None,
    }
}

/// 发单用的方向/开平/类型三元组回探(原稿 DIRECTION_VT2CTP / OFFSET_VT2CTP /
/// ORDERTYPE_VT2CTP 76-90;`OrderType` 回撤三元组是正演)。
pub fn direction_to(d: Direction) -> Option<&'static str> {
    match d {
        Direction::LONG => Some(D_BUY),
        Direction::SHORT => Some(D_SELL),
        _ => None,
    }
}

/// [`Offset`] → 开平码(OFEN_*);`Offset::NONE` 不在原稿表内(misse → `None`)。
pub fn offset_to(o: Offset) -> Option<&'static str> {
    match o {
        Offset::OPEN => Some(OFEN_OPEN),
        Offset::CLOSE => Some(OFEN_CLOSE),
        Offset::CLOSETODAY => Some(OFEN_CLOSE_TODAY),
        Offset::CLOSEYESTERDAY => Some(OFEN_CLOSE_YESTERDAY),
        _ => None,
    }
}

/// [`OrderType`] → (价格类型码, 有效期码, 量码) 发单三元组。
pub fn order_type_to(t: OrderType) -> Option<(&'static str, &'static str, &'static str)> {
    match t {
        OrderType::LIMIT => Some((OPT_LIMIT_PRICE, TC_GFD, VC_AV)),
        OrderType::MARKET => Some((OPT_ANY_PRICE, TC_GFD, VC_AV)),
        OrderType::FAK => Some((OPT_LIMIT_PRICE, TC_IOC, VC_AV)),
        OrderType::FOK => Some((OPT_LIMIT_PRICE, TC_IOC, VC_CV)),
        _ => None,
    }
}

// ================ 精度与时间 ================

/// 异常浮点值修正(原稿 895-899 行):MAX_FLOAT → 0。
pub fn adjust_price(price: f64) -> f64 {
    if price == MAX_FLOAT { 0.0 } else { price }
}

/// Howard Hinnant civil→days 算法(自 1970-01-01 的天数;零依赖)。
///
/// 注:`doy` 里的 `(153*mx + 2)/5` 那个 **`+2` 不能写成 `-2`** —— 写成 `-2` 会让
/// **部分日期整体差一天**(实测 2026-01-01、2026-04-15/16 差一天,而 2026-03-01、
/// 2026-12-30 恰好正确,所以自比型单测照不出来)。2026-10-15 实盘联调靠"行情新鲜度"
/// 与 ek-data `civil_to_nanos` 独立真值比对才抓到。
fn days_from_civil(y: i64, m: i64, d: i64) -> i64 {
    let y = if m <= 2 { y - 1 } else { y };
    let era = if y >= 0 { y } else { y - 399 } / 400;
    let yoe = y - era * 400;
    let doy = (153 * (m + if m > 2 { -3 } else { 9 }) + 2) / 5 + d - 1;
    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
    era * 146097 + doe - 719468
}

/// CTP 时间戳 → [`DtNs`](UTC 纪元纳秒)。
///
/// date = "YYYYMMDD"、time = "HH:MM:SS";约定(D-TZ):CTP 原稿把该组合按
/// `CHINA_TZ = Asia/Shanghai` 处理,本实现按【固定 +08:00】换算为 UTC 纪元纳秒。
/// 畸形输入(长度/数字缺失)→ `None`,调用方全量丢行(原稿会 strptime 异常)。
pub fn ctp_datetime(date: &str, time: &str, millis: i64) -> Option<DtNs> {
    // 长度按**字节**判,所以必须先证明两边都是 ASCII:非 ASCII 输入(GBK 报文经 shim
    // 转成 UTF-8 后的汉字)会让下面的 `&time[..2]` 落在多字节字符中间 —— 那是 str 切片
    // panic,而本函数跑在 CTP 回调帧里(edition 2024 的 `extern "C"` 遇 panic 直接
    // abort,全仓无 catch_unwind)。8 字节且全 ASCII 之后,下面每个下标都是字符边界。
    if date.len() != 8 || time.len() != 8 || !date.is_ascii() || !time.is_ascii() {
        return None;
    }
    let digits_ok = |s: &str| s.bytes().all(|b: u8| b.is_ascii_digit());
    if !(digits_ok(date)
        && digits_ok(&time[..2])
        && digits_ok(&time[3..5])
        && digits_ok(&time[6..8]))
    {
        return None;
    }
    let (y, m, d) = (
        date[0..4].parse::<i64>().ok()?,
        date[4..6].parse::<i64>().ok()?,
        date[6..8].parse::<i64>().ok()?,
    );
    let (h, mi, s) = (
        time[0..2].parse::<i64>().ok()?,
        time[3..5].parse::<i64>().ok()?,
        time[6..8].parse::<i64>().ok()?,
    );
    if !((1..=12).contains(&m) && h < 24 && mi < 60 && s < 60) {
        return None;
    }
    // 溢出保护:年月日与毫秒都是经纪人可控字段;公元 2262 之后纳秒不再装得进 i64。
    // 溢出 → `None` 丢行(D-STRUCT-SKIP),而不是 dbg 里 panic(回调帧里 = abort)、
    // release 里静默回绕成错值。
    // CTP 报文的日期/时间是【北京本地墙钟】(原稿按 CHINA_TZ 建 tz-aware datetime),
    // 而 DtNs 是 **UTC 纪元纳秒**(ek-data `time.rs:3-6/29-30`)⇒ 换 UTC 必须**减** 8 小时。
    // 2026-10-15 实盘联调暴露:此前写成 `+ 8*3_600`,所有 tick/委托/成交时间戳整体偏
    // +16 小时(拿"行情新鲜度"跟 `now_nanos()` 一比立刻显形)。
    let secs = days_from_civil(y, m, d)
        .checked_mul(86_400)?
        .checked_add(h * 3_600 + mi * 60 + s - 8 * 3_600)?;
    secs.checked_mul(1_000_000_000)?
        .checked_add(millis.checked_mul(1_000_000)?)
}

/// 纪元毫秒(0.9.0 状态口用:登录/回报/断开的「最近时刻」都以此为准)。
///
/// 口径:ek-data `time::now_nanos()`(墙上时钟,纪元纳秒)**除以 1e6** —— 不另起
/// 一个时钟源,状态口的时刻与 tick/委托/成交的时间戳同源于同一把钟,消费侧
/// (ek-ui)拿 `sampled_ms` 减别的 crate 的 `now_nanos()/1e6` 才是同一把尺。
/// 不用单调钟:`ctp.status` 的回带值要被**跨插件、跨进程重启**的界面读,
/// 单调钟的零点在别处没有意义;差值由消费侧做减法,不受时区影响。
#[must_use]
pub fn now_epoch_ms() -> i64 {
    ek_data::time::now_nanos() / 1_000_000
}

/// 上海本地当日("YYYYMMDD";eTimer 秒级刷新口径,对齐原稿 md 的 update_date 406-408)。
pub fn shanghai_now_date() -> String {
    let secs = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_secs() as i64)
        .unwrap_or(0)
        + 8 * 3_600;
    let days = secs.div_euclid(86_400);
    // 反算 civil(经 Hinnant days_from_civil 的逆,长年等价于儒略法;40 年内无损)
    let z = days + 719_468;
    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
    let doe = z - era * 146_097;
    let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365;
    let y = yoe + era * 400;
    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
    let mp = (5 * doy + 2) / 153;
    let d = doy - (153 * mp + 2) / 5 + 1;
    let m = if mp < 10 { mp + 3 } else { mp - 9 };
    let y = if m <= 2 { y + 1 } else { y };
    format!("{y:04}{m:02}{d:02}")
}

// ================ 对象映射(wire → ek-data) ================

/// CTP 错误行 → 日志正文(原稿 `write_error` 216-222:`"{msg}，代码：{id}，信息：{m}"`)。
pub fn error_text(msg: &str, e: &ErrorField) -> String {
    format!("{}，代码：{}，信息：{}", msg, e.error_id, e.error_msg)
}

/// 合约映射结果:期货期权链按 [`Asset`] 过滤,非映射产品类整行静默丢
/// (原稿 632-655 的 `if product:` 面;不产生日志)。
pub enum Mapped<T> {
    /// 映射成功
    Ok(T),
    /// 整行丢(附原因;是否写日志由调用方按原稿行为定)
    Skip(String),
}

// ================ 映射 ================

/// "YYYYMMDD" → `Option<i32>`(8 位 ASCII 数字严格验;缺省/畸形 ⇒ `None`)。
///
/// 附加轴专用:CTP 日期字符串恒为 ASCII(GBK↔UTF-8 转换不改变它)。
/// 全零串 `"00000000"` 视为缺省(校历无效的整零值不该作为日历标签上岸)。
fn yyyymmdd_i32(s: &str) -> Option<i32> {
    if s.len() != 8 || !s.bytes().all(|b| b.is_ascii_digit()) {
        return None;
    }
    match s.parse::<i32>() {
        Ok(0) => None,
        Ok(v) => Some(v),
        Err(_) => None,
    }
}

/// 行情行 → [`TickData`](原稿 301-366。
///
/// - 缺 UpdateTime → `Mapped::Skip("无时间戳的异常行情")`(原稿 303-305 静默丢)。
/// - 交易日口径:ActionDay 空或大商所 → 用上层传入的 current_date(313-317)。
/// - 大商所特判原样:DCE 的 ActionDay 不能当自然日用 ⇒ 全部 current_date
///   (`contract.exchange == Exchange::DCE` 或空 action_day)。
/// - 时间戳带毫秒:`.{UpdateMillisec}`(319-320)。
/// - `datetime` 之外的两条日期轴(记档偏差,原稿网关不产出;下游 2514-2521 才用启发式
///   推交易日):`trading_day` = 报文 `TradingDay` 原值(业务日权威);`action_day` =
///   参与拼 `datetime` 的那个日期串(规则化自然日)。两轴都保留报文缺省 → `None`。
/// - 二至五档骨架:`BidVolume2 或 AskVolume2 非零`才添盘口(345-364)。
/// - `last_volume` 原稿网关**不复算**(TickData 缺省 0),此处也照留。
pub fn tick_from(
    dm: &DepthMarketData,
    contract: Option<&ContractData>,
    gw: &str,
    current_date: &str,
) -> Mapped<TickData> {
    if dm.update_time.is_empty() {
        return Mapped::Skip("行情缺少更新时间".into());
    }
    let Some(contract) = contract else {
        return Mapped::Skip("合约未收录(合约查询未完成前丢弃)".into());
    };
    let exchange = contract.exchange;
    let date_str = if dm.action_day.is_empty() || exchange == Exchange::DCE {
        current_date.to_string()
    } else {
        dm.action_day.clone()
    };
    let Some(dt) = ctp_datetime(&date_str, &dm.update_time, dm.update_millisec) else {
        return Mapped::Skip("时间戳畸形".into());
    };
    let trading_day = yyyymmdd_i32(&dm.trading_day);
    let action_day = yyyymmdd_i32(&date_str);
    let mut tick = TickData {
        gateway_name: gw.to_string(),
        symbol: dm.instrument_id.clone(),
        exchange,
        datetime: dt,
        trading_day,
        action_day,
        name: contract.name.clone(),
        volume: dm.volume,
        turnover: dm.turnover,
        open_interest: dm.open_interest,
        last_price: adjust_price(dm.last_price),
        limit_up: adjust_price(dm.upper_limit_price),
        limit_down: adjust_price(dm.lower_limit_price),
        open_price: adjust_price(dm.open_price),
        high_price: adjust_price(dm.highest_price),
        low_price: adjust_price(dm.lowest_price),
        pre_close: adjust_price(dm.pre_close_price),
        bid_price_1: adjust_price(dm.bid_price1),
        ask_price_1: adjust_price(dm.ask_price1),
        bid_volume_1: dm.bid_volume1,
        ask_volume_1: dm.ask_volume1,
        ..TickData::default()
    };
    if dm.bid_volume2 != 0.0 || dm.ask_volume2 != 0.0 {
        tick.bid_price_2 = adjust_price(dm.bid_price2);
        tick.bid_price_3 = adjust_price(dm.bid_price3);
        tick.bid_price_4 = adjust_price(dm.bid_price4);
        tick.bid_price_5 = adjust_price(dm.bid_price5);
        tick.ask_price_2 = adjust_price(dm.ask_price2);
        tick.ask_price_3 = adjust_price(dm.ask_price3);
        tick.ask_price_4 = adjust_price(dm.ask_price4);
        tick.ask_price_5 = adjust_price(dm.ask_price5);
        tick.bid_volume_2 = dm.bid_volume2;
        tick.bid_volume_3 = dm.bid_volume3;
        tick.bid_volume_4 = dm.bid_volume4;
        tick.bid_volume_5 = dm.bid_volume5;
        tick.ask_volume_2 = dm.ask_volume2;
        tick.ask_volume_3 = dm.ask_volume3;
        tick.ask_volume_4 = dm.ask_volume4;
        tick.ask_volume_5 = dm.ask_volume5;
    }
    Mapped::Ok(tick)
}

/// 合约行 → [`ContractData`](原稿 632-654;产品类 miss → `Mapped::Skip` 静默丢,
/// 交易所 miss → `Mapped::Skip`(原稿此处交易所未映射会 KeyError,端口换成结构化跳过))。
pub fn contract_from(inf: &InstrumentField, gw: &str) -> Mapped<ContractData> {
    let Some(asset) = asset_from(&inf.product_class) else {
        return Mapped::Skip(format!("产品类码 {} 未映射", inf.product_class));
    };
    let Some(exchange) = exchange_of(&inf.exchange_id) else {
        return Mapped::Skip(format!("交易所码 {} 未映射", inf.exchange_id));
    };
    Mapped::Ok(ContractData {
        gateway_name: gw.to_string(),
        symbol: inf.instrument_id.clone(),
        exchange,
        name: inf.instrument_name.clone(),
        asset,
        // 原稿不填 instrument_type(缺省 None,已按现货样例比对)
        size: inf.volume_multiple,
        price_tick: inf.price_tick,
        max_limit_order_volume: Some(inf.max_limit_order_volume),
        min_limit_order_volume: Some(inf.min_limit_order_volume),
        max_market_order_volume: Some(inf.max_market_order_volume),
        min_market_order_volume: Some(inf.min_market_order_volume),
        delivery_year: Some(inf.delivery_year as i32),
        delivery_month: Some(inf.delivery_month as i32),
        product_id: Some(inf.product_id.clone()),
        is_trading: Some(inf.is_trading == 1),
        ..ContractData::default()
    })
}

/// 单委托行 → [`OrderData`](原稿 onRtnOrder 669-716;订单号三段下划线)。
///
/// 0.7.0(甲):`contract` 参数退役 —— `symbol` 取报文 InstrumentID,
/// `exchange` 由调用方用报文 ExchangeID 经 [`exchange_of`] 预映射后传入
/// (未映射的行在驱动层丢弃 + 去重 WARNING,到不了这里)。
pub fn order_from(of: &OrderField, exchange: Exchange, gw: &str) -> Mapped<OrderData> {
    // 原稿 681:委托号先算,未知状态/类型日志都携带完整订单号(685/699,全角标点)
    let orderid = format!("{}_{}_{}", of.front_id, of.session_id, of.order_ref);
    let Some(status) = status_of(&of.order_status) else {
        return Mapped::Skip(format!("收到不支持的委托状态，委托号：{}", orderid));
    };
    let Some(order_type) = order_type_from(
        &of.order_price_type,
        &of.time_condition,
        &of.volume_condition,
    ) else {
        return Mapped::Skip(format!("收到不支持的委托类型，委托号：{}", orderid));
    };
    let Some(dt) = ctp_datetime(&of.insert_date, &of.insert_time, 0) else {
        return Mapped::Skip("委托时间戳畸形".into());
    };
    let (direction, offset) = match (
        direction_from(&of.direction),
        offset_from(&of.comb_offset_flag),
    ) {
        (Some(d), Some(o)) => (Some(d), o),
        _ => return Mapped::Skip("委托方向/开平码未映射".into()),
    };
    Mapped::Ok(OrderData {
        gateway_name: gw.to_string(),
        symbol: of.instrument_id.clone(),
        exchange,
        orderid,
        order_type,
        direction,
        offset,
        price: of.limit_price,
        volume: of.volume_total_original,
        traded: of.volume_traded,
        status,
        datetime: Some(dt),
        ..OrderData::default()
    })
}

/// 单成交行 → [`TradeData`](原稿 onRtnTrade 720-747;仓位报单号由 sysid 表换算)。
///
/// 0.7.0(甲):`contract` 参数退役 —— 语义同 [`order_from`];原稿的成交
/// 更新本来就取 `trade.exchange`(converter 语义),这里只是把同一条纪律
/// 落到映射层。
pub fn trade_from(
    tf: &TradeField,
    orderid: &str,
    exchange: Exchange,
    gw: &str,
) -> Mapped<TradeData> {
    let Some(dt) = ctp_datetime(&tf.trade_date, &tf.trade_time, 0) else {
        return Mapped::Skip("成交时间戳畸形".into());
    };
    let (direction, offset) = match (direction_from(&tf.direction), offset_from(&tf.offset_flag)) {
        (Some(d), Some(o)) => (Some(d), o),
        _ => return Mapped::Skip("成交方向/开平码未映射".into()),
    };
    Mapped::Ok(TradeData {
        gateway_name: gw.to_string(),
        symbol: tf.instrument_id.clone(),
        exchange,
        orderid: orderid.to_string(),
        tradeid: tf.trade_id.clone(),
        direction,
        offset,
        price: tf.price,
        volume: tf.volume,
        datetime: Some(dt),
        ..TradeData::default()
    })
}

/// 资金行 → [`AccountData`](原稿 604-610)。
///
/// frozen = FrozenMargin + FrozenCash + FrozenCommission 三项求和;
/// CTP `Available` 字段**按原稿语义属派生面**(balance − frozen 的差 =
/// 占用保证金),ek-data 的 available() 为派生 —— 差额详见 DESIGN.md D-AVAIL。
pub fn account_from(ta: &TradingAccountField, gw: &str) -> AccountData {
    AccountData {
        gateway_name: gw.to_string(),
        accountid: ta.account_id.clone(),
        balance: ta.balance,
        frozen: ta.frozen_margin + ta.frozen_cash + ta.frozen_commission,
    }
}

/// 累积一次仓位行(原稿 546-586;合并语义:键 = (InstrumentID, PosiDirection),
/// SHFE/INE 昨仓特判,对向仓量记冻结)。
pub fn accumulate_position(
    row: &InvestorPositionField,
    pos: &mut ek_data::PositionData,
    exchange: Exchange,
    contract_size: f64,
) {
    // 上期系昨仓特判(原稿 559-565 逐字,**零补全**):
    //   if exchange in {SHFE, INE}:
    //       if YdPosition and not TodayPosition: yd_volume = Position
    //   else:                                # 连回上 if(非上期系)
    //       yd_volume = Position - TodayPosition
    // 注意两处均为**赋值**(562/565),非累加——SHFE 今/昨两行同键时,昨行
    // 命中特判最后一次赋值,结果与原稿一致;不满足特判则**什么都不写**。
    if exchange == Exchange::SHFE || exchange == Exchange::INE {
        if row.yd_position != 0.0 && row.today_position == 0.0 {
            pos.yd_volume = row.position;
        }
    } else {
        pos.yd_volume = row.position - row.today_position;
    }
    // 累积量与盈亏(571-580):volume += Position;pnl += PositionProfit;
    // 均价 = (上成本 + 本行 PositionCost) / (量×乘数),量与乘数皆非零才写。
    let cost = pos.price * pos.volume * contract_size;
    pos.volume += row.position;
    pos.pnl += row.position_profit;
    if pos.volume != 0.0 && contract_size != 0.0 {
        pos.price = (cost + row.position_cost) / (pos.volume * contract_size);
    }
    // 冻结量:多头仓累计空头冻结,空头仓累计多头冻结(583-586)。
    if pos.direction == Direction::LONG {
        pos.frozen += row.short_frozen;
    } else {
        pos.frozen += row.long_frozen;
    }
}

/// 单仓位行建仓初值(原稿 551-556;零值骨架由驱动层累加)。
pub fn new_position_data(
    symbol: &str,
    exchange: Exchange,
    direction: Option<Direction>,
    gw: &str,
) -> Option<ek_data::PositionData> {
    Some(ek_data::PositionData {
        gateway_name: gw.to_string(),
        symbol: symbol.to_string(),
        exchange,
        direction: direction?,
        ..ek_data::PositionData::default()
    })
}

// ================ 下单/撤单请求构建(P1 面) ================

/// 撤单请求的委托号解析(原稿 `cancel_order` 858 行 `req.orderid.split("_")`)。
///
/// 三段 `front_session_ref`(原稿 `f"{frontid}_{sessionid}_{order_ref}"`);
/// 非三段或 front/session 非整数 → `None`(原稿 int() 会抛 ValueError,
/// 本实现转结构化丢弃并记日志,DESIGN.md D6)。
pub fn cancel_action_from(
    orderid: &str,
    symbol: &str,
    exchange: Exchange,
    broker: &str,
    user: &str,
) -> Option<InputOrderAction> {
    let mut parts = orderid.split('_');
    let (front, session, ore) = (parts.next()?, parts.next()?, parts.next()?);
    if parts.next().is_some() {
        return None;
    }
    let (front_id, session_id): (i64, i64) = (front.parse().ok()?, session.parse().ok()?);
    Some(InputOrderAction {
        instrument_id: symbol.to_string(),
        exchange_id: exchange.as_str().to_string(),
        order_ref: ore.to_string(),
        front_id,
        session_id,
        // AF_Delete = '0'(常量 258;原稿 THOST_FTDC_AF_Delete)
        action_flag: "0".to_string(),
        broker_id: broker.to_string(),
        investor_id: user.to_string(),
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn yyyymmdd_i32_accepts_real_dates_and_rejects_garbage() {
        assert_eq!(yyyymmdd_i32("20261015"), Some(20261015));
        // 全零串=缺省(校历无效的整零值不上岸)。
        assert_eq!(yyyymmdd_i32("00000000"), None);
        // 形状畸形:长度错/非 ASCII 数字/空串。
        assert_eq!(yyyymmdd_i32("2026101"), None);
        assert_eq!(yyyymmdd_i32("202610150"), None);
        assert_eq!(yyyymmdd_i32("2026101a"), None);
        assert_eq!(yyyymmdd_i32(""), None);
    }
}