系统架构

# 行为验证码 - 系统架构 本文档介绍 Vastark 行为验证码的完整集成流程。 ```mermaid sequenceDiagram autonumber participant U as 终端用户浏览器 participant JS as 调用方前端JS-SDK participant B as 调用方业务后端 participant S as 本开放平台后端(/sdk/v1) participant Q as 计费与风控(异步) Note over JS,B: 初始化阶段:调用方配置全局故障策略 严格阻断(fail-close) / 降级放行(fail-open) JS->>B: 1) 请求生成验证码(业务接口) B->>S: 2) POST /saas/sdk/v1/recaptcha/secure/generate + X-API-Key + site_id + X-Log-Id S->>Q: 3) 记录 generate 计费事件(成功计费) S-->>B: 4) 返回 captcha_id + verify_ticket(短效) + ticket_expire_at + x_log_id B-->>JS: 5) 返回 challenge(含 verify_ticket) JS->>S: 6) POST /saas/sdk/v1/recaptcha/secure/click + captcha_id + verify_ticket + 坐标 S-->>JS: 7) click结果(用于前端交互提示,不做最终准入) JS->>B: 8) 提交登录/注册表单 + captcha_id + clicks + verify_ticket B->>S: 9) POST /saas/sdk/v1/recaptcha/secure/verify + X-API-Key + captcha_id + clicks + verify_ticket + X-Log-Id S->>Q: 10) 记录 verify 计费事件(成功/失败都计费) S-->>B: 11) 返回 verify_result + verify_receipt(sig) + x_log_id B-->>JS: 12) 业务最终响应(登录通过/拒绝) alt 本开放平台后端不可用 且 严格阻断(fail-close) S--xB: 返回服务不可用 B-->>JS: 阻断业务流程(不可登录) else 本开放平台后端不可用 且 降级放行(fail-open) S--xB: 返回服务不可用 B-->>JS: 业务降级放行(等价未接入验证码) end ``` ## 核心流程说明 | 步骤 | 说明 | |------|------| | 初始化 | 调用方配置全局故障策略:**严格阻断(fail-close)** 或 **降级放行(fail-open)** | | Generate | 调用方后端使用 API-Key 请求生成验证码,返回 `captcha_id` 和短效 `verify_ticket` | | Click | 前端 SDK 直连开放平台提交点击坐标,结果仅用于前端交互提示 | | Verify | 调用方后端使用 API-Key + `verify_ticket` 进行最终验证,以此次结果为准 | | 故障处理 | 平台不可用时,根据策略决定阻断业务流程或降级放行 |