Skip to main content

financial_api/a_share/
special_data.rs

1use serde::de::DeserializeOwned;
2
3use crate::endpoints;
4use crate::endpoints::join_values;
5use crate::{
6    AShareCode, AnomalyData, AnomalyTag, Client, DragonTigerBoard, DragonTigerData, Error,
7    HotListPeriod, HotStockData, HotStockHistoryData, HotStockTrendData, LadderData,
8    LimitBreakData, LimitBreakSortField, LimitDownData, LimitDownSortField, LimitUpData,
9    LimitUpSortField, NaturalDate, Page, Response, ShanghaiDateMillis, SortDirection,
10    ValidationError,
11};
12
13use super::validate_date_order;
14
15impl Client {
16    /// 获取当日异动分析记录,可按“或”关系组合标签筛选。
17    ///
18    /// # 示例
19    #[doc = concat!(
20        "```no_run\n",
21        include_str!("../../examples/special_data_anomaly_analysis_list.rs"),
22        "\n```"
23    )]
24    pub async fn special_data_anomaly_analysis_list(
25        &self,
26        tag_codes: &[AnomalyTag],
27    ) -> Result<Response<AnomalyData>, Error> {
28        let query = if tag_codes.is_empty() {
29            Vec::new()
30        } else {
31            vec![("tag_codes", join_values("tag_codes", tag_codes, None)?)]
32        };
33        self.get(endpoints::ANOMALY_LIST, &query).await
34    }
35
36    /// 获取最多 50 个 A 股标的的当日异动分析记录。
37    ///
38    /// # 示例
39    #[doc = concat!(
40        "```no_run\n",
41        include_str!("../../examples/special_data_anomaly_analysis_stock.rs"),
42        "\n```"
43    )]
44    pub async fn special_data_anomaly_analysis_stock(
45        &self,
46        thscodes: &[AShareCode],
47    ) -> Result<Response<AnomalyData>, Error> {
48        let query = [("thscodes", join_values("thscodes", thscodes, Some(50))?)];
49        self.get(endpoints::ANOMALY_STOCK, &query).await
50    }
51
52    /// 获取龙虎榜。
53    ///
54    /// # 示例
55    #[doc = concat!(
56        "```no_run\n",
57        include_str!("../../examples/special_data_dragon_tiger_list.rs"),
58        "\n```"
59    )]
60    pub async fn special_data_dragon_tiger_list(
61        &self,
62        board_type: DragonTigerBoard,
63        date: Option<NaturalDate>,
64    ) -> Result<Response<DragonTigerData>, Error> {
65        if let Some(date) = date {
66            self.validate_recent_date(date, "date")?;
67        }
68        let mut query = vec![("board_type", board_type.to_string())];
69        if let Some(date) = date {
70            query.push(("date", date.to_string()));
71        }
72        self.get(endpoints::DRAGON_TIGER, &query).await
73    }
74
75    /// 获取当前个股热榜。
76    ///
77    /// # 示例
78    #[doc = concat!(
79        "```no_run\n",
80        include_str!("../../examples/special_data_hot_stock_list.rs"),
81        "\n```"
82    )]
83    pub async fn special_data_hot_stock_list(
84        &self,
85        period: HotListPeriod,
86    ) -> Result<Response<HotStockData>, Error> {
87        self.get(endpoints::HOT_STOCK_LIST, &[("period", period.to_string())])
88            .await
89    }
90
91    /// 获取指定自然日的历史个股热榜。
92    ///
93    /// # 示例
94    #[doc = concat!(
95        "```no_run\n",
96        include_str!("../../examples/special_data_hot_stock_list_history.rs"),
97        "\n```"
98    )]
99    pub async fn special_data_hot_stock_list_history(
100        &self,
101        date: NaturalDate,
102    ) -> Result<Response<HotStockHistoryData>, Error> {
103        self.validate_recent_date(date, "date")?;
104        self.get(endpoints::HOT_STOCK_HISTORY, &[("date", date.to_string())])
105            .await
106    }
107
108    /// 获取指定 A 股标的的热榜排名趋势。
109    ///
110    /// # 示例
111    #[doc = concat!(
112        "```no_run\n",
113        include_str!("../../examples/special_data_hot_stock_rank_trend.rs"),
114        "\n```"
115    )]
116    pub async fn special_data_hot_stock_rank_trend(
117        &self,
118        thscode: &AShareCode,
119        start_date: NaturalDate,
120        end_date: NaturalDate,
121    ) -> Result<Response<HotStockTrendData>, Error> {
122        validate_date_order(start_date, end_date, "end_date")?;
123        self.validate_recent_date(start_date, "start_date")?;
124        self.validate_recent_date(end_date, "end_date")?;
125        if start_date
126            .checked_add_years(1)
127            .is_none_or(|limit| end_date > limit)
128        {
129            return Err(
130                ValidationError::new("end_date", "date range must not exceed one year").into(),
131            );
132        }
133        let query = [
134            ("thscode", thscode.to_string()),
135            ("start_date", start_date.to_string()),
136            ("end_date", end_date.to_string()),
137        ];
138        self.get(endpoints::HOT_STOCK_TREND, &query).await
139    }
140
141    /// 获取涨停池。
142    ///
143    /// # 示例
144    #[doc = concat!(
145        "```no_run\n",
146        include_str!("../../examples/special_data_limit_up_pool.rs"),
147        "\n```"
148    )]
149    pub async fn special_data_limit_up_pool(
150        &self,
151        date_ms: Option<ShanghaiDateMillis>,
152        page: Page,
153        sort_field: LimitUpSortField,
154        sort_dir: SortDirection,
155    ) -> Result<Response<LimitUpData>, Error> {
156        self.special_data_pool(
157            endpoints::LIMIT_UP_POOL,
158            date_ms,
159            page,
160            sort_field.to_string(),
161            sort_dir,
162        )
163        .await
164    }
165
166    /// 获取跌停池。
167    ///
168    /// # 示例
169    #[doc = concat!(
170        "```no_run\n",
171        include_str!("../../examples/special_data_limit_down_pool.rs"),
172        "\n```"
173    )]
174    pub async fn special_data_limit_down_pool(
175        &self,
176        date_ms: Option<ShanghaiDateMillis>,
177        page: Page,
178        sort_field: LimitDownSortField,
179        sort_dir: SortDirection,
180    ) -> Result<Response<LimitDownData>, Error> {
181        self.special_data_pool(
182            endpoints::LIMIT_DOWN_POOL,
183            date_ms,
184            page,
185            sort_field.to_string(),
186            sort_dir,
187        )
188        .await
189    }
190
191    /// 获取炸板池。
192    ///
193    /// # 示例
194    #[doc = concat!(
195        "```no_run\n",
196        include_str!("../../examples/special_data_limit_break_pool.rs"),
197        "\n```"
198    )]
199    pub async fn special_data_limit_break_pool(
200        &self,
201        date_ms: Option<ShanghaiDateMillis>,
202        page: Page,
203        sort_field: LimitBreakSortField,
204        sort_dir: SortDirection,
205    ) -> Result<Response<LimitBreakData>, Error> {
206        self.special_data_pool(
207            endpoints::LIMIT_BREAK_POOL,
208            date_ms,
209            page,
210            sort_field.to_string(),
211            sort_dir,
212        )
213        .await
214    }
215
216    async fn special_data_pool<T: DeserializeOwned>(
217        &self,
218        path: &str,
219        date_ms: Option<ShanghaiDateMillis>,
220        page: Page,
221        sort_field: String,
222        sort_dir: SortDirection,
223    ) -> Result<Response<T>, Error> {
224        let mut query = vec![
225            ("page", page.number().to_string()),
226            ("size", page.size().to_string()),
227            ("sort_field", sort_field),
228            ("sort_dir", sort_dir.to_string()),
229        ];
230        if let Some(date_ms) = date_ms {
231            query.push(("date_ms", date_ms.to_string()));
232        }
233        self.get(path, &query).await
234    }
235
236    fn validate_recent_date(
237        &self,
238        date: NaturalDate,
239        field: &'static str,
240    ) -> Result<(), ValidationError> {
241        let today = self.shanghai_today();
242        let earliest = today
243            .checked_add_years(-1)
244            .ok_or_else(|| ValidationError::new(field, "could not calculate one-year window"))?;
245        if date < earliest || date > today {
246            return Err(ValidationError::new(
247                field,
248                "must be within the previous natural year and not in the future",
249            ));
250        }
251        Ok(())
252    }
253
254    /// 获取固定覆盖 30 个交易日的连板天梯。
255    ///
256    /// # 示例
257    #[doc = concat!(
258        "```no_run\n",
259        include_str!("../../examples/special_data_limit_up_ladder.rs"),
260        "\n```"
261    )]
262    pub async fn special_data_limit_up_ladder(&self) -> Result<Response<LadderData>, Error> {
263        self.get(endpoints::LIMIT_UP_LADDER, &[] as &[(&str, &str)])
264            .await
265    }
266
267    /// 获取当前飙升榜。
268    ///
269    /// # 示例
270    #[doc = concat!(
271        "```no_run\n",
272        include_str!("../../examples/special_data_skyrocket_list.rs"),
273        "\n```"
274    )]
275    pub async fn special_data_skyrocket_list(
276        &self,
277        period: HotListPeriod,
278    ) -> Result<Response<HotStockData>, Error> {
279        self.get(endpoints::SKYROCKET_LIST, &[("period", period.to_string())])
280            .await
281    }
282}
283
284#[cfg(test)]
285mod tests {
286    use super::*;
287    use crate::ApiKey;
288
289    fn client() -> Client {
290        Client::builder(ApiKey::new("test-api-key").unwrap())
291            .base_url("http://127.0.0.1:9")
292            .reference_date(NaturalDate::parse("2026-08-25").unwrap())
293            .build()
294            .unwrap()
295    }
296
297    #[tokio::test]
298    async fn stock_analysis_rejects_more_than_fifty_targets_before_transport() {
299        let stock = AShareCode::new("600519.SH").unwrap();
300
301        let error = client()
302            .special_data_anomaly_analysis_stock(&vec![stock; 51])
303            .await
304            .unwrap_err();
305
306        assert!(matches!(error, Error::InvalidInput(_)));
307    }
308
309    #[tokio::test]
310    async fn recent_date_capabilities_enforce_their_documented_windows() {
311        let client = client();
312        let stock = AShareCode::new("600519.SH").unwrap();
313
314        for error in [
315            client
316                .special_data_hot_stock_rank_trend(
317                    &stock,
318                    NaturalDate::parse("2024-02-29").unwrap(),
319                    NaturalDate::parse("2025-03-01").unwrap(),
320                )
321                .await
322                .unwrap_err(),
323            client
324                .special_data_hot_stock_list_history(NaturalDate::parse("2025-08-24").unwrap())
325                .await
326                .unwrap_err(),
327            client
328                .special_data_dragon_tiger_list(
329                    DragonTigerBoard::All,
330                    Some(NaturalDate::parse("2026-08-26").unwrap()),
331                )
332                .await
333                .unwrap_err(),
334        ] {
335            assert!(matches!(error, Error::InvalidInput(_)));
336        }
337    }
338}