fix(t236): retry rejected ERP captchas

2026-07-29 11:54:06 +08:00
parent d7ab970f5a
commit cf83fb50e4
6 changed files with 237 additions and 23 deletions
@@ -198,7 +198,7 @@ T-203 成功返回 `201`。使用相同 `Idempotency-Key` 和相同图片内容
 不得返回 receiver、receiverTel、receiverAddr、Cookie、JWT、ERP 用户资料或完整原始
 对象。多商品必须全部保留；缺失详情返回协议错误，不允许部分成功。

-### Go ERP 会话（T-230）
+### Go ERP 会话（T-230、T-236）

 `/erp`、`/erp/captcha`、`/erp/login` 和 `/api/v1/erp-session*` 不再暴露。创建货运同步
 前，单一 API 进程在未认证时以同一 Cookie jar 获取验证码、调用受控 OCR、登录并校验用户。
@@ -207,6 +207,11 @@ T-203 成功返回 `201`。使用相同 `Idempotency-Key` 和相同图片内容
 `GET /am/user/get?id=<user.id>`；返回身份必须一致。只有 HTTP 401/403 或 ERP code `-2` 被视为
 会话失效，其他 `status=false` 返回 `ERP_RESPONSE_INVALID`。

+ERP 登录明确返回 `status=false`、`msg=图片验证码不正确` 时，首次失败后最多额外重试 6 次，
+单次认证最多登录 7 次；每次都重新获取验证码图片并重新调用 OCR。认证总预算为 20 秒，调用方
+deadline 更短时以调用方为准。账号密码错误、其他登录拒绝、OCR 异常、网络错误和协议错误均不
+重试；次数耗尽返回 `ERP_LOGIN_REJECTED`。
+
 ERP 配置来源：

 - `CMROUBAO_SHUNYUNBAO_URL`：默认 `https://www.shunyunbaoerp.com`；只接受无路径、
@@ -230,7 +235,8 @@ ERP 配置来源：
  `false` 并重启 API。Windows 可使用根目录 `start-backend.bat --erp-debug` 仅为本次 API
 进程覆盖开启；也可与 `--migrate` 组合。该模式额外在 ERP 登录前输出单行
 `erp_ocr_result value="..." length=...`，值只限本次有效 OCR 结果；OCR 失败或无效时只输出
- `class=failed` 或 `class=invalid`，不输出原文。
+ `class=failed` 或 `class=invalid`，不输出原文。每次登录另输出
+ `erp_login_attempt attempt=<n> max_attempts=7 result=<固定分类>`，不包含凭证或 ERP 原始响应。

 会话不写 SQLite 或 Redis；服务重启后在下一次货运导入前重新经 OCR 建立会话。

@@ -5,7 +5,7 @@
 ## 当前快照

 - 日期：2026-07-29
- 阶段：T-236 已规划顺运宝验证码错误有限重试，待实现
+- 阶段：T-236 已完成顺运宝验证码错误有限重试
 - Git：当前分支为 `main`；T-001 至 T-004、T-101 至 T-104、T-201 至 T-219
  均按文档提交、实现提交的顺序纳入历史
 - 生产代码：`android-buyer/` 已接入 Roubao Android 源码
@@ -25,7 +25,7 @@
  文字并建立内存会话，人工 `/erp` 模块已删除。T-227 已将其作为 `FreightSource`，
  查询先校验会话、再执行有界分页/详情
  批量并返回 allowlist；T-228 已删除旧 Python Connector、loopback 端口和共享 API Key；
-  T-236 计划在 ERP 明确拒绝验证码时额外重试 6 次，每次重新取图和 OCR，单次认证最多
+  T-236 在 ERP 明确拒绝验证码时额外重试 6 次，每次重新取图和 OCR，单次认证最多
  7 次登录并受 20 秒总预算限制；不对账号密码、OCR、网络或协议错误重试。未访问真实 ERP。
 - ERP 增量同步：v14 支持 Asia/Shanghai 创建日期闭区间和“同步至现在”，source 单窗
  最多 7 天，后端对较长水位范围切窗并从成功水位前 10 分钟所在自然日回看。
@@ -39,11 +39,14 @@ T-225 至 T-227 在 `backend-api/internal/platform/shunyunbao` 用脱敏 fixture
 - 所有结果必须经 Go allowlist 归一化；fixture 专门含收件信息、Cookie/JWT 标记值，
  测试断言它们不会出现在输出或错误里。

-Go 直连的验证码、登录、Cookie jar 和查询 source 都在 API 进程内。T-230 在未认证时仅可将
-验证码图片一次提交给受控本机/HTTPS OCR endpoint，结果只用于当前登录请求；不得写入 Redis、
-SQLite、普通日志或浏览器，也不得轮询或重试。T-234 仅允许显式 diagnostics 进程短时输出有效
-OCR 文本；T-235 仅在受锁内存中保存已核验 user id/username，不保存登录 token。HTTP 401/403
-或 ERP code `-2` 才代表会话失效；其他 `status=false` 是协议错误。真实线上请求不属于自动化测试。
+Go 直连的验证码、登录、Cookie jar 和查询 source 都在 API 进程内。T-230 在未认证时只可将
+验证码图片提交给受控本机/HTTPS OCR endpoint，结果只用于当前登录请求；不得写入 Redis、
+SQLite、普通日志或浏览器。T-236 仅在 ERP 登录精确返回“图片验证码不正确”时，在首次失败后
+额外重试最多 6 次；每次重新获取验证码和调用 OCR，最多 7 次登录且认证总预算为 20 秒。其他
+登录拒绝、OCR、网络或协议错误不重试。T-234 仅允许显式 diagnostics 进程短时输出有效 OCR
+文本和固定登录尝试分类；T-235 仅在受锁内存中保存已核验 user id/username，不保存登录 token。
+HTTP 401/403 或 ERP code `-2` 才代表会话失效；其他非登录接口 `status=false` 是协议错误。
+真实线上请求不属于自动化测试。

 ## 身份和规范字段

@@ -4,7 +4,7 @@ title: 顺运宝验证码错误有限重试
 phase: 2
 deps:
  - T-235
-status: PLANNED
+status: DONE
 created: 2026-07-29
 context_ref: 81f75cc
 work_branch: null
@@ -37,12 +37,12 @@ write_paths:

 ## 验收要点

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

 ## 边界

@@ -54,3 +54,6 @@ write_paths:

 - 2026-07-29：创建任务。确认“重试 6 次”定义为首次失败后额外重试 6 次，最多 7 次登录；
  仅对 ERP 明确返回的验证码错误执行全新验证码/OCR 尝试，并设置 20 秒总预算。
+- 2026-07-29：实现精确验证码拒绝分类和受锁有限认证循环。脱敏 fixture 覆盖第 7 次成功、
+  连续 7 次耗尽、其他登录拒绝不重试和诊断尝试序号；标准 Go 测试、race、vet 及
+  api/migrate/authctl 构建均通过。