From 1f740a345e937dd2ee0b824a7b0c24257fe9dcb4 Mon Sep 17 00:00:00 2001 From: ila Date: Fri, 7 Aug 2026 16:36:45 +0800 Subject: [PATCH] docs: import wiki at afc651f75a3a --- T-230.-.md | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 T-230.-.md diff --git a/T-230.-.md b/T-230.-.md new file mode 100644 index 0000000..8cdbb37 --- /dev/null +++ b/T-230.-.md @@ -0,0 +1,90 @@ + +> 同步来源：[`docs/tasks/T-230.md`](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/tasks/T-230.md) · commit `afc651f75a3a` + +--- +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=`；请求/响应 + 均有超时和大小上限，不记录验证码、图片或 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 路由移除；测试与构建命令见实现提交。