chengma/cmroubao
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Page: T-221
Pages
00-ai-start-here 01-vision 02-requirements 03-tech-stack 04-architecture 05-coding-rules 06-tasks 07-user-stories 08-interaction-checklist Design Home Integrations-shunyunbao-contract PPT T-001 T-002 T-003 T-004 T-101 T-102 T-103 T-104 T-201 T-202 T-203 T-204 T-205 T-206 T-207 T-208 T-209 T-210 T-211 T-212 T-213 T-214 T-215 T-216 T-217 T-218 T-219 T-220 T-221 T-222 T-223 T-224 T-225 T-226 T-227 T-228 T-229 T-230 T-231 T-232 T-233 T-234 T-235 T-236 T-237 T-238 T-239 T-240 T-241 T-242 T-243 T-244 T-245 T-246 T-247 T-248 T-249 T-250 T-251 T-252 T-253 T-254 T-255 T-256 T-257 T-258 T-259 T-260 T-261 T-262 T-263 T-264 T-265 T-266 T-267 T-268 T-269 T-270 T-271 T-272 T-273 T-274 T-275 T-276 T-277 T-278 T-279 T-280 T-281 Task-Template Tasks agent-context api clean-state-checklist current-state routes
Clone
1
T-221
ila edited this page 2026-08-07 16:36:37 +08:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

同步来源：docs/tasks/T-221.md · commit afc651f75a3a

id: T-221 title: 顺运宝精确单号 Connector phase: 2 deps:

  • T-220 status: DONE created: 2026-07-28 context_ref: 78dc595 work_branch: null write_paths:
  • 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 完成后领取。
  • 2026-07-28：erp-connector/ 接入 Python 3.10+ 客户端、FastAPI 内部适配、 normalize_freight_result 和 loopback 启动脚本。源代码来自同一开发机已用私有 HAR 验证的参考工程；只复制源代码和伪响应测试，没有复制 HAR/真实响应。
  • 2026-07-28：API Key 最少 32 UTF-8 字节；captcha/login/query 返回稳定错误码。 query 响应只含 allowlist 字段，多商品按 external item id 稳定排序，冲突重复身份 整批失败。收件人、电话、地址、查询原值和原始对象有负向测试。
  • 2026-07-28：在 erp-connector/ 执行 $env:PYTHONPATH=(Resolve-Path .\src).Path; python -m pytest -q，16 项通过； python -m compileall -q src tests 通过。uvicorn 在 127.0.0.1:18092 启动， curl --noproxy "*" /health 返回 200 后已停止。根 .\init.ps1 通过。 全部验证使用伪凭证且未访问线上 ERP。