Skip to main content

acosmi/finance/
types.rs

1//! 财务(P7)类型。端口自 `finance/types.ts`(商品化总规划 2026-05-25)。
2//!
3//! 与 tk-dist `dist_invoice` / `dist_refund_*` / `dist_corporate_transfer` 七表族对齐。
4//! **金额阵营(§3)**:所有 `*Fen` 字段 = i64 整数分;`taxRate` = f64 比率。
5
6use crate::macros::open_string_union;
7use serde::{Deserialize, Serialize};
8
9/// 发票视图(P7)。TS `Invoice`。
10///
11/// PII 分级(与 tk-dist `DistInvoiceDO @Sensitive` 对齐):L3 字段(taxId/bankAccount/
12/// contactPhone/bankName)由服务端按上下文脱敏/加密,SDK 类型不强制 PII 级。
13#[derive(Debug, Clone, Serialize, Deserialize)]
14pub struct Invoice {
15    pub id: i64,
16    /// 发票号(开票后回写)。L0。
17    #[serde(rename = "invoiceNo", default, skip_serializing_if = "Option::is_none")]
18    pub invoice_no: Option<String>,
19    #[serde(rename = "orderId", default, skip_serializing_if = "Option::is_none")]
20    pub order_id: Option<i64>,
21    /// UUID。L0。
22    #[serde(rename = "userId", default, skip_serializing_if = "Option::is_none")]
23    pub user_id: Option<String>,
24    #[serde(
25        rename = "enterpriseId",
26        default,
27        skip_serializing_if = "Option::is_none"
28    )]
29    pub enterprise_id: Option<i64>,
30    /// NORMAL / VAT_GENERAL / VAT_SPECIAL。L0。
31    #[serde(
32        rename = "invoiceType",
33        default,
34        skip_serializing_if = "Option::is_none"
35    )]
36    pub invoice_type: Option<String>,
37    /// 抬头。L2。
38    #[serde(default, skip_serializing_if = "Option::is_none")]
39    pub title: Option<String>,
40    /// 税号。L3 —— 服务端按上下文脱敏/加密。
41    #[serde(rename = "taxId", default, skip_serializing_if = "Option::is_none")]
42    pub tax_id: Option<String>,
43    /// 开户行。L3。
44    #[serde(rename = "bankName", default, skip_serializing_if = "Option::is_none")]
45    pub bank_name: Option<String>,
46    /// 银行账号。L3 —— `@FieldEncrypt` 存储加密。
47    #[serde(
48        rename = "bankAccount",
49        default,
50        skip_serializing_if = "Option::is_none"
51    )]
52    pub bank_account: Option<String>,
53    /// 收件地址。L2。
54    #[serde(
55        rename = "contactAddress",
56        default,
57        skip_serializing_if = "Option::is_none"
58    )]
59    pub contact_address: Option<String>,
60    /// 联系手机。L3 —— `@FieldEncrypt` 存储加密。
61    #[serde(
62        rename = "contactPhone",
63        default,
64        skip_serializing_if = "Option::is_none"
65    )]
66    pub contact_phone: Option<String>,
67    /// 金额(整数分,§3)。
68    #[serde(rename = "amountFen", default, skip_serializing_if = "Option::is_none")]
69    pub amount_fen: Option<i64>,
70    /// 6% 默认(f64,比率非金额)。
71    #[serde(rename = "taxRate", default, skip_serializing_if = "Option::is_none")]
72    pub tax_rate: Option<f64>,
73    /// 税额(整数分,§3)。
74    #[serde(
75        rename = "taxAmountFen",
76        default,
77        skip_serializing_if = "Option::is_none"
78    )]
79    pub tax_amount_fen: Option<i64>,
80    /// PENDING / ISSUED / VOIDED / REISSUED。
81    #[serde(default, skip_serializing_if = "Option::is_none")]
82    pub status: Option<String>,
83    #[serde(rename = "issuedAt", default, skip_serializing_if = "Option::is_none")]
84    pub issued_at: Option<String>,
85    #[serde(rename = "pdfUrl", default, skip_serializing_if = "Option::is_none")]
86    pub pdf_url: Option<String>,
87}
88
89open_string_union! {
90    /// 发票类型(开票申请用)。TS `'NORMAL'|'VAT_GENERAL'|'VAT_SPECIAL'`。
91    InvoiceType {
92        NORMAL => "NORMAL",
93        VAT_GENERAL => "VAT_GENERAL",
94        VAT_SPECIAL => "VAT_SPECIAL",
95    }
96}
97
98/// 开票申请 request。TS `RequestInvoiceInput`。
99#[derive(Debug, Clone, Serialize, Deserialize)]
100pub struct RequestInvoiceInput {
101    #[serde(rename = "orderId", default, skip_serializing_if = "Option::is_none")]
102    pub order_id: Option<i64>,
103    #[serde(
104        rename = "enterpriseId",
105        default,
106        skip_serializing_if = "Option::is_none"
107    )]
108    pub enterprise_id: Option<i64>,
109    #[serde(
110        rename = "invoiceType",
111        default,
112        skip_serializing_if = "Option::is_none"
113    )]
114    pub invoice_type: Option<InvoiceType>,
115    pub title: String,
116    #[serde(rename = "taxId", default, skip_serializing_if = "Option::is_none")]
117    pub tax_id: Option<String>,
118    #[serde(rename = "bankName", default, skip_serializing_if = "Option::is_none")]
119    pub bank_name: Option<String>,
120    #[serde(
121        rename = "bankAccount",
122        default,
123        skip_serializing_if = "Option::is_none"
124    )]
125    pub bank_account: Option<String>,
126    #[serde(
127        rename = "contactAddress",
128        default,
129        skip_serializing_if = "Option::is_none"
130    )]
131    pub contact_address: Option<String>,
132    #[serde(
133        rename = "contactPhone",
134        default,
135        skip_serializing_if = "Option::is_none"
136    )]
137    pub contact_phone: Option<String>,
138    /// 金额(整数分,§3)。
139    #[serde(rename = "amountFen")]
140    pub amount_fen: i64,
141    /// 税率(f64,比率非金额)。
142    #[serde(rename = "taxRate", default, skip_serializing_if = "Option::is_none")]
143    pub tax_rate: Option<f64>,
144}
145
146/// 退款规则字典(决策 15)。TS `RefundPolicy`。
147#[derive(Debug, Clone, Serialize, Deserialize)]
148pub struct RefundPolicy {
149    pub id: i64,
150    /// SUBSCRIPTION_NO_REFUND / TOKEN_PACK_7DAY_UNUSED / ...
151    #[serde(rename = "policyCode")]
152    pub policy_code: String,
153    /// MODEL_MEMBERSHIP / TOKEN_PACK / COMPLIANCE / LEGAL_SERVICE。
154    #[serde(
155        rename = "productFamily",
156        default,
157        skip_serializing_if = "Option::is_none"
158    )]
159    pub product_family: Option<String>,
160    /// 退款窗口期(NULL = 不退)。
161    #[serde(
162        rename = "refundWindowDays",
163        default,
164        skip_serializing_if = "Option::is_none"
165    )]
166    pub refund_window_days: Option<i64>,
167    /// NO_REFUND / FULL_IF_UNUSED / PRORATA_UNUSED。
168    #[serde(
169        rename = "refundRule",
170        default,
171        skip_serializing_if = "Option::is_none"
172    )]
173    pub refund_rule: Option<String>,
174    #[serde(
175        rename = "requireProof",
176        default,
177        skip_serializing_if = "Option::is_none"
178    )]
179    pub require_proof: Option<bool>,
180    #[serde(default, skip_serializing_if = "Option::is_none")]
181    pub status: Option<String>,
182    #[serde(default, skip_serializing_if = "Option::is_none")]
183    pub description: Option<String>,
184}
185
186/// 退款记录。TS `RefundRecord`。所有 `*Fen` = i64 整数分(§3)。
187#[derive(Debug, Clone, Serialize, Deserialize)]
188pub struct RefundRecord {
189    pub id: i64,
190    #[serde(rename = "orderId")]
191    pub order_id: i64,
192    /// UUID。
193    #[serde(rename = "userId")]
194    pub user_id: String,
195    #[serde(
196        rename = "policyCode",
197        default,
198        skip_serializing_if = "Option::is_none"
199    )]
200    pub policy_code: Option<String>,
201    /// 申请金额(整数分,§3)。
202    #[serde(
203        rename = "requestedAmountFen",
204        default,
205        skip_serializing_if = "Option::is_none"
206    )]
207    pub requested_amount_fen: Option<i64>,
208    /// 核准金额(整数分,§3)。
209    #[serde(
210        rename = "approvedAmountFen",
211        default,
212        skip_serializing_if = "Option::is_none"
213    )]
214    pub approved_amount_fen: Option<i64>,
215    /// 实退(扣已用)(整数分,§3)。
216    #[serde(
217        rename = "actualAmountFen",
218        default,
219        skip_serializing_if = "Option::is_none"
220    )]
221    pub actual_amount_fen: Option<i64>,
222    #[serde(default, skip_serializing_if = "Option::is_none")]
223    pub reason: Option<String>,
224    /// PENDING / APPROVED / REFUNDED / REJECTED。
225    #[serde(default, skip_serializing_if = "Option::is_none")]
226    pub status: Option<String>,
227    /// UUID。
228    #[serde(
229        rename = "operatorUserId",
230        default,
231        skip_serializing_if = "Option::is_none"
232    )]
233    pub operator_user_id: Option<String>,
234    #[serde(
235        rename = "refundedAt",
236        default,
237        skip_serializing_if = "Option::is_none"
238    )]
239    pub refunded_at: Option<String>,
240    #[serde(
241        rename = "rejectedReason",
242        default,
243        skip_serializing_if = "Option::is_none"
244    )]
245    pub rejected_reason: Option<String>,
246}
247
248open_string_union! {
249    /// 商品族(退款申请用)。TS `'MODEL_MEMBERSHIP'|'TOKEN_PACK'|'COMPLIANCE'|'LEGAL_SERVICE'`。
250    RefundProductFamily {
251        MODEL_MEMBERSHIP => "MODEL_MEMBERSHIP",
252        TOKEN_PACK => "TOKEN_PACK",
253        COMPLIANCE => "COMPLIANCE",
254        LEGAL_SERVICE => "LEGAL_SERVICE",
255    }
256}
257
258/// 退款申请 request。TS `RequestRefundInput`。
259#[derive(Debug, Clone, Serialize, Deserialize)]
260pub struct RequestRefundInput {
261    #[serde(rename = "orderId")]
262    pub order_id: i64,
263    /// 直传 policyCode;留空可用 productFamily + anyUsage 派生。
264    #[serde(
265        rename = "policyCode",
266        default,
267        skip_serializing_if = "Option::is_none"
268    )]
269    pub policy_code: Option<String>,
270    #[serde(
271        rename = "productFamily",
272        default,
273        skip_serializing_if = "Option::is_none"
274    )]
275    pub product_family: Option<RefundProductFamily>,
276    #[serde(rename = "anyUsage", default, skip_serializing_if = "Option::is_none")]
277    pub any_usage: Option<bool>,
278    /// 申请金额(整数分,§3)。
279    #[serde(rename = "requestedAmountFen")]
280    pub requested_amount_fen: i64,
281    #[serde(default, skip_serializing_if = "Option::is_none")]
282    pub reason: Option<String>,
283}
284
285/// 对公转账记录(决策 14)。TS `CorporateTransfer`。`amountFen` = i64 整数分(§3)。
286#[derive(Debug, Clone, Serialize, Deserialize)]
287pub struct CorporateTransfer {
288    pub id: i64,
289    #[serde(rename = "orderId", default, skip_serializing_if = "Option::is_none")]
290    pub order_id: Option<i64>,
291    #[serde(
292        rename = "contractId",
293        default,
294        skip_serializing_if = "Option::is_none"
295    )]
296    pub contract_id: Option<i64>,
297    /// UUID。
298    #[serde(rename = "userId", default, skip_serializing_if = "Option::is_none")]
299    pub user_id: Option<String>,
300    #[serde(
301        rename = "enterpriseId",
302        default,
303        skip_serializing_if = "Option::is_none"
304    )]
305    pub enterprise_id: Option<i64>,
306    /// 金额(整数分,§3)。
307    #[serde(rename = "amountFen", default, skip_serializing_if = "Option::is_none")]
308    pub amount_fen: Option<i64>,
309    #[serde(rename = "payerBank", default, skip_serializing_if = "Option::is_none")]
310    pub payer_bank: Option<String>,
311    #[serde(
312        rename = "payerAccount",
313        default,
314        skip_serializing_if = "Option::is_none"
315    )]
316    pub payer_account: Option<String>,
317    #[serde(
318        rename = "receiverBank",
319        default,
320        skip_serializing_if = "Option::is_none"
321    )]
322    pub receiver_bank: Option<String>,
323    #[serde(
324        rename = "receiverAccount",
325        default,
326        skip_serializing_if = "Option::is_none"
327    )]
328    pub receiver_account: Option<String>,
329    /// UUID。
330    #[serde(
331        rename = "salesRepUserId",
332        default,
333        skip_serializing_if = "Option::is_none"
334    )]
335    pub sales_rep_user_id: Option<String>,
336    /// UUID。
337    #[serde(
338        rename = "financeUserId",
339        default,
340        skip_serializing_if = "Option::is_none"
341    )]
342    pub finance_user_id: Option<String>,
343    #[serde(
344        rename = "wechatGroupUrl",
345        default,
346        skip_serializing_if = "Option::is_none"
347    )]
348    pub wechat_group_url: Option<String>,
349    /// INITIATED / WAITING_PROOF / PROOF_RECEIVED / CONFIRMED / FAILED。
350    #[serde(default, skip_serializing_if = "Option::is_none")]
351    pub status: Option<String>,
352    #[serde(rename = "proofUrl", default, skip_serializing_if = "Option::is_none")]
353    pub proof_url: Option<String>,
354    #[serde(
355        rename = "confirmedAt",
356        default,
357        skip_serializing_if = "Option::is_none"
358    )]
359    pub confirmed_at: Option<String>,
360    #[serde(default, skip_serializing_if = "Option::is_none")]
361    pub note: Option<String>,
362}
363
364/// 对公转账发起 request。TS `InitiateCorporateTransferInput`。`amountFen` = i64 整数分(§3)。
365#[derive(Debug, Clone, Serialize, Deserialize)]
366pub struct InitiateCorporateTransferInput {
367    #[serde(rename = "orderId", default, skip_serializing_if = "Option::is_none")]
368    pub order_id: Option<i64>,
369    #[serde(
370        rename = "enterpriseId",
371        default,
372        skip_serializing_if = "Option::is_none"
373    )]
374    pub enterprise_id: Option<i64>,
375    #[serde(
376        rename = "contractId",
377        default,
378        skip_serializing_if = "Option::is_none"
379    )]
380    pub contract_id: Option<i64>,
381    /// 金额(整数分,§3)。
382    #[serde(rename = "amountFen")]
383    pub amount_fen: i64,
384    #[serde(rename = "payerBank", default, skip_serializing_if = "Option::is_none")]
385    pub payer_bank: Option<String>,
386    #[serde(
387        rename = "payerAccount",
388        default,
389        skip_serializing_if = "Option::is_none"
390    )]
391    pub payer_account: Option<String>,
392    #[serde(default, skip_serializing_if = "Option::is_none")]
393    pub note: Option<String>,
394}
395
396/// 对公转账发起 response(决策 14)。TS `InitiateCorporateTransferResult`。
397#[derive(Debug, Clone, Serialize, Deserialize)]
398pub struct InitiateCorporateTransferResult {
399    pub id: i64,
400    /// 销售名片二维码 URL(ops 配置)。
401    #[serde(rename = "qrUrl", default, skip_serializing_if = "Option::is_none")]
402    pub qr_url: Option<String>,
403    /// 销售企微 ID。
404    #[serde(
405        rename = "salesWechatId",
406        default,
407        skip_serializing_if = "Option::is_none"
408    )]
409    pub sales_wechat_id: Option<String>,
410    /// 财务对接邮箱。
411    #[serde(
412        rename = "financeEmail",
413        default,
414        skip_serializing_if = "Option::is_none"
415    )]
416    pub finance_email: Option<String>,
417}
418
419#[cfg(test)]
420mod tests {
421    use super::*;
422
423    #[test]
424    fn invoice_amount_fen_is_i64_integer() {
425        // §3:所有 *Fen 字段是 i64 整数分(非 f64 元、非 string)。
426        let v: Invoice = serde_json::from_str(
427            r#"{"id":1,"amountFen":12345,"taxRate":0.06,"taxAmountFen":740,"orderId":99}"#,
428        )
429        .unwrap();
430        assert_eq!(v.amount_fen, Some(12345_i64));
431        assert_eq!(v.tax_amount_fen, Some(740_i64));
432        // taxRate 是 f64 比率(非金额)。
433        assert_eq!(v.tax_rate, Some(0.06_f64));
434        // wire 仍是 camelCase。
435        let back = serde_json::to_value(&v).unwrap();
436        assert_eq!(back["amountFen"], 12345);
437        assert_eq!(back["taxAmountFen"], 740);
438    }
439
440    #[test]
441    fn refund_record_all_fen_i64() {
442        let r: RefundRecord = serde_json::from_str(
443            r#"{"id":2,"orderId":3,"userId":"u-uuid","requestedAmountFen":50000,"approvedAmountFen":40000,"actualAmountFen":30000}"#,
444        )
445        .unwrap();
446        assert_eq!(r.requested_amount_fen, Some(50000_i64));
447        assert_eq!(r.approved_amount_fen, Some(40000_i64));
448        assert_eq!(r.actual_amount_fen, Some(30000_i64));
449    }
450
451    #[test]
452    fn initiate_input_amount_fen_i64_serialize() {
453        let inp = InitiateCorporateTransferInput {
454            order_id: Some(7),
455            enterprise_id: None,
456            contract_id: None,
457            amount_fen: 99_000_000,
458            payer_bank: Some("ICBC".into()),
459            payer_account: None,
460            note: None,
461        };
462        let body = serde_json::to_value(&inp).unwrap();
463        assert_eq!(body["amountFen"], 99_000_000_i64);
464        // 大额(>2^32)仍是整数,不丢精度。
465        assert!(body["amountFen"].is_i64());
466    }
467
468    #[test]
469    fn invoice_type_open_union_roundtrip_unknown() {
470        // 开放 union 容忍未知值(前向兼容)。
471        let it: InvoiceType = serde_json::from_value(json_str("VAT_DIGITAL")).unwrap();
472        assert_eq!(it.as_str(), "VAT_DIGITAL");
473        assert_eq!(InvoiceType::VAT_SPECIAL, "VAT_SPECIAL");
474    }
475
476    fn json_str(s: &str) -> serde_json::Value {
477        serde_json::Value::String(s.to_string())
478    }
479}