rustdx-complete 1.16.0

功能完整的 A 股数据获取库,完全对标 pytdx
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
//! A 股涨跌停规则:板块判定、涨跌停价、封板/炸板判型、连板高度。
//!
//! 纯函数、无 IO:调用方负责给出正确输入——原始不复权价格、正确的昨收盘
//! (除权日用 [`ex_right_reference`](crate::tcp::stock::ex_right_reference))。
//!
//! 涨跌停价规则:`前收盘 × (1 ± 幅度)`,**四舍五入到分**(与交易所/行情软件
//! 一致)。新股上市首日等特殊涨跌幅不在本模块,调用方应跳过首日
//! (如日线 `prev_close == 0` 的首行)。
//!
//! **主板 ST 的幅度随日期变化**:[`MAIN_ST_10PCT_SINCE`](crate::limit::MAIN_ST_10PCT_SINCE)
//! (2026-07-06)起由 ±5% 调整为
//! ±10%。不带日期的函数按现行规则计算,用于盘中;回算历史(如连板高度)时
//! 用带 `_on` 后缀的版本并传入当日日期。
//!
//! ## 示例
//! ```ignore
//! use rustdx_complete::limit::{self, LimitStatus};
//!
//! let board = limit::board_of("000428").unwrap();
//! let up = limit::limit_up_price(4.26, board, false).unwrap(); // 4.69
//! assert_eq!(
//!     limit::limit_status(4.69, 4.69, up),
//!     Some(LimitStatus::Sealed)
//! );
//! ```

/// 个股所属板块(按代码前缀判定,决定涨跌幅)。
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Board {
    /// 沪深主板(60x / 000·001·002·003)±10%
    Main,
    /// 创业板(300·301·302)±20%
    ChiNext,
    /// 科创板(688·689)±20%
    Star,
    /// 北交所(43·82·83·87·88·92 开头)±30%
    Beijing,
}

/// 沪深主板 ST(风险警示)股票涨跌幅由 ±5% 调整为 ±10% 的生效日(YYYYMMDD)。
///
/// 2026-11-19 实盘核对:141 只主板 ST 中 17 只的当日最高/最低价超出 ±5%,
/// 最大涨跌幅为 +10.09% / -10.00%;历史日线上主板 ST 收于 ±5% 档的次数自
/// 2026 年 7 月起骤降。
pub const MAIN_ST_10PCT_SINCE: u32 = 20260706;

impl Board {
    /// 现行规则下、含 ST 修正的涨跌停幅度(%)。
    ///
    /// 主板 ±10%(ST 自 [`MAIN_ST_10PCT_SINCE`] 起同为 ±10%);创业板/科创板
    /// ±20%(ST 同幅度);北交所 ±30%。新股上市首日等特殊规则不在本模块。
    /// 回算历史请用 [`Board::limit_pct_on`]。
    pub fn limit_pct_for(self, st: bool) -> f64 {
        self.limit_pct_on(st, u32::MAX)
    }

    /// `date`(YYYYMMDD)当日适用的涨跌停幅度(%)。
    ///
    /// 与 [`Board::limit_pct_for`] 的唯一区别:主板 ST 在
    /// [`MAIN_ST_10PCT_SINCE`] 之前是 ±5%。
    pub fn limit_pct_on(self, st: bool, date: u32) -> f64 {
        match self {
            Board::Main if st && date < MAIN_ST_10PCT_SINCE => 5.0,
            Board::Main => 10.0,
            Board::ChiNext | Board::Star => 20.0,
            Board::Beijing => 30.0,
        }
    }

    /// 落库/日志用小写串。
    pub fn as_str(self) -> &'static str {
        match self {
            Board::Main => "main",
            Board::ChiNext => "chinext",
            Board::Star => "star",
            Board::Beijing => "beijing",
        }
    }
}

/// 按代码前缀判定板块。代码应为 6 位数字;无法识别(如指数、基金、债券)
/// 返回 `None`。
pub fn board_of(code: &str) -> Option<Board> {
    let b = code.as_bytes();
    if b.len() != 6 || !b.iter().all(u8::is_ascii_digit) {
        return None;
    }
    match b {
        // 沪市主板 60x(含 601/603/605)
        [b'6', b'0', ..] => Some(Board::Main),
        // 科创板 688/689
        [b'6', b'8', b'8' | b'9', ..] => Some(Board::Star),
        // 深市主板 000/001/002/003(002 中小板已并入主板)
        [b'0', b'0'..=b'3', ..] => Some(Board::Main),
        // 创业板 300/301/302
        [b'3', b'0', b'0'..=b'2', ..] => Some(Board::ChiNext),
        // 北交所 43/82/83/87/88/92
        [b'4', b'3', ..] | [b'8', b'2' | b'3' | b'7' | b'8', ..] | [b'9', b'2', ..] => {
            Some(Board::Beijing)
        }
        _ => None,
    }
}

