cmroubao/docs/tasks/T-225.md

id, title, phase, deps, status, created, context_ref, work_branch, write_paths

id	title	phase	deps	status	created	context_ref	work_branch	write_paths
T-225	冻结 Go 直连 ERP 协议与安全边界	2	T-224	DONE	2026-07-29	d62a4af	null	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 契约、脱敏测试和接口边界，不切换运行时查询路径。

验收要点

• Go fixture 测试固定请求 header、查询条件、分页、详情批量和 allowlist 归一化。
• 负向测试证明 PII、Cookie、JWT、账号、密码和验证码不会出现在输出或错误中。
• 第一版 Go 设计不依赖 OCR、Redis 或 Python HTTP 服务。
• 未访问线上 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，并需要人员配置凭证和完成验证码。