统一状态码，优化对应逻辑

2026-02-09 16:53:20 +08:00
parent 3ea0f008b5
commit f46ec4c461
19 changed files with 591 additions and 236 deletions
--- a/pages/mall/delivery/doc/需求文档/README.md
+++ b/pages/mall/delivery/doc/需求文档/README.md
@@ -67,8 +67,8 @@

 测试/预发环境（不使用 mock_* 表也能联调）：
 - 仍然执行 [express_tracking_platform_upgrade.sql](express_tracking_platform_upgrade.sql) 创建“生产同款”三表。
- 再执行 [seed_platform_express_test_data.sql](seed_platform_express_test_data.sql) 向 `platform_express_*` 写入少量 TEST_ 前缀示例数据，用于页面联调与排障演示（可随时清理）。
-	- 说明：当前脚本会插入 9 条 `TEST_` 运单（含 1 条 `PENDING/未发货`），并为每条运单插入 1～3 条不等的轨迹事件（幂等，可重复执行）。
+- 再执行 [seed_platform_express_test_data.sql](seed_platform_express_test_data.sql) 向 `platform_express_*` 写入少量示例数据（大多数运单号以 `TEST_` 开头），用于页面联调与排障演示（可随时清理）。
+	- 说明：当前脚本会插入 10 条示例运单：其中 9 条 `tracking_no` 以 `TEST_` 开头，另 1 条 `ORDER_PLACED/已下单` 示例运单号为空；并为每条运单插入 1～3 条不等的轨迹事件（幂等，可重复执行）。

 ### Ubuntu 上的 Supabase（测试/预发）怎么执行

@@ -92,13 +92,13 @@
 	- `psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f pages/mall/delivery/doc/需求文档/seed_platform_express_test_data.sql`

 清理测试数据：
- 种子脚本底部自带清理 SQL（按 `tracking_no LIKE 'TEST_%'` 删除），需要时复制执行即可。
+- 种子脚本底部自带清理 SQL（按 `tracking_no LIKE 'TEST_%'` + raw `body->>'order_no'` 删除），需要时复制执行即可。

 ### 执行成功后的校验 SQL（建议）

 在 Supabase SQL Editor 执行以下查询，确认数据是否写入成功、事件是否按时间线可查：

-1) 查看全部 TEST_ 运单（应看到 9 条）：
+1) 查看全部示例运单（应看到 10 条）：
 ```sql
 select
 	carrier,
@@ -109,7 +109,7 @@ select
 	last_synced_at,
 	created_at
 from public.platform_express_waybills
-where tracking_no like 'TEST_%'
+where order_no like 'ORD_TEST_%'
 order by created_at desc;
 ```

@@ -124,7 +124,7 @@ select
 from public.platform_express_waybills w
 left join public.platform_express_tracking_events e
 	on e.waybill_id = w.id
-where w.tracking_no like 'TEST_%'
+where w.order_no like 'ORD_TEST_%'
 group by w.carrier, w.tracking_no
 order by last_event_time desc nulls last;
 ```
@@ -152,11 +152,13 @@ select
 	source,
 	carrier,
 	tracking_no,
+	body,
 	signature_valid,
 	request_id,
 	dedupe_key
 from public.platform_express_event_raw
 where tracking_no like 'TEST_%'
+	or (body->>'order_no') like 'ORD_TEST_%'
 order by received_at desc
 limit 50;
 ```
