Skip to main content

financial_api/types/
finance.rs

1use std::str::FromStr;
2
3use serde::{Deserialize, Deserializer, Serialize};
4
5use super::wire::wire_enum;
6use crate::ValidationError;
7
8/// `YYYY-[1-4]` 格式的财务报告期标识。
9#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, derive_more::Display)]
10#[serde(transparent)]
11pub struct FinancialReport(String);
12
13impl FinancialReport {
14    pub fn parse(value: impl Into<String>) -> Result<Self, ValidationError> {
15        let value = value.into();
16        let bytes = value.as_bytes();
17        let valid = bytes.len() == 6
18            && bytes[..4].iter().all(u8::is_ascii_digit)
19            && bytes[4] == b'-'
20            && matches!(bytes[5], b'1'..=b'4');
21        if !valid {
22            return Err(ValidationError::new("report", "must use YYYY-[1-4] format"));
23        }
24        Ok(Self(value))
25    }
26
27    #[must_use]
28    pub fn as_str(&self) -> &str {
29        &self.0
30    }
31}
32
33impl FromStr for FinancialReport {
34    type Err = ValidationError;
35
36    fn from_str(value: &str) -> Result<Self, Self::Err> {
37        Self::try_from(value)
38    }
39}
40
41impl TryFrom<&str> for FinancialReport {
42    type Error = ValidationError;
43
44    fn try_from(value: &str) -> Result<Self, Self::Error> {
45        Self::parse(value)
46    }
47}
48
49impl TryFrom<String> for FinancialReport {
50    type Error = ValidationError;
51
52    fn try_from(value: String) -> Result<Self, Self::Error> {
53        Self::parse(value)
54    }
55}
56
57impl TryFrom<&String> for FinancialReport {
58    type Error = ValidationError;
59
60    fn try_from(value: &String) -> Result<Self, Self::Error> {
61        Self::parse(value)
62    }
63}
64
65impl From<&FinancialReport> for FinancialReport {
66    fn from(value: &FinancialReport) -> Self {
67        value.clone()
68    }
69}
70
71impl AsRef<str> for FinancialReport {
72    fn as_ref(&self) -> &str {
73        self.as_str()
74    }
75}
76
77impl<'de> Deserialize<'de> for FinancialReport {
78    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
79        let value = String::deserialize(deserializer)?;
80        Self::parse(value).map_err(serde::de::Error::custom)
81    }
82}
83
84wire_enum! {
85    /// 财务报表频率。
86    pub enum FinancialPeriod {
87        Annual => "annual",
88        Quarterly => "quarterly",
89    }
90}
91
92wire_enum! {
93    /// 上市公司财务报表返回的会计期间。
94    pub enum FiscalPeriod {
95        FullYear => "FY",
96        FirstQuarter => "Q1",
97        SecondQuarter => "Q2",
98        ThirdQuarter => "Q3",
99        FourthQuarter => "Q4",
100    }
101}
102
103wire_enum! {
104    /// 固定的财务分析能力分组。
105    pub enum FinancialAbilityKind {
106        Growth => "growth",
107        Profitability => "profitability",
108        Solvency => "solvency",
109        Operation => "operation",
110        CashFlow => "cash-flow",
111    }
112}
113
114wire_enum! {
115    /// 上游契约定义的财务指标标识。
116    pub enum FinancialIndicatorId {
117        TotalAssetsGrowthRatio => "total_assets_growth_ratio",
118        NetProfitYoyGrowthRatio => "net_profit_yoy_growth_ratio",
119        #[serde(alias = "calculate_operating_income_yoy_growth_ratio")]
120        OperatingIncomeYoyGrowthRatio => "operating_income_yoy_growth_ratio",
121        #[serde(alias = "calculate_operating_profit_yoy_growth_ratio")]
122        OperatingProfitYoyGrowthRatio => "operating_profit_yoy_growth_ratio",
123        FixedAssetInvestExpansionRatio => "fixed_asset_invest_expansion_ratio",
124        #[serde(alias = "calculate_parent_holder_net_profit_yoy_growth_ratio")]
125        ParentHolderNetProfitYoyGrowthRatio => "parent_holder_net_profit_yoy_growth_ratio",
126        SaleGrossMargin => "sale_gross_margin",
127        SaleNetInterestRatio => "sale_net_interest_ratio",
128        TotalAssetsNetRatio => "total_assets_net_ratio",
129        DeductWeightedAverageReturnOnEquity => "index_deduct_weighted_avg_roe",
130        WeightedAverageReturnOnEquity => "index_weighted_avg_roe",
131        CurrentRatio => "current_ratio",
132        QuickRatio => "quick_ratio",
133        AssetsDebtRatio => "assets_debt_ratio",
134        CashRatio => "cash_ratio",
135        EarnedInterestMultiple => "earned_interest_multiple",
136        LongTermDebtEquityRatio => "long_term_debt_equity_ratio",
137        TotalAssetsTurnoverRatio => "total_assets_turnover_ratio",
138        InventoryTurnoverRatio => "inventory_turnover_ratio",
139        CurrentAssetsTurnoverRatio => "current_assets_turnover_ratio",
140        ReceiveAccountTurnoverRatio => "receive_account_turnover_ratio",
141        CashOperatingIndex => "cash_operating_index",
142        OperatingCashFlowNetDivideIncome => "operating_cash_flow_net_divide_income",
143        NetProfitCashContent => "net_profit_cash_content",
144        OperatingCashNetYoyGrowthRatio => "operating_cash_net_yoy_growth_ratio",
145        CashMeetInvestRatio => "cash_meet_invest_ratio",
146    }
147}
148
149#[cfg(test)]
150mod tests {
151    use super::FinancialReport;
152
153    #[test]
154    fn financial_report_uses_standard_fallible_conversion() {
155        let report = FinancialReport::try_from("2024-4").unwrap();
156
157        assert_eq!(report.as_str(), "2024-4");
158        assert!(FinancialReport::try_from("2024-5".to_owned()).is_err());
159    }
160}