diff --git a/T-236.-.md b/T-236.-.md new file mode 100644 index 0000000..d6f1c21 --- /dev/null +++ b/T-236.-.md @@ -0,0 +1,62 @@ + +> 同步来源：[`docs/tasks/T-236.md`](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/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、账号密码或登录响应正文。 + +## 验收要点 + +- [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 构建均通过。