From d7ab970f5a5cec84ce5bb5c6ee54bbc12cb67264 Mon Sep 17 00:00:00 2001
From: QiuSW <105186638@qq.com>
Date: Wed, 29 Jul 2026 11:50:54 +0800
Subject: [PATCH] docs(t236): plan bounded captcha retries

---
 docs/current-state.md |  5 ++--
 docs/tasks/T-236.md   | 56 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+), 2 deletions(-)
 create mode 100644 docs/tasks/T-236.md

diff --git a/docs/current-state.md b/docs/current-state.md
index 104c53d..0ff3d1b 100644
--- a/docs/current-state.md
+++ b/docs/current-state.md
@@ -5,7 +5,7 @@
 ## 当前快照
 
 - 日期：2026-07-29
-- 阶段：T-235 已修复顺运宝登录后用户会话校验协议
+- 阶段：T-236 已规划顺运宝验证码错误有限重试，待实现
 - Git：当前分支为 `main`；T-001 至 T-004、T-101 至 T-104、T-201 至 T-219
   均按文档提交、实现提交的顺序纳入历史
 - 生产代码：`android-buyer/` 已接入 Roubao Android 源码
@@ -25,7 +25,8 @@
   文字并建立内存会话，人工 `/erp` 模块已删除。T-227 已将其作为 `FreightSource`，
   查询先校验会话、再执行有界分页/详情
   批量并返回 allowlist；T-228 已删除旧 Python Connector、loopback 端口和共享 API Key；
-  未访问真实 ERP。
+  T-236 计划在 ERP 明确拒绝验证码时额外重试 6 次，每次重新取图和 OCR，单次认证最多
+  7 次登录并受 20 秒总预算限制；不对账号密码、OCR、网络或协议错误重试。未访问真实 ERP。
 - ERP 增量同步：v14 支持 Asia/Shanghai 创建日期闭区间和“同步至现在”，source 单窗
   最多 7 天，后端对较长水位范围切窗并从成功水位前 10 分钟所在自然日回看。
   货运落库、同步成功和水位推进同事务完成；失败与较旧范围成功不推进水位。Admin
diff --git a/docs/tasks/T-236.md b/docs/tasks/T-236.md
new file mode 100644
index 0000000..b4a9a71
--- /dev/null
+++ b/docs/tasks/T-236.md
@@ -0,0 +1,56 @@
+---
+id: T-236
+title: 顺运宝验证码错误有限重试
+phase: 2
+deps:
+  - T-235
+status: PLANNED
+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 秒总预算。