2026-07-29 09:09:40 +08:00
|
|
|
---
|
|
|
|
|
id: T-225
|
|
|
|
|
title: 冻结 Go 直连 ERP 协议与安全边界
|
|
|
|
|
phase: 2
|
|
|
|
|
deps:
|
|
|
|
|
- T-224
|
2026-07-29 09:21:32 +08:00
|
|
|
status: DONE
|
2026-07-29 09:09:40 +08:00
|
|
|
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
|
2026-07-29 09:21:32 +08:00
|
|
|
- docs/current-state.md
|
|
|
|
|
- backend-api/internal/domain/freight_source_errors.go
|
|
|
|
|
- backend-api/internal/usecase/freight_service.go
|
2026-07-29 09:09:40 +08:00
|
|
|
- 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 契约、脱敏测试和接口边界，不切换运行时查询路径。
|
|
|
|
|
|
|
|
|
|
## 验收要点
|
|
|
|
|
|
2026-07-29 09:21:32 +08:00
|
|
|
- [x] Go fixture 测试固定请求 header、查询条件、分页、详情批量和 allowlist 归一化。
|
|
|
|
|
- [x] 负向测试证明 PII、Cookie、JWT、账号、密码和验证码不会出现在输出或错误中。
|
|
|
|
|
- [x] 第一版 Go 设计不依赖 OCR、Redis 或 Python HTTP 服务。
|
|
|
|
|
- [x] 未访问线上 ERP；现有 Python Connector 仍可继续运行，货运导入行为不改变。
|
2026-07-29 09:09:40 +08:00
|
|
|
|
|
|
|
|
## 边界
|
|
|
|
|
|
|
|
|
|
- 不修改 Admin 页面、SQLite schema、采购任务生成或拼多多流程。
|
|
|
|
|
- 不把 Python 请求脚本逐行翻译为业务 handler。
|
|
|
|
|
- 不删除 `erp-connector/`；删除属于 T-228。
|
|
|
|
|
|
|
|
|
|
## 执行记录
|
|
|
|
|
|
|
|
|
|
- 2026-07-29：由 `d62a4af` 创建，等待 T-224 后开始。
|
2026-07-29 09:21:32 +08:00
|
|
|
- 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，并需要人员配置凭证和完成验证码。
|
