Skip to main content

financial_api/a_share/
special_data.rs

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