Skip to main content

acosmi/compliance/
client.rs

1//! SDK-facing Compliance 域子客户端。端口自 `compliance/client.ts`
2//! (getter 子客户端 + 独立 base URL `{server_url}/admin-api`,不复用 `/api/v4` 路由)。
3//!
4//! 设计原则(严格):
5//!   - 走独立 base URL([`Client::compliance_url`]),不复用 `/api/v4` 路径。
6//!   - GET 认证读走 retry_on_401=true(与 agent-runs 同节奏,幂等安全)。
7//!   - 公开 verify 走 public_read:无 token 匿名请求,有 token 附带 Authorization 以保留审计
8//!     上下文;public 端点不应要求认证 → 401 不触发 force_refresh,也不做 refresh replay。
9//!   - POST 写操作走专属 helper:发送前 ensure_token 一次确保 token fresh;遇到 401 直接抛
10//!     HTTPError,不自动重放 —— compliance 写接口可能在 provider 侧落幂等写入,SDK 自动重放
11//!     会导致 provider 重复请求 / 重复扣费风险。
12//!   - 写操作支持 Idempotency-Key header;调用方应持久化 key,重试 / 恢复时复用。
13//!   - SDK 不传 provider 字段;服务端按配置选择 provider。
14
15use crate::compliance::errors::{
16    classify_compliance_error, is_compliance_business_error, ComplianceErrorInfo,
17    ComplianceErrorKey,
18};
19use crate::compliance::evidence::{
20    CreateEvidenceAssetRequest, EvidenceAsset, EvidenceAssetPageItem, EvidencePackage,
21    EvidencePackagePageItem, ListEvidenceAssetsRequest, ListEvidencePackagesRequest,
22    PublicEvidenceVerifyResult,
23};
24use crate::compliance::operation::{
25    ComplianceCapability, ListOperationsRequest, OperationDetail, OperationPageItem,
26};
27use crate::compliance::provider::{ComplianceProviderRequestStatus, ProviderRequestStatusView};
28use crate::compliance::report::{
29    ComplianceReport, CreateReportRequest, ListReportsRequest, ReportDownload, ReportPageItem,
30};
31use crate::compliance::seal_approval::{
32    ApproveSealApprovalQuery, CancelSealApprovalQuery, ListSealApprovalsRequest,
33    ListSealUsesRequest, RejectSealApprovalQuery, SealApproval, SealApprovalPageItem,
34    SealUsePageItem, SubmitSealApprovalRequest,
35};
36use crate::compliance::signing::{
37    CreateH5SigningUrlRequest, CreateSigningEnvelopeRequest, EnvelopeContractItem,
38    ListSigningEnvelopesRequest, SignEnvelopeRequest, SigningEnvelope, SigningEnvelopePageItem,
39    VoidEnvelopeRequest,
40};
41use crate::compliance::template::{
42    ContractTemplatePageItem, ContractTemplateResp, ContractTemplateVersion,
43    CreateContractTemplateRequest, ListContractTemplatesRequest, UpdateContractTemplateRequest,
44    UploadContractTemplatePdfRequest,
45};
46use crate::compliance::timestamp::{
47    ComplianceTimestampVerificationStatus, IssueTimestampRequest, ListTimestampsRequest,
48    TimestampPageItem, TimestampToken, TimestampVerifyResult, TsaProvider, TsaStats,
49    VerifyTimestampRequest,
50};
51use crate::compliance::types::{CompliancePollOptions, ComplianceWriteOptions};
52use crate::core::client::Client;
53use crate::core::http::{
54    parse_http_error_with_retry_after, read_limited_text_result as read_limited_text,
55    DEFAULT_JSON_TIMEOUT_MS, MAX_ERROR_BODY_SIZE,
56};
57use crate::shared::pagination::PageRequest;
58use crate::shared::{ApiResponse, Error, Result};
59use serde::de::DeserializeOwned;
60use serde::Serialize;
61use std::future::Future;
62use std::pin::Pin;
63use std::time::{Duration, Instant};
64use tokio_util::sync::CancellationToken;
65
66/// compliance 业务方法默认轮询参数。
67const DEFAULT_POLL_TIMEOUT_MS: u64 = 60_000;
68const DEFAULT_POLL_INITIAL_INTERVAL_MS: u64 = 1_000;
69const DEFAULT_POLL_MAX_INTERVAL_MS: u64 = 5_000;
70const DEFAULT_POLL_MULTIPLIER: f64 = 1.5;
71
72/// CompliancePollError 分类。对应 TS union `'timeout' | 'terminal_failure' | 'step_up_required' | 'unknown'`。
73#[derive(Debug, Clone, Copy, PartialEq, Eq)]
74pub enum CompliancePollErrorKind {
75    Timeout,
76    TerminalFailure,
77    StepUpRequired,
78    Unknown,
79}
80
81/// 当 compliance polling 检测到终态失败 / 已过 timeout / step-up 时返回。对应 TS
82/// `CompliancePollError`。
83///
84/// 分类逻辑:终态失败优先于 timeout;timeout 不算 retryable,调用方必须用新 idempotency-key
85/// 重新发起整条链路。
86#[derive(Debug, Clone)]
87pub struct CompliancePollError {
88    pub message: String,
89    pub kind: CompliancePollErrorKind,
90    pub last_info: Option<ComplianceErrorInfo>,
91}
92
93impl std::fmt::Display for CompliancePollError {
94    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
95        f.write_str(&self.message)
96    }
97}
98
99impl std::error::Error for CompliancePollError {}
100
101impl CompliancePollError {
102    fn new(
103        message: impl Into<String>,
104        kind: CompliancePollErrorKind,
105        last_info: Option<ComplianceErrorInfo>,
106    ) -> Self {
107        Self {
108            message: message.into(),
109            kind,
110            last_info,
111        }
112    }
113}
114
115/// poll 一次的分类决策。
116#[derive(Debug, Clone, Copy, PartialEq, Eq)]
117enum PollDecision {
118    Continue,
119    Done,
120    Failed,
121}
122
123/// SDK-facing compliance 子客户端。对应 TS `ComplianceClient`。
124///
125/// 经 [`Client::compliance`] getter 获取(无状态,持 [`Client`] clone)。
126pub struct ComplianceClient {
127    client: Client,
128}
129
130impl ComplianceClient {
131    pub(crate) fn new(client: Client) -> Self {
132        Self { client }
133    }
134
135    // =========================================================================
136    // Evidence Asset
137    // =========================================================================
138
139    /// 创建证据资产(写)。对应 TS `createEvidenceAsset`。
140    pub async fn create_evidence_asset(
141        &self,
142        req: &CreateEvidenceAssetRequest,
143        opts: &ComplianceWriteOptions,
144        signal: Option<CancellationToken>,
145    ) -> Result<EvidenceAsset> {
146        self.write(
147            "POST",
148            "/compliance/evidence/assets",
149            Some(req),
150            opts,
151            signal,
152        )
153        .await
154    }
155
156    /// 读 —— 证据资产详情。对应 TS `getEvidenceAsset`。
157    pub async fn get_evidence_asset(
158        &self,
159        id: i64,
160        signal: Option<CancellationToken>,
161    ) -> Result<EvidenceAsset> {
162        self.read(&format!("/compliance/evidence/assets/{id}"), None, signal)
163            .await
164    }
165
166    /// 读 —— 证据资产分页列表(S1)。对应 TS `listEvidenceAssets`。
167    pub async fn list_evidence_assets(
168        &self,
169        req: &ListEvidenceAssetsRequest,
170        signal: Option<CancellationToken>,
171    ) -> Result<crate::shared::pagination::PageResult<EvidenceAssetPageItem>> {
172        let mut q = QueryBuilder::new(&req.page);
173        q.add("assetType", req.asset_type.as_deref());
174        q.add("status", req.status.as_deref());
175        q.add("createTimeStart", req.create_time_start.as_deref());
176        q.add("createTimeEnd", req.create_time_end.as_deref());
177        let path = format!("/compliance/evidence/assets/page{}", q.finish());
178        self.read(&path, None, signal).await
179    }
180
181    /// 公开 verify。匿名可调用:未 login 时走匿名请求。已 login / 已持有 token 时附带
182    /// `Authorization` 以保留审计上下文。对应 TS `verifyEvidencePublic`。
183    pub async fn verify_evidence_public(
184        &self,
185        evidence_no: Option<&str>,
186        public_verify_code: Option<&str>,
187        signal: Option<CancellationToken>,
188    ) -> Result<PublicEvidenceVerifyResult> {
189        let mut parts: Vec<String> = Vec::new();
190        if let Some(v) = evidence_no.filter(|s| !s.is_empty()) {
191            parts.push(format!("evidenceNo={}", urlencode(v)));
192        }
193        if let Some(v) = public_verify_code.filter(|s| !s.is_empty()) {
194            parts.push(format!("publicVerifyCode={}", urlencode(v)));
195        }
196        let qs = if parts.is_empty() {
197            String::new()
198        } else {
199            format!("?{}", parts.join("&"))
200        };
201        self.public_read(&format!("/compliance/evidence/verify{qs}"), signal)
202            .await
203    }
204
205    // =========================================================================
206    // Timestamp
207    // =========================================================================
208
209    /// 申请时间章(写)。SDK 永远不传 provider 字段。对应 TS `issueTimestamp`。
210    pub async fn issue_timestamp(
211        &self,
212        req: &IssueTimestampRequest,
213        opts: &ComplianceWriteOptions,
214        signal: Option<CancellationToken>,
215    ) -> Result<TimestampToken> {
216        self.write("POST", "/compliance/timestamps", Some(req), opts, signal)
217            .await
218    }
219
220    /// 给已有资产申请时间章(写)。对应 TS `issueTimestampForAsset`。
221    pub async fn issue_timestamp_for_asset(
222        &self,
223        asset_id: i64,
224        opts: &ComplianceWriteOptions,
225        signal: Option<CancellationToken>,
226    ) -> Result<TimestampToken> {
227        self.write::<(), _>(
228            "POST",
229            &format!("/compliance/evidence/assets/{asset_id}/timestamp"),
230            None,
231            opts,
232            signal,
233        )
234        .await
235    }
236
237    /// 读 —— 时间章 token 详情。对应 TS `getTimestamp`。
238    pub async fn get_timestamp(
239        &self,
240        id: i64,
241        signal: Option<CancellationToken>,
242    ) -> Result<TimestampToken> {
243        self.read(&format!("/compliance/timestamps/{id}"), None, signal)
244            .await
245    }
246
247    /// 读 —— 时间章分页列表(S1)。对应 TS `listTimestamps`。
248    pub async fn list_timestamps(
249        &self,
250        req: &ListTimestampsRequest,
251        signal: Option<CancellationToken>,
252    ) -> Result<crate::shared::pagination::PageResult<TimestampPageItem>> {
253        let mut q = QueryBuilder::new(&req.page);
254        q.add("provider", req.provider.as_deref());
255        q.add("verificationStatus", req.verification_status.as_deref());
256        q.add("createTimeStart", req.create_time_start.as_deref());
257        q.add("createTimeEnd", req.create_time_end.as_deref());
258        let path = format!("/compliance/timestamps/page{}", q.finish());
259        self.read(&path, None, signal).await
260    }
261
262    /// verify —— 本地离线校验已申请的时间章(写)。对应 TS `verifyTimestamp`。
263    pub async fn verify_timestamp(
264        &self,
265        req: &VerifyTimestampRequest,
266        opts: &ComplianceWriteOptions,
267        signal: Option<CancellationToken>,
268    ) -> Result<TimestampVerifyResult> {
269        self.write(
270            "POST",
271            "/compliance/timestamps/verify",
272            Some(req),
273            opts,
274            signal,
275        )
276        .await
277    }
278
279    /// 轮询到 VERIFIED 终态。对应 TS `waitForTimestampVerified`。
280    pub async fn wait_for_timestamp_verified(
281        &self,
282        id: i64,
283        opts: &CompliancePollOptions,
284        signal: Option<CancellationToken>,
285    ) -> std::result::Result<TimestampToken, CompliancePollError> {
286        self.poll(
287            || self.get_timestamp(id, signal.clone()),
288            |t: &TimestampToken| classify_timestamp(&t.verification_status),
289            opts,
290            signal.clone(),
291            derive_last_info_timestamp,
292        )
293        .await
294    }
295
296    // =========================================================================
297    // TSA readonly views (S3 / gap-register U-7)
298    // =========================================================================
299
300    /// 读 —— 时间章授权机构(TSA)provider 列表(S3)。对应 TS `listTsaProviders`。
301    pub async fn list_tsa_providers(
302        &self,
303        signal: Option<CancellationToken>,
304    ) -> Result<Vec<TsaProvider>> {
305        self.read("/compliance/timestamps/providers", None, signal)
306            .await
307    }
308
309    /// 读 —— 时间章统计视图(S3)。对应 TS `getTsaStats`。
310    pub async fn get_tsa_stats(&self, signal: Option<CancellationToken>) -> Result<TsaStats> {
311        self.read("/compliance/timestamps/stats", None, signal)
312            .await
313    }
314
315    // =========================================================================
316    // Evidence Package
317    // =========================================================================
318
319    /// 构建证据包(写)。对应 TS `buildEvidencePackage`。
320    pub async fn build_evidence_package(
321        &self,
322        asset_id: i64,
323        timestamp_token_id: Option<i64>,
324        opts: &ComplianceWriteOptions,
325        signal: Option<CancellationToken>,
326    ) -> Result<EvidencePackage> {
327        let ts_param = match timestamp_token_id {
328            Some(id) => format!("?timestampTokenId={id}"),
329            None => String::new(),
330        };
331        self.write::<(), _>(
332            "POST",
333            &format!("/compliance/evidence/assets/{asset_id}/packages{ts_param}"),
334            None,
335            opts,
336            signal,
337        )
338        .await
339    }
340
341    /// 读 —— 证据包分页列表(S1)。对应 TS `listEvidencePackages`。
342    pub async fn list_evidence_packages(
343        &self,
344        req: &ListEvidencePackagesRequest,
345        signal: Option<CancellationToken>,
346    ) -> Result<crate::shared::pagination::PageResult<EvidencePackagePageItem>> {
347        let mut q = QueryBuilder::new(&req.page);
348        q.add("status", req.status.as_deref());
349        q.add("createTimeStart", req.create_time_start.as_deref());
350        q.add("createTimeEnd", req.create_time_end.as_deref());
351        let path = format!("/compliance/evidence/packages/page{}", q.finish());
352        self.read(&path, None, signal).await
353    }
354
355    // =========================================================================
356    // Report
357    // =========================================================================
358
359    /// 创建证据报告(写)。对应 TS `createReport`。
360    pub async fn create_report(
361        &self,
362        req: &CreateReportRequest,
363        opts: &ComplianceWriteOptions,
364        signal: Option<CancellationToken>,
365    ) -> Result<ComplianceReport> {
366        self.write("POST", "/compliance/reports", Some(req), opts, signal)
367            .await
368    }
369
370    /// 读 —— 报告详情。对应 TS `getReport`。
371    pub async fn get_report(
372        &self,
373        id: i64,
374        signal: Option<CancellationToken>,
375    ) -> Result<ComplianceReport> {
376        self.read(&format!("/compliance/reports/{id}"), None, signal)
377            .await
378    }
379
380    /// 读 —— 证据报告分页列表(S1)。对应 TS `listReports`。
381    pub async fn list_reports(
382        &self,
383        req: &ListReportsRequest,
384        signal: Option<CancellationToken>,
385    ) -> Result<crate::shared::pagination::PageResult<ReportPageItem>> {
386        let mut q = QueryBuilder::new(&req.page);
387        q.add("status", req.status.as_deref());
388        q.add("createTimeStart", req.create_time_start.as_deref());
389        q.add("createTimeEnd", req.create_time_end.as_deref());
390        let path = format!("/compliance/reports/page{}", q.finish());
391        self.read(&path, None, signal).await
392    }
393
394    /// 发布报告(写,step-up 必须)。对应 TS `publishReport`。
395    ///
396    /// `@status gated` —— step-up 闸门未闭合前服务端会一致返回 `COMPLIANCE_STEP_UP_REQUIRED`。
397    /// SDK 不会自动重试、不伪成功;调用方需引导用户重新做 OAuth introspection 或重新登录后再次
398    /// 调用本方法(使用同一 idempotency-key)。
399    pub async fn publish_report(
400        &self,
401        id: i64,
402        opts: &ComplianceWriteOptions,
403        signal: Option<CancellationToken>,
404    ) -> Result<ComplianceReport> {
405        self.write::<(), _>(
406            "POST",
407            &format!("/compliance/reports/{id}/publish"),
408            None,
409            opts,
410            signal,
411        )
412        .await
413    }
414
415    /// 下载报告(读)。对应 TS `downloadReport`。
416    pub async fn download_report(
417        &self,
418        id: i64,
419        signal: Option<CancellationToken>,
420    ) -> Result<ReportDownload> {
421        self.read(&format!("/compliance/reports/{id}/download"), None, signal)
422            .await
423    }
424
425    // =========================================================================
426    // Signing Envelope
427    // =========================================================================
428
429    /// 创建 envelope(写)。返回 envelope id。对应 TS `createSigningEnvelope`。
430    pub async fn create_signing_envelope(
431        &self,
432        req: &CreateSigningEnvelopeRequest,
433        opts: &ComplianceWriteOptions,
434        signal: Option<CancellationToken>,
435    ) -> Result<i64> {
436        self.write(
437            "POST",
438            "/compliance/signing-envelopes",
439            Some(req),
440            opts,
441            signal,
442        )
443        .await
444    }
445
446    /// 读 —— envelope 详情。对应 TS `getSigningEnvelope`。
447    pub async fn get_signing_envelope(
448        &self,
449        envelope_id: i64,
450        signal: Option<CancellationToken>,
451    ) -> Result<SigningEnvelope> {
452        self.read(
453            &format!("/compliance/signing-envelopes/{envelope_id}"),
454            None,
455            signal,
456        )
457        .await
458    }
459
460    /// 读 —— 签署 envelope 分页列表(S1)。对应 TS `listSigningEnvelopes`。
461    pub async fn list_signing_envelopes(
462        &self,
463        req: &ListSigningEnvelopesRequest,
464        signal: Option<CancellationToken>,
465    ) -> Result<crate::shared::pagination::PageResult<SigningEnvelopePageItem>> {
466        let mut q = QueryBuilder::new(&req.page);
467        q.add("status", req.status.as_deref());
468        q.add("createTimeStart", req.create_time_start.as_deref());
469        q.add("createTimeEnd", req.create_time_end.as_deref());
470        let path = format!("/compliance/signing-envelopes/page{}", q.finish());
471        self.read(&path, None, signal).await
472    }
473
474    /// 正式签署(写,step-up 必须)。对应 TS `signEnvelope`。空体写接口返回 `()`。
475    pub async fn sign_envelope(
476        &self,
477        envelope_id: i64,
478        req: &SignEnvelopeRequest,
479        opts: &ComplianceWriteOptions,
480        signal: Option<CancellationToken>,
481    ) -> Result<()> {
482        self.write_unit(
483            "POST",
484            &format!("/compliance/signing-envelopes/{envelope_id}/sign"),
485            Some(req),
486            opts,
487            signal,
488        )
489        .await
490    }
491
492    /// 创建 H5 签署短链(写,step-up 必须)。对应 TS `createH5SigningUrl`。
493    pub async fn create_h5_signing_url(
494        &self,
495        envelope_id: i64,
496        req: &CreateH5SigningUrlRequest,
497        opts: &ComplianceWriteOptions,
498        signal: Option<CancellationToken>,
499    ) -> Result<String> {
500        self.write(
501            "POST",
502            &format!("/compliance/signing-envelopes/{envelope_id}/h5-url"),
503            Some(req),
504            opts,
505            signal,
506        )
507        .await
508    }
509
510    /// 同步 provider 状态(写但只读对账)。对应 TS `syncSigningEnvelopeStatus`。
511    pub async fn sync_signing_envelope_status(
512        &self,
513        envelope_id: i64,
514        opts: &ComplianceWriteOptions,
515        signal: Option<CancellationToken>,
516    ) -> Result<()> {
517        self.write_unit::<()>(
518            "POST",
519            &format!("/compliance/signing-envelopes/{envelope_id}/sync-provider-status"),
520            None,
521            opts,
522            signal,
523        )
524        .await
525    }
526
527    /// 读 —— envelope 下挂的合同列表(S4)。返回普通数组(非 PageResult)。对应 TS
528    /// `listEnvelopeContracts`。
529    pub async fn list_envelope_contracts(
530        &self,
531        envelope_id: i64,
532        signal: Option<CancellationToken>,
533    ) -> Result<Vec<EnvelopeContractItem>> {
534        self.read(
535            &format!("/compliance/signing-envelopes/{envelope_id}/contracts"),
536            None,
537            signal,
538        )
539        .await
540    }
541
542    /// 读 —— envelope 关联的 provider 请求列表(S4,复用 OperationPageItem)。对应 TS
543    /// `listEnvelopeProviderRequests`。
544    pub async fn list_envelope_provider_requests(
545        &self,
546        envelope_id: i64,
547        signal: Option<CancellationToken>,
548    ) -> Result<Vec<OperationPageItem>> {
549        self.read(
550            &format!("/compliance/signing-envelopes/{envelope_id}/provider-requests"),
551            None,
552            signal,
553        )
554        .await
555    }
556
557    /// 作废 envelope(写,S4)。对应 TS `voidEnvelope`。
558    pub async fn void_envelope(
559        &self,
560        envelope_id: i64,
561        req: &VoidEnvelopeRequest,
562        opts: &ComplianceWriteOptions,
563        signal: Option<CancellationToken>,
564    ) -> Result<bool> {
565        self.write(
566            "POST",
567            &format!("/compliance/signing-envelopes/{envelope_id}/void"),
568            Some(req),
569            opts,
570            signal,
571        )
572        .await
573    }
574
575    // =========================================================================
576    // Seal Approval
577    // =========================================================================
578
579    /// 提交用印审批申请(写)。返回审批 id。对应 TS `submitSealApproval`。
580    pub async fn submit_seal_approval(
581        &self,
582        req: &SubmitSealApprovalRequest,
583        opts: &ComplianceWriteOptions,
584        signal: Option<CancellationToken>,
585    ) -> Result<i64> {
586        self.write(
587            "POST",
588            "/compliance/seal-approvals",
589            Some(req),
590            opts,
591            signal,
592        )
593        .await
594    }
595
596    /// 审批通过用印申请(写,step-up 必须)。对应 TS `approveSealApproval`。
597    pub async fn approve_seal_approval(
598        &self,
599        id: i64,
600        query: &ApproveSealApprovalQuery,
601        opts: &ComplianceWriteOptions,
602        signal: Option<CancellationToken>,
603    ) -> Result<()> {
604        let mut parts: Vec<String> = Vec::new();
605        if let Some(v) = query.expires_at.as_deref().filter(|s| !s.is_empty()) {
606            parts.push(format!("expiresAt={}", urlencode(v)));
607        }
608        if let Some(v) = query.note.as_deref().filter(|s| !s.is_empty()) {
609            parts.push(format!("note={}", urlencode(v)));
610        }
611        let qs = qstr(&parts);
612        self.write_unit::<()>(
613            "POST",
614            &format!("/compliance/seal-approvals/{id}/approve{qs}"),
615            None,
616            opts,
617            signal,
618        )
619        .await
620    }
621
622    /// 审批拒绝用印申请(写)。对应 TS `rejectSealApproval`。
623    pub async fn reject_seal_approval(
624        &self,
625        id: i64,
626        query: &RejectSealApprovalQuery,
627        opts: &ComplianceWriteOptions,
628        signal: Option<CancellationToken>,
629    ) -> Result<()> {
630        let mut parts: Vec<String> = Vec::new();
631        if let Some(v) = query.reason.as_deref().filter(|s| !s.is_empty()) {
632            parts.push(format!("reason={}", urlencode(v)));
633        }
634        let qs = qstr(&parts);
635        self.write_unit::<()>(
636            "POST",
637            &format!("/compliance/seal-approvals/{id}/reject{qs}"),
638            None,
639            opts,
640            signal,
641        )
642        .await
643    }
644
645    /// 取消用印申请(写)。对应 TS `cancelSealApproval`。
646    pub async fn cancel_seal_approval(
647        &self,
648        id: i64,
649        query: &CancelSealApprovalQuery,
650        opts: &ComplianceWriteOptions,
651        signal: Option<CancellationToken>,
652    ) -> Result<()> {
653        let mut parts: Vec<String> = Vec::new();
654        if let Some(v) = query.reason.as_deref().filter(|s| !s.is_empty()) {
655            parts.push(format!("reason={}", urlencode(v)));
656        }
657        let qs = qstr(&parts);
658        self.write_unit::<()>(
659            "POST",
660            &format!("/compliance/seal-approvals/{id}/cancel{qs}"),
661            None,
662            opts,
663            signal,
664        )
665        .await
666    }
667
668    /// 读 —— pending 用印审批列表(不分页)。对应 TS `listPendingSealApprovals`。
669    pub async fn list_pending_seal_approvals(
670        &self,
671        signal: Option<CancellationToken>,
672    ) -> Result<Vec<SealApproval>> {
673        self.read("/compliance/seal-approvals/pending", None, signal)
674            .await
675    }
676
677    /// 读 —— 用印审批详情。对应 TS `getSealApproval`。
678    pub async fn get_seal_approval(
679        &self,
680        id: i64,
681        signal: Option<CancellationToken>,
682    ) -> Result<SealApproval> {
683        self.read(&format!("/compliance/seal-approvals/{id}"), None, signal)
684            .await
685    }
686
687    /// 读 —— 用印审批分页列表(S1)。对应 TS `listSealApprovals`。
688    pub async fn list_seal_approvals(
689        &self,
690        req: &ListSealApprovalsRequest,
691        signal: Option<CancellationToken>,
692    ) -> Result<crate::shared::pagination::PageResult<SealApprovalPageItem>> {
693        let mut q = QueryBuilder::new(&req.page);
694        q.add("status", req.status.as_deref());
695        q.add("createTimeStart", req.create_time_start.as_deref());
696        q.add("createTimeEnd", req.create_time_end.as_deref());
697        let path = format!("/compliance/seal-approvals/page{}", q.finish());
698        self.read(&path, None, signal).await
699    }
700
701    // =========================================================================
702    // Seal Use (read-only — S6 / gap-register U-4)
703    // =========================================================================
704
705    /// 读 —— 用印执行记录分页列表(S6)。对应 TS `listSealUses`。
706    pub async fn list_seal_uses(
707        &self,
708        req: &ListSealUsesRequest,
709        signal: Option<CancellationToken>,
710    ) -> Result<crate::shared::pagination::PageResult<SealUsePageItem>> {
711        let mut q = QueryBuilder::new(&req.page);
712        q.add("sealId", req.seal_id.map(|v| v.to_string()).as_deref());
713        q.add(
714            "envelopeId",
715            req.envelope_id.map(|v| v.to_string()).as_deref(),
716        );
717        q.add("usageStatus", req.usage_status.as_deref());
718        q.add("createTimeStart", req.create_time_start.as_deref());
719        q.add("createTimeEnd", req.create_time_end.as_deref());
720        let path = format!("/compliance/seal-uses/page{}", q.finish());
721        self.read(&path, None, signal).await
722    }
723
724    // =========================================================================
725    // Provider Request (read-only)
726    // =========================================================================
727
728    /// 读 —— provider request 状态视图。对应 TS `getProviderRequest`。
729    pub async fn get_provider_request(
730        &self,
731        id: i64,
732        signal: Option<CancellationToken>,
733    ) -> Result<ProviderRequestStatusView> {
734        self.read(&format!("/compliance/provider-requests/{id}"), None, signal)
735            .await
736    }
737
738    /// 轮询 provider request 到 SUCCESS / FAILED 终态。对应 TS
739    /// `waitForProviderRequestTerminal`。
740    pub async fn wait_for_provider_request_terminal(
741        &self,
742        id: i64,
743        opts: &CompliancePollOptions,
744        signal: Option<CancellationToken>,
745    ) -> std::result::Result<ProviderRequestStatusView, CompliancePollError> {
746        self.poll(
747            || self.get_provider_request(id, signal.clone()),
748            |v: &ProviderRequestStatusView| classify_provider_status(&v.status),
749            opts,
750            signal.clone(),
751            derive_last_info_provider,
752        )
753        .await
754    }
755
756    // =========================================================================
757    // Capabilities (read-only — S2 / gap-register U-6)
758    // =========================================================================
759
760    /// 读 —— compliance 能力闸门列表(S2)。对应 TS `getCapabilities`。
761    pub async fn get_capabilities(
762        &self,
763        signal: Option<CancellationToken>,
764    ) -> Result<Vec<ComplianceCapability>> {
765        self.read("/compliance/capabilities", None, signal).await
766    }
767
768    /// 读 —— 单个动作的能力闸门视图(便捷方法)。无匹配返回 `None`。对应 TS `getFeatureGate`。
769    pub async fn get_feature_gate(
770        &self,
771        action: &str,
772        signal: Option<CancellationToken>,
773    ) -> Result<Option<ComplianceCapability>> {
774        let caps = self.get_capabilities(signal).await?;
775        Ok(caps.into_iter().find(|c| c.action == action))
776    }
777
778    // =========================================================================
779    // Operation projection (read-only — S2 / gap-register U-5)
780    // =========================================================================
781
782    /// 读 —— compliance 操作投影分页列表(S2)。对应 TS `listOperations`。
783    pub async fn list_operations(
784        &self,
785        req: &ListOperationsRequest,
786        signal: Option<CancellationToken>,
787    ) -> Result<crate::shared::pagination::PageResult<OperationPageItem>> {
788        let mut q = QueryBuilder::new(&req.page);
789        q.add("status", req.status.as_deref());
790        q.add("createTimeStart", req.create_time_start.as_deref());
791        q.add("createTimeEnd", req.create_time_end.as_deref());
792        let path = format!("/compliance/operations/page{}", q.finish());
793        self.read(&path, None, signal).await
794    }
795
796    /// 读 —— compliance 操作投影详情(S2)。`id` 为数值行主键。对应 TS `getOperation`。
797    pub async fn get_operation(
798        &self,
799        id: i64,
800        signal: Option<CancellationToken>,
801    ) -> Result<OperationDetail> {
802        self.read(&format!("/compliance/operations/{id}"), None, signal)
803            .await
804    }
805
806    // =========================================================================
807    // Contract Template (S5 — gap-register U-2)
808    // =========================================================================
809
810    /// 创建合同模板(写)。对应 TS `createContractTemplate`。
811    pub async fn create_contract_template(
812        &self,
813        req: &CreateContractTemplateRequest,
814        opts: &ComplianceWriteOptions,
815        signal: Option<CancellationToken>,
816    ) -> Result<ContractTemplateResp> {
817        self.write(
818            "POST",
819            "/compliance/contract-templates",
820            Some(req),
821            opts,
822            signal,
823        )
824        .await
825    }
826
827    /// 更新合同模板(写,仅 DRAFT 状态)。对应 TS `updateContractTemplate`。
828    pub async fn update_contract_template(
829        &self,
830        id: i64,
831        req: &UpdateContractTemplateRequest,
832        opts: &ComplianceWriteOptions,
833        signal: Option<CancellationToken>,
834    ) -> Result<ContractTemplateResp> {
835        self.write(
836            "POST",
837            &format!("/compliance/contract-templates/{id}"),
838            Some(req),
839            opts,
840            signal,
841        )
842        .await
843    }
844
845    /// 删除合同模板(写,仅 DRAFT 状态)。对应 TS `deleteContractTemplate`。
846    pub async fn delete_contract_template(
847        &self,
848        id: i64,
849        opts: &ComplianceWriteOptions,
850        signal: Option<CancellationToken>,
851    ) -> Result<()> {
852        self.write_unit::<()>(
853            "POST",
854            &format!("/compliance/contract-templates/{id}/delete"),
855            None,
856            opts,
857            signal,
858        )
859        .await
860    }
861
862    /// 读 —— 合同模板详情。对应 TS `getContractTemplate`。
863    pub async fn get_contract_template(
864        &self,
865        id: i64,
866        signal: Option<CancellationToken>,
867    ) -> Result<ContractTemplateResp> {
868        self.read(
869            &format!("/compliance/contract-templates/{id}"),
870            None,
871            signal,
872        )
873        .await
874    }
875
876    /// 读 —— 合同模板分页列表(S5)。对应 TS `listContractTemplates`。
877    pub async fn list_contract_templates(
878        &self,
879        req: &ListContractTemplatesRequest,
880        signal: Option<CancellationToken>,
881    ) -> Result<crate::shared::pagination::PageResult<ContractTemplatePageItem>> {
882        let mut q = QueryBuilder::new(&req.page);
883        q.add("status", req.status.as_deref());
884        q.add("createTimeStart", req.create_time_start.as_deref());
885        q.add("createTimeEnd", req.create_time_end.as_deref());
886        let path = format!("/compliance/contract-templates/page{}", q.finish());
887        self.read(&path, None, signal).await
888    }
889
890    /// 上传合同模板 PDF(写)。对应 TS `uploadContractTemplatePdf`。
891    pub async fn upload_contract_template_pdf(
892        &self,
893        id: i64,
894        req: &UploadContractTemplatePdfRequest,
895        opts: &ComplianceWriteOptions,
896        signal: Option<CancellationToken>,
897    ) -> Result<ContractTemplateResp> {
898        self.write(
899            "POST",
900            &format!("/compliance/contract-templates/{id}/pdf"),
901            Some(req),
902            opts,
903            signal,
904        )
905        .await
906    }
907
908    /// 发布合同模板(写)。DRAFT → PUBLISHED。对应 TS `publishContractTemplate`。
909    pub async fn publish_contract_template(
910        &self,
911        id: i64,
912        opts: &ComplianceWriteOptions,
913        signal: Option<CancellationToken>,
914    ) -> Result<ContractTemplateResp> {
915        self.write::<(), _>(
916            "POST",
917            &format!("/compliance/contract-templates/{id}/publish"),
918            None,
919            opts,
920            signal,
921        )
922        .await
923    }
924
925    /// 归档合同模板(写)。PUBLISHED → ARCHIVED。对应 TS `archiveContractTemplate`。
926    pub async fn archive_contract_template(
927        &self,
928        id: i64,
929        opts: &ComplianceWriteOptions,
930        signal: Option<CancellationToken>,
931    ) -> Result<ContractTemplateResp> {
932        self.write::<(), _>(
933            "POST",
934            &format!("/compliance/contract-templates/{id}/archive"),
935            None,
936            opts,
937            signal,
938        )
939        .await
940    }
941
942    /// 读 —— 合同模板版本快照列表。对应 TS `listContractTemplateVersions`。
943    pub async fn list_contract_template_versions(
944        &self,
945        id: i64,
946        signal: Option<CancellationToken>,
947    ) -> Result<Vec<ContractTemplateVersion>> {
948        self.read(
949            &format!("/compliance/contract-templates/{id}/versions"),
950            None,
951            signal,
952        )
953        .await
954    }
955
956    // =========================================================================
957    // Error classification (re-export for convenience)
958    // =========================================================================
959
960    /// 把一个错误分类为 compliance 视图。非 compliance 段位的 BusinessError 返回 `None`。
961    /// 对应 TS `classifyError`。
962    pub fn classify_error(&self, err: &Error) -> Option<ComplianceErrorInfo> {
963        if !matches!(err, Error::Business { .. }) {
964            return None;
965        }
966        if !is_compliance_business_error(err) {
967            return None;
968        }
969        Some(classify_compliance_error(err))
970    }
971
972    // =========================================================================
973    // Internal helpers
974    // =========================================================================
975
976    /// 读路径:GET / 公开 verify。允许 401 单次刷新后重放(GET 幂等安全)。
977    async fn read<T: DeserializeOwned>(
978        &self,
979        path: &str,
980        body: Option<&str>,
981        signal: Option<CancellationToken>,
982    ) -> Result<T> {
983        self.client
984            .compliance_execute_json(http::Method::GET, path, body, signal, true, &[])
985            .await
986    }
987
988    /// 公开读路径:public verify。无 token 匿名;有 token 附 Authorization;401 不刷新重放。
989    async fn public_read<T: DeserializeOwned>(
990        &self,
991        path: &str,
992        signal: Option<CancellationToken>,
993    ) -> Result<T> {
994        self.client.compliance_public_read(path, signal).await
995    }
996
997    /// 写路径:POST。发送前 ensure_token 一次;401 → 抛 HTTPError;不重试。
998    async fn write<B: Serialize, T: DeserializeOwned>(
999        &self,
1000        method: &str,
1001        path: &str,
1002        body: Option<&B>,
1003        opts: &ComplianceWriteOptions,
1004        signal: Option<CancellationToken>,
1005    ) -> Result<T> {
1006        let body_str = match body {
1007            Some(b) => Some(
1008                serde_json::to_string(b)
1009                    .map_err(|e| Error::other(format!("{path}: serialize body: {e}")))?,
1010            ),
1011            None => None,
1012        };
1013        let m = http::Method::from_bytes(method.as_bytes())
1014            .map_err(|e| Error::other(format!("invalid method {method}: {e}")))?;
1015        let extra = idempotency_header(opts);
1016        self.client
1017            .compliance_execute_json(m, path, body_str.as_deref(), signal, false, &extra)
1018            .await
1019    }
1020
1021    /// 写路径返回 `()`(空体 void 端点)。对应 TS `write<void>`。
1022    async fn write_unit<B: Serialize>(
1023        &self,
1024        method: &str,
1025        path: &str,
1026        body: Option<&B>,
1027        opts: &ComplianceWriteOptions,
1028        signal: Option<CancellationToken>,
1029    ) -> Result<()> {
1030        let body_str = match body {
1031            Some(b) => Some(
1032                serde_json::to_string(b)
1033                    .map_err(|e| Error::other(format!("{path}: serialize body: {e}")))?,
1034            ),
1035            None => None,
1036        };
1037        let m = http::Method::from_bytes(method.as_bytes())
1038            .map_err(|e| Error::other(format!("invalid method {method}: {e}")))?;
1039        let extra = idempotency_header(opts);
1040        self.client
1041            .compliance_execute_unit(m, path, body_str.as_deref(), signal, false, &extra)
1042            .await
1043    }
1044
1045    /// 轮询循环(exponential backoff)。对应 TS `poll`。
1046    ///
1047    /// 终态失败优先于 timeout;abort 携带最后状态;timeout 不算 retryable。
1048    async fn poll<T, F, Fut, C, D>(
1049        &self,
1050        mut fetcher: F,
1051        classify: C,
1052        opts: &CompliancePollOptions,
1053        signal: Option<CancellationToken>,
1054        derive_last: D,
1055    ) -> std::result::Result<T, CompliancePollError>
1056    where
1057        F: FnMut() -> Fut,
1058        Fut: Future<Output = Result<T>>,
1059        C: Fn(&T) -> PollDecision,
1060        D: Fn(&T) -> ComplianceErrorInfo,
1061    {
1062        let timeout_ms = opts.timeout_ms.unwrap_or(DEFAULT_POLL_TIMEOUT_MS);
1063        let initial = opts
1064            .initial_interval_ms
1065            .unwrap_or(DEFAULT_POLL_INITIAL_INTERVAL_MS);
1066        let max_interval = opts.max_interval_ms.unwrap_or(DEFAULT_POLL_MAX_INTERVAL_MS);
1067        let multiplier = opts.multiplier.unwrap_or(DEFAULT_POLL_MULTIPLIER);
1068
1069        let deadline = Instant::now() + Duration::from_millis(timeout_ms);
1070        let mut interval_ms = initial;
1071        let mut last_value: Option<T> = None;
1072
1073        while Instant::now() < deadline {
1074            if signal.as_ref().map(|s| s.is_cancelled()).unwrap_or(false) {
1075                return Err(CompliancePollError::new(
1076                    "compliance poll aborted",
1077                    CompliancePollErrorKind::Unknown,
1078                    last_value.as_ref().map(&derive_last),
1079                ));
1080            }
1081            let value = fetcher().await.map_err(|e| {
1082                CompliancePollError::new(
1083                    format!("compliance poll fetch failed: {e}"),
1084                    CompliancePollErrorKind::Unknown,
1085                    None,
1086                )
1087            })?;
1088            let decision = classify(&value);
1089            match decision {
1090                PollDecision::Done => return Ok(value),
1091                PollDecision::Failed => {
1092                    return Err(CompliancePollError::new(
1093                        "compliance poll observed terminal failure",
1094                        CompliancePollErrorKind::TerminalFailure,
1095                        Some(derive_last(&value)),
1096                    ));
1097                }
1098                PollDecision::Continue => {}
1099            }
1100            last_value = Some(value);
1101
1102            let remaining = deadline.saturating_duration_since(Instant::now());
1103            let sleep_ms = interval_ms.min(remaining.as_millis() as u64);
1104            if sleep_ms == 0 {
1105                break;
1106            }
1107            // 可取消 sleep。
1108            match &signal {
1109                Some(cancel) => {
1110                    tokio::select! {
1111                        _ = tokio::time::sleep(Duration::from_millis(sleep_ms)) => {}
1112                        _ = cancel.cancelled() => {
1113                            return Err(CompliancePollError::new(
1114                                "compliance poll aborted",
1115                                CompliancePollErrorKind::Unknown,
1116                                last_value.as_ref().map(&derive_last),
1117                            ));
1118                        }
1119                    }
1120                }
1121                None => tokio::time::sleep(Duration::from_millis(sleep_ms)).await,
1122            }
1123            interval_ms = ((interval_ms as f64 * multiplier).floor() as u64).min(max_interval);
1124        }
1125
1126        Err(CompliancePollError::new(
1127            "compliance poll timed out",
1128            CompliancePollErrorKind::Timeout,
1129            last_value.as_ref().map(&derive_last),
1130        ))
1131    }
1132}
1133
1134impl Client {
1135    /// SDK-facing compliance 域子客户端。对应 TS `client.compliance` getter。
1136    ///
1137    /// # Examples
1138    ///
1139    /// ```no_run
1140    /// # use acosmi::Client;
1141    /// # async fn demo(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
1142    /// let cc = client.compliance();
1143    /// let stats = cc.get_tsa_stats(None).await?; // TSA 只读统计视图
1144    /// # let _ = stats; Ok(()) }
1145    /// ```
1146    pub fn compliance(&self) -> ComplianceClient {
1147        ComplianceClient::new(self.clone())
1148    }
1149
1150    /// Compliance API URL 拼接。`compliance_base_url` 已配置时直接拼接;未配置时默认
1151    /// `{server_url}/admin-api` + path,匹配 Java compliance controller 的 `/compliance/...` 路径。
1152    /// 对应 TS `complianceURL`。不复用 `api_url`(后者强制 `/api/v4`)。
1153    pub fn compliance_url(&self, path: &str) -> String {
1154        let base = match self.compliance_base_url() {
1155            Some(b) => b.to_string(),
1156            None => format!("{}/admin-api", self.server_url()),
1157        };
1158        format!("{base}{path}")
1159    }
1160
1161    /// compliance 认证 JSON 请求(read=retry_on_401 / write=不重试)→ `ApiResponse<T>` 解包 → data。
1162    /// 对应 TS `ComplianceClient.executeJson`。空体成功响应(void 端点除外)→ 强 Err。
1163    pub(crate) async fn compliance_execute_json<T: DeserializeOwned>(
1164        &self,
1165        method: http::Method,
1166        path: &str,
1167        body: Option<&str>,
1168        signal: Option<CancellationToken>,
1169        retry_on_401: bool,
1170        extra_headers: &[(String, String)],
1171    ) -> Result<T> {
1172        let bytes = self
1173            .compliance_execute_bytes(method, path, body, signal, retry_on_401, extra_headers)
1174            .await?;
1175        if bytes.is_empty() {
1176            return Err(Error::other(format!("{path}: empty response body")));
1177        }
1178        let env: ApiResponse<T> = serde_json::from_slice(&bytes)
1179            .map_err(|e| Error::other(format!("{path}: decode: {e}")))?;
1180        if let Some(err) = env.business_error() {
1181            return Err(err);
1182        }
1183        Ok(env.data)
1184    }
1185
1186    /// compliance void 写端点:空体合法(返回 `()`);非空体仍走业务码检查。对应 TS
1187    /// `write<void>`(`undefined as T`)。
1188    pub(crate) async fn compliance_execute_unit(
1189        &self,
1190        method: http::Method,
1191        path: &str,
1192        body: Option<&str>,
1193        signal: Option<CancellationToken>,
1194        retry_on_401: bool,
1195        extra_headers: &[(String, String)],
1196    ) -> Result<()> {
1197        let bytes = self
1198            .compliance_execute_bytes(method, path, body, signal, retry_on_401, extra_headers)
1199            .await?;
1200        if bytes.is_empty() {
1201            return Ok(());
1202        }
1203        // 非空体:仍检查业务码(不解 data)。
1204        let env: ApiResponse<serde_json::Value> = serde_json::from_slice(&bytes)
1205            .map_err(|e| Error::other(format!("{path}: decode: {e}")))?;
1206        if let Some(err) = env.business_error() {
1207            return Err(err);
1208        }
1209        Ok(())
1210    }
1211
1212    /// compliance 请求底座:派生超时 → ensure_token → Bearer → 单次 do_request →
1213    /// 401(read)单次 force_refresh 重放 → 非 2xx 抛 HTTPError → 返回 body bytes。
1214    async fn compliance_execute_bytes(
1215        &self,
1216        method: http::Method,
1217        path: &str,
1218        body: Option<&str>,
1219        signal: Option<CancellationToken>,
1220        retry_on_401: bool,
1221        extra_headers: &[(String, String)],
1222    ) -> Result<Vec<u8>> {
1223        // 非流式 JSON 套默认超时(对应 TS withRequestTimeout(DEFAULT_API_TIMEOUT_MS))。
1224        let ctl = self.derive_timeout_token(DEFAULT_JSON_TIMEOUT_MS, signal);
1225        self.compliance_execute_bytes_inner(
1226            method,
1227            path,
1228            body,
1229            ctl.as_ref(),
1230            retry_on_401,
1231            extra_headers,
1232            false,
1233        )
1234        .await
1235    }
1236
1237    #[allow(clippy::too_many_arguments)]
1238    fn compliance_execute_bytes_inner<'a>(
1239        &'a self,
1240        method: http::Method,
1241        path: &'a str,
1242        body: Option<&'a str>,
1243        signal: Option<&'a CancellationToken>,
1244        retry_on_401: bool,
1245        extra_headers: &'a [(String, String)],
1246        retried: bool,
1247    ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>>> + Send + 'a>> {
1248        Box::pin(async move {
1249            let token = self.ensure_token(signal.cloned()).await?;
1250            let url = self.compliance_url(path);
1251
1252            let mut headers: Vec<(http::header::HeaderName, String)> = vec![
1253                (http::header::AUTHORIZATION, format!("Bearer {token}")),
1254                (http::header::ACCEPT, "application/json".to_string()),
1255            ];
1256            if body.is_some() {
1257                headers.push((http::header::CONTENT_TYPE, "application/json".to_string()));
1258            }
1259            for (k, v) in extra_headers {
1260                if let Ok(name) = http::header::HeaderName::from_bytes(k.as_bytes()) {
1261                    headers.push((name, v.clone()));
1262                }
1263            }
1264
1265            let resp = self
1266                .do_request(
1267                    method.clone(),
1268                    &url,
1269                    &headers,
1270                    body,
1271                    signal,
1272                    crate::core::transport::HttpContext::default(),
1273                )
1274                .await?;
1275
1276            if resp.status().as_u16() == 401 && retry_on_401 && !retried {
1277                drop(resp);
1278                self.force_refresh(signal.cloned())
1279                    .await
1280                    .map_err(|e| Error::other(format!("unauthorized and refresh failed: {e}")))?;
1281                return self
1282                    .compliance_execute_bytes_inner(
1283                        method,
1284                        path,
1285                        body,
1286                        signal,
1287                        retry_on_401,
1288                        extra_headers,
1289                        true,
1290                    )
1291                    .await;
1292            }
1293
1294            if !resp.status().is_success() {
1295                let status = resp.status().as_u16();
1296                let retry_after = parse_retry_after(resp.headers());
1297                let text = read_limited_text(resp.bytes_stream(), MAX_ERROR_BODY_SIZE).await?;
1298                return Err(Error::Http(parse_http_error_with_retry_after(
1299                    status,
1300                    &text,
1301                    retry_after,
1302                )));
1303            }
1304
1305            let bytes = resp
1306                .bytes()
1307                .await
1308                .map_err(|e| Error::other(format!("{path}: read body: {e}")))?;
1309            Ok(bytes.to_vec())
1310        })
1311    }
1312
1313    /// compliance 公开读:无 token 匿名(ensure_token 失败吞掉);有 token 附 Authorization;
1314    /// 401 不刷新重放。对应 TS `ComplianceClient.publicRead`。
1315    pub(crate) async fn compliance_public_read<T: DeserializeOwned>(
1316        &self,
1317        path: &str,
1318        signal: Option<CancellationToken>,
1319    ) -> Result<T> {
1320        let ctl = self.derive_timeout_token(DEFAULT_JSON_TIMEOUT_MS, signal);
1321        let token_result = self.ensure_token(ctl.clone()).await;
1322        let token = if self.uses_strict_authority() {
1323            Some(token_result?)
1324        } else {
1325            token_result.ok()
1326        };
1327        let url = self.compliance_url(path);
1328        let mut headers: Vec<(http::header::HeaderName, String)> =
1329            vec![(http::header::ACCEPT, "application/json".to_string())];
1330        if let Some(t) = token.filter(|t| !t.is_empty()) {
1331            headers.push((http::header::AUTHORIZATION, format!("Bearer {t}")));
1332        }
1333
1334        let resp = self
1335            .do_request(
1336                http::Method::GET,
1337                &url,
1338                &headers,
1339                None,
1340                ctl.as_ref(),
1341                crate::core::transport::HttpContext::default(),
1342            )
1343            .await?;
1344
1345        if !resp.status().is_success() {
1346            let status = resp.status().as_u16();
1347            let retry_after = parse_retry_after(resp.headers());
1348            let text = read_limited_text(resp.bytes_stream(), MAX_ERROR_BODY_SIZE).await?;
1349            return Err(Error::Http(parse_http_error_with_retry_after(
1350                status,
1351                &text,
1352                retry_after,
1353            )));
1354        }
1355
1356        let bytes = resp
1357            .bytes()
1358            .await
1359            .map_err(|e| Error::other(format!("{path}: read body: {e}")))?;
1360        if bytes.is_empty() {
1361            return Err(Error::other(format!("{path}: empty response body")));
1362        }
1363        let env: ApiResponse<T> = serde_json::from_slice(&bytes)
1364            .map_err(|e| Error::other(format!("{path}: decode: {e}")))?;
1365        if let Some(err) = env.business_error() {
1366            return Err(err);
1367        }
1368        Ok(env.data)
1369    }
1370}
1371
1372// =============================================================================
1373// poll 分类 + last-info 派生(对齐 TS classifyTimestamp / classifyProviderStatus / deriveLastInfo)
1374// =============================================================================
1375
1376fn classify_timestamp(status: &ComplianceTimestampVerificationStatus) -> PollDecision {
1377    match status.as_str() {
1378        ComplianceTimestampVerificationStatus::VERIFIED => PollDecision::Done,
1379        ComplianceTimestampVerificationStatus::FAILED
1380        | ComplianceTimestampVerificationStatus::LOCAL_VERIFY_FAILED => PollDecision::Failed,
1381        // PENDING / UNKNOWN / RETRYING / 未知 → continue。
1382        _ => PollDecision::Continue,
1383    }
1384}
1385
1386fn classify_provider_status(status: &ComplianceProviderRequestStatus) -> PollDecision {
1387    match status.as_str() {
1388        ComplianceProviderRequestStatus::SUCCESS => PollDecision::Done,
1389        ComplianceProviderRequestStatus::FAILED => PollDecision::Failed,
1390        // PENDING / UNKNOWN / RETRYING / 未知 → continue。
1391        _ => PollDecision::Continue,
1392    }
1393}
1394
1395/// 从最后一次轮询到的状态视图派生 ComplianceErrorInfo(best-effort 诊断载体,不伪造 code)。
1396fn derive_last_info_timestamp(t: &TimestampToken) -> ComplianceErrorInfo {
1397    let status = t.verification_status.as_str();
1398    let message = t
1399        .verification_error
1400        .clone()
1401        .filter(|s| !s.is_empty())
1402        .unwrap_or_else(|| {
1403            if status.is_empty() {
1404                "compliance poll: last observed status (no detail)".to_string()
1405            } else {
1406                format!("last polled status: {status}")
1407            }
1408        });
1409    last_info(message)
1410}
1411
1412fn derive_last_info_provider(v: &ProviderRequestStatusView) -> ComplianceErrorInfo {
1413    let status = v.status.as_str();
1414    let message = if status.is_empty() {
1415        "compliance poll: last observed status (no detail)".to_string()
1416    } else {
1417        format!("last polled status: {status}")
1418    };
1419    last_info(message)
1420}
1421
1422fn last_info(message: String) -> ComplianceErrorInfo {
1423    ComplianceErrorInfo {
1424        code: 0,
1425        message,
1426        key: ComplianceErrorKey::UnknownComplianceError,
1427        retryable: false,
1428        terminal: false,
1429        step_up_required: false,
1430    }
1431}
1432
1433// =============================================================================
1434// query / header helpers
1435// =============================================================================
1436
1437/// 把分页 + 过滤字段拼成 query string(含前导 `?`,空则返回 `""`)。对应 TS `pageQuery`。
1438struct QueryBuilder {
1439    parts: Vec<String>,
1440}
1441
1442impl QueryBuilder {
1443    fn new(page: &PageRequest) -> Self {
1444        let mut b = QueryBuilder { parts: Vec::new() };
1445        b.add("pageNo", page.page_no.map(|v| v.to_string()).as_deref());
1446        b.add("pageSize", page.page_size.map(|v| v.to_string()).as_deref());
1447        b.add("sortBy", page.sort_by.as_deref());
1448        if let Some(dir) = &page.sort_direction {
1449            let s = match dir {
1450                crate::shared::pagination::SortDirection::Asc => "asc",
1451                crate::shared::pagination::SortDirection::Desc => "desc",
1452            };
1453            b.add("sortDirection", Some(s));
1454        }
1455        b
1456    }
1457
1458    fn add(&mut self, key: &str, value: Option<&str>) {
1459        if let Some(v) = value.filter(|s| !s.is_empty()) {
1460            self.parts.push(format!("{}={}", key, urlencode(v)));
1461        }
1462    }
1463
1464    fn finish(self) -> String {
1465        qstr(&self.parts)
1466    }
1467}
1468
1469fn qstr(parts: &[String]) -> String {
1470    if parts.is_empty() {
1471        String::new()
1472    } else {
1473        format!("?{}", parts.join("&"))
1474    }
1475}
1476
1477fn idempotency_header(opts: &ComplianceWriteOptions) -> Vec<(String, String)> {
1478    match opts.idempotency_key.as_deref().filter(|s| !s.is_empty()) {
1479        Some(k) => vec![("Idempotency-Key".to_string(), k.to_string())],
1480        None => Vec::new(),
1481    }
1482}
1483
1484/// 最小 URL 编码(与 billing entitlements urlencoding 同口径)。复用 crate 内既有实现。
1485fn urlencode(s: &str) -> String {
1486    crate::billing::entitlements::urlencoding(s)
1487}
1488
1489fn parse_retry_after(headers: &http::header::HeaderMap) -> i64 {
1490    headers
1491        .get(http::header::RETRY_AFTER)
1492        .and_then(|v| v.to_str().ok())
1493        .and_then(|s| s.trim().parse::<i64>().ok())
1494        .filter(|&s| s > 0)
1495        .unwrap_or(0)
1496}
1497
1498#[cfg(test)]
1499mod tests {
1500    use super::*;
1501
1502    #[test]
1503    fn query_builder_skips_empty_and_encodes() {
1504        let page = PageRequest {
1505            page_no: Some(2),
1506            page_size: Some(20),
1507            ..Default::default()
1508        };
1509        let mut q = QueryBuilder::new(&page);
1510        q.add("status", Some("DRAFT"));
1511        q.add("createTimeStart", Some("2026-05-01 00:00:00"));
1512        q.add("nope", None);
1513        q.add("empty", Some(""));
1514        let s = q.finish();
1515        assert!(s.starts_with('?'));
1516        assert!(s.contains("pageNo=2"));
1517        assert!(s.contains("pageSize=20"));
1518        assert!(s.contains("status=DRAFT"));
1519        // 空格被编码。
1520        assert!(s.contains("createTimeStart=2026-05-01%2000%3A00%3A00"));
1521        assert!(!s.contains("nope"));
1522        assert!(!s.contains("empty"));
1523    }
1524
1525    #[test]
1526    fn query_builder_empty_is_blank() {
1527        let q = QueryBuilder::new(&PageRequest::default());
1528        assert_eq!(q.finish(), "");
1529    }
1530
1531    #[test]
1532    fn classify_timestamp_decisions() {
1533        assert_eq!(
1534            classify_timestamp(&ComplianceTimestampVerificationStatus::from("VERIFIED")),
1535            PollDecision::Done
1536        );
1537        assert_eq!(
1538            classify_timestamp(&ComplianceTimestampVerificationStatus::from("FAILED")),
1539            PollDecision::Failed
1540        );
1541        assert_eq!(
1542            classify_timestamp(&ComplianceTimestampVerificationStatus::from(
1543                "LOCAL_VERIFY_FAILED"
1544            )),
1545            PollDecision::Failed
1546        );
1547        assert_eq!(
1548            classify_timestamp(&ComplianceTimestampVerificationStatus::from("PENDING")),
1549            PollDecision::Continue
1550        );
1551        assert_eq!(
1552            classify_timestamp(&ComplianceTimestampVerificationStatus::from("WHATEVER")),
1553            PollDecision::Continue
1554        );
1555    }
1556
1557    #[test]
1558    fn classify_provider_decisions() {
1559        assert_eq!(
1560            classify_provider_status(&ComplianceProviderRequestStatus::from("SUCCESS")),
1561            PollDecision::Done
1562        );
1563        assert_eq!(
1564            classify_provider_status(&ComplianceProviderRequestStatus::from("FAILED")),
1565            PollDecision::Failed
1566        );
1567        assert_eq!(
1568            classify_provider_status(&ComplianceProviderRequestStatus::from("RETRYING")),
1569            PollDecision::Continue
1570        );
1571    }
1572
1573    #[test]
1574    fn idempotency_header_present_and_absent() {
1575        let opts = ComplianceWriteOptions {
1576            idempotency_key: Some("key-1".to_string()),
1577        };
1578        assert_eq!(
1579            idempotency_header(&opts),
1580            vec![("Idempotency-Key".to_string(), "key-1".to_string())]
1581        );
1582        assert!(idempotency_header(&ComplianceWriteOptions::default()).is_empty());
1583    }
1584
1585    // 🔴 同名字段分歧(方案 §3):provider.seal_id=String vs operation/seal-approval.seal_id=i64。
1586    #[test]
1587    fn seal_id_divergence_provider_string_vs_operation_i64() {
1588        // provider 域:seal_id 是 String。
1589        let pv: ProviderRequestStatusView = serde_json::from_str(
1590            r#"{"id":1,"status":"PENDING","terminal":false,"retryable":false,"sealId":"SEAL-ABC"}"#,
1591        )
1592        .unwrap();
1593        assert_eq!(pv.seal_id.as_deref(), Some("SEAL-ABC"));
1594
1595        // operation 域:seal_id 是 i64。
1596        let op: OperationDetail = serde_json::from_str(
1597            r#"{"id":2,"operationId":"op-1","status":"running","terminal":false,"retryable":true,"attemptCount":1,"sealId":42,"createTime":"2026-05-01T00:00:00"}"#,
1598        )
1599        .unwrap();
1600        assert_eq!(op.base.seal_id, Some(42));
1601
1602        // seal-approval 域:seal_id 是 i64。
1603        let sa: SealApproval =
1604            serde_json::from_str(r#"{"id":3,"status":"SUBMITTED","sealId":7}"#).unwrap();
1605        assert_eq!(sa.seal_id, Some(7));
1606    }
1607
1608    #[test]
1609    fn operation_detail_and_page_item_independent_round_trip() {
1610        let json = r#"{"id":5,"operationId":"op-x","status":"succeeded","terminal":true,"retryable":false,"attemptCount":3,"businessNo":"B1","createTime":"2026-05-01T01:02:03"}"#;
1611        let item: OperationPageItem = serde_json::from_str(json).unwrap();
1612        assert_eq!(item.base.operation_id, "op-x");
1613        assert_eq!(item.base.business_no.as_deref(), Some("B1"));
1614        let detail: OperationDetail = serde_json::from_str(json).unwrap();
1615        assert_eq!(detail.base.attempt_count, 3);
1616        // flatten 序列化 round-trip 不丢字段。
1617        let back = serde_json::to_value(&item).unwrap();
1618        assert_eq!(back["operationId"], "op-x");
1619        assert_eq!(back["attemptCount"], 3);
1620    }
1621
1622    #[test]
1623    fn evidence_asset_wire_round_trip() {
1624        let json = r#"{"id":1,"evidenceNo":"EV-1","assetType":"CONTRACT","name":"x","hashAlgorithm":"sha256","contentHash":"abcd","digestSource":"CLIENT","privacyLevel":"private","status":"DRAFT"}"#;
1625        let a: EvidenceAsset = serde_json::from_str(json).unwrap();
1626        assert_eq!(a.evidence_no, "EV-1");
1627        assert_eq!(a.asset_type.as_str(), "CONTRACT");
1628        assert_eq!(a.hash_algorithm.as_str(), "sha256");
1629        let back = serde_json::to_value(&a).unwrap();
1630        assert_eq!(back["evidenceNo"], "EV-1");
1631        assert_eq!(back["assetType"], "CONTRACT");
1632    }
1633}