cmroubao/docs/tasks/T-221.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-221	顺运宝精确单号 Connector	2	T-220	TODO	2026-07-28	78dc595	null	erp-connector/** scripts/start-erp-connector.bat docs/integrations/** docs/tasks/T-221.md docs/current-state.md

问题 / 背景

Go 后端不应在 Gin 请求里启动 Python，也不应保存 ERP 密码、Cookie 或 JWT。需要把 已验证的 Python 客户端收敛为仅监听 loopback、带服务密钥的内部 Connector。首版只 支持完整单号，先验证稳定读取和规范化，不提前做定时同步。

关联需求与交互

• 功能：F-011
• 用户故事：US-011
• 交互：IX-012
• 架构/API：ERP Connector 内部 API

方案

1. 采用 Python 3.10+、requests 和可选 FastAPI/uvicorn，复用本机已验证客户端结构； 不复制 HAR、真实响应或凭证。
2. Connector 默认 127.0.0.1，除健康检查外所有接口要求至少 32 字节服务密钥并 常量时间比较；ERP 密码仅从进程环境读取。
3. 保留人工/受控验证码登录，不承诺无人值守 OCR。读取型列表/详情请求才允许有界 重试；登录不自动重放。
4. POST /v1/freight/query 接受完整单号，查询 listTotal/list 和 listByStock， 按 stock id 去重并保留所有 details[]。
5. 响应经过规范化和 PII 最小化，只返回后续货运模块所需字段；错误不包含服务端 body、Cookie、JWT、账号、收件人、电话或地址。

验收要点

• 伪 ERP 响应覆盖验证码约束、登录、分页、重试、安全上限、多货运头和多商品。
• 精确单号响应具有稳定 schema，商品不被 dict 覆盖或错误关联。
• API Key 缺失/错误、未登录、未找到、ERP 超时和协议异常返回稳定状态。
• pytest/编译和无网络单测通过；启动脚本不包含秘密。

边界

• 不支持日期区间查询，属于 T-224。
• 不把 Connector 暴露到局域网，不提供 ERP 密码 Web 表单。
• 不持久化货运数据，不调用 Go 采购任务接口。

执行记录

• 2026-07-28：任务合约已冻结，等待 T-220。