diff --git a/T-225.-.md b/T-225.-.md new file mode 100644 index 0000000..78c42c7 --- /dev/null +++ b/T-225.-.md @@ -0,0 +1,76 @@ + +> 同步来源:[`docs/tasks/T-225.md`](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/tasks/T-225.md) · commit `afc651f75a3a` + +--- +id: T-225 +title: 冻结 Go 直连 ERP 协议与安全边界 +phase: 2 +deps: + - T-224 +status: DONE +created: 2026-07-29 +context_ref: d62a4af +work_branch: null +write_paths: + - docs/tasks/T-225.md + - docs/03-tech-stack.md + - docs/04-architecture.md + - docs/05-coding-rules.md + - docs/integrations/shunyunbao-contract.md + - docs/current-state.md + - backend-api/internal/domain/freight_source_errors.go + - backend-api/internal/usecase/freight_service.go + - backend-api/internal/platform/shunyunbao/** + - backend-api/internal/platform/erpconnector/** +--- + +## 问题 / 背景 + +T-221 至 T-224 把顺运宝协议收敛在 Python Connector,导致单机 Admin 还要维护 +Python 环境、loopback 端口和与 Go 后端相同的服务密钥。当前 `ERP_CONNECTOR_NOT_CONFIGURED` +证明这组额外进程边界会成为日常操作失败点。迁移前必须先固定 Go 实现的协议、字段和 +安全界限,不能按猜测重写私有 ERP 请求。 + +## 关联需求与交互 + +- 功能:F-011、F-012。 +- 用户故事:US-011、US-012。 +- 交互:IX-012、IX-013;本任务不新增可操作页面。 +- 架构:Go `FreightSource` 保持为货运用例的唯一上游边界,顺运宝实现移至 + `internal/platform/shunyunbao`。 + +## 方案 + +1. 以现有脱敏 fixture 和已验证脚本为依据,在 Go 中固定验证码、登录、用户校验、 + 完整单号、日期范围、分页和 `listByStock` 请求/响应契约。 +2. 只保留下游 allowlist 规范化对象;收件人、电话、详细地址、Cookie、JWT、密码、 + 验证码和原始响应不得进入数据库、日志、错误消息、fixture 或 VLM。 +3. 验证码固定由人员读取和输入。不得迁移本地 OCR 自动识别、自动重试绕过验证码或 + 对外暴露 ERP 会话。 +4. 统一来源错误为未配置、会话失效、未找到、协议异常和暂时不可用;用例层不再依赖 + Python Connector 包定义的错误变量。 +5. 本任务只建立 Go 契约、脱敏测试和接口边界,不切换运行时查询路径。 + +## 验收要点 + +- [x] Go fixture 测试固定请求 header、查询条件、分页、详情批量和 allowlist 归一化。 +- [x] 负向测试证明 PII、Cookie、JWT、账号、密码和验证码不会出现在输出或错误中。 +- [x] 第一版 Go 设计不依赖 OCR、Redis 或 Python HTTP 服务。 +- [x] 未访问线上 ERP;现有 Python Connector 仍可继续运行,货运导入行为不改变。 + +## 边界 + +- 不修改 Admin 页面、SQLite schema、采购任务生成或拼多多流程。 +- 不把 Python 请求脚本逐行翻译为业务 handler。 +- 不删除 `erp-connector/`;删除属于 T-228。 + +## 执行记录 + +- 2026-07-29:由 `d62a4af` 创建,等待 T-224 后开始。 +- 2026-07-29:开始实施;已核对现有脱敏 Python 契约和 T-224 异步导入边界,未访问线上 ERP。 +- 2026-07-29:新增 Go 协议常量、header/payload 构造、脱敏 fixture 归一化与来源中立错误; + 运行时仍装配 Python Connector,未改 Admin 页面、schema 或同步异步边界。 +- 验证:在 `backend-api/` 执行 `$env:GOTOOLCHAIN='local'; go test ./...; go test -race ./...;` + `go vet ./...; go build ./cmd/api; go build ./cmd/migrate; go build ./cmd/authctl`,全部通过; + 未访问线上 ERP。 +- 未验证项:真实顺运宝登录和查询有意留给 T-226/T-227,并需要人员配置凭证和完成验证码。