Skip to main content

acosmi/finance/
client.rs

1//! 财务(P7)业务方法。端口自 `finance/client.ts`(declaration-merging → `impl Client` 块)。
2//!
3//! 决策 14 对公转账:弹窗 + 企微对接,零银行 API。决策 15 退款规则按 Policy 表配置。
4//! 端点路径形如 `/api/distribution/finance/*`。admin 板块由 admin UI 直连,不在 SDK 边界。
5
6use super::types::{
7    CorporateTransfer, InitiateCorporateTransferInput, InitiateCorporateTransferResult, Invoice,
8    RefundRecord, RequestInvoiceInput, RequestRefundInput,
9};
10use crate::billing::entitlements::urlencoding;
11use crate::core::client::Client;
12use crate::shared::{Error, Result};
13use tokio_util::sync::CancellationToken;
14
15impl Client {
16    // ========================================================================
17    // 退款(决策 15)
18    // ========================================================================
19
20    /// 申请退款(决策 15:按 policyCode 自动判定;NO_REFUND 即时拒)。对应 TS `requestRefund`。
21    ///
22    /// 空 data → Err(`refund/request: empty response`)。
23    pub async fn request_refund(
24        &self,
25        req: &RequestRefundInput,
26        signal: Option<CancellationToken>,
27    ) -> Result<RefundRecord> {
28        let body = serde_json::to_string(req)
29            .map_err(|e| Error::other(format!("requestRefund: marshal: {e}")))?;
30        self.commerce_post_opt::<RefundRecord>(
31            "/api/distribution/finance/refund/request",
32            Some(&body),
33            signal,
34        )
35        .await?
36        .ok_or_else(|| Error::other("refund/request: empty response"))
37    }
38
39    /// 我的退款记录。对应 TS `listMyRefunds`。空 data → []。
40    pub async fn list_my_refunds(
41        &self,
42        signal: Option<CancellationToken>,
43    ) -> Result<Vec<RefundRecord>> {
44        self.commerce_get_list("/api/distribution/finance/refund/my", signal)
45            .await
46    }
47
48    // ========================================================================
49    // 发票
50    // ========================================================================
51
52    /// 申请开票。对应 TS `requestInvoice`。空 data → Err(`invoice/request: empty response`)。
53    pub async fn request_invoice(
54        &self,
55        req: &RequestInvoiceInput,
56        signal: Option<CancellationToken>,
57    ) -> Result<Invoice> {
58        let body = serde_json::to_string(req)
59            .map_err(|e| Error::other(format!("requestInvoice: marshal: {e}")))?;
60        self.commerce_post_opt::<Invoice>(
61            "/api/distribution/finance/invoice/request",
62            Some(&body),
63            signal,
64        )
65        .await?
66        .ok_or_else(|| Error::other("invoice/request: empty response"))
67    }
68
69    /// 我的发票列表。对应 TS `listMyInvoices`。空 data → []。
70    pub async fn list_my_invoices(
71        &self,
72        signal: Option<CancellationToken>,
73    ) -> Result<Vec<Invoice>> {
74        self.commerce_get_list("/api/distribution/finance/invoice/my", signal)
75            .await
76    }
77
78    // ========================================================================
79    // 对公转账(决策 14:弹窗 + 企微对接)
80    // ========================================================================
81
82    /// 发起对公转账(决策 14)。对应 TS `initiateCorporateTransfer`。
83    ///
84    /// 服务端创建 INITIATED 记录,返回销售名片二维码 + 销售企微 ID + 财务邮箱。
85    /// 空 data → Err(`corporate-transfer/initiate: empty response`)。
86    pub async fn initiate_corporate_transfer(
87        &self,
88        req: &InitiateCorporateTransferInput,
89        signal: Option<CancellationToken>,
90    ) -> Result<InitiateCorporateTransferResult> {
91        let body = serde_json::to_string(req)
92            .map_err(|e| Error::other(format!("initiateCorporateTransfer: marshal: {e}")))?;
93        self.commerce_post_opt::<InitiateCorporateTransferResult>(
94            "/api/distribution/finance/corporate-transfer/initiate",
95            Some(&body),
96            signal,
97        )
98        .await?
99        .ok_or_else(|| Error::other("corporate-transfer/initiate: empty response"))
100    }
101
102    /// 上传对公转账凭证 URL。对应 TS `uploadCorporateTransferProof`。
103    ///
104    /// **bug-for-bug**:后端契约是 `@RequestParam("proofUrl")`,走 **query 参数**(非 body);
105    /// `encodeURIComponent` 直拼 path。空 data → false(TS `?? false`)。
106    pub async fn upload_corporate_transfer_proof(
107        &self,
108        id: i64,
109        proof_url: &str,
110        signal: Option<CancellationToken>,
111    ) -> Result<bool> {
112        let path = format!(
113            "/api/distribution/finance/corporate-transfer/{}/upload-proof?proofUrl={}",
114            urlencoding(&id.to_string()),
115            urlencoding(proof_url)
116        );
117        self.commerce_post_bool(&path, None, signal).await
118    }
119
120    /// 我的对公转账记录。对应 TS `listMyCorporateTransfers`。空 data → []。
121    pub async fn list_my_corporate_transfers(
122        &self,
123        signal: Option<CancellationToken>,
124    ) -> Result<Vec<CorporateTransfer>> {
125        self.commerce_get_list("/api/distribution/finance/corporate-transfer/my", signal)
126            .await
127    }
128}