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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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}