系统架构
# 行为验证码 - 系统架构
本文档介绍 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` 进行最终验证,以此次结果为准 |
| 故障处理 | 平台不可用时,根据策略决定阻断业务流程或降级放行 |