---
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，并需要人员配置凭证和完成验证码。