feat(t221): add exact-order erp connector

docs/current-state.md

@@ -5,7 +5,7 @@
 ## 当前快照
 
 - 日期：2026-07-28
-- 阶段：T-220 已完成，T-221 顺运宝精确单号 Connector 已领取
+- 阶段：T-221 已完成，T-222 货运信息存储 API 与 Admin 页面已领取
 - Git：当前分支为 `main`；T-001 至 T-004、T-101 至 T-104、T-201 至 T-219
   均按文档提交、实现提交的顺序纳入历史
 - 生产代码：`android-buyer/` 已接入 Roubao Android 源码
@@ -84,6 +84,10 @@
   对账和唯一对账成功；成功态展示完整订单号、平台时间、授权 SKU/数量/金额及受控
   证据，只提醒采购员打开拼多多人工核对付款。Roubao 显示相同终态；Web/App 均没有
   付款、重复提交或自动支付动作。隔离数据库真实 SSR 已通过三个响应式视口验收。
+- T-220/T-221 ERP 来源：字段契约已固定 stock/detail/item 外部身份、PII 最小化和
+  缺图边界；Python Connector 只监听 loopback，服务密钥鉴权，受控验证码登录后按
+  完整单号读取全部商品并输出 allowlist schema。16 项伪响应测试和真实 HTTP 健康
+  smoke 通过，未访问线上 ERP。
 - Workflow：纯 Kotlin runner 已支持步骤 timeout、最多 3 次 retry、安全阻塞、
   用户停止和单 runner 并发拒绝；T-102 已接入搜索加有界候选采集五步
 - TaskSource：严格 CLI 已生成并验证真实私有 ProbeTask；默认 APK 不含私有 fixture
@@ -152,8 +156,8 @@
 | `docs/tasks/T-218.md` | DONE | 单次提交围栏、最多一次提交动作和待付款订单唯一对账 |
 | `docs/tasks/T-219.md` | DONE | Admin 待付款提醒、Roubao 终态和跨端闭环验收 |
 | `docs/tasks/T-220.md` | DONE | 顺运宝 ERP 字段契约与凭证安全基线 |
-| `docs/tasks/T-221.md` | DOING | 顺运宝精确单号 Connector |
-| `docs/tasks/T-222.md` | TODO | 货运信息存储、API 与 Admin 页面 |
+| `docs/tasks/T-221.md` | DONE | 顺运宝精确单号 Connector |
+| `docs/tasks/T-222.md` | DOING | 货运信息存储、API 与 Admin 页面 |
 | `docs/tasks/T-223.md` | TODO | 待采购需求提取与任务生成 |
 | `docs/tasks/T-224.md` | TODO | ERP 日期增量同步 |
 | `docs/design/` | 已确认 | T-202 原型索引、4 个管理页和 7 个 Android 页面 |
@@ -162,15 +166,16 @@
 | `android-buyer/task-contract/` | 已有 | Android/CLI 共享 ProbeTask 与 TaskSource |
 | `android-buyer/tools/shopee-importer/` | 已有 | 开发机私有 fixture 导入 CLI |
 | `backend-api/` | 已有 | Go-Gin 任务 API、SQLite、图片存储、管理 Web 和 migration |
+| `erp-connector/` | 已有 | 顺运宝 loopback Python Connector 与无网络伪响应测试 |
 | `init.ps1` / `init.sh` | 已验证/待跨平台 | Windows 同时验证 Android/Go；Unix 入口待 Linux/WSL 复核 |
 
 ## 任务摘要
 
 - 已完成：T-001 至 T-004、T-101 至 T-104、T-201 至 T-219。
-- 已完成：另含 T-220 顺运宝 ERP 字段契约与凭证安全基线。
-- 进行中：T-221 顺运宝精确单号 Connector。
-- 下一步：完成 T-222 货运模块、T-223 采购需求生成和 T-224 日期增量同步，再进入
-  T-301 P0 UI 完整交互验收。
+- 已完成：另含 T-220、T-221 ERP 安全字段契约与精确单号 Connector。
+- 进行中：T-222 货运信息存储、API 与 Admin 页面。
+- 下一步：完成 T-223 采购需求生成和 T-224 日期增量同步，再进入 T-301 P0 UI
+  完整交互验收。
 
 ## 当前可运行内容
 

docs/tasks/T-221.md

@@ -4,7 +4,7 @@ title: 顺运宝精确单号 Connector
 phase: 2
 deps:
   - T-220
-status: DOING
+status: DONE
 created: 2026-07-28
 context_ref: 78dc595
 work_branch: null
@@ -44,10 +44,10 @@ Go 后端不应在 Gin 请求里启动 Python，也不应保存 ERP 密码、Coo
 
 ## 验收要点
 
-- [ ] 伪 ERP 响应覆盖验证码约束、登录、分页、重试、安全上限、多货运头和多商品。
-- [ ] 精确单号响应具有稳定 schema，商品不被 dict 覆盖或错误关联。
-- [ ] API Key 缺失/错误、未登录、未找到、ERP 超时和协议异常返回稳定状态。
-- [ ] `pytest`/编译和无网络单测通过；启动脚本不包含秘密。
+- [x] 伪 ERP 响应覆盖验证码约束、登录、分页、重试、安全上限、多货运头和多商品。
+- [x] 精确单号响应具有稳定 schema，商品不被 dict 覆盖或错误关联。
+- [x] API Key 缺失/错误、未登录、未找到、ERP 超时和协议异常返回稳定状态。
+- [x] `pytest`/编译和无网络单测通过；启动脚本不包含秘密。
 
 ## 边界
 
@@ -58,3 +58,14 @@ Go 后端不应在 Gin 请求里启动 Python，也不应保存 ERP 密码、Coo
 ## 执行记录
 
 - 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。

docs/tasks/T-222.md

@@ -4,7 +4,7 @@ title: 货运信息存储 API 与 Admin 页面
 phase: 2
 deps:
   - T-221
-status: TODO
+status: DOING
 created: 2026-07-28
 context_ref: 78dc595
 work_branch: null
@@ -65,4 +65,4 @@ write_paths:
 
 ## 执行记录
 
-- 2026-07-28：任务合约已冻结，等待 T-221。
+- 2026-07-28：任务合约已冻结；T-221 完成后领取。