diff --git a/pages/mall/delivery/doc/需求文档/README.md b/pages/mall/delivery/doc/需求文档/README.md index 4bcbba03..a51ad835 100644 --- 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; ``` diff --git a/pages/mall/delivery/doc/需求文档/express_tracking_mock_platform.sql b/pages/mall/delivery/doc/需求文档/express_tracking_mock_platform.sql index 01592533..605c0a49 100644 --- 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, diff --git a/pages/mall/delivery/doc/需求文档/express_tracking_platform_upgrade.sql b/pages/mall/delivery/doc/需求文档/express_tracking_platform_upgrade.sql index 03966177..f3cd0548 100644 --- 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, diff --git a/pages/mall/delivery/doc/需求文档/seed_platform_express_test_data.sql b/pages/mall/delivery/doc/需求文档/seed_platform_express_test_data.sql index 8f064d5b..9f355f52 100644 --- 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; diff --git a/pages/mall/delivery/doc/需求文档/simulate_third_party_to_db.sql b/pages/mall/delivery/doc/需求文档/simulate_third_party_to_db.sql index 7ef01733..e47525d2 100644 --- 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, diff --git a/pages/mall/delivery/doc/需求文档/前端字段清单.md b/pages/mall/delivery/doc/需求文档/前端字段清单.md index 2c8ec6f4..01c28795 100644 --- 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` 缓存在本地（仅该用户的订单范围），离线可展示并提示“数据可能不是最新”。 diff --git a/pages/mall/delivery/doc/需求文档/接口规范.md b/pages/mall/delivery/doc/需求文档/接口规范.md index 562df9e7..1b5f6e97 100644 --- 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: " \ - -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） diff --git a/pages/mall/delivery/doc/需求文档/状态映射表.md b/pages/mall/delivery/doc/需求文档/状态映射表.md index 478b97f4..cf11b51a 100644 --- 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 图片） diff --git a/pages/mall/delivery/doc/需求文档/生产表说明_platform_express.md b/pages/mall/delivery/doc/需求文档/生产表说明_platform_express.md index 7b2789b4..61051d06 100644 --- 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 | 是 | | 最近一次与承运方/聚合方同步时间（用于健康度与补偿轮询判断） | diff --git a/pages/mall/delivery/doc/需求文档/配送模块需求文档.md b/pages/mall/delivery/doc/需求文档/配送模块需求文档.md index a2dace9a..ae191284 100644 --- 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 白名单等。 diff --git a/pages/mall/delivery/test/api-simulator.uvue b/pages/mall/delivery/test/api-simulator.uvue index bd392901..408a30f5 100644 --- a/pages/mall/delivery/test/api-simulator.uvue +++ b/pages/mall/delivery/test/api-simulator.uvue @@ -85,15 +85,17 @@ infoContent: 'SEND', remark: '快件已到达【XX分拨中心】，准备发往下一站', acceptTime: '', - carrier: '圆通速递' + carrier: '顺丰速运' }) const statusOptions = [ - { label: '揽收 (GOT)', value: 'GOT' }, + { label: '已揽收 (GOT)', value: 'GOT' }, { label: '运输中 (SEND)', value: 'SEND' }, { label: '派送中 (SENT)', value: 'SENT' }, + { label: '待取件 (PICKUP)', value: 'PICKUP' }, { label: '已签收 (SIGNED)', value: 'SIGNED' }, - { label: '异常 (FAILED)', value: 'FAILED' } + { label: '异常 (FAILED)', value: 'FAILED' }, + { label: '退回 (RETURNED)', value: 'RETURNED' } ] const currentStatusLabel = computed((): string => { diff --git a/pages/mall/delivery/test/consumer-logistics-detail.uvue b/pages/mall/delivery/test/consumer-logistics-detail.uvue index 56f2d46f..894a5276 100644 --- a/pages/mall/delivery/test/consumer-logistics-detail.uvue +++ b/pages/mall/delivery/test/consumer-logistics-detail.uvue @@ -8,7 +8,7 @@ {{ getStatusText(order.status) }} - {{ seg.text }} + {{ seg.text }} @@ -20,9 +20,10 @@ {{ order.carrier }}快递 - 运单号: {{ order.tracking_no }} + 运单号: {{ order.tracking_no }} + 运单号: 暂无 - + @@ -40,13 +41,13 @@ - - {{ getStatusLabel(event.status_code) }} - {{ event.event_time }} - - - {{ seg.text }} - + + {{ getStatusLabel(event.status_code) }} + {{ event.event_time }} + + + {{ seg.text }} + @@ -84,14 +85,15 @@ - - + + +