cmroubao/docs/tasks/T-227.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-227	Go 直连顺运宝查询接入货运同步	2	T-226	TODO	2026-07-29	d62a4af	null	docs/tasks/T-227.md docs/04-architecture.md docs/api.md docs/current-state.md backend-api/cmd/api/** backend-api/internal/platform/shunyunbao/** backend-api/internal/usecase/** backend-api/internal/transport/httpapi/** backend-api/internal/transport/webui/** backend-api/internal/config/**

问题 / 背景

T-226 能在 Go 后端建立受控 ERP 会话，但货运同步仍通过 Python Connector。需要将 FreightSource 的运行时实现替换为 Go 直连客户端，同时完整保留 T-222 至 T-224 的 异步同步、幂等、日期窗口、水位、revision 与采购需求语义。

关联需求与交互

• 功能：F-011、F-012。
• 用户故事：US-011、US-012。
• 交互：IX-012、IX-013；现有“按完整单号”“按创建日期”“同步至现在”入口不变。
• 架构：FreightService 后台同步继续只依赖 FreightSource，Go 顺运宝实现直接调用 外部 HTTPS，不经 loopback HTTP 或共享服务密钥。

方案

1. 将 Go 顺运宝 source 注入 API 进程；查询前验证会话，按完整单号或 Asia/Shanghai 日期范围执行有界分页和详情批量读取。
2. 保留既有同步记录和异步执行：浏览器只创建同步 run，后台工作执行外部请求，进程 中断后的 RUNNING run 仍按现有规则恢复为稳定失败。
3. 复用 T-225 allowlist 归一化；响应不完整、超限、重复外部身份冲突或会话失效均整批 失败，不保存半批数据、不推进水位。
4. 单 ERP 账号同步使用有界串行执行，避免登录/验证码与查询竞争；不增加无界 goroutine 或系统级队列。
5. 真实验证只在人员已配置凭证并完成验证码登录后按单号执行一次；测试和开发使用 httptest 伪 ERP。

验收要点

• 完整单号、日期范围、重叠水位、分页去重、详情多商品、失败不推进水位均有 Go 集成测试。
• Admin 输入单号后创建异步 run，并由 Go source 直接得到相同规范化货运/明细结果。
• 缺会话显示 ERP_SESSION_REQUIRED；不再出现 Connector URL/API Key 相关错误。
• 真实受控单号 smoke 可选且不记录订单内容；未具备凭证时明确标记未运行。
• go test ./...、go test -race ./...、go vet ./... 通过。

边界

• 不改变商品采购状态判定、参考图上传和采购任务生成。
• 不将 ERP 原始图片引用解释为可访问 URL。
• 不删除 Python Connector；切换清理属于 T-228。

执行记录

• 2026-07-29：由 T-226 依赖创建，等待 Admin 会话能力完成。