Skip to main content

acosmi/compliance/
errors.rs

1//! Java numeric ErrorCode → SDK symbolic key。端口自 `compliance/errors.ts`。
2//!
3//! 设计原则:
4//!   - Java 后端通过 `cn.iocoder.yudao.module.compliance.enums.ErrorCodeConstants` 暴露数值
5//!     错误码(1-031-xxx-xxx)。本文件按段位 + 具体码值映射为 SDK 内部 symbolic key,仅作
6//!     SDK 分支判断 / 文档说明,不作为 wire response 反序列化字段。
7//!   - 不要尝试从后端 message 文案做正则识别 —— message 是中文可变的,code 才是合同。
8//!   - retryable / terminal / step_up_required 严格按"是否安全自动重发"语义:
9//!       * step_up_required: 客户端引导用户重新做 OAuth introspection / step-up,不要静默 retry。
10//!       * retryable: 仅对幂等的网络/资源短暂错误为 true(当前默认全为 false,因为 compliance
11//!         写接口严禁自动重发)。
12//!       * terminal: 不需要 SDK 再次轮询;用户必须用新 idempotency-key 重新发起。
13//!
14//! Rust 化:TS `ComplianceErrorKey` 是 50+ 项的字符串字面量 union。本文件端口为 **enum +
15//! serde rename**(每个 variant 的 wire 字符串 = TS 字面量),便于 `retry_advice` 在编译期
16//! 穷举映射不漏(match 缺分支 = 编译错误)。
17
18use crate::shared::errors::Error;
19use serde::{Deserialize, Serialize};
20
21/// SDK 内部 symbolic key;用于代码分支判断与文档。**不是 wire contract**。
22///
23/// 端口自 TS `ComplianceErrorKey`。serde rename 使每个 variant 序列化为 TS 同名字面量字符串。
24#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
25pub enum ComplianceErrorKey {
26    // 通用 / token / scope
27    #[serde(rename = "COMPLIANCE_UNAUTHORIZED")]
28    ComplianceUnauthorized,
29    #[serde(rename = "COMPLIANCE_INSUFFICIENT_SCOPE")]
30    ComplianceInsufficientScope,
31    #[serde(rename = "COMPLIANCE_STEP_UP_REQUIRED")]
32    ComplianceStepUpRequired,
33    #[serde(rename = "COMPLIANCE_TOKEN_INVALID")]
34    ComplianceTokenInvalid,
35    // 主体快照
36    #[serde(rename = "SUBJECT_SNAPSHOT_REQUIRED")]
37    SubjectSnapshotRequired,
38    #[serde(rename = "SUBJECT_SNAPSHOT_NOT_FOUND")]
39    SubjectSnapshotNotFound,
40    #[serde(rename = "SUBJECT_SNAPSHOT_TENANT_MISMATCH")]
41    SubjectSnapshotTenantMismatch,
42    // Evidence / Timestamp / Package / Report
43    #[serde(rename = "EVIDENCE_ASSET_NOT_FOUND")]
44    EvidenceAssetNotFound,
45    #[serde(rename = "EVIDENCE_ASSET_HASH_MISMATCH")]
46    EvidenceAssetHashMismatch,
47    #[serde(rename = "EVIDENCE_ASSET_PAYLOAD_REQUIRED")]
48    EvidenceAssetPayloadRequired,
49    #[serde(rename = "TIMESTAMP_TOKEN_NOT_FOUND")]
50    TimestampTokenNotFound,
51    #[serde(rename = "TIMESTAMP_PROVIDER_FAILED")]
52    TimestampProviderFailed,
53    #[serde(rename = "TIMESTAMP_PROVIDER_UNKNOWN")]
54    TimestampProviderUnknown,
55    #[serde(rename = "TIMESTAMP_LOCAL_VERIFY_FAILED")]
56    TimestampLocalVerifyFailed,
57    #[serde(rename = "TIMESTAMP_PROVIDER_NOT_AVAILABLE")]
58    TimestampProviderNotAvailable,
59    #[serde(rename = "EVIDENCE_PACKAGE_NOT_FOUND")]
60    EvidencePackageNotFound,
61    #[serde(rename = "EVIDENCE_PACKAGE_TIMESTAMP_REQUIRED")]
62    EvidencePackageTimestampRequired,
63    #[serde(rename = "EVIDENCE_PACKAGE_MANIFEST_HASH_MISMATCH")]
64    EvidencePackageManifestHashMismatch,
65    #[serde(rename = "REPORT_NOT_FOUND")]
66    ReportNotFound,
67    #[serde(rename = "REPORT_ALREADY_PUBLISHED")]
68    ReportAlreadyPublished,
69    #[serde(rename = "REPORT_DRAFT_REQUIRED")]
70    ReportDraftRequired,
71    #[serde(rename = "EVIDENCE_VERIFY_TARGET_REQUIRED")]
72    EvidenceVerifyTargetRequired,
73    #[serde(rename = "EVIDENCE_VERIFY_TARGET_NOT_FOUND")]
74    EvidenceVerifyTargetNotFound,
75    // Provider request
76    #[serde(rename = "PROVIDER_REQUEST_UNKNOWN_NO_RETRY")]
77    ProviderRequestUnknownNoRetry,
78    #[serde(rename = "PROVIDER_CALLBACK_SOURCE_INVALID")]
79    ProviderCallbackSourceInvalid,
80    #[serde(rename = "PROVIDER_NOT_CONFIGURED")]
81    ProviderNotConfigured,
82    #[serde(rename = "PROVIDER_REQUEST_NOT_FOUND")]
83    ProviderRequestNotFound,
84    #[serde(rename = "PROVIDER_REQUEST_IDEMPOTENCY_REQUIRED")]
85    ProviderRequestIdempotencyRequired,
86    #[serde(rename = "PROVIDER_REQUEST_STATUS_NOT_TERMINAL")]
87    ProviderRequestStatusNotTerminal,
88    // Envelope
89    #[serde(rename = "ENVELOPE_NOT_FOUND")]
90    EnvelopeNotFound,
91    #[serde(rename = "ENVELOPE_TENANT_MISMATCH")]
92    EnvelopeTenantMismatch,
93    #[serde(rename = "ENVELOPE_STATE_NOT_ALLOWED")]
94    EnvelopeStateNotAllowed,
95    #[serde(rename = "ENVELOPE_GATE_CLOSED")]
96    EnvelopeGateClosed,
97    #[serde(rename = "CONTRACT_NOT_FOUND")]
98    ContractNotFound,
99    #[serde(rename = "CONTRACT_HASH_MISMATCH")]
100    ContractHashMismatch,
101    #[serde(rename = "PROVIDER_AUTHORIZATION_NOT_CONFIRMED")]
102    ProviderAuthorizationNotConfirmed,
103    #[serde(rename = "ENVELOPE_EVIDENCE_NOT_READY")]
104    EnvelopeEvidenceNotReady,
105    // Seal approval
106    #[serde(rename = "SEAL_ASSET_NOT_FOUND")]
107    SealAssetNotFound,
108    #[serde(rename = "SEAL_APPROVAL_NOT_FOUND")]
109    SealApprovalNotFound,
110    #[serde(rename = "SEAL_APPROVAL_STATE_NOT_APPROVED")]
111    SealApprovalStateNotApproved,
112    #[serde(rename = "SEAL_APPROVAL_EXPIRED")]
113    SealApprovalExpired,
114    #[serde(rename = "SEAL_APPROVAL_ALREADY_USED")]
115    SealApprovalAlreadyUsed,
116    #[serde(rename = "SEAL_APPROVAL_NONCE_USED")]
117    SealApprovalNonceUsed,
118    #[serde(rename = "SEAL_APPROVAL_SEAL_MISMATCH")]
119    SealApprovalSealMismatch,
120    #[serde(rename = "SEAL_APPROVAL_LOCATION_MISMATCH")]
121    SealApprovalLocationMismatch,
122    #[serde(rename = "SEAL_APPROVAL_TRANSACTOR_MISMATCH")]
123    SealApprovalTransactorMismatch,
124    #[serde(rename = "SEAL_APPROVAL_CONTRACT_HASH_MISMATCH")]
125    SealApprovalContractHashMismatch,
126    #[serde(rename = "SEAL_APPROVAL_INVALID_TRANSITION")]
127    SealApprovalInvalidTransition,
128    #[serde(rename = "SEAL_USE_ALREADY_CONSUMED")]
129    SealUseAlreadyConsumed,
130    // Audit chain
131    #[serde(rename = "AUDIT_CHAIN_TAMPER_DETECTED")]
132    AuditChainTamperDetected,
133    // Billing
134    #[serde(rename = "BILLING_COMMIT_REQUIRES_LOCAL_VERIFY")]
135    BillingCommitRequiresLocalVerify,
136    #[serde(rename = "BILLING_COMMIT_REQUIRES_PROVIDER_SUCCESS")]
137    BillingCommitRequiresProviderSuccess,
138    #[serde(rename = "BILLING_CALLBACK_CANNOT_COMMIT")]
139    BillingCallbackCannotCommit,
140    #[serde(rename = "BILLING_PROVIDER_UNKNOWN_NOT_COMMITTABLE")]
141    BillingProviderUnknownNotCommittable,
142    #[serde(rename = "BILLING_S2S_FORBIDDEN")]
143    BillingS2sForbidden,
144    // SDK fallback
145    #[serde(rename = "UNKNOWN_COMPLIANCE_ERROR")]
146    UnknownComplianceError,
147}
148
149/// 单个错误的 SDK 视图。对应 TS `ComplianceErrorInfo`。
150#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
151pub struct ComplianceErrorInfo {
152    /// Java numeric error code (wire contract)。
153    pub code: i64,
154    /// 服务端原始 message(中文,可变);仅用于日志/展示。
155    pub message: String,
156    /// SDK 分支判断用 symbolic key。
157    pub key: ComplianceErrorKey,
158    /// 是否安全自动重试 —— compliance 写接口几乎全为 false。
159    pub retryable: bool,
160    /// 是否已经是终态 —— 用户必须用新 idempotency-key 重新发起。
161    pub terminal: bool,
162    /// 高风险动作需要 step-up / introspection。
163    #[serde(rename = "stepUpRequired")]
164    pub step_up_required: bool,
165}
166
167/// numeric → symbolic 映射(与 Java ErrorCodeConstants 同步)。对应 TS `CODE_TO_KEY`。
168fn code_to_key(code: i64) -> Option<ComplianceErrorKey> {
169    use ComplianceErrorKey as K;
170    Some(match code {
171        // 通用 / token / scope (1-031-000-xxx)
172        1031000001 => K::ComplianceUnauthorized,
173        1031000002..=1031000011 => K::ComplianceTokenInvalid,
174        1031000012 => K::ComplianceInsufficientScope,
175        1031000013 => K::ComplianceStepUpRequired,
176        // Subject snapshot (1-031-001-xxx)
177        1031001001 => K::SubjectSnapshotNotFound,
178        1031001002 => K::SubjectSnapshotTenantMismatch,
179        1031001003 => K::SubjectSnapshotRequired,
180        // Evidence / Timestamp / Package / Report (1-031-002-xxx)
181        1031002001 => K::EvidenceAssetNotFound,
182        1031002002 => K::SubjectSnapshotTenantMismatch,
183        1031002003 => K::EvidenceAssetHashMismatch,
184        1031002004 | 1031002005 => K::EvidenceAssetPayloadRequired,
185        1031002006 => K::TimestampTokenNotFound,
186        1031002007 => K::TimestampProviderFailed,
187        1031002008 => K::TimestampProviderUnknown,
188        1031002009 => K::TimestampLocalVerifyFailed,
189        1031002010 => K::TimestampProviderNotAvailable,
190        1031002011 => K::EvidencePackageNotFound,
191        1031002012 => K::EvidencePackageTimestampRequired,
192        1031002013 => K::EvidencePackageManifestHashMismatch,
193        1031002014 => K::ReportNotFound,
194        1031002015 => K::ReportAlreadyPublished,
195        1031002016 => K::ReportDraftRequired,
196        1031002017 => K::EvidenceVerifyTargetRequired,
197        1031002018 => K::EvidenceVerifyTargetNotFound,
198        // Provider request (1-031-003-xxx)
199        1031003001 => K::ProviderRequestUnknownNoRetry,
200        1031003002 => K::ProviderCallbackSourceInvalid,
201        1031003003 => K::ProviderNotConfigured,
202        1031003010 => K::ProviderRequestNotFound,
203        1031003011 => K::ProviderRequestIdempotencyRequired,
204        1031003012 => K::ProviderRequestStatusNotTerminal,
205        // Envelope (1-031-004-xxx)
206        1031004001 => K::EnvelopeNotFound,
207        1031004002 => K::EnvelopeTenantMismatch,
208        1031004003 => K::EnvelopeStateNotAllowed,
209        1031004004 => K::EnvelopeGateClosed,
210        1031004005 => K::ContractNotFound,
211        1031004006 => K::ContractHashMismatch,
212        1031004007 => K::ContractNotFound,
213        1031004008 | 1031004009 => K::ProviderAuthorizationNotConfirmed,
214        1031004010 => K::EnvelopeEvidenceNotReady,
215        // Seal approval / use (1-031-005-xxx)
216        1031005001 => K::SealAssetNotFound,
217        1031005010 | 1031005011 => K::SealApprovalNotFound,
218        1031005012 => K::SealApprovalStateNotApproved,
219        1031005013 => K::SealApprovalExpired,
220        1031005014 => K::SealApprovalAlreadyUsed,
221        1031005015 => K::SealApprovalNonceUsed,
222        1031005016 => K::SealApprovalSealMismatch,
223        1031005017 => K::SealApprovalLocationMismatch,
224        1031005018 => K::SealApprovalTransactorMismatch,
225        1031005019 => K::SealApprovalContractHashMismatch,
226        1031005020 => K::SealApprovalInvalidTransition,
227        1031005030 => K::SealUseAlreadyConsumed,
228        // Billing (1-031-006-xxx)
229        1031006004 => K::BillingCommitRequiresLocalVerify,
230        1031006005 => K::BillingCommitRequiresProviderSuccess,
231        1031006007 => K::BillingCallbackCannotCommit,
232        1031006008 => K::BillingProviderUnknownNotCommittable,
233        1031006009 => K::BillingS2sForbidden,
234        // Audit (1-031-007-xxx)
235        1031007011 => K::AuditChainTamperDetected,
236        _ => return None,
237    })
238}
239
240/// 该 key 是否需要 step-up。对应 TS `STEP_UP_KEYS`。
241fn is_step_up_key(key: ComplianceErrorKey) -> bool {
242    matches!(key, ComplianceErrorKey::ComplianceStepUpRequired)
243}
244
245/// 该 key 是否终态。对应 TS `TERMINAL_KEYS`。
246fn is_terminal_key(key: ComplianceErrorKey) -> bool {
247    use ComplianceErrorKey as K;
248    matches!(
249        key,
250        K::EnvelopeGateClosed
251            | K::ProviderNotConfigured
252            | K::ProviderRequestUnknownNoRetry
253            | K::BillingCallbackCannotCommit
254            | K::BillingCommitRequiresLocalVerify
255            | K::BillingCommitRequiresProviderSuccess
256            | K::BillingProviderUnknownNotCommittable
257            | K::BillingS2sForbidden
258            | K::SealApprovalNonceUsed
259            | K::SealApprovalExpired
260            | K::SealApprovalContractHashMismatch
261            | K::SealApprovalSealMismatch
262            | K::SealApprovalLocationMismatch
263            | K::SealApprovalTransactorMismatch
264            | K::SealUseAlreadyConsumed
265            | K::ContractHashMismatch
266            | K::TimestampLocalVerifyFailed
267            | K::EvidencePackageManifestHashMismatch
268            | K::AuditChainTamperDetected
269            | K::ProviderRequestNotFound
270            | K::EvidenceAssetHashMismatch
271            | K::EvidenceVerifyTargetNotFound
272            | K::ReportAlreadyPublished
273    )
274}
275
276/// 该 key 是否 retryable。对应 TS `RETRYABLE_KEYS`(当前为空 —— 真正网络层短暂错误才允许)。
277fn is_retryable_key(_key: ComplianceErrorKey) -> bool {
278    false
279}
280
281/// 把一个 `BusinessError`(`Error::Business`)分类为 compliance 视图。对应 TS
282/// `classifyComplianceError`。
283///
284/// 非 compliance 段位的错误码会回退到 `UnknownComplianceError`,调用方应该当作业务错误处理。
285/// 传入的 `Error` 必须是 `Error::Business` 变体;其它变体不携带 numeric code,返回回退视图。
286pub fn classify_compliance_error(err: &Error) -> ComplianceErrorInfo {
287    let (code, message) = match err {
288        Error::Business { code, message } => (*code, message.clone()),
289        _ => (0, err.to_string()),
290    };
291    let key = code_to_key(code).unwrap_or(ComplianceErrorKey::UnknownComplianceError);
292    ComplianceErrorInfo {
293        code,
294        message,
295        key,
296        retryable: is_retryable_key(key),
297        terminal: is_terminal_key(key),
298        step_up_required: is_step_up_key(key),
299    }
300}
301
302/// 判断 `BusinessError` 是否属于 compliance 段位(1-031-xxx-xxx)。对应 TS
303/// `isComplianceBusinessError`。
304///
305/// 不在段位的错误码可能来自其它 yudao 模块,按通用业务错误处理即可。非 `Error::Business`
306/// 变体返回 false。
307pub fn is_compliance_business_error(err: &Error) -> bool {
308    matches!(err, Error::Business { code, .. } if (1031000000..=1031999999).contains(code))
309}
310
311#[cfg(test)]
312mod tests {
313    use super::*;
314
315    #[test]
316    fn key_serializes_to_symbolic_string() {
317        let s = serde_json::to_string(&ComplianceErrorKey::EnvelopeGateClosed).unwrap();
318        assert_eq!(s, "\"ENVELOPE_GATE_CLOSED\"");
319        let back: ComplianceErrorKey =
320            serde_json::from_str("\"SEAL_USE_ALREADY_CONSUMED\"").unwrap();
321        assert_eq!(back, ComplianceErrorKey::SealUseAlreadyConsumed);
322    }
323
324    #[test]
325    fn classify_step_up() {
326        let info = classify_compliance_error(&Error::business(1031000013, "需 step-up"));
327        assert_eq!(info.key, ComplianceErrorKey::ComplianceStepUpRequired);
328        assert!(info.step_up_required);
329        assert!(!info.terminal);
330        assert!(!info.retryable);
331    }
332
333    #[test]
334    fn classify_terminal_gate_closed() {
335        let info = classify_compliance_error(&Error::business(1031004004, "gate closed"));
336        assert_eq!(info.key, ComplianceErrorKey::EnvelopeGateClosed);
337        assert!(info.terminal);
338        assert!(!info.step_up_required);
339    }
340
341    #[test]
342    fn classify_token_invalid_band() {
343        for code in [1031000002, 1031000007, 1031000011] {
344            let info = classify_compliance_error(&Error::business(code, "x"));
345            assert_eq!(info.key, ComplianceErrorKey::ComplianceTokenInvalid);
346        }
347    }
348
349    #[test]
350    fn classify_unknown_out_of_band() {
351        let info = classify_compliance_error(&Error::business(9999, "other module"));
352        assert_eq!(info.key, ComplianceErrorKey::UnknownComplianceError);
353        assert!(!info.terminal);
354    }
355
356    #[test]
357    fn is_compliance_band_detection() {
358        assert!(is_compliance_business_error(&Error::business(
359            1031004004, ""
360        )));
361        assert!(!is_compliance_business_error(&Error::business(
362            1010000001, ""
363        )));
364        assert!(!is_compliance_business_error(&Error::other("not business")));
365    }
366}