From 8c84b81d487f0579f08fe6354dc5b554f785cdf9 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Wed, 29 Jul 2026 10:35:52 +0800 Subject: [PATCH] docs(t230): plan OCR ERP login --- docs/current-state.md | 6 +-- docs/tasks/T-230.md | 85 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+), 3 deletions(-) create mode 100644 docs/tasks/T-230.md diff --git a/docs/current-state.md b/docs/current-state.md index 86d852f..059fdbb 100644 --- a/docs/current-state.md +++ b/docs/current-state.md @@ -5,7 +5,7 @@ ## 当前快照 - 日期：2026-07-29 -- 阶段：T-229 已完成受控 `backend-api/.env` ERP 凭证加载；随后进行人工验证码登录 smoke +- 阶段：T-230 待将本机 OCR 接入 ERP 自动登录并移除人工 `/erp` 连接模块 - Git：当前分支为 `main`；T-001 至 T-004、T-101 至 T-104、T-201 至 T-219 均按文档提交、实现提交的顺序纳入历史 - 生产代码：`android-buyer/` 已接入 Roubao Android 源码 @@ -201,8 +201,8 @@ - 已完成：另含 T-220 至 T-229 ERP 契约、货运存储、采购需求生成、日期增量同步、Go 直连协议、人工验证码会话、直连 `FreightSource`、旧 Connector 清理和受控本地凭证加载。 - 进行中：无。 -- 下一步：确认开放 API、数据使用权限，并由人员在 `/erp` 完成验证码登录后以受控单号 - 执行一次不记录订单内容的 smoke。 +- 下一步：T-230 在按单号导入前受控调用本机 OCR 并建立 ERP 会话；完成后确认开放 API、 + OCR/ERP 数据使用权限，并以受控单号执行一次不记录订单内容的 smoke。 ## 当前可运行内容 diff --git a/docs/tasks/T-230.md b/docs/tasks/T-230.md new file mode 100644 index 0000000..143584f --- /dev/null +++ b/docs/tasks/T-230.md @@ -0,0 +1,85 @@ +--- +id: T-230 +title: OCR 自动登录顺运宝并移除人工连接页 +phase: 2 +deps: + - T-229 +status: TODO +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、路由、集成和安全文档。 + +## 验收要点 + +- [ ] `.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。