cmroubao/docs/tasks/T-230.md

id, title, phase, deps, status, created, context_ref, work_branch, write_paths

id	title	phase	deps	status	created	context_ref	work_branch	write_paths
T-230	OCR 自动登录顺运宝并移除人工连接页	2	T-229	DONE	2026-07-29	f0fbdba	null	docs/tasks/T-230.md docs/api.md docs/current-state.md docs/routes.md docs/integrations/shunyunbao-contract.md docs/05-coding-rules.md backend-api/.env.example backend-api/README.md backend-api/cmd/api/** backend-api/internal/config/** backend-api/internal/domain/** backend-api/internal/platform/ocrapi/** backend-api/internal/platform/shunyunbao/** backend-api/internal/transport/httpapi/** backend-api/internal/transport/webui/** backend-api/internal/usecase/**

问题 / 背景

目前顺运宝必须先访问 /erp 获取验证码并人工输入，货运按单号导入会在缺少会话时异步失败。 用户已提供本机 OCR endpoint：POST http://127.0.0.1:8000/ocr，multipart 字段名为 file。 需要将 OCR URL 放入本地 .env，在创建货运同步前验证 OCR、读取验证码并登录；OCR 不可用时 必须在 Admin 导入页直接提示，不能先创建必然失败的同步记录。

关联需求与交互

• 功能：F-011、F-012、F-013。
• 用户故事：US-011、US-012。
• 交互：移除 /erp 人工连接页、导航项和 JSON 接口。管理员在 /freight/import 提交完整 单号时，后端先检查/建立 ERP 会话；OCR 连接或响应无效时返回导入页的可关闭错误弹窗，保留 已填单号和提交标识且不创建同步。
• 架构：验证码图片、OCR 请求和识别文字只停留在 API 进程内；SessionManager 保持单账号串行 Cookie jar，货运 usecase 仍只依赖 FreightSource。

方案

1. .env 增加 CMROUBAO_OCR_API_URL，仅允许完整 endpoint：HTTPS，或仅本机 loopback 的 HTTP；禁止 userinfo、query、fragment、重定向和任意任务输入 URL。进程环境 变量优先，缺失时 OCR 视为未配置。
2. 新建 Go OCR client，按给定 curl 发送一次 multipart/form-data; file=<captcha>；请求/响应 均有超时和大小上限，不记录验证码、图片或 OCR 原始响应。受支持响应是非空纯文本，或 JSON 字符串字段 text、result、data；其他格式为无效响应。
3. SessionManager 在没有有效会话时串行执行“获取 ERP 验证码 -> OCR -> 登录 -> 用户校验”。 不显示验证码图片、不持久化验证码/OCR 文本，不做猜测、重试、轮询或后台定时登录。
4. CreateFreightSync 在完整单号（以及日期导入）入队前执行会话预检。OCR 不可达、HTTP 非 成功、超时、过大或格式无效映射为稳定 OCR_SERVICE_INVALID；Admin 表单直接渲染该错误 弹窗。ERP 登录拒绝和协议错误保持其既有匿名错误语义。
5. 删除 /erp、/erp/captcha、/erp/login 和 /api/v1/erp-session* 路由、模板、导航及 人工验证码 transport 类型；更新 API、路由、集成和安全文档。

验收要点

• .env.example 包含本机 OCR URL，环境变量覆盖 .env；无效 URL 不启动，真实 OCR endpoint 不进入 Git、日志、浏览器或数据库。
• OCR client 的 multipart 字段、超时、重定向拒绝、上限、纯文本/JSON 结果与敏感错误均有 fixture 测试。
• 未认证的按单号导入先完成 OCR 登录再创建同步；OCR 失败不创建同步且 Admin 返回可关闭 OCR_SERVICE_INVALID 弹窗并保留表单；已认证会话不重复 OCR。
• /erp、人工验证码图片/文本和 ERP connection JSON 路由不再暴露；API 不返回验证码、 Cookie、账号、密码或 OCR 原文。
• go test ./...、go test -race ./...、go vet ./... 和 API/migrate/authctl 构建通过。

边界

• 不修改 ERP 协议字段、货运 SQLite schema、同步幂等语义、采购任务或 Android App。
• 不持久化 OCR 结果、不增加多个 OCR provider、轮询健康检查、自动重试或远程任意 URL。
• 不在真实 ERP、真实账号或真实验证码上执行自动化测试；线上使用前由部署者确认 ERP 与 OCR 服务的授权、可用性和数据处理边界。

执行记录

• 2026-07-29：创建任务；本机发现 127.0.0.1:8000 正在监听，但缺少可安全复现的验证码 fixture，线上 OCR/ERP 验证留给部署 smoke。
• 2026-07-29：实现受控 OCR multipart client、ERP 自动会话预检、导入失败弹窗和公开人工 ERP 路由移除；测试与构建命令见实现提交。