---
id: T-234
title: 在受控 ERP 诊断模式输出 OCR 验证码文本
phase: 2
deps:
  - T-233
status: DONE
created: 2026-07-29
context_ref: 1e703ef
work_branch: null
write_paths:
  - docs/tasks/T-234.md
  - docs/api.md
  - docs/current-state.md
  - backend-api/internal/platform/shunyunbao/**
---

## 问题 / 背景

现场受控 ERP 日志显示登录 JSON 为 `status=false` 且 `msg=图片验证码不正确`。这表明 ERP
endpoint 可达且已处理登录请求，当前无法确认本机 OCR 为该次验证码返回了什么文本。T-233
有意不记录验证码/OCR 文本，导致无法区分 OCR 识别错误、大小写/字符集规则差异或 ERP 验证码
协议变化。

## 方案

1. 仅在已有 `CMROUBAO_ERP_DEBUG_LOG=true` 或 `start-backend.bat --erp-debug` 的受控模式中，
   在 OCR 成功返回后、登录前记录本次实际提交的有效验证码文本和长度。
2. 无效、空白、过长或含控制字符的 OCR 输出只记录 `ocr_result class=invalid`，绝不记录原文；
   OCR client error 只记录 `class=failed`，不输出响应 body。
3. 保持验证码图片、ticket、Cookie、登录 payload、账号密码及常规生产日志不可见；调试开关默认
   关闭，诊断结束后关闭。
4. 固定 session 测试，断言有效 OCR 文本仅在 diagnostics 开启时输出，非法文本、图片和凭证
   均不泄露。

## 验收要点

- [x] 当前验证码错误场景可在 ERP 登录请求前看到 `erp_ocr_result value=... length=...`。
- [x] diagnostics 关闭时不记录 OCR 文本；无效/OCR 失败不记录其原始输出或错误正文。
- [x] 验证码图片、ticket、Cookie、账号密码和登录 payload 不进入日志。
- [x] 标准 Go 验证和入口构建通过。

## 边界

- 不修改 OCR endpoint、验证码请求、ERP 登录协议、重试或同步 schema。
- OCR 文本仅为短时人工诊断用途，不持久化、不发给浏览器/API；不得用于绕过验证码或自动重试。

## 执行记录

- 2026-07-29：创建任务。现场 ERP 返回“图片验证码不正确”，因此进入受控 OCR 文本观测；
  当前证据不足以断言是 OCR 准确率、验证码规则还是外部 ERP 协议变化。
- 2026-07-29：在有效 OCR 识别后、ERP 登录前增加仅 diagnostics 可见的转义文本/长度日志；
  OCR failed/invalid 只记录 class。固定测试覆盖图片、凭证、无效文本和 OCR error 不泄露；
  标准 Go 测试、race、vet 及 api/migrate/authctl 构建均通过。