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