docs(erp): define freight ingestion tasks

2026-07-28 22:39:18 +08:00
parent 78dc595815
commit cc847c9aed
15 changed files with 547 additions and 6 deletions
@@ -164,6 +164,99 @@ T-203 成功返回 `201`。使用相同 `Idempotency-Key` 和相同图片内容

 受鉴权的文件流。只能读取用户有权查看的任务资产；不返回服务端文件路径。

+## ERP Connector 与货运信息
+
+Connector 是 loopback 内部服务，不复用 ADMIN/BUYER 凭证。除 `/health` 外要求
+`X-API-Key`，密钥至少 32 字节并由两进程环境变量注入；请求和响应不得写 body 日志。
+
+### Connector `POST /v1/freight/query`
+
+```json
+{"order_number":"完整单号"}
+```
+
+成功返回最小化规范结构：
+
+```json
+{
+  "schema_version": 1,
+  "query": {"mode":"ORDER_NUMBER"},
+  "orders": [{
+    "external_stock_id": "99001122",
+    "source_code": "masked-at-log-boundary",
+    "platform_order_no": "optional",
+    "shop_name": "来源店铺",
+    "source_created_at": "2026-07-28T08:00:00+08:00",
+    "order_status": "0",
+    "purchase_status": "0",
+    "is_canceled": false,
+    "items": [{
+      "external_item_id": "880011",
+      "title": "商品标题",
+      "product_spec": "灰色,2XL",
+      "sku": "原始 SKU",
+      "quantity": 2,
+      "product_thumb_ref": "190000000",
+      "purchase_status": "0"
+    }]
+  }]
+}
+```
+
+不得返回 receiver、receiverTel、receiverAddr、Cookie、JWT、ERP 用户资料或完整原始
+对象。多商品必须全部保留；缺失详情返回协议错误，不允许部分成功。
+
+### `POST /api/v1/freight-syncs`
+
+ADMIN 创建异步同步记录，必须带 `Idempotency-Key`：
+
+```json
+{"mode":"ORDER_NUMBER","order_number":"完整单号"}
+```
+
+T-224 增加：
+
+```json
+{
+  "mode":"CREATED_RANGE",
+  "created_from":"2026-07-27T16:00:00Z",
+  "created_to":"2026-07-28T16:00:00Z"
+}
+```
+
+响应 `202`，返回 sync id/status。订单号不进入 URL、事件 message 或访问日志；数据库
+只保存规范值及用于审计/检索的受控字段，不保存 Connector 密钥。
+
+### `GET /api/v1/freight-syncs/{sync_id}`
+
+返回 `PENDING/RUNNING/SUCCEEDED/FAILED`、查询模式、匿名查询摘要、开始/结束时间、
+订单/商品计数和稳定错误码。失败不返回 ERP 原始 body 或个人信息。
+
+### `GET /api/v1/freight-orders`
+
+支持 `q`、`sync_status`、`created_from/to`、`limit/cursor`。`q` 匹配受控来源单号、
+店铺或内部 UUID，不匹配电话/地址。稳定排序为 `source_created_at DESC, id DESC`。
+
+### `GET /api/v1/freight-orders/{id}`
+
+返回货运头、全部商品明细、revision/hash 状态、采购需求和已生成 task 引用。不存在和
+跨 creator 统一 404；响应 `Cache-Control: no-store`。
+
+### `POST /api/v1/freight-items/{item_id}/procurement-request`
+
+T-223 创建或重放该商品当前 revision 的采购需求。标题、SKU/规格或数量不合法时返回
+`422 FREIGHT_ITEM_NOT_PURCHASABLE`；不调用 VLM 补字段。
+
+### `PUT /api/v1/procurement-requests/{id}/reference-asset`
+
+绑定当前 ADMIN 已上传的 `TASK_REFERENCE` asset。asset 必须尚未属于其他任务/请求，
+内容仍走既有解码、像素、规范化和 hash 校验。
+
+### `POST /api/v1/procurement-requests/{id}/purchase-task`
+
+必须带 `Idempotency-Key`。只有 `READY` request 可生成任务；同一 request revision
+并发或重试返回同一 task。来源后续更新不修改已生成任务。
+
 ## 采购任务

 ### `POST /api/v1/tasks`