88 lines
4.5 KiB
Markdown
88 lines
4.5 KiB
Markdown
---
|
||
id: T-230
|
||
title: OCR 自动登录顺运宝并移除人工连接页
|
||
phase: 2
|
||
deps:
|
||
- T-229
|
||
status: DONE
|
||
created: 2026-07-29
|
||
context_ref: f0fbdba
|
||
work_branch: null
|
||
write_paths:
|
||
- 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、路由、集成和安全文档。
|
||
|
||
## 验收要点
|
||
|
||
- [x] `.env.example` 包含本机 OCR URL，环境变量覆盖 `.env`；无效 URL 不启动，真实 OCR
|
||
endpoint 不进入 Git、日志、浏览器或数据库。
|
||
- [x] OCR client 的 multipart 字段、超时、重定向拒绝、上限、纯文本/JSON 结果与敏感错误均有
|
||
fixture 测试。
|
||
- [x] 未认证的按单号导入先完成 OCR 登录再创建同步；OCR 失败不创建同步且 Admin 返回可关闭
|
||
`OCR_SERVICE_INVALID` 弹窗并保留表单；已认证会话不重复 OCR。
|
||
- [x] `/erp`、人工验证码图片/文本和 ERP connection JSON 路由不再暴露；API 不返回验证码、
|
||
Cookie、账号、密码或 OCR 原文。
|
||
- [x] `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 路由移除；测试与构建命令见实现提交。
|