1

T-236

ila edited this page 2026-08-07 16:36:49 +08:00

Table of Contents

• 问题 / 背景
• 方案
• 验收要点
• 边界
• 执行记录

同步来源：docs/tasks/T-236.md · commit afc651f75a3a

---

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、账号密码或登录响应正文。

验收要点

• 前 6 次验证码错误、第 7 次成功时认证成功，验证码获取、OCR 和登录均各执行 7 次。
• 连续 7 次验证码错误后返回稳定的 ERP_LOGIN_REJECTED，不执行第 8 次。
• 非验证码登录拒绝、OCR/网络/协议错误不触发重试。
• 重试期间每次使用新验证码，且整个认证不突破 20 秒或调用方 deadline。
• diagnostics 可定位尝试次数，但不泄露验证码、凭证、Cookie、token 或响应正文。
• 标准 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 构建均通过。