/// ST 股名识别:名称含 "ST"(含 *ST)即按 ST 幅度处理。
/// 未股改 "S" 前缀股已基本消亡,不单独建模。
pub fn is_st_name(name: &str) -> bool {
    name.contains("ST")
}

/// 按分比较价格相等(涨跌停判定必须免疫浮点误差)。
fn same_fen(a: f64, b: f64) -> bool {
    (a * 100.0).round() == (b * 100.0).round()
}

/// 现行规则下的涨停价(正常交易日)。回算历史请用 [`limit_up_price_on`]。
///
/// `prev_close` 非正或非有限时返回 `None`(除权日昨收应传除权参考价,
/// 见 [`crate::tcp::stock::ex_right_reference`])。
pub fn limit_up_price(prev_close: f64, board: Board, st: bool) -> Option<f64> {
    limit_up_price_on(prev_close, board, st, u32::MAX)
}

/// 现行规则下的跌停价(正常交易日)。非法输入同 [`limit_up_price`]。
pub fn limit_down_price(prev_close: f64, board: Board, st: bool) -> Option<f64> {
    limit_down_price_on(prev_close, board, st, u32::MAX)
}

/// `date`(YYYYMMDD)当日的涨停价。非法输入同 [`limit_up_price`]。
pub fn limit_up_price_on(prev_close: f64, board: Board, st: bool, date: u32) -> Option<f64> {
    limit_price(prev_close, board.limit_pct_on(st, date))
}

/// `date`(YYYYMMDD)当日的跌停价。非法输入同 [`limit_up_price`]。
pub fn limit_down_price_on(prev_close: f64, board: Board, st: bool, date: u32) -> Option<f64> {
    limit_price(prev_close, -board.limit_pct_on(st, date))
}

/// `前收盘 × (1 + 幅度%)` 按交易所口径(十进制四舍五入到分)计算;前收盘非法时
/// 返回 `None`。
///
/// **全程用整数分运算**:`(昨收分 × (100 ± 幅度) + 50) / 100`。直接在浮点上乘再
/// 舍入会出错——`1.15 × 1.1` 在 f64 里是 `1.26499…`,舍入得 1.26,而交易所的
/// 涨停价是 1.27。穷举 0.01~999.99 元 × 10%/20%/30% 两个方向共约 60 万组,
/// 浮点做法有 5133 组差 1 分,会把真实的封板误判成炸板。
fn limit_price(prev_close: f64, pct: f64) -> Option<f64> {
    if !prev_close.is_finite() || prev_close <= 0.0 {
        return None;
    }
    // 昨收本身精确到分,取整只是消除 f64 的表示误差
    let prev_fen = (prev_close * 100.0).round() as i64;
    let pct = pct.round() as i64; // 幅度都是整数百分比(5/10/20/30)
    (prev_fen > 0).then(|| ((prev_fen * (100 + pct) + 50) / 100) as f64 / 100.0)
}

/// 个股当日相对涨停价的状态。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LimitStatus {
    /// 封板:收盘价 = 涨停价(含一字板)。
    Sealed,
    /// 炸板:盘中触板(最高价达涨停价)但收盘未封住。
    Blown,
    /// 未触板。
    Untouched,
}

impl LimitStatus {
    /// 落库/日志用小写串。
    pub fn as_str(self) -> &'static str {
        match self {
            LimitStatus::Sealed => "sealed",
            LimitStatus::Blown => "blown",
            LimitStatus::Untouched => "untouched",
        }
    }
}

/// 判定某日相对涨停价的状态。
///
/// - 收盘 = 涨停价 → [`LimitStatus::Sealed`];
/// - 最高价达涨停价但收盘未封住 → [`LimitStatus::Blown`];
/// - 否则 → [`LimitStatus::Untouched`]。
///
/// `prev_close` 非法时返回 `None`(调用方应跳过该日,如上市首日)。
/// 按现行规则判定,用于盘中;回算历史请用 [`limit_status_on`]。
pub fn limit_status(
    close: f64,
    high: f64,
    prev_close: f64,
    board: Board,
    st: bool,
) -> Option<LimitStatus> {
    limit_status_on(close, high, prev_close, board, st, u32::MAX)
}

