Skip to main content

financial_api/a_share/
financials.rs

1use serde::de::DeserializeOwned;
2
3use crate::endpoints;
4use crate::types::TEN_YEARS_MS;
5use crate::{
6    AShareCode, BalanceSheetsData, CashFlowStatementsData, Client, Error, FinancialIndicatorsData,
7    FinancialPeriod, FinancialReport, IncomeStatementsData, Response, UnixMillis, ValidationError,
8};
9
10/// “最近报告期”和“时间戳区间”互斥的财务查询。
11#[derive(Debug, Clone, Copy, PartialEq, Eq)]
12pub struct FinancialRange(FinancialRangeKind);
13
14#[derive(Debug, Clone, Copy, PartialEq, Eq)]
15enum FinancialRangeKind {
16    Recent { limit: u8 },
17    Between { start: UnixMillis, end: UnixMillis },
18}
19
20impl FinancialRange {
21    pub const fn recent(limit: u8) -> Result<Self, ValidationError> {
22        if limit == 0 || limit > 20 {
23            return Err(ValidationError::new("limit", "must be in the range 1..=20"));
24        }
25        Ok(Self(FinancialRangeKind::Recent { limit }))
26    }
27
28    pub fn between(start: i64, end: i64) -> Result<Self, ValidationError> {
29        let start = UnixMillis::new(start)?;
30        let end = UnixMillis::new(end)?;
31        if end.get() < start.get() {
32            return Err(ValidationError::new(
33                "end",
34                "must not be earlier than start",
35            ));
36        }
37        if end.get() - start.get() > TEN_YEARS_MS {
38            return Err(ValidationError::new(
39                "end",
40                "requested time window exceeds ten years",
41            ));
42        }
43        Ok(Self(FinancialRangeKind::Between { start, end }))
44    }
45}
46
47impl Client {
48    /// 获取利润表。
49    ///
50    /// # 示例
51    #[doc = concat!(
52        "```no_run\n",
53        include_str!("../../examples/financials_income_statements.rs"),
54        "\n```"
55    )]
56    pub async fn financials_income_statements(
57        &self,
58        thscode: impl AsRef<str> + Send,
59        period: FinancialPeriod,
60        range: FinancialRange,
61    ) -> Result<Response<IncomeStatementsData>, Error> {
62        self.financial_statements(endpoints::INCOME_STATEMENTS, thscode, period, range)
63            .await
64    }
65
66    /// 获取资产负债表。
67    ///
68    /// # 示例
69    #[doc = concat!(
70        "```no_run\n",
71        include_str!("../../examples/financials_balance_sheets.rs"),
72        "\n```"
73    )]
74    pub async fn financials_balance_sheets(
75        &self,
76        thscode: impl AsRef<str> + Send,
77        period: FinancialPeriod,
78        range: FinancialRange,
79    ) -> Result<Response<BalanceSheetsData>, Error> {
80        self.financial_statements(endpoints::BALANCE_SHEETS, thscode, period, range)
81            .await
82    }
83
84    /// 获取现金流量表。
85    ///
86    /// # 示例
87    #[doc = concat!(
88        "```no_run\n",
89        include_str!("../../examples/financials_cash_flow_statements.rs"),
90        "\n```"
91    )]
92    pub async fn financials_cash_flow_statements(
93        &self,
94        thscode: impl AsRef<str> + Send,
95        period: FinancialPeriod,
96        range: FinancialRange,
97    ) -> Result<Response<CashFlowStatementsData>, Error> {
98        self.financial_statements(endpoints::CASH_FLOW_STATEMENTS, thscode, period, range)
99            .await
100    }
101
102    async fn financial_statements<T: DeserializeOwned>(
103        &self,
104        path: &str,
105        thscode: impl AsRef<str> + Send,
106        period: FinancialPeriod,
107        range: FinancialRange,
108    ) -> Result<Response<T>, Error> {
109        let thscode = AShareCode::new(thscode)?;
110        let mut query = vec![
111            ("thscode", thscode.into_string()),
112            ("period", period.to_string()),
113        ];
114        match range.0 {
115            FinancialRangeKind::Recent { limit } => {
116                query.push(("limit", limit.to_string()));
117            }
118            FinancialRangeKind::Between { start, end } => {
119                query.push(("start", start.to_string()));
120                query.push(("end", end.to_string()));
121            }
122        }
123        self.get(path, &query).await
124    }
125
126    /// 获取指定报告期的五类财务指标。
127    ///
128    /// # 示例
129    #[doc = concat!(
130        "```no_run\n",
131        include_str!("../../examples/financials_indicators.rs"),
132        "\n```"
133    )]
134    pub async fn financials_indicators(
135        &self,
136        thscode: impl AsRef<str> + Send,
137        report: impl AsRef<str> + Send,
138    ) -> Result<Response<FinancialIndicatorsData>, Error> {
139        let thscode = AShareCode::new(thscode)?;
140        let report = FinancialReport::parse(report.as_ref())?;
141        let query = [("thscode", thscode.as_str()), ("report", report.as_str())];
142        self.get(endpoints::FINANCIAL_INDICATORS, &query).await
143    }
144}
145
146#[cfg(test)]
147mod tests {
148    use super::FinancialRange;
149
150    #[test]
151    fn financial_range_rejects_invalid_limits_and_reversed_windows() {
152        assert!(FinancialRange::recent(1).is_ok());
153        assert!(FinancialRange::recent(20).is_ok());
154        assert!(FinancialRange::recent(0).is_err());
155        assert!(FinancialRange::recent(21).is_err());
156
157        assert!(FinancialRange::between(1_700_000_000_000, 1_600_000_000_000).is_err());
158    }
159
160    #[test]
161    fn financial_range_rejects_windows_over_ten_years_at_construction() {
162        assert!(FinancialRange::between(1_000_000_000_000, 1_315_576_000_001).is_err());
163    }
164}