60 lines
2.8 KiB
Markdown
60 lines
2.8 KiB
Markdown
---
|
|
id: T-236
|
|
title: 顺运宝验证码错误有限重试
|
|
phase: 2
|
|
deps:
|
|
- T-235
|
|
status: DONE
|
|
created: 2026-07-29
|
|
context_ref: 81f75cc
|
|
work_branch: null
|
|
write_paths:
|
|
- docs/tasks/T-236.md
|
|
- docs/api.md
|
|
- docs/current-state.md
|
|
- docs/integrations/shunyunbao-contract.md
|
|
- backend-api/internal/platform/shunyunbao/**
|
|
---
|
|
|
|
## 问题 / 背景
|
|
|
|
顺运宝验证码由 OCR 自动识别，单次识别可能因字符相似、图片噪声或验证码刷新而被 ERP 明确
|
|
拒绝。当前实现只尝试一次；ERP 返回“图片验证码不正确”后，货运导入立即失败，采购人员只能
|
|
重新提交整个导入操作。
|
|
|
|
## 方案
|
|
|
|
1. 首次登录被 ERP 明确判定为验证码错误后，最多再重试 6 次，即单次认证流程最多执行 7 次
|
|
登录尝试。
|
|
2. 每次重试都重新获取验证码图片、重新调用 OCR，并使用新验证码发起登录；不复用已被拒绝
|
|
的验证码或识别文本。
|
|
3. 仅识别 ERP `status=false` 且消息精确为已知验证码错误的登录响应。账号密码错误、OCR
|
|
服务异常、网络错误、协议错误和其他登录拒绝均立即停止，不盲目重试。
|
|
4. 整个认证流程受 20 秒总预算约束；先达到总预算或调用方 deadline 时立即停止，即使尚未
|
|
用完 6 次重试。
|
|
5. 受控 ERP diagnostics 只记录尝试序号和脱敏结果，不记录验证码图片、ticket、Cookie、
|
|
token、账号密码或登录响应正文。
|
|
|
|
## 验收要点
|
|
|
|
- [x] 前 6 次验证码错误、第 7 次成功时认证成功，验证码获取、OCR 和登录均各执行 7 次。
|
|
- [x] 连续 7 次验证码错误后返回稳定的 `ERP_LOGIN_REJECTED`，不执行第 8 次。
|
|
- [x] 非验证码登录拒绝、OCR/网络/协议错误不触发重试。
|
|
- [x] 重试期间每次使用新验证码，且整个认证不突破 20 秒或调用方 deadline。
|
|
- [x] diagnostics 可定位尝试次数，但不泄露验证码、凭证、Cookie、token 或响应正文。
|
|
- [x] 标准 Go 测试、race、vet 和三个入口构建通过。
|
|
|
|
## 边界
|
|
|
|
- 不增加 Redis 或其他 ERP 会话持久化；成功会话仍按 T-235 仅保存在当前 Go 进程内存中。
|
|
- 不修改 OCR endpoint、ERP 账号密码来源、货运字段、数据库或采购流程。
|
|
- 不在自动测试中访问真实 ERP；使用脱敏本机 fixture 验证重试协议。
|
|
|
|
## 执行记录
|
|
|
|
- 2026-07-29：创建任务。确认“重试 6 次”定义为首次失败后额外重试 6 次，最多 7 次登录；
|
|
仅对 ERP 明确返回的验证码错误执行全新验证码/OCR 尝试，并设置 20 秒总预算。
|
|
- 2026-07-29：实现精确验证码拒绝分类和受锁有限认证循环。脱敏 fixture 覆盖第 7 次成功、
|
|
连续 7 次耗尽、其他登录拒绝不重试和诊断尝试序号；标准 Go 测试、race、vet 及
|
|
api/migrate/authctl 构建均通过。
|