/// 按 `date`(YYYYMMDD)当日适用的涨跌幅判定状态,规则同 [`limit_status`]。
///
/// 回算连板高度时逐日调用本函数:主板 ST 在 [`MAIN_ST_10PCT_SINCE`] 前后的
/// 涨停价不同,用现行规则回算旧日期会把当时的涨停板全部漏掉。
pub fn limit_status_on(
    close: f64,
    high: f64,
    prev_close: f64,
    board: Board,
    st: bool,
    date: u32,
) -> Option<LimitStatus> {
    let up = limit_up_price_on(prev_close, board, st, date)?;
    if same_fen(close, up) {
        Some(LimitStatus::Sealed)
    } else if same_fen(high, up) || high > up {
        Some(LimitStatus::Blown)
    } else {
        Some(LimitStatus::Untouched)
    }
}

/// 连板高度:`statuses` 按时间升序,从最近一日往前数连续
/// [`LimitStatus::Sealed`] 的天数。空序列或最近一日未封板 → 0。
pub fn limit_up_streak(statuses: &[LimitStatus]) -> u32 {
    statuses
        .iter()
        .rev()
        .take_while(|s| **s == LimitStatus::Sealed)
        .count() as u32
}

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

    #[test]
    fn board_of_by_prefix() {
        assert_eq!(board_of("600519"), Some(Board::Main)); // 沪主板
        assert_eq!(board_of("605111"), Some(Board::Main));
        assert_eq!(board_of("000001"), Some(Board::Main)); // 深主板
        assert_eq!(board_of("002594"), Some(Board::Main)); // 原中小板
        assert_eq!(board_of("300750"), Some(Board::ChiNext));
        assert_eq!(board_of("301269"), Some(Board::ChiNext));
        assert_eq!(board_of("688981"), Some(Board::Star));
        assert_eq!(board_of("689009"), Some(Board::Star));
        assert_eq!(board_of("832566"), Some(Board::Beijing));
        assert_eq!(board_of("430047"), Some(Board::Beijing));
        assert_eq!(board_of("920002"), Some(Board::Beijing));
        // 非股票(指数/基金/未知前缀/非法代码)
        assert_eq!(board_of("510300"), None); // ETF
        assert_eq!(board_of("999999"), None); // 指数
        assert_eq!(board_of("60005"), None); // 位数不足
        assert_eq!(board_of("000001."), None); // 含非数字
        assert_eq!(board_of(""), None);
    }

    #[test]
    fn limit_prices_main_10pct() {
        // 实测样本:000428 昨收 4.26 → 涨停 4.69(4.686 四舍五入到分)
        let up = limit_up_price(4.26, Board::Main, false).unwrap();
        assert_eq!(up, 4.69);
        assert_eq!(limit_down_price(4.26, Board::Main, false).unwrap(), 3.83);
    }

    #[test]
    fn limit_prices_by_board_and_st() {
        // 主板 ST 现行 ±10%,与普通主板股票相同
        assert_eq!(limit_up_price(10.03, Board::Main, true).unwrap(), 11.03);
        assert_eq!(limit_down_price(10.03, Board::Main, true).unwrap(), 9.03);
        // 创业板/科创板 ±20%(ST 同幅度)
        assert_eq!(limit_up_price(10.00, Board::ChiNext, false).unwrap(), 12.0);
        assert_eq!(limit_up_price(10.00, Board::ChiNext, true).unwrap(), 12.0);
        assert_eq!(limit_up_price(50.13, Board::Star, false).unwrap(), 60.16);
        // 北交所 ±30%
        assert_eq!(limit_up_price(10.00, Board::Beijing, false).unwrap(), 13.0);
    }

    /// 主板 ST 的幅度在 2026-07-06 由 ±5% 调整为 ±10%;其它板块不随日期变化。
    #[test]
    fn main_st_limit_depends_on_date() {
        let before = MAIN_ST_10PCT_SINCE - 3; // 2026-07-03,调整前最后一个交易日
        // 调整前:10.03 → 10.53(10.5315)/ 9.53(9.5285)
        assert_eq!(
            limit_up_price_on(10.03, Board::Main, true, before),
            Some(10.53)
        );
        assert_eq!(
            limit_down_price_on(10.03, Board::Main, true, before),
            Some(9.53)
        );
        // 生效日起
        assert_eq!(
            limit_up_price_on(10.03, Board::Main, true, MAIN_ST_10PCT_SINCE),
            Some(11.03)
        );
        assert_eq!(
            limit_up_price_on(10.03, Board::Main, true, 20261119),
            Some(11.03)
        );
        // 非 ST 与其它板块不受日期影响
        for date in [before, MAIN_ST_10PCT_SINCE] {
            assert_eq!(Board::Main.limit_pct_on(false, date), 10.0);
            assert_eq!(Board::ChiNext.limit_pct_on(true, date), 20.0);
            assert_eq!(Board::Star.limit_pct_on(true, date), 20.0);
            assert_eq!(Board::Beijing.limit_pct_on(true, date), 30.0);
        }
        // 2026-11-19 实盘样本:*ST雅博 昨收 1.09,现价 1.14(+5% 档)、最高 1.18。
        // 现行规则涨停价是 1.20,这不是封板;按旧的 5% 才会被误判成封板。
        assert_eq!(limit_up_price(1.09, Board::Main, true), Some(1.2));
        assert_eq!(
            limit_status(1.14, 1.18, 1.09, Board::Main, true),
            Some(LimitStatus::Untouched)
        );
        assert_eq!(
            limit_status_on(1.14, 1.14, 1.09, Board::Main, true, before),
            Some(LimitStatus::Sealed)
        );
    }

    /// 交易所口径是十进制四舍五入到分;浮点乘法后再舍入会差 1 分。
    #[test]
    fn limit_prices_use_exact_decimal_rounding() {
        // f64 路径算错的实例:1.15×1.1=1.265 → 1.27(f64 得 1.26)
        assert_eq!(limit_up_price(1.15, Board::Main, false), Some(1.27));
        assert_eq!(limit_down_price(1.15, Board::Main, false), Some(1.04));
        assert_eq!(limit_down_price(2.65, Board::Main, false), Some(2.39));
        assert_eq!(limit_down_price(9.35, Board::Main, false), Some(8.42));
        // 调整前的主板 ST 5%:4.30 → 4.52(f64 得 4.51)
        assert_eq!(
            limit_up_price_on(4.30, Board::Main, true, MAIN_ST_10PCT_SINCE - 1),
            Some(4.52)
        );
        // 穷举 0.01~999.99 元:每个结果都等于整数分的十进制四舍五入
        for (board, pct) in [
            (Board::Main, 10i64),
            (Board::ChiNext, 20),
            (Board::Beijing, 30),
        ] {
            for fen in 1..=99_999i64 {
                let prev = fen as f64 / 100.0;
                let up = limit_up_price(prev, board, false).unwrap();
                let down = limit_down_price(prev, board, false).unwrap();
                assert_eq!(
                    (up * 100.0).round() as i64,
                    (fen * (100 + pct) + 50) / 100,
                    "{prev} 涨停"
                );
                assert_eq!(
                    (down * 100.0).round() as i64,
                    (fen * (100 - pct) + 50) / 100,
                    "{prev} 跌停"
                );
            }
        }
    }

    #[test]
    fn limit_prices_invalid_preclose() {
        assert_eq!(limit_up_price(0.0, Board::Main, false), None); // 上市首日
        assert_eq!(limit_up_price(-1.0, Board::Main, false), None);
        assert_eq!(limit_up_price(f64::NAN, Board::Main, false), None);
    }

    #[test]
    fn limit_status_classification() {
        let _up = limit_up_price(4.26, Board::Main, false).unwrap(); // 4.69
        // 收盘 = 涨停 → 封板(浮点免疫:4.69 vs 4.689999)
        assert_eq!(
            limit_status(4.69, 4.69, 4.26, Board::Main, false),
            Some(LimitStatus::Sealed)
        );
        // 盘中触板(high = 涨停)但收盘未封住 → 炸板
        assert_eq!(
            limit_status(4.60, 4.69, 4.26, Board::Main, false),
            Some(LimitStatus::Blown)
        );
        // 未触板
        assert_eq!(
            limit_status(4.60, 4.65, 4.26, Board::Main, false),
            Some(LimitStatus::Untouched)
        );
        // 首日 prev_close = 0 → None
        assert_eq!(limit_status(4.69, 4.69, 0.0, Board::Main, false), None);
    }

    #[test]
    fn limit_up_streak_counts_recent_seals() {
        let s = [
            LimitStatus::Sealed,
            LimitStatus::Sealed,
            LimitStatus::Blown,
            LimitStatus::Sealed,
            LimitStatus::Sealed,
            LimitStatus::Sealed,
        ];
        assert_eq!(limit_up_streak(&s), 3); // 最近连续 3 板
        assert_eq!(limit_up_streak(&[]), 0);
        assert_eq!(limit_up_streak(&[LimitStatus::Blown]), 0);
    }

    #[test]
    fn is_st_name_detection() {
        assert!(is_st_name("ST易联众"));
        assert!(is_st_name("*ST左江"));
        assert!(is_st_name("STO panasonic")); // 含 ST 即判
        assert!(!is_st_name("平安银行"));
    }

    #[test]
    fn board_as_str_roundtrip_meaning() {
        assert_eq!(Board::Main.as_str(), "main");
        assert_eq!(Board::ChiNext.as_str(), "chinext");
        assert_eq!(Board::Star.as_str(), "star");
        assert_eq!(Board::Beijing.as_str(), "beijing");
    }
}