--- a/pages/mall/delivery/doc/需求文档/express_tracking_mock_platform.sql
+++ b/pages/mall/delivery/doc/需求文档/express_tracking_mock_platform.sql
@@ -39,7 +39,7 @@ CREATE TABLE IF NOT EXISTS platform_express_waybills (
  tracking_no varchar(64) NOT NULL,
  source varchar(16) NOT NULL DEFAULT 'mock', -- mock/carrier/aggregator

-  current_status_code varchar(32) NOT NULL DEFAULT 'PENDING',
+  current_status_code varchar(32) NOT NULL DEFAULT 'SHIPPED',
  current_status_text text NULL,

  eta timestamptz NULL,
--- a/pages/mall/delivery/doc/需求文档/express_tracking_platform_upgrade.sql
+++ b/pages/mall/delivery/doc/需求文档/express_tracking_platform_upgrade.sql
@@ -47,7 +47,7 @@ CREATE TABLE IF NOT EXISTS public.platform_express_waybills (
  tracking_no VARCHAR(64) NOT NULL,
  source VARCHAR(16) NOT NULL DEFAULT 'mock',   -- mock/carrier/aggregator

-  current_status_code VARCHAR(32) NOT NULL DEFAULT 'PENDING',
+  current_status_code VARCHAR(32) NOT NULL DEFAULT 'SHIPPED',
  current_status_text TEXT NULL,

  eta TIMESTAMP WITH TIME ZONE NULL,
--- a/pages/mall/delivery/doc/需求文档/seed_platform_express_test_data.sql
+++ b/pages/mall/delivery/doc/需求文档/seed_platform_express_test_data.sql
@@ -5,12 +5,18 @@
 -- 适用：已执行 express_tracking_platform_upgrade.sql 后。
 --
 -- 注意：
-- - 本文件会插入 tracking_no 以 TEST_ 前缀开头的示例数据。
+-- - 本文件会插入示例数据：大多数 tracking_no 以 TEST_ 前缀开头；另有 1 条 ORDER_PLACED 示例运单号为空。
 -- - 如需清理，可执行文末的清理 SQL。
 -- =====================================================================================

 BEGIN;

+-- 兼容旧版本种子数据：曾使用 TEST_YT_20260206_0010 作为“已下单”示例
+-- 现要求：已下单运单号为空；因此先清理旧 tracking_no 相关记录，避免重复数据。
+-- DELETE FROM public.platform_express_tracking_events WHERE tracking_no = 'TEST_YT_20260206_0010';
+-- DELETE FROM public.platform_express_event_raw WHERE tracking_no = 'TEST_YT_20260206_0010';
+-- DELETE FROM public.platform_express_waybills WHERE carrier = 'YTO' AND tracking_no = 'TEST_YT_20260206_0010' AND order_no = 'ORD_TEST_20260206010';
+
 -- 1) 创建/更新示例运单（若已存在则跳过）
 INSERT INTO public.platform_express_waybills (
  order_id,
@@ -28,11 +34,12 @@ VALUES
  (NULL, 'ORD_TEST_20260206002', 'YTO',   'TEST_YT_20260206_0002', 'mock', 'OUT_FOR_DELIVERY', '派送中', NULL, NOW()),
  (NULL, 'ORD_TEST_20260206003', 'ZTO',   'TEST_ZT_20260206_0003', 'mock', 'DELIVERED', '已签收', NULL, NOW()),
  (NULL, 'ORD_TEST_20260206004', 'STO',   'TEST_STO_20260206_0004', 'mock', 'EXCEPTION', '异常', NULL, NOW()),
-  (NULL, 'ORD_TEST_20260206005', 'SF',    'TEST_SF_20260206_0005', 'mock', 'ARRIVED_HUB', '到达网点', NULL, NOW()),
+  (NULL, 'ORD_TEST_20260206005', 'SF',    'TEST_SF_20260206_0005', 'mock', 'IN_TRANSIT', '运输中', NULL, NOW()),
  (NULL, 'ORD_TEST_20260206006', 'YUNDA', 'TEST_YD_20260206_0006', 'mock', 'SHIPPED', '已发货', NULL, NOW()),
  (NULL, 'ORD_TEST_20260206007', 'YTO',   'TEST_YT_20260206_0007', 'mock', 'IN_TRANSIT', '运输中', NULL, NOW()),
  (NULL, 'ORD_TEST_20260206008', 'ZTO',   'TEST_ZT_20260206_0008', 'mock', 'OUT_FOR_DELIVERY', '派送中', NULL, NOW()),
-  (NULL, 'ORD_TEST_20260206009', 'YUNDA', 'TEST_YD_20260206_0009', 'mock', 'PENDING', '未发货', NULL, NOW())
+  (NULL, 'ORD_TEST_20260206010', 'YTO',   '', 'mock', 'ORDER_PLACED', '已下单', NULL, NOW()),
+  (NULL, 'ORD_TEST_20260206011', 'ZTO',   'TEST_ZT_20260206_0011', 'mock', 'READY_FOR_PICKUP', '待取件', NULL, NOW())
 ON CONFLICT (carrier, tracking_no) DO NOTHING;


@@ -49,7 +56,8 @@ WITH w AS (
    'TEST_YD_20260206_0006',
    'TEST_YT_20260206_0007',
    'TEST_ZT_20260206_0008',
-    'TEST_YD_20260206_0009'
+    '',
+    'TEST_ZT_20260206_0011'
  )
 )
 INSERT INTO public.platform_express_tracking_events (
@@ -80,7 +88,7 @@ SELECT * FROM (
    NOW() - INTERVAL '12 hours' AS event_time,
    'PICKED' AS event_code,
    '包裹已揽收' AS event_text,
-    'ARRIVED_HUB' AS status_code,
+    'IN_TRANSIT' AS status_code,
    '上海浦东集散中心' AS node_name,
    '上海市 浦东新区' AS location,
    NULL AS description,
@@ -97,7 +105,7 @@ SELECT * FROM (
    'test_e_1002',
    NOW() - INTERVAL '6 hours',
    'TRANSIT',
-    '快件离开【上海浦东集散中心】，已发往【杭州转运中心】',
+    '运输中（测试数据）',
    'IN_TRANSIT',
    '上海浦东集散中心',
    '上海市 浦东新区',
@@ -117,7 +125,7 @@ SELECT * FROM (
    'test_e_2001',
    NOW() - INTERVAL '8 hours',
    'ARRIVAL',
-    '快件已到达【广州天河网点】',
+    '运输中',
    'IN_TRANSIT',
    '广州天河网点',
    '广州市 天河区',
@@ -156,7 +164,7 @@ SELECT * FROM (
    NOW() - INTERVAL '2 days',
    'PICKED',
    '包裹已揽收',
-    'ARRIVED_HUB',
+    'IN_TRANSIT',
    '北京朝阳网点',
    '北京市 朝阳区',
    NULL,
@@ -212,7 +220,7 @@ SELECT * FROM (
    NOW() - INTERVAL '20 hours',
    'PICKED',
    '包裹已揽收',
-    'ARRIVED_HUB',
+    'IN_TRANSIT',
    '深圳南山网点',
    '深圳市 南山区',
    NULL,
@@ -240,7 +248,7 @@ SELECT * FROM (
    'webhook',
    'test_e_4002'

-  -- 运单 5：到达网点
+  -- 运单 5：运输中（不区分中转/到达节点/分拨）
  UNION ALL
  SELECT
    (SELECT id FROM w WHERE tracking_no = 'TEST_SF_20260206_0005'),
@@ -250,7 +258,7 @@ SELECT * FROM (
    NOW() - INTERVAL '10 hours',
    'PICKED',
    '包裹已揽收',
-    'ARRIVED_HUB',
+    'IN_TRANSIT',
    '南京江宁集散中心',
    '南京市 江宁区',
    NULL,
@@ -267,8 +275,8 @@ SELECT * FROM (
    'test_e_5002',
    NOW() - INTERVAL '30 minutes',
    'ARRIVAL',
-    '快件已到达【南京江宁网点】，等待派送（测试数据）',
-    'ARRIVED_HUB',
+    '运输中（测试数据）',
+    'IN_TRANSIT',
    '南京江宁网点',
    '南京市 江宁区',
    NULL,
@@ -308,7 +316,7 @@ SELECT * FROM (
    NOW() - INTERVAL '18 hours',
    'PICKED',
    '包裹已揽收',
-    'ARRIVED_HUB',
+    'IN_TRANSIT',
    '武汉江夏网点',
    '武汉市 江夏区',
    NULL,
@@ -325,7 +333,7 @@ SELECT * FROM (
    'test_e_7002',
    NOW() - INTERVAL '7 hours',
    'TRANSIT',
-    '快件离开【武汉江夏网点】，已发往【长沙转运中心】（测试数据）',
+    '运输中（测试数据）',
    'IN_TRANSIT',
    '武汉江夏网点',
    '武汉市 江夏区',
@@ -345,7 +353,7 @@ SELECT * FROM (
    'test_e_8001',
    NOW() - INTERVAL '9 hours',
    'ARRIVAL',
-    '快件已到达【西安高新网点】（测试数据）',
+    '运输中（测试数据）',
    'IN_TRANSIT',
    '西安高新网点',
    '西安市 雁塔区',
@@ -374,25 +382,45 @@ SELECT * FROM (
    'webhook',
    'test_e_8002'

-  -- 运单 9：未发货（占位事件，便于前端展示）
+  -- 运单 9：已下单（平台生成事件示例；运单号为空）
  UNION ALL
  SELECT
-    (SELECT id FROM w WHERE tracking_no = 'TEST_YD_20260206_0009'),
-    'YUNDA',
-    'TEST_YD_20260206_0009',
-    'test_e_9001',
-    NOW() - INTERVAL '3 hours',
-    'PENDING',
-    '商家待发货（测试数据）',
-    'PENDING',
+    (SELECT id FROM w WHERE tracking_no = ''),
+    'YTO',
+    '',
+    'test_e_10001',
+    NOW() - INTERVAL '1 days',
+    'ORDER_PLACED',
+    '订单已下单（测试数据）',
+    'ORDER_PLACED',
+    NULL,
    NULL,
-    '杭州市 余杭区',
    NULL,
    '[]'::jsonb,
    NULL::jsonb,
    NOW(),
    'manual',
-    'test_e_9001'
+    'test_e_10001'
+
+  -- 运单 10：待取件（到驿站/自提柜）
+  UNION ALL
+  SELECT
+    (SELECT id FROM w WHERE tracking_no = 'TEST_ZT_20260206_0011'),
+    'ZTO',
+    'TEST_ZT_20260206_0011',
+    'test_e_11001',
+    NOW() - INTERVAL '3 hours',
+    'READY_FOR_PICKUP',
+    '快件已到达【杭州余杭菜鸟驿站】，请凭取件码取件（测试数据）',
+    'READY_FOR_PICKUP',
+    '杭州余杭菜鸟驿站',
+    '杭州市 余杭区',
+    NULL,
+    '[]'::jsonb,
+    NULL::jsonb,
+    NOW(),
+    'webhook',
+    'test_e_11001'
 ) AS rows_to_insert
 WHERE rows_to_insert.waybill_id IS NOT NULL
 ON CONFLICT (waybill_id, dedupe_key) DO NOTHING;
@@ -465,13 +493,47 @@ VALUES (
  'raw_test_0002'
 );

+-- ORDER_PLACED 示例：允许 tracking_no 为空，但 raw body 中保留 order_no 便于排障/审计筛选
+INSERT INTO public.platform_express_event_raw (
+  received_at,
+  source,
+  client_id,
+  carrier,
+  tracking_no,
+  signature_valid,
+  signature,
+  ts_header,
+  request_id,
+  remote_ip,
+  headers,
+  body,
+  parse_error,
+  dedupe_key
+)
+VALUES (
+  NOW(),
+  'webhook',
+  'test_client',
+  'YTO',
+  NULL,
+  TRUE,
+  'test-signature',
+  EXTRACT(EPOCH FROM NOW())::text,
+  'req_test_0003',
+  '127.0.0.1',
+  '{"content-type":"application/json"}'::jsonb,
+  '{"order_no":"ORD_TEST_20260206010","tracking_no":"","status_code":"ORDER_PLACED","event_text":"已下单（测试数据）"}'::jsonb,
+  NULL,
+  'raw_test_0003'
+);
+
 COMMIT;

 -- =====================================================================================
 -- 清理（需要时手工执行）
 -- =====================================================================================
 -- BEGIN;
-- DELETE FROM public.platform_express_event_raw WHERE tracking_no LIKE 'TEST_%';
-- DELETE FROM public.platform_express_tracking_events WHERE tracking_no LIKE 'TEST_%';
-- DELETE FROM public.platform_express_waybills WHERE tracking_no LIKE 'TEST_%';
+-- DELETE FROM public.platform_express_event_raw WHERE tracking_no LIKE 'TEST_%' OR (body->>'order_no') = 'ORD_TEST_20260206010';
+-- DELETE FROM public.platform_express_tracking_events WHERE tracking_no LIKE 'TEST_%' OR status_code = 'ORDER_PLACED';
+-- DELETE FROM public.platform_express_waybills WHERE tracking_no LIKE 'TEST_%' OR order_no = 'ORD_TEST_20260206010';
 -- COMMIT;
--- a/pages/mall/delivery/doc/需求文档/simulate_third_party_to_db.sql
+++ b/pages/mall/delivery/doc/需求文档/simulate_third_party_to_db.sql
@@ -37,6 +37,7 @@ DECLARE
  v_event_code TEXT := 'OUT_FOR_DELIVERY';
  v_event_text TEXT := '派送员正在派件（伪造推送，直写数据库）';
  v_status_code TEXT := 'OUT_FOR_DELIVERY';
+  v_status_code_normalized TEXT;
  v_node_name TEXT := '广州天河网点';
  v_location TEXT := '广州市 天河区';

@@ -49,6 +50,13 @@ DECLARE
  v_waybill_id UUID;
  v_dedupe_key TEXT;
 BEGIN
+  -- 兼容旧值：不再使用 ARRIVED_HUB，统一归类为 IN_TRANSIT（运输中）
+  v_status_code_normalized := CASE
+    WHEN v_status_code = 'ARRIVED_HUB' THEN 'IN_TRANSIT'
+    WHEN v_status_code = 'PENDING' THEN 'ORDER_PLACED'
+    ELSE v_status_code
+  END;
+
  -- 1) Upsert 运单主表（保证 waybill 存在）
  INSERT INTO public.platform_express_waybills (
    order_id,
@@ -66,12 +74,12 @@ BEGIN
    v_carrier,
    v_tracking_no,
    'mock',
-    v_status_code,
+    v_status_code_normalized,
    CASE
-      WHEN v_status_code = 'PENDING' THEN '待发货'
+      WHEN v_status_code = 'PENDING' THEN '已下单'
      WHEN v_status_code = 'SHIPPED' THEN '已发货'
      WHEN v_status_code = 'IN_TRANSIT' THEN '运输中'
-      WHEN v_status_code = 'ARRIVED_HUB' THEN '到达网点'
+      WHEN v_status_code = 'ARRIVED_HUB' THEN '运输中'
      WHEN v_status_code = 'OUT_FOR_DELIVERY' THEN '派送中'
      WHEN v_status_code = 'DELIVERED' THEN '已签收'
      WHEN v_status_code = 'EXCEPTION' THEN '异常'
@@ -130,7 +138,7 @@ BEGIN
      'event_time', v_event_time,
      'event_code', v_event_code,
      'event_text', v_event_text,
-      'status_code', v_status_code,
+      'status_code', v_status_code_normalized,
      'node_name', v_node_name,
      'location', v_location
    ),
@@ -165,7 +173,7 @@ BEGIN
    v_event_time,
    v_event_code,
    v_event_text,
-    v_status_code,
+    v_status_code_normalized,
    v_node_name,
    v_location,
    NULL,
--- a/pages/mall/delivery/doc/需求文档/前端字段清单.md
+++ b/pages/mall/delivery/doc/需求文档/前端字段清单.md
@@ -17,7 +17,7 @@
 - `order_no`：订单号
 - `tracking_no` / `waybill_no`：运单号（可能为空）
 - `carrier`：承运商标识（YUNDA/YTO/KDN 等）
- `status`：平台统一状态码（PENDING/IN_TRANSIT/ARRIVED_HUB/OUT_FOR_DELIVERY/DELIVERED/EXCEPTION/RETURNED）
+- `status`：平台统一状态码（ORDER_PLACED/SHIPPED/IN_TRANSIT/OUT_FOR_DELIVERY/READY_FOR_PICKUP/DELIVERED/EXCEPTION/RETURNED）
 - `status_history`：事件数组，元素结构 `{event_id, event_time, event_code, event_text, status_code, node_name, location, description, evidence_urls, source}`
 - `eta`：预计到达时间（ISO8601，若承运方或 ETA 服务提供）
 - `pod`：签收凭证数组，元素 `{type: photo|signature, url, timestamp, remark}`
@@ -55,6 +55,7 @@
 - 最小实现：
 	- 商家端优先展示 `status_code + node_name/location` 组合出的摘要；必要时展示清洗后的 `event_text`。
 	- 消费者端可展示清洗后的 `event_text`；仅在 `OUT_FOR_DELIVERY` 等末端节点按需提供脱敏联系方式。
+- 口径要求：除末端状态（派送中/待取件/已签收/异常/退回等）外，中转/到达/发往下一站等统一展示为“运输中”，不展示“到达××网点/分拨中心”等中间节点状态文案。

 5. 安卓端适配要点
 - 缓存：将最近一次 `status_history` 缓存在本地（仅该用户的订单范围），离线可展示并提示“数据可能不是最新”。
--- a/pages/mall/delivery/doc/需求文档/接口规范.md
+++ b/pages/mall/delivery/doc/需求文档/接口规范.md
@@ -36,7 +36,7 @@
 - `event_time`：事件时间（ISO8601）
 - `event_code`：第三方原始事件码（尽量不改写，用于审计与一致性对齐）
 - `event_text`：第三方原始事件文案（前端时间线默认展示）
- `status_code`：平台统一状态（PENDING, IN_TRANSIT, ARRIVED_HUB, OUT_FOR_DELIVERY, DELIVERED, EXCEPTION）
+- `status_code`：平台统一状态（ORDER_PLACED, SHIPPED, IN_TRANSIT, OUT_FOR_DELIVERY, READY_FOR_PICKUP, DELIVERED, EXCEPTION, RETURNED）
 - `node_name`：节点名称（中转站/网点/城市）
 - `location`：节点位置描述（城市/网点地址，注意隐私）
 - `description`：事件详细描述
@@ -68,8 +68,8 @@
  "tracking_no":"YD123456789",
  "carrier":"YUNDA",
  "event_id":"e_20260205_0001",
-  "event_code":"ARRIVED_HUB",
-  "event_text":"到达北京分拨中心",
+  "event_code":"TRANSIT",
+  "event_text":"运输中",
  "event_time":"2026-02-05T14:32:00+08:00",
  "node_name":"北京分拨中心",
  "location":"北京市朝阳区XXX",
@@ -90,7 +90,7 @@
  "carrier":"YUNDA",
  "events":[
    {"event_id":"e1","event_code":"PICKED","event_text":"已揽收","event_time":"2026-02-04T18:00:00+08:00","node_name":"门店揽收网点","location":"北京市顺义"},
-    {"event_id":"e2","event_code":"ARRIVED_HUB","event_text":"到达北京分拨中心","event_time":"2026-02-05T14:32:00+08:00","node_name":"北京分拨中心","location":"北京市朝阳区"}
+    {"event_id":"e2","event_code":"ARRIVAL","event_text":"运输中","event_time":"2026-02-05T14:32:00+08:00","node_name":"北京分拨中心","location":"北京市朝阳区"}
  ]
 }

@@ -141,8 +141,8 @@
 - 请求示例:
 {
  "event_id":"e_20260205_0002",
-  "event_code":"ARRIVED_HUB",
-  "event_text":"到达北京分拨中心",
+  "event_code":"TRANSIT",
+  "event_text":"运输中",
  "event_time":"2026-02-05T14:32:00+08:00",
  "node_name":"北京分拨中心",
  "location":"北京市朝阳区",
@@ -241,7 +241,7 @@ curl -X POST https://api.yourplatform.com/webhook/express/status \
  -H "X-Client-Id: carrier_yunda" \
  -H "X-Timestamp: 2026-02-05T14:32:00+08:00" \
  -H "X-Signature: <hmac-signature>" \
-  -d '{"tracking_no":"YD123456789","event_id":"e_20260205_0001","event_code":"ARRIVED_HUB","event_time":"2026-02-05T14:32:00+08:00","event_text":"到达北京分拨中心"}'
+  -d '{"tracking_no":"YD123456789","event_id":"e_20260205_0001","event_code":"TRANSIT","event_time":"2026-02-05T14:32:00+08:00","event_text":"运输中"}'
 ```

 ## 十一、日志与保留策略
@@ -407,7 +407,7 @@ X-Signature: hmac_sha256(body + timestamp)
  "tracking_no": "SF1234567890",
  "routes": [
    { "code": "PICKED", "desc": "已揽收", "time": "2026-02-05T09:10:00+08:00", "station": "深圳XX营业点" },
-    { "code": "ARRIVED_HUB", "desc": "到达分拨中心", "time": "2026-02-05T21:45:00+08:00", "station": "广州分拨中心" }
+    { "code": "TRANSIT", "desc": "运输中", "time": "2026-02-05T21:45:00+08:00", "station": "广州分拨中心" }
  ],
  "pod": { "signed": false, "photo_url": null }
 }
@@ -471,7 +471,7 @@ X-Signature: hmac_sha256(body + timestamp)

 `infoContent` 到平台统一 `status_code` 的建议映射（示例）：
 - GOT（已揽收）-> IN_TRANSIT
- ARRIVAL（已收入/到达）-> ARRIVED_HUB
+- ARRIVAL（已收入/到达）-> IN_TRANSIT（中转/到达节点统一视为运输中）
 - DEPARTURE（已发出/离开节点）-> IN_TRANSIT
 - SENT_SCAN（派件）-> OUT_FOR_DELIVERY
 - INBOUND（自提柜入柜）-> IN_TRANSIT（或按业务定义为 OUT_FOR_DELIVERY）
--- a/pages/mall/delivery/doc/需求文档/状态映射表.md
+++ b/pages/mall/delivery/doc/需求文档/状态映射表.md
@@ -1,36 +1,43 @@
-# 状态映射表（Mock 承运方 Server -> 平台统一状态）
+# 状态映射表（第三方/Mock -> 平台统一状态）

-本表用于将 Mock Server 产生的 `event_code/event_text` 映射为平台统一 `status_code`，以保证前端时间线与告警规则可复用。
+本表用于将第三方（或 Mock Server）产生的 `event_code/event_text` 映射为平台统一 `status_code`，以保证前端时间线与告警规则可复用。

 关联文档：
 - `接口规范.md`：统一事件模型与接入模式
 - `前端字段清单.md`：时间线字段契约（status_history/status_code）

-平台统一状态（建议）：
- PENDING：待揽收
- IN_TRANSIT：运输中
- ARRIVED_HUB：到达中转/分拨中心
+平台统一状态（建议，尽量少且稳定）：
+- ORDER_PLACED：已下单（平台侧订单状态；通常不是第三方快递事件）
+- SHIPPED：已发货（已绑定运单/待揽收）
+- IN_TRANSIT：运输中（含“中转中/发往下一站/分拨/到达节点/在途”等）
 - OUT_FOR_DELIVERY：派送中
- DELIVERED：已签收
- EXCEPTION：异常
- RETURNED：退回
+- READY_FOR_PICKUP：待取件（到驿站/自提柜等，等待收件人取件）
+- DELIVERED：已签收（含本人签收/代收点签收）
+- EXCEPTION：异常（地址不详、拒收、破损、丢件、派送失败等）
+- RETURNED：退回/退件

-Mock 事件码（建议） -> 平台统一状态
- CREATED / ORDERED -> PENDING
- PICKED / COLLECTED -> IN_TRANSIT
- ARRIVED_HUB -> ARRIVED_HUB
- DEPARTED_HUB / IN_TRANSIT -> IN_TRANSIT
+说明：
+- `ORDER_PLACED` 通常来自平台订单系统（下单成功），不一定存在 `tracking_no`；在“统一时间线展示”场景下可作为平台生成事件出现在物流时间线里。
+- 第三方事件原文（`event_text`）尽量保留；平台只用 `status_code` 做标签/筛选/告警。
+
+第三方/Mock 事件码（建议） -> 平台统一状态（示例映射）
+- ORDERED / CREATED -> SHIPPED（若该事件表示“快递单已创建/已出库”，而非平台下单）
+- PICKED / COLLECTED -> IN_TRANSIT（已揽收后进入物流网络）
+- ARRIVED_HUB / ARRIVAL -> IN_TRANSIT（中转/到达节点统一视为运输中）
+- DEPARTED_HUB / TRANSIT / IN_TRANSIT -> IN_TRANSIT
 - ARRIVED_DEST_CITY -> IN_TRANSIT
 - OUT_FOR_DELIVERY -> OUT_FOR_DELIVERY
+- AT_PICKUP_POINT / READY_FOR_PICKUP / DELIVERED_TO_PICKUP -> READY_FOR_PICKUP
 - SIGNED / DELIVERED -> DELIVERED
- REJECTED -> EXCEPTION
- ADDRESS_INVALID -> EXCEPTION
- DAMAGED -> EXCEPTION
- LOST -> EXCEPTION
+- FAILED_DELIVERY / REJECTED / ADDRESS_INVALID / DAMAGED / LOST -> EXCEPTION
 - RETURNED / RETURNING -> RETURNED

+平台生成事件（用于统一时间线，可选） -> 平台统一状态
+- ORDER_PLACED -> ORDER_PLACED
+- MERCHANT_CONFIRMED_SHIPMENT / SHIPPED -> SHIPPED
+
 示例（用于 UI 文案）
- ARRIVED_HUB：到达北京分拨中心
+- IN_TRANSIT：运输中
 - OUT_FOR_DELIVERY：快件正在派送中
 - SIGNED：客户已签收（可带 POD 图片）

--- a/pages/mall/delivery/doc/需求文档/生产表说明_platform_express.md
+++ b/pages/mall/delivery/doc/需求文档/生产表说明_platform_express.md
@@ -46,7 +46,7 @@
 | carrier | VARCHAR(32) | 否 | 参与唯一约束 | 承运方编码（如 `YUNDA`/`YTO`/`ZTO` 等；也可接入聚合方编码） |
 | tracking_no | VARCHAR(64) | 否 | 参与唯一约束 | 运单号/快递单号 |
 | source | VARCHAR(16) | 否 | 默认 `'mock'` | 运单数据来源：`mock`/`carrier`/`aggregator` 等 |
-| current_status_code | VARCHAR(32) | 否 | 默认 `'PENDING'` | 运单当前平台状态（用于列表页/摘要），通常由最新事件映射得到 |
+| current_status_code | VARCHAR(32) | 否 | 默认 `'SHIPPED'` | 运单当前平台状态（用于列表页/摘要），通常由最新事件映射得到 |
 | current_status_text | TEXT | 是 |  | 运单当前状态文本（可为最新事件文本的“清洗版”或平台自定义） |
 | eta | TIMESTAMPTZ | 是 |  | 预计送达时间（可选；来自承运方/聚合方或平台预测） |
 | last_synced_at | TIMESTAMPTZ | 是 |  | 最近一次与承运方/聚合方同步时间（用于健康度与补偿轮询判断） |
--- a/pages/mall/delivery/doc/需求文档/配送模块需求文档.md
+++ b/pages/mall/delivery/doc/需求文档/配送模块需求文档.md
@@ -72,7 +72,8 @@
 - 平台提供“发货与运单绑定”的入口（承运方选择、运单号录入/回填/打单），把差异收敛在平台 Adapter/映射规则，避免前端直接适配多家第三方。

 商家职责：
- 在平台选择承运方并完成发货动作：提供/回填 `tracking_no` 与必要的订单关联信息（如 `order_no`）。
+- 商家在平台的订单列表/订单详情页点击“发货/绑定运单”，选择承运方并录入/回填 `tracking_no`；`order_no` 由平台订单上下文自动带入，不要求商家手工输入订单号。
+- `ORDER_PLACED`（已下单）阶段允许 `tracking_no` 为空（前端展示“暂无运单号”）；完成发货绑定后进入 `SHIPPED`，此时必须具备 `carrier + tracking_no`。
 - 若商家坚持使用“商家与第三方的独立合同/账号”，可向平台提交第三方对接所需材料，由平台统一配置与代接入（不要求商家自建回调服务）。

 可选增强：商家在平台内“自助对接第三方”（无需商家开发）
@@ -99,7 +100,7 @@
 	- Phase 2：先接入 1 家聚合平台做统一下单/面单/轨迹（降低多家直连成本）。
 	- Phase 3：再开放 BYO Account（商家自带账号）自助配置（安全与运维成本最高）。

-优点：平台轻、商家灵活。
+优点：相对方案 A 平台责任更轻、商家更灵活。
 风险/成本：体验碎片化风险大；如果不强制回传规范，平台客服/前端会被迫处理多样差异，长期维护成本更高。

 #### 商家自选配送需要提供的内容（接入清单）
@@ -107,12 +108,12 @@
 基础信息（发货侧最小闭环）：
 - `carrier`：承运方标识（可为直连承运方或聚合平台，如 YUNDA/YTO/ZTO/STO/KDN 等）。
 - `tracking_no`：运单号生成与回传方式（商家生成/第三方返回/平台生成）。
- 订单关联信息：`order_no`（或平台侧可解析的业务单号），用于把轨迹绑定到订单详情页。
+- 订单关联信息：`order_no`（或平台侧可解析的业务单号），用于把轨迹绑定到订单详情页；通常由平台在“订单发货/绑定运单”操作中自动带入，不要求商家手工录入。

 运单号（`tracking_no`）获取方式（两种常见落地，二选一或并存）：
 1) 回填运单号（最小模式，推荐先上线）：
 	- 商家在线下/快递官方系统/聚合平台完成下单与交接，获得运单号。
-	- 商家在平台后台“发货”时选择承运商并回填 `tracking_no`。
+	- 商家在平台后台“发货/绑定运单”时选择承运商并回填 `tracking_no`（订单号无需手填，平台自动关联当前订单）。
 	- 平台不需要调用第三方“下单/面单”接口，只需后续接入轨迹（Webhook/轮询）用于展示。
 2) 电子面单 / 在线下单（增强模式，体验更好）：
 	- 平台（或平台集成的服务商）需要对接第三方提供的“下单/面单”接口，向第三方提交发货所需信息（收件人/地址/重量/件数等），并获得：运单号 `tracking_no` + 面单文件/面单号等。
@@ -143,6 +144,29 @@
 - 事件码/文案 -> 平台 `status_code` 的映射（至少覆盖：揽收/在途/派送中/签收/异常/退回）。
 - 幂等去重策略：优先 `event_id`；缺失时使用组合键（见 `接口规范.md` 的入库层建议）。

+#### 平台统一配送状态（`status_code`，必须遵循）
+
+说明：平台内部与对外输出统一使用同一套 `status_code`，三端（C/B/管理端）按需展示，不得随意改写状态口径。
+
+状态枚举（当前统一口径）：
+- `ORDER_PLACED`：已下单（平台侧订单已创建；通常不是第三方快递事件；此阶段允许 `tracking_no` 为空）
+- `SHIPPED`：已发货（已绑定运单/待揽收）
+- `IN_TRANSIT`：运输中（所有中转/分拨/到达节点统一归类为运输中）
+- `OUT_FOR_DELIVERY`：派送中
+- `READY_FOR_PICKUP`：待取件（驿站/自提柜等）
+- `DELIVERED`：已签收
+- `EXCEPTION`：异常
+- `RETURNED`：退回/退件
+
+展示规范：
+- 为保证用户体验，应真实展示第三方回传的物流轨迹文案（如“到达北京分拨中心”、“离开上海网点”等），不做脱敏处理。
+- 前端时间线展示 `event_text` 原文，状态标签对应 `status_code`。
+
+说明：本项目不维护“发货前”的配送状态；在未绑定运单阶段属于订单域状态，不纳入物流轨迹状态枚举。
+
+补充约束（与页面展示相关）：
+- 当 `tracking_no` 为空时，前端仅展示订单的配送状态为 `ORDER_PLACED` 与“暂无运单号”，不展示可查询的第三方物流时间线；待商家完成“发货/绑定运单”后，再展示轨迹时间线。
+
 #### 差异化来源与平台收敛策略
 差异化来源（商家自选必然存在）：
 - 鉴权差异：Token/HMAC/证书/IP 白名单等。