fidc-backtest-engine/crates/fidc-core/src/instrument.rs

use chrono::NaiveDate;
use serde::{Deserialize, Serialize};

pub fn listed_sector_is_kcb(value: &str) -> Option<bool> {
    match value.trim().to_ascii_uppercase().as_str() {
        "科创板" | "KSH" | "STAR" | "STAR_MARKET" => Some(true),
        "主板" | "沪市主板" | "深市主板" | "中小板" | "中小企业板" | "创业板"
        | "北交所" | "北证" | "新三板" | "基础层" | "创新层" | "精选层"
        | "MAIN" | "MAIN_BOARD" | "CHINEXT" | "GEM" | "BJ" | "BJS" | "BJSE"
        | "BSE" => Some(false),
        _ => None,
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Instrument {
    pub symbol: String,
    pub name: String,
    pub board: String,
    pub round_lot: u32,
    #[serde(default, with = "optional_date_format")]
    pub listed_at: Option<NaiveDate>,
    #[serde(default, with = "optional_date_format")]
    pub delisted_at: Option<NaiveDate>,
    #[serde(default = "default_status")]
    pub status: String,
}

impl Instrument {
    /// Classification from the admitted security master, never a code prefix
    /// or a name substring. This does not grant T+0 settlement eligibility.
    pub fn is_exchange_traded_fund(&self) -> bool {
        matches!(self.board.trim().to_ascii_uppercase().as_str(), "ETF" | "EXCHANGE_TRADED_FUND")
    }

    pub fn effective_round_lot(&self) -> u32 {
        self.round_lot.max(1)
    }

    pub fn minimum_order_quantity(&self) -> u32 {
        let board = self.board.trim();
        if board.eq_ignore_ascii_case("KSH") {
            200
        } else if board.eq_ignore_ascii_case("BJS")
            || board.eq_ignore_ascii_case("BJ")
            || board.eq_ignore_ascii_case("BJSE")
        {
            100
        } else {
            self.effective_round_lot()
        }
    }

    pub fn order_step_size(&self) -> u32 {
        let board = self.board.trim();
        if board.eq_ignore_ascii_case("KSH")
            || board.eq_ignore_ascii_case("BJS")
            || board.eq_ignore_ascii_case("BJ")
            || board.eq_ignore_ascii_case("BJSE")
        {
            1
        } else {
            self.effective_round_lot()
        }
    }

    pub fn is_delisted_before(&self, date: NaiveDate) -> bool {
        self.delisted_at
            .is_some_and(|delisted_at| delisted_at < date)
    }

    pub fn is_delisted_on_or_before(&self, date: NaiveDate) -> bool {
        self.delisted_at
            .is_some_and(|delisted_at| delisted_at <= date)
    }

    pub fn is_active_on(&self, date: NaiveDate) -> bool {
        self.listed_at.is_none_or(|listed_at| listed_at <= date)
            && !self.is_delisted_on_or_before(date)
    }

    pub fn dated_market_absence_reason(&self, date: NaiveDate) -> Option<&'static str> {
        if self.listed_at.is_some_and(|listed| date < listed) {
            Some("not_yet_listed")
        } else if self.is_delisted_on_or_before(date) {
            Some("delisted")
        } else {
            None
        }
    }
}

fn default_status() -> String {
    "active".to_string()
}

#[cfg(test)]
mod tests {
    use super::{Instrument, listed_sector_is_kcb};

    #[test]
    fn listing_sector_is_explicit_and_unknown_stays_unknown() {
        assert_eq!(listed_sector_is_kcb("科创板"), Some(true));
        assert_eq!(listed_sector_is_kcb(" star "), Some(true));
        assert_eq!(listed_sector_is_kcb("主板"), Some(false));
        assert_eq!(listed_sector_is_kcb("创业板"), Some(false));
        assert_eq!(listed_sector_is_kcb("北证"), Some(false));
        for value in ["", "-", "SH", "688001.SH", "半导体"] {
            assert_eq!(listed_sector_is_kcb(value), None);
        }
    }

    fn instrument(board: &str, round_lot: u32) -> Instrument {
        Instrument {
            symbol: "000001.SZ".to_string(),
            name: "test".to_string(),
            board: board.to_string(),
            round_lot,
            listed_at: None,
            delisted_at: None,
            status: "active".to_string(),
        }
    }

    #[test]
    fn lifecycle_is_dated_and_latest_undated_terminal_status_is_not_historical_evidence() {
        let mut item = instrument("BJS", 100);
        let listing = chrono::NaiveDate::from_ymd_opt(2026, 8, 5).unwrap();
        let removal = chrono::NaiveDate::from_ymd_opt(2026, 9, 10).unwrap();
        item.listed_at = Some(listing);
        item.delisted_at = Some(removal);
        assert_eq!(item.dated_market_absence_reason(listing.pred_opt().unwrap()), Some("not_yet_listed"));
        assert!(item.is_active_on(listing));
        assert!(!item.is_active_on(removal));
        assert_eq!(item.dated_market_absence_reason(removal), Some("delisted"));
        item.delisted_at = None;
        for status in ["delisting", "delisted", "inactive", "terminated"] {
            item.status = status.into();
            assert!(item.is_active_on(listing));
            assert_eq!(item.dated_market_absence_reason(listing), None);
        }
    }

    #[test]
    fn order_quantity_rules_are_case_insensitive_without_allocating_normalized_boards() {
        let kcb = instrument(" kSh ", 100);
        assert_eq!(kcb.minimum_order_quantity(), 200);
        assert_eq!(kcb.order_step_size(), 1);

        let bjse = instrument("bjse", 100);
        assert_eq!(bjse.minimum_order_quantity(), 100);
        assert_eq!(bjse.order_step_size(), 1);

        let main_board = instrument("SZSE", 50);
        assert_eq!(main_board.minimum_order_quantity(), 50);
        assert_eq!(main_board.order_step_size(), 50);
    }
}

mod optional_date_format {
    use chrono::NaiveDate;
    use serde::{self, Deserialize, Deserializer, Serializer};

    const FORMAT: &str = "%Y-%m-%d";

    pub fn serialize<S>(value: &Option<NaiveDate>, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        match value {
            Some(date) => serializer.serialize_some(&date.format(FORMAT).to_string()),
            None => serializer.serialize_none(),
        }
    }

    pub fn deserialize<'de, D>(deserializer: D) -> Result<Option<NaiveDate>, D::Error>
    where
        D: Deserializer<'de>,
    {
        let value = Option::<String>::deserialize(deserializer)?;
        match value.as_deref().map(str::trim).filter(|v| !v.is_empty()) {
            Some(text) => NaiveDate::parse_from_str(text, FORMAT)
                .map(Some)
                .map_err(serde::de::Error::custom),
            None => Ok(None),
        }
    }
}