Skip to main content

financial_api/types/
fund.rs

1use std::str::FromStr;
2
3use serde::{Deserialize, Deserializer, Serialize};
4
5use super::wire::wire_enum;
6use crate::ValidationError;
7
8macro_rules! identifier_type {
9    ($(#[$meta:meta])* $name:ident, $field:literal) => {
10        $(#[$meta])*
11        #[derive(
12            Debug,
13            Clone,
14            PartialEq,
15            Eq,
16            PartialOrd,
17            Ord,
18            Hash,
19            Serialize,
20            derive_more::Display,
21        )]
22        #[serde(transparent)]
23        pub struct $name(String);
24
25        impl $name {
26            pub fn new(value: impl Into<String>) -> Result<Self, ValidationError> {
27                let value = value.into();
28                let trimmed = value.trim();
29                if trimmed.is_empty() {
30                    return Err(ValidationError::new($field, "must not be empty"));
31                }
32                if trimmed.len() == value.len() {
33                    Ok(Self(value))
34                } else {
35                    Ok(Self(trimmed.to_owned()))
36                }
37            }
38
39            #[must_use]
40            pub fn as_str(&self) -> &str {
41                &self.0
42            }
43        }
44
45        impl FromStr for $name {
46            type Err = ValidationError;
47
48            fn from_str(value: &str) -> Result<Self, Self::Err> {
49                Self::try_from(value)
50            }
51        }
52
53        impl TryFrom<&str> for $name {
54            type Error = ValidationError;
55
56            fn try_from(value: &str) -> Result<Self, Self::Error> {
57                Self::new(value)
58            }
59        }
60
61        impl TryFrom<String> for $name {
62            type Error = ValidationError;
63
64            fn try_from(value: String) -> Result<Self, Self::Error> {
65                Self::new(value)
66            }
67        }
68
69        impl TryFrom<&String> for $name {
70            type Error = ValidationError;
71
72            fn try_from(value: &String) -> Result<Self, Self::Error> {
73                Self::new(value)
74            }
75        }
76
77        impl From<&$name> for $name {
78            fn from(value: &$name) -> Self {
79                value.clone()
80            }
81        }
82
83        impl AsRef<str> for $name {
84            fn as_ref(&self) -> &str {
85                self.as_str()
86            }
87        }
88
89        impl<'de> Deserialize<'de> for $name {
90            fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
91                let value = String::deserialize(deserializer)?;
92                Self::new(value).map_err(serde::de::Error::custom)
93            }
94        }
95    };
96}
97
98identifier_type!(
99    /// 从基金资料数据中发现的不透明基金经理标识。
100    ManagerId,
101    "manager_id"
102);
103identifier_type!(
104    /// 从基金资料数据中发现的不透明基金公司标识。
105    CompanyId,
106    "company_id"
107);
108identifier_type!(
109    /// 从报告期端点中发现的基金披露报告类型。
110    ReportType,
111    "report_type"
112);
113identifier_type!(
114    /// 在诊断数据中观察到的不透明基金分类代码。
115    FundCategoryCode,
116    "fund_type"
117);
118
119impl ReportType {
120    pub(crate) fn into_string(self) -> String {
121        self.0
122    }
123}
124
125/// 游标分页端点返回的不透明分页游标。
126#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, derive_more::Display)]
127#[serde(transparent)]
128pub struct Cursor(String);
129
130impl Cursor {
131    pub fn new(value: impl Into<String>) -> Result<Self, ValidationError> {
132        let value = value.into();
133        if value.trim().is_empty() {
134            return Err(ValidationError::new("offset", "must not be empty"));
135        }
136        Ok(Self(value))
137    }
138
139    #[must_use]
140    pub fn as_str(&self) -> &str {
141        &self.0
142    }
143}
144
145impl FromStr for Cursor {
146    type Err = ValidationError;
147
148    fn from_str(value: &str) -> Result<Self, Self::Err> {
149        Self::try_from(value)
150    }
151}
152
153impl TryFrom<&str> for Cursor {
154    type Error = ValidationError;
155
156    fn try_from(value: &str) -> Result<Self, Self::Error> {
157        Self::new(value)
158    }
159}
160
161impl TryFrom<String> for Cursor {
162    type Error = ValidationError;
163
164    fn try_from(value: String) -> Result<Self, Self::Error> {
165        Self::new(value)
166    }
167}
168
169impl TryFrom<&String> for Cursor {
170    type Error = ValidationError;
171
172    fn try_from(value: &String) -> Result<Self, Self::Error> {
173        Self::new(value)
174    }
175}
176
177impl From<&Cursor> for Cursor {
178    fn from(value: &Cursor) -> Self {
179        value.clone()
180    }
181}
182
183impl AsRef<str> for Cursor {
184    fn as_ref(&self) -> &str {
185        self.as_str()
186    }
187}
188
189impl<'de> Deserialize<'de> for Cursor {
190    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
191        let value = String::deserialize(deserializer)?;
192        Self::new(value).map_err(serde::de::Error::custom)
193    }
194}
195
196wire_enum! {
197    /// 基金标的宇宙。
198    pub enum FundType {
199        Otc => "otc",
200        Exchange => "exchange",
201        Reits => "reits",
202    }
203}
204
205wire_enum! {
206    /// 持有人记录合并策略。
207    pub enum HolderMergeScope {
208        All => "all",
209        Merged => "merged",
210        Separate => "separate",
211    }
212}
213
214wire_enum! {
215    /// 基金历史净值区间。
216    pub enum FundRange {
217        Week => "week",
218        Month => "month",
219        ThreeMonths => "tmonth",
220        HalfYear => "hyear",
221        Year => "year",
222        TwoYears => "twoyear",
223        ThreeYears => "tyear",
224        FiveYears => "fyear",
225    }
226}
227
228wire_enum! {
229    /// 基金净值序列选择。
230    pub enum FundNavType {
231        Unit => "unit",
232        Adjusted => "adj",
233        UnitAndAdjusted => "unit,adj",
234    }
235}
236
237wire_enum! {
238    /// 基金经理业绩区间。
239    pub enum ManagerPerformanceRange {
240        Month => "month",
241        ThreeMonths => "tmonth",
242        Year => "year",
243        CurrentYear => "nowyear",
244        SinceInception => "now",
245    }
246}
247
248wire_enum! {
249    /// 新发基金认购状态。
250    pub enum OfferingStatus {
251        Active => "active",
252        Upcoming => "upcoming",
253    }
254}
255
256wire_enum! {
257    /// 基金持有人记录返回的实际披露范围。
258    pub enum HolderRecordScope {
259        Merged => "merged",
260        Separate => "separate",
261    }
262}
263
264wire_enum! {
265    /// 基金持仓披露使用的资产类别。
266    pub enum PortfolioAssetType {
267        Stock => "stock",
268        Bond => "bond",
269        Fund => "fund",
270    }
271}
272
273#[cfg(test)]
274mod tests {
275    use super::{CompanyId, Cursor, FundCategoryCode, ManagerId, ReportType};
276
277    #[test]
278    fn endpoint_identifiers_have_distinct_validated_types() {
279        assert_eq!(
280            ManagerId::try_from("manager-1").unwrap().as_str(),
281            "manager-1"
282        );
283        assert_eq!(
284            CompanyId::try_from("company-1".to_owned())
285                .unwrap()
286                .as_str(),
287            "company-1"
288        );
289        assert_eq!(
290            Cursor::new("opaque+/cursor==").unwrap().as_str(),
291            "opaque+/cursor=="
292        );
293        assert_eq!(ReportType::new("quarter").unwrap().as_str(), "quarter");
294        assert_eq!(
295            FundCategoryCode::new("282001003").unwrap().as_str(),
296            "282001003"
297        );
298        assert_eq!(ManagerId::new(" manager-1 ").unwrap().as_str(), "manager-1");
299        assert_eq!(
300            CompanyId::new("\tcompany-1\n").unwrap().as_str(),
301            "company-1"
302        );
303        assert_eq!(ReportType::new(" quarter ").unwrap().as_str(), "quarter");
304        assert_eq!(
305            Cursor::new(" opaque+/cursor== ").unwrap().as_str(),
306            " opaque+/cursor== "
307        );
308
309        assert!(ManagerId::new(" ").is_err());
310        assert!(CompanyId::new("").is_err());
311        assert!(Cursor::new("\t").is_err());
312        assert!(ReportType::new("\n").is_err());
313        assert!(FundCategoryCode::new(" ").is_err());
314    }
315}