From f33efe6ec8373f7993d9e36014510983fef3c091 Mon Sep 17 00:00:00 2001 From: not-like-juvenile <16056107+not-like-juvenile@user.noreply.gitee.com> Date: Tue, 17 Mar 2026 11:06:26 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E6=94=B9=E8=BF=87=E6=97=B6=E6=96=87?= =?UTF-8?q?=E6=A1=A3=EF=BC=8C=E4=BC=98=E5=8C=96=E6=96=87=E6=A1=A3=E5=86=85?= =?UTF-8?q?=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- BACKEND_MIGRATION_PLAN.md | 18 +- PAGES_ROUTES.md | 4 +- README.md | 3 +- .../test/07_ml_analytics_rpcs_delivery.sql | 2 + .../doc/{old => old(弃用)}/DELIVERY_LOGIC.md | 0 .../{old => old(弃用)}/FIX_REPORT_20260203.md | 0 .../doc/{old => old(弃用)}/STATE_1-5_LOGIC.md | 0 .../delivery/doc/{old => old(弃用)}/all.md | 0 .../db/create_pending_orders.sql | 0 .../db/create_test_orders.sql | 0 .../db/db-data-generation.md | 0 .../db/realistic_mock_data.sql | 0 .../doc/{old => old(弃用)}/delivery.md | 0 .../doc/{old => old(弃用)}/earnings.md | 0 .../delivery/doc/{old => old(弃用)}/index.md | 0 .../doc/{old => old(弃用)}/more-orders.md | 0 .../doc/{old => old(弃用)}/order-detail.md | 0 .../doc/{old => old(弃用)}/order-history.md | 0 .../doc/{old => old(弃用)}/profile-edit.md | 0 .../doc/{old => old(弃用)}/profile.md | 0 .../delivery/doc/需求文档(现用)/README.md | 46 ++++ .../db/20260224_add_push_devices_and_notifications.sql | 0 .../20260309_add_express_notifications_send_status.sql | 0 .../db/20260309_add_notify_queue_and_trigger.sql | 0 ...fix_express_notifications_on_conflict_message_id.sql | 0 .../db/express_tracking_platform_upgrade.sql | 0 .../db/消息推送后台_数据库表结构需求文档.md | 101 ++++++++ .../20260311_add_rpc_notify_get_order_recipients.sql | 0 .../express_tracking_mock_platform.sql | 0 .../seed_platform_express_test_data.sql | 0 .../simulate_third_party_to_db.sql | 0 .../uni-push2_安卓联调与取CID说明.md | 0 .../前端字段清单.md | 0 .../后台页面设计说明.md | 0 .../{需求文档 => 需求文档(现用)}/接口规范.md | 0 .../推送与设备需求文档.md | 0 .../推送与设备需求文档_含建表附录.md | 0 .../数据库对比与修改建议.md | 0 .../物流消息推送方案_用户端与商家端.md | 0 .../状态映射表.md | 0 .../生产表说明_platform_express.md | 0 .../缺口与待补充清单.md | 0 .../配送模块需求文档.md | 0 pages/mall/delivery/doc/需求文档/README.md | 223 ------------------ server/消息推送文档/README.md | 1 + 45 files changed, 162 insertions(+), 236 deletions(-) rename pages/mall/delivery/doc/{old => old(弃用)}/DELIVERY_LOGIC.md (100%) rename pages/mall/delivery/doc/{old => old(弃用)}/FIX_REPORT_20260203.md (100%) rename pages/mall/delivery/doc/{old => old(弃用)}/STATE_1-5_LOGIC.md (100%) rename pages/mall/delivery/doc/{old => old(弃用)}/all.md (100%) rename pages/mall/delivery/doc/{old => old(弃用)}/db/create_pending_orders.sql (100%) rename pages/mall/delivery/doc/{old => old(弃用)}/db/create_test_orders.sql (100%) rename pages/mall/delivery/doc/{old => old(弃用)}/db/db-data-generation.md (100%) rename pages/mall/delivery/doc/{old => old(弃用)}/db/realistic_mock_data.sql (100%) rename pages/mall/delivery/doc/{old => old(弃用)}/delivery.md (100%) rename pages/mall/delivery/doc/{old => old(弃用)}/earnings.md (100%) rename pages/mall/delivery/doc/{old => old(弃用)}/index.md (100%) rename pages/mall/delivery/doc/{old => old(弃用)}/more-orders.md (100%) rename pages/mall/delivery/doc/{old => old(弃用)}/order-detail.md (100%) rename pages/mall/delivery/doc/{old => old(弃用)}/order-history.md (100%) rename pages/mall/delivery/doc/{old => old(弃用)}/profile-edit.md (100%) rename pages/mall/delivery/doc/{old => old(弃用)}/profile.md (100%) create mode 100644 pages/mall/delivery/doc/需求文档(现用)/README.md rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/db/20260224_add_push_devices_and_notifications.sql (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/db/20260309_add_express_notifications_send_status.sql (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/db/20260309_add_notify_queue_and_trigger.sql (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/db/20260310_fix_express_notifications_on_conflict_message_id.sql (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/db/express_tracking_platform_upgrade.sql (100%) create mode 100644 pages/mall/delivery/doc/需求文档(现用)/db/消息推送后台_数据库表结构需求文档.md rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/db/绕过RLS的方案(慎用)/20260311_add_rpc_notify_get_order_recipients.sql (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/express_tracking_mock_platform.sql (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/seed_platform_express_test_data.sql (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/simulate_third_party_to_db.sql (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/uni-push2_安卓联调与取CID说明.md (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/前端字段清单.md (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/后台页面设计说明.md (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/接口规范.md (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/推送与设备需求文档.md (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/推送与设备需求文档_含建表附录.md (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/数据库对比与修改建议.md (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/物流消息推送方案_用户端与商家端.md (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/状态映射表.md (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/生产表说明_platform_express.md (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/缺口与待补充清单.md (100%) rename pages/mall/delivery/doc/{需求文档 => 需求文档(现用)}/配送模块需求文档.md (100%) delete mode 100644 pages/mall/delivery/doc/需求文档/README.md diff --git a/BACKEND_MIGRATION_PLAN.md b/BACKEND_MIGRATION_PLAN.md index c3b0d975..82409a1d 100644 --- a/BACKEND_MIGRATION_PLAN.md +++ b/BACKEND_MIGRATION_PLAN.md @@ -13,7 +13,7 @@ ## 概要执行步骤（What / High level） 1. 立刻移除前端的 `service_role`，前端只用 `anon`（阻断最大风险）。 -2. 实现最小后台 API（先做配送接单/状态流转 rpc + HTTP 接口）。 +2. 实现最小后台 API（订单管理、核心状态流转 rpc + HTTP 接口）。 3. 在数据库添加约束、RLS 策略与 RPC（把关键状态流转做成原子函数）。 4. 前端分阶段切换到新 API 并回归测试。 5. 补充审计、幂等与监控，逐步迁移其它敏感写入。 @@ -64,11 +64,11 @@ BEGIN VALUES (p_action_id, now()) ON CONFLICT (action_id) DO NOTHING; - -- 执行原子更新：仅当 task 可被领取（status=1 且 driver_id IS NULL） + -- 执行原子更新 WITH u AS ( - UPDATE ml_delivery_tasks - SET driver_id = p_driver_uuid, status = 2, updated_at = now() - WHERE id = p_task_uuid AND status = 1 AND driver_id IS NULL + UPDATE ml_orders + SET status = 2, updated_at = now() + WHERE id = p_task_uuid AND status = 1 RETURNING * ) SELECT * INTO v_task FROM u LIMIT 1; @@ -79,7 +79,7 @@ BEGIN -- 写审计 INSERT INTO audit_logs(actor_id, action, target_table, target_id, payload, created_at) - VALUES (p_driver_uuid, 'accept_task', 'ml_delivery_tasks', p_task_uuid, row_to_json(v_task), now()); + VALUES (p_driver_uuid, 'accept_task', 'ml_orders', p_task_uuid, row_to_json(v_task), now()); RETURN jsonb_build_object('ok', true, 'task', to_jsonb(v_task)); END; @@ -99,8 +99,8 @@ CREATE POLICY user_owns_address ON user_addresses USING (auth.uid() = user_id) WITH CHECK (auth.uid() = user_id); ``` -- 对关键表（`ml_delivery_tasks`、`ml_orders`）： - - 禁止直接由匿名或普通前端更新关键列（例如 driver_id、status）；只允许 `rpc` / service 调用通过函数更新。 +- 对关键表（如 `ml_orders`）： + - 禁止直接由匿名或普通前端更新关键列；只允许 `rpc` / service 调用通过函数更新。 - 索引/约束： - message_id 唯一：`CREATE UNIQUE INDEX ux_express_notifications_message_id ON express_notifications(message_id);` - 补全 NOT NULL / FK / CHECK（枚举字段限制等）。 @@ -131,7 +131,7 @@ CREATE POLICY user_owns_address ON user_addresses - [ ] 注释/移除前端 `service_role`：`ak/config.uts`（紧急） - [ ] 在 `server/` 新增 `POST /api/v1/delivery/accept-task`（鉴权 + 调用 RPC） - [ ] 在 DB 创建 `rpc_accept_task`、`action_dedupe`、`audit_logs` 表 -- [ ] 对 `user_addresses`、`ml_delivery_tasks`、`ml_orders` 等启用 RLS 策略（逐表） +- [ ] 对 `user_addresses`、`ml_orders` 等启用 RLS 策略（逐表） - [ ] 前端将接单/确认调用迁移到新 API（feature-flag）并回归测试 - [ ] 部署后监控并逐步扩大灰度 diff --git a/PAGES_ROUTES.md b/PAGES_ROUTES.md index 14c36d31..6faf5217 100644 --- a/PAGES_ROUTES.md +++ b/PAGES_ROUTES.md @@ -45,7 +45,7 @@ Generated from root pages.json (pages + subPackages). - pages/mall/consumer/subscription/subscribe-checkout - pages/mall/consumer/subscription/my-subscriptions -### pages/mall/delivery + ### pages/mall/analytics - pages/mall/analytics/index diff --git a/README.md b/README.md index d72df404..82f78526 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 🛍️ Mall (uni-app / uvue) -本仓库为 uni-app（uvue/uts）商城项目，包含消费者端、配送端、数据分析、管理后台、商家端、客服端等模块。 +本仓库为 uni-app（uvue/uts）商城项目，包含消费者端、数据分析、管理后台、商家端、客服端等模块（注：旧有独立配送端已弃用，现改为第三方物流对接）。 ## 📦 路由与分包 @@ -18,7 +18,6 @@ pages/ user/ # 登录/注册/用户中心等公共页面 mall/ consumer/ # 消费者端 - delivery/ # 配送端 analytics/ # 数据分析 admin/ # 管理后台 merchant/ # 商家端 diff --git a/pages/mall/analytics/test/07_ml_analytics_rpcs_delivery.sql b/pages/mall/analytics/test/07_ml_analytics_rpcs_delivery.sql index 81a3096a..4710e1e2 100644 --- a/pages/mall/analytics/test/07_ml_analytics_rpcs_delivery.sql +++ b/pages/mall/analytics/test/07_ml_analytics_rpcs_delivery.sql @@ -7,6 +7,8 @@ -- - 完成配送：ml_delivery_tasks.status = 5 -- - 配送时长：delivered_at - assigned_at（分钟） -- - avg_fee：delivery_fee 平均 + +-- 弃用 -- ===================================================================================== -- 1) 配送效率日趋势 diff --git a/pages/mall/delivery/doc/old/DELIVERY_LOGIC.md b/pages/mall/delivery/doc/old(弃用)/DELIVERY_LOGIC.md similarity index 100% rename from pages/mall/delivery/doc/old/DELIVERY_LOGIC.md rename to pages/mall/delivery/doc/old(弃用)/DELIVERY_LOGIC.md diff --git a/pages/mall/delivery/doc/old/FIX_REPORT_20260203.md b/pages/mall/delivery/doc/old(弃用)/FIX_REPORT_20260203.md similarity index 100% rename from pages/mall/delivery/doc/old/FIX_REPORT_20260203.md rename to pages/mall/delivery/doc/old(弃用)/FIX_REPORT_20260203.md diff --git a/pages/mall/delivery/doc/old/STATE_1-5_LOGIC.md b/pages/mall/delivery/doc/old(弃用)/STATE_1-5_LOGIC.md similarity index 100% rename from pages/mall/delivery/doc/old/STATE_1-5_LOGIC.md rename to pages/mall/delivery/doc/old(弃用)/STATE_1-5_LOGIC.md diff --git a/pages/mall/delivery/doc/old/all.md b/pages/mall/delivery/doc/old(弃用)/all.md similarity index 100% rename from pages/mall/delivery/doc/old/all.md rename to pages/mall/delivery/doc/old(弃用)/all.md diff --git a/pages/mall/delivery/doc/old/db/create_pending_orders.sql b/pages/mall/delivery/doc/old(弃用)/db/create_pending_orders.sql similarity index 100% rename from pages/mall/delivery/doc/old/db/create_pending_orders.sql rename to pages/mall/delivery/doc/old(弃用)/db/create_pending_orders.sql diff --git a/pages/mall/delivery/doc/old/db/create_test_orders.sql b/pages/mall/delivery/doc/old(弃用)/db/create_test_orders.sql similarity index 100% rename from pages/mall/delivery/doc/old/db/create_test_orders.sql rename to pages/mall/delivery/doc/old(弃用)/db/create_test_orders.sql diff --git a/pages/mall/delivery/doc/old/db/db-data-generation.md b/pages/mall/delivery/doc/old(弃用)/db/db-data-generation.md similarity index 100% rename from pages/mall/delivery/doc/old/db/db-data-generation.md rename to pages/mall/delivery/doc/old(弃用)/db/db-data-generation.md diff --git a/pages/mall/delivery/doc/old/db/realistic_mock_data.sql b/pages/mall/delivery/doc/old(弃用)/db/realistic_mock_data.sql similarity index 100% rename from pages/mall/delivery/doc/old/db/realistic_mock_data.sql rename to pages/mall/delivery/doc/old(弃用)/db/realistic_mock_data.sql diff --git a/pages/mall/delivery/doc/old/delivery.md b/pages/mall/delivery/doc/old(弃用)/delivery.md similarity index 100% rename from pages/mall/delivery/doc/old/delivery.md rename to pages/mall/delivery/doc/old(弃用)/delivery.md diff --git a/pages/mall/delivery/doc/old/earnings.md b/pages/mall/delivery/doc/old(弃用)/earnings.md similarity index 100% rename from pages/mall/delivery/doc/old/earnings.md rename to pages/mall/delivery/doc/old(弃用)/earnings.md diff --git a/pages/mall/delivery/doc/old/index.md b/pages/mall/delivery/doc/old(弃用)/index.md similarity index 100% rename from pages/mall/delivery/doc/old/index.md rename to pages/mall/delivery/doc/old(弃用)/index.md diff --git a/pages/mall/delivery/doc/old/more-orders.md b/pages/mall/delivery/doc/old(弃用)/more-orders.md similarity index 100% rename from pages/mall/delivery/doc/old/more-orders.md rename to pages/mall/delivery/doc/old(弃用)/more-orders.md diff --git a/pages/mall/delivery/doc/old/order-detail.md b/pages/mall/delivery/doc/old(弃用)/order-detail.md similarity index 100% rename from pages/mall/delivery/doc/old/order-detail.md rename to pages/mall/delivery/doc/old(弃用)/order-detail.md diff --git a/pages/mall/delivery/doc/old/order-history.md b/pages/mall/delivery/doc/old(弃用)/order-history.md similarity index 100% rename from pages/mall/delivery/doc/old/order-history.md rename to pages/mall/delivery/doc/old(弃用)/order-history.md diff --git a/pages/mall/delivery/doc/old/profile-edit.md b/pages/mall/delivery/doc/old(弃用)/profile-edit.md similarity index 100% rename from pages/mall/delivery/doc/old/profile-edit.md rename to pages/mall/delivery/doc/old(弃用)/profile-edit.md diff --git a/pages/mall/delivery/doc/old/profile.md b/pages/mall/delivery/doc/old(弃用)/profile.md similarity index 100% rename from pages/mall/delivery/doc/old/profile.md rename to pages/mall/delivery/doc/old(弃用)/profile.md diff --git a/pages/mall/delivery/doc/需求文档(现用)/README.md b/pages/mall/delivery/doc/需求文档(现用)/README.md new file mode 100644 index 00000000..6a2de5a7 --- /dev/null +++ b/pages/mall/delivery/doc/需求文档(现用)/README.md @@ -0,0 +1,46 @@ +# 消息推送与物流发货后台 —— 需求与架构文档总览 + +> **更新日期**：2026年03月16日 +> **核心职责**：管理商城发货物流对接、Webhook状态更新接受、基于消息队列模型的异步应用内推送（UniPush 2.0）。 + +本目录包含了本系统从“接收物流消息”到“完成终端设备 APP 推送”的全核心链路设计与需求规范。我们采用了**免 Redis 的高可靠去中心化架构（基于 PostgreSQL Transactional Outbox 模式）**。 + +## 🎯 必读核心文档（从 0 到 1 快速理解本套系统） + +1. 📂 **数据库表结构设计（全系统基石）** + - [消息推送后台_数据库表结构需求文档.md](./db/消息推送后台_数据库表结构需求文档.md) *(核心！详述了从快递节点到通知排队流转经过的 5 张关键表)* +2. 🔄 **数据流向与演进架构** + - 见 `server/消息推送文档/DELIVERY_NOTIFICATION_DATA_FLOW.md` *(全局架构数据泳道流转图与为什么不使用 Redis 的技术选型解说)* +3. 📦 **业务推送机制文档** + - [物流消息推送方案_用户端与商家端.md](物流消息推送方案_用户端与商家端.md) *(阐述推送业务交互形态及场景)* + - [推送与设备需求文档_含建表附录.md](推送与设备需求文档_含建表附录.md) *(阐述设备绑定及队列下发业务目标)* + +--- + +## 📚 目录体系详解 + +### 1. 核心架构与数据库执行脚本 (`db/` 目录) +如果需要在全新环境部署此推送系统，请**按顺序执行**以下表结构 SQL 迁移脚本： +- `express_tracking_platform_upgrade.sql`: 运单主表、源事件表（`platform_express_event_raw`/`tracking_events`）的创建。 +- `20260224_add_push_devices_and_notifications.sql`: 客户端推送标记路由表（`push_devices`）与最终推送记录大表（`express_notifications`）创建。 +- `20260309_add_notify_queue_and_trigger.sql`: **极度重要！**创建异步缓冲外箱表 `notify_queue` 和连接事件与处理器的 PostgreSQL 防丢触发器 `event_to_queue_trigger`。 +- `20260309_add_express_notifications_send_status.sql`: 添加投递状态控制。 +- `20260310_fix_express_notifications_on_conflict_message_id.sql`: 去重逻辑修复。 + +### 2. 前端与联调试配规范文档 +本块文档聚焦于多端（客户端 UniApp 与 管理后台端）关于物流模块的展现与对接规范： +- **客户端获取 CID 核心技术栈**：[uni-push2_安卓联调与取CID说明.md](uni-push2_安卓联调与取CID说明.md)（指导客户端童鞋如果提取各厂手机独立推送凭证） +- **后台页面结构**：[后台页面设计说明.md](后台页面设计说明.md) +- **数据流与展示字段**：[前端字段清单.md](前端字段清单.md) +- **前后端快递状态映射**：[状态映射表.md](状态映射表.md) (如：快递参数如何转为本系统枚举类型代码) + +### 3. 测试与沙盘联调 (Mock 专属) +因接入第三方（如快递100）需签约，本系统也内置了一套模拟联调能力。 +- [接口规范.md](接口规范.md) +- SQL 数据灌入脚本：`simulate_third_party_to_db.sql` / `seed_platform_express_test_data.sql` / `express_tracking_mock_platform.sql` + +### 4. （历史/备份）早期草案与建议档案 +以下文档作为架构迭代的历史依据： +- `推送与设备需求文档.md`（原始未涵盖表结构的草案） +- `配送模块需求文档.md`（旧三通一达体系梳理） +- `生产表说明_platform_express.md` / `数据库对比与修改建议.md` / `缺口与待补充清单.md` diff --git a/pages/mall/delivery/doc/需求文档/db/20260224_add_push_devices_and_notifications.sql b/pages/mall/delivery/doc/需求文档(现用)/db/20260224_add_push_devices_and_notifications.sql similarity index 100% rename from pages/mall/delivery/doc/需求文档/db/20260224_add_push_devices_and_notifications.sql rename to pages/mall/delivery/doc/需求文档(现用)/db/20260224_add_push_devices_and_notifications.sql diff --git a/pages/mall/delivery/doc/需求文档/db/20260309_add_express_notifications_send_status.sql b/pages/mall/delivery/doc/需求文档(现用)/db/20260309_add_express_notifications_send_status.sql similarity index 100% rename from pages/mall/delivery/doc/需求文档/db/20260309_add_express_notifications_send_status.sql rename to pages/mall/delivery/doc/需求文档(现用)/db/20260309_add_express_notifications_send_status.sql diff --git a/pages/mall/delivery/doc/需求文档/db/20260309_add_notify_queue_and_trigger.sql b/pages/mall/delivery/doc/需求文档(现用)/db/20260309_add_notify_queue_and_trigger.sql similarity index 100% rename from pages/mall/delivery/doc/需求文档/db/20260309_add_notify_queue_and_trigger.sql rename to pages/mall/delivery/doc/需求文档(现用)/db/20260309_add_notify_queue_and_trigger.sql diff --git a/pages/mall/delivery/doc/需求文档/db/20260310_fix_express_notifications_on_conflict_message_id.sql b/pages/mall/delivery/doc/需求文档(现用)/db/20260310_fix_express_notifications_on_conflict_message_id.sql similarity index 100% rename from pages/mall/delivery/doc/需求文档/db/20260310_fix_express_notifications_on_conflict_message_id.sql rename to pages/mall/delivery/doc/需求文档(现用)/db/20260310_fix_express_notifications_on_conflict_message_id.sql diff --git a/pages/mall/delivery/doc/需求文档/db/express_tracking_platform_upgrade.sql b/pages/mall/delivery/doc/需求文档(现用)/db/express_tracking_platform_upgrade.sql similarity index 100% rename from pages/mall/delivery/doc/需求文档/db/express_tracking_platform_upgrade.sql rename to pages/mall/delivery/doc/需求文档(现用)/db/express_tracking_platform_upgrade.sql diff --git a/pages/mall/delivery/doc/需求文档(现用)/db/消息推送后台_数据库表结构需求文档.md b/pages/mall/delivery/doc/需求文档(现用)/db/消息推送后台_数据库表结构需求文档.md new file mode 100644 index 00000000..f2d1e32c --- /dev/null +++ b/pages/mall/delivery/doc/需求文档(现用)/db/消息推送后台_数据库表结构需求文档.md @@ -0,0 +1,101 @@ +# 消息推送后台 —— 核心数据库表结构需求文档 + +> **创建日期**：2026年03月16日 +> **模块归属**：商城发货与物流推送后台 +> **涉及架构**：Node.js Worker + Supabase (PostgreSQL) + UniPush 2.0 + +为支撑高可用、防丢失、可追溯的异步消息推送架构，本消息推送系统在底层（Supabase/PostgreSQL）摒弃了传统的 Redis 中间件依赖，直接利用关系型数据库的横表与触发器机制（Transactional Outbox 事务外箱模式）完成了高并发状态下的物流事件缓冲与分发。 + +本需求文档详细列出了参与推送闭环的 **5 张核心数据表** 的设计规范、字段说明与职责定位，是后端/DBA 开发与日常客诉运维排障的唯一真理依据。 + +--- + +## 整体库表流转全景 +消息在数据库中的物理游走路径为： +**`平台接收原生钩子`** $\rightarrow$ **`轨迹业务表入库`** $\rightarrow$ (触发器) $\rightarrow$ **`任务队列缓冲表`** $\rightarrow$ (合并订单/用户数据) $\rightarrow$ **`最终下发通知表`** $\rightarrow$ **`匹配设备表CID推送`** + +--- + +## 一、 原始通信日志表 (`platform_express_event_raw`) + +### 1. 表职责方向 +保存第一手的物流商（如快递100）Webhook 推送过来的原生 JSON 报文。不做任何业务过滤。 +- **核心价值**：排查“某单是不是底下的快递公司就没给我们发回调？”的第一现场。如果这里没有记录，绝不可能是本系统的 Bug。 + +### 2. 核心字段设计 (逻辑概述) +* `id` (UUID): 唯一自增主键。 +* `raw_payload` (JSONB): 快递100推过来的纯原生报文。 +* `created_at` (Timestamp): 平台接收到外网请求的确切服务器时间。 + +--- + +## 二、 规范化轨迹主表 (`platform_express_tracking_events` / `waybills`) + +### 1. 表职责方向 +用于商城订单域查询使用的结构化物流跟踪事件表。接收服务将 `event_raw` 里的 JSON 解包后，转化为本商城统一的枚举状态。 +- **机制特点**：这张表在发生 `INSERT` (即产生新轨迹节点) 时，会触发 PostgreSQL 内置触发器 `event_to_queue_trigger`。 + +### 2. 核心字段要求 +* `waybill_id` (UUID): 关联的运单主键。 +* `status_code` (VARCHAR): 规范化的签收/派件枚举状态码。 +* `event_text` (TEXT): 具体的物流节点描述文本（例：“北京市【朝阳区】，您的快递已由门卫代签收”）。 + +--- + +## 三、 异步缓冲队列表 (`notify_queue`) + +### 1. 表职责方向 +承接业务量暴增时的**削峰填谷**与**断电防丢**任务（本质是实现基于 DB 的 Message Queue）。 +- **流程规范**：触发器把满足条件（如需要给用户弹推送的节点）的事件主键，极速插入本表待命。后台的 `notify-worker.js` (消费者) 轮询查表消费。 + +### 2. 核心字段定义 +* `id` (UUID): 队列任务唯一标识。 +* `waybill_id` (UUID): 运单号，Worker 读取后利用它去关联查询出订单里的 `user_id` 和商品信息。 +* `status_code` (VARCHAR): 通知级别状态。 +* **`dedupe_key` (VARCHAR)**: 防重幂等键。防止因为相同事件重复回调产生两条推送。 +* **`process_status` (VARCHAR)**: 最核心的状态机！ + * `pending`: 等待 Node.js Worker 消费。 + * `processing`: Worker 消费中（乐观锁占用）。 + * `processed`: 拼接业务数据完成，已成功放入推送大表，完美结束。 + * `failed`: 服务异常或订单找不到，抛弃处理。 +* `last_error` (TEXT): 消费报错时的堆栈。 + +--- + +## 四、 最终下发通知表 (`express_notifications`) + +### 1. 表职责方向 +面向客户端推送与“站内信展示”的实体记录表。这里存放的是已经完成业务数据组装（谁买的、买的啥、什么物流状态），只需调用第三方厂商接口往外发的纯粹“信件”内容。 +- **流程规范**：`push-server.js` 轮询此表进行真实推送。 + +### 2. 核心字段定义 +* `id` (UUID): 消息的主键ID。 +* `recipient_id` (UUID): 接收用户的标识 (商城买家ID)。 +* `event_text_safe` (TEXT): 已经组装好且脱敏的安全话术（例如：“[张*]，您的Nike球鞋正在派送中”）。 +* **`send_status / push_status` (VARCHAR)**: 推送服务通道状态机。 + * `pending`: 已产生信件，排队等待网络 POST 请发给 UniPush 云函数。 + * `delivered`: 云函数返回 200，且厂家确认通道收录。 + * `failed`: 网络异常或设备CID已注销失效。 +* `provider_response` (JSONB): 如果推送失败，此处会存储华为/小米等厂商或推服务产生的物理失败原因。 + +--- + +## 五、 设备凭证绑定表 (`push_devices`) + +### 1. 表职责方向 +提供从“商城系统 `user_id`” 到“手机厂家原生通道标识 `cid`” 的 KV 路由映射能力。 +- **业务场景**：用户 App 在启动或大版本更新时，前端会通过 `uni.getPushClientId` 获取本设备的厂商识别码，通过接口上报并 UPSERT 写入此表。 + +### 2. 核心字段定义 +* `id` (UUID): 映射记录主键。 +* `user_id` (UUID): 系统业务逻辑里的用户身份标识。 +* **`cid` (VARCHAR)**: UniPush 2.0 分配在设备当前生命周期的绝对推送识别码（至关重要，一旦清空缓存/重装系统可能会变动，必须持续覆盖更新）。 +* `updated_at` (Timestamp): 用以判断该设备CID的活跃新鲜度。如果一个CID超过1年未更新导致 `push_status` 频繁 `failed`，后台可将其标记为离线沉默用户放弃网络调用。 + +--- + +## 附：业务表拓展准则 (Guidelines) +如果未来需要将这套机制从物流推送拓展至**“拼团成功通知”**或**“特价秒杀通知”**，只需要： +1. 复用 `express_notifications` 表，或者建立同层级类似的 `system_notifications` 表，保留 `push_status` 和 `recipient_id`。 +2. 复用 `push_devices` 路由查找。 +3. 把源头触发器挂载到新的交易表中即可。此五表闭环具备极佳的**水平扩展性**与**极低的中间件运维成本**。 \ No newline at end of file diff --git a/pages/mall/delivery/doc/需求文档/db/绕过RLS的方案(慎用)/20260311_add_rpc_notify_get_order_recipients.sql b/pages/mall/delivery/doc/需求文档(现用)/db/绕过RLS的方案(慎用)/20260311_add_rpc_notify_get_order_recipients.sql similarity index 100% rename from pages/mall/delivery/doc/需求文档/db/绕过RLS的方案(慎用)/20260311_add_rpc_notify_get_order_recipients.sql rename to pages/mall/delivery/doc/需求文档(现用)/db/绕过RLS的方案(慎用)/20260311_add_rpc_notify_get_order_recipients.sql diff --git a/pages/mall/delivery/doc/需求文档/express_tracking_mock_platform.sql b/pages/mall/delivery/doc/需求文档(现用)/express_tracking_mock_platform.sql similarity index 100% rename from pages/mall/delivery/doc/需求文档/express_tracking_mock_platform.sql rename to pages/mall/delivery/doc/需求文档(现用)/express_tracking_mock_platform.sql diff --git a/pages/mall/delivery/doc/需求文档/seed_platform_express_test_data.sql b/pages/mall/delivery/doc/需求文档(现用)/seed_platform_express_test_data.sql similarity index 100% rename from pages/mall/delivery/doc/需求文档/seed_platform_express_test_data.sql rename to pages/mall/delivery/doc/需求文档(现用)/seed_platform_express_test_data.sql diff --git a/pages/mall/delivery/doc/需求文档/simulate_third_party_to_db.sql b/pages/mall/delivery/doc/需求文档(现用)/simulate_third_party_to_db.sql similarity index 100% rename from pages/mall/delivery/doc/需求文档/simulate_third_party_to_db.sql rename to pages/mall/delivery/doc/需求文档(现用)/simulate_third_party_to_db.sql diff --git a/pages/mall/delivery/doc/需求文档/uni-push2_安卓联调与取CID说明.md b/pages/mall/delivery/doc/需求文档(现用)/uni-push2_安卓联调与取CID说明.md similarity index 100% rename from pages/mall/delivery/doc/需求文档/uni-push2_安卓联调与取CID说明.md rename to pages/mall/delivery/doc/需求文档(现用)/uni-push2_安卓联调与取CID说明.md diff --git a/pages/mall/delivery/doc/需求文档/前端字段清单.md b/pages/mall/delivery/doc/需求文档(现用)/前端字段清单.md similarity index 100% rename from pages/mall/delivery/doc/需求文档/前端字段清单.md rename to pages/mall/delivery/doc/需求文档(现用)/前端字段清单.md diff --git a/pages/mall/delivery/doc/需求文档/后台页面设计说明.md b/pages/mall/delivery/doc/需求文档(现用)/后台页面设计说明.md similarity index 100% rename from pages/mall/delivery/doc/需求文档/后台页面设计说明.md rename to pages/mall/delivery/doc/需求文档(现用)/后台页面设计说明.md diff --git a/pages/mall/delivery/doc/需求文档/接口规范.md b/pages/mall/delivery/doc/需求文档(现用)/接口规范.md similarity index 100% rename from pages/mall/delivery/doc/需求文档/接口规范.md rename to pages/mall/delivery/doc/需求文档(现用)/接口规范.md diff --git a/pages/mall/delivery/doc/需求文档/推送与设备需求文档.md b/pages/mall/delivery/doc/需求文档(现用)/推送与设备需求文档.md similarity index 100% rename from pages/mall/delivery/doc/需求文档/推送与设备需求文档.md rename to pages/mall/delivery/doc/需求文档(现用)/推送与设备需求文档.md diff --git a/pages/mall/delivery/doc/需求文档/推送与设备需求文档_含建表附录.md b/pages/mall/delivery/doc/需求文档(现用)/推送与设备需求文档_含建表附录.md similarity index 100% rename from pages/mall/delivery/doc/需求文档/推送与设备需求文档_含建表附录.md rename to pages/mall/delivery/doc/需求文档(现用)/推送与设备需求文档_含建表附录.md diff --git a/pages/mall/delivery/doc/需求文档/数据库对比与修改建议.md b/pages/mall/delivery/doc/需求文档(现用)/数据库对比与修改建议.md similarity index 100% rename from pages/mall/delivery/doc/需求文档/数据库对比与修改建议.md rename to pages/mall/delivery/doc/需求文档(现用)/数据库对比与修改建议.md diff --git a/pages/mall/delivery/doc/需求文档/物流消息推送方案_用户端与商家端.md b/pages/mall/delivery/doc/需求文档(现用)/物流消息推送方案_用户端与商家端.md similarity index 100% rename from pages/mall/delivery/doc/需求文档/物流消息推送方案_用户端与商家端.md rename to pages/mall/delivery/doc/需求文档(现用)/物流消息推送方案_用户端与商家端.md diff --git a/pages/mall/delivery/doc/需求文档/状态映射表.md b/pages/mall/delivery/doc/需求文档(现用)/状态映射表.md similarity index 100% rename from pages/mall/delivery/doc/需求文档/状态映射表.md rename to pages/mall/delivery/doc/需求文档(现用)/状态映射表.md diff --git a/pages/mall/delivery/doc/需求文档/生产表说明_platform_express.md b/pages/mall/delivery/doc/需求文档(现用)/生产表说明_platform_express.md similarity index 100% rename from pages/mall/delivery/doc/需求文档/生产表说明_platform_express.md rename to pages/mall/delivery/doc/需求文档(现用)/生产表说明_platform_express.md diff --git a/pages/mall/delivery/doc/需求文档/缺口与待补充清单.md b/pages/mall/delivery/doc/需求文档(现用)/缺口与待补充清单.md similarity index 100% rename from pages/mall/delivery/doc/需求文档/缺口与待补充清单.md rename to pages/mall/delivery/doc/需求文档(现用)/缺口与待补充清单.md diff --git a/pages/mall/delivery/doc/需求文档/配送模块需求文档.md b/pages/mall/delivery/doc/需求文档(现用)/配送模块需求文档.md similarity index 100% rename from pages/mall/delivery/doc/需求文档/配送模块需求文档.md rename to pages/mall/delivery/doc/需求文档(现用)/配送模块需求文档.md diff --git a/pages/mall/delivery/doc/需求文档/README.md b/pages/mall/delivery/doc/需求文档/README.md deleted file mode 100644 index d4de33a3..00000000 --- a/pages/mall/delivery/doc/需求文档/README.md +++ /dev/null @@ -1,223 +0,0 @@ -# 配送模块文档目录（Mock 三通一达后台联调） - -本目录聚焦“模拟三通一达后台（Mock 承运方 Server）”的联调与测试需求，用于在未签约真实承运方前验证平台侧的 Webhook 接收、验签、幂等、入库与前端时间线展示。 - -## 文档分层（先看什么、后看什么） -- 需求（做什么）：[配送模块需求文档.md](配送模块需求文档.md) -- 页面（后台长什么样）：[后台页面设计说明.md](后台页面设计说明.md) -- 接口（怎么对接）：[接口规范.md](接口规范.md) -- 映射（状态怎么统一）：[状态映射表.md](状态映射表.md) -- 前端契约（怎么展示）：[前端字段清单.md](前端字段清单.md) -- 补齐清单（还缺什么）：[缺口与待补充清单.md](缺口与待补充清单.md) -- 数据库（旧表 vs 新表）：[数据库对比与修改建议.md](数据库对比与修改建议.md) -- 数据库（生产表字段说明）：[生产表说明_platform_express.md](生产表说明_platform_express.md) -- 移动端推送联调（uni-push2）：[uni-push2_安卓联调与取CID说明.md](uni-push2_安卓联调与取CID说明.md) - -## 先读这个：这套文档在解决什么 -你现在要做的是一个“像三通一达一样会产生物流节点并回调的平台外部系统”。真实承运方接口通常需要签约与联调周期，因此先通过 Mock 承运方 Server 把平台侧能力跑通： -- 事件接收：平台接收并处理 Webhook 回调 -- 安全与可靠性：验签、防重放、幂等去重、乱序/重复/延迟处理 -- 数据闭环：事件入库 -> 前端按时间线展示（类似京东/淘宝订单物流关键节点） - -说明：本目录文档服务于“平台系统的一部分”（订单详情页的物流区块、客服/履约排障与对接联调）。 -- 平台端通常需要在订单详情中查看与履约相关的信息（订单号、运单号、承运方、物流时间线、异常记录等）。 -- 本目录不展开订单商品/支付/营销等业务字段，仅覆盖“订单详情里的物流子模块”与其对接/入库/展示规范。 - -## 核心思想（设计原则） -- 以“事件流”为中心：物流展示本质就是一组按时间发生的事件（揽收/中转/在途/派送/签收/异常）。 -- Webhook + 控制面分层：Webhook 用来模拟“承运方回调”，控制面 API 用来“造数据/控节奏/注入故障”。 -- 统一状态码 + 原文并存：平台用 `status_code` 做标签/统计/告警；用 `event_text` 展示承运方原文，并保留 `raw_payload` 便于客服核查。 -- 故障注入必须：重复推送、乱序、延迟、签名错误、缺字段等是外部对接最常见问题，必须在联调阶段覆盖。 - -## 阅读顺序（推荐） -1) 先看 [配送模块需求文档.md](配送模块需求文档.md)：理解 Mock Server 要做什么、有哪些验收与故障注入。 -2) 再看 [后台页面设计说明.md](后台页面设计说明.md)：明确平台后台/商家后台需要哪些页面与最小展示/权限要求。 -3) 再看 [接口规范.md](接口规范.md)： - - Mock Server -> 平台：Webhook 推送格式与验签 - - 平台/测试工具 -> Mock Server：控制面 API（创建运单/追加事件/跑场景/触发推送） -4) 看 [状态映射表.md](状态映射表.md)：明确 `event_code` 如何映射到平台统一 `status_code`。 -5) 看 [前端字段清单.md](前端字段清单.md)：前端时间线组件到底需要哪些字段（以及 `source` 如何标注）。 -6) 最后看 [缺口与待补充清单.md](缺口与待补充清单.md)：把联调验收所需材料补齐，避免漏项。 - -## 快速上手（联调路径） -1) 平台准备一个 Webhook 接收地址：`/webhook/express/status`，并实现 `X-Signature` 验签与幂等去重（按 `event_id`）。 -2) 使用 Mock Server 控制面配置目标：设置 `target_webhook_url`、`client_id`、`secret`。 -3) 创建运单（tracking_no）并运行场景（例如 `standard_delivered`），选择是否立即推送。 -4) 在平台查看：事件是否按预期入库、时间线是否按 `event_time` 展示、异常注入是否触发告警/日志。 - -## 常见问题（为什么这么设计） -- 为什么不直接做真实韵达/圆通对接？因为联调成本高且不可控，Mock 能让你先把平台侧工程能力打牢。 -- 为什么需要控制面 API？因为测试需要“可复现/可回放/可注入”，而不是只等外部推送。 -- 为什么要状态映射？因为不同承运方文案与事件码不稳定，统一状态才能做稳定 UI 与统计。 - -文件列表： -- [配送模块需求文档.md](配送模块需求文档.md)：Mock 承运方 Server 的目标、范围、流程与验收。 -- [后台页面设计说明.md](后台页面设计说明.md)：后台页面结构、权限与最小交互。 -- [接口规范.md](接口规范.md)：Mock Server 控制面 API + Mock -> 平台 Webhook 推送规范。 -- [状态映射表.md](状态映射表.md)：Mock 事件码到平台统一状态映射建议。 -- [前端字段清单.md](前端字段清单.md)：时间线组件所需字段契约与展示规则。 -- [缺口与待补充清单.md](缺口与待补充清单.md)：联调/验收需要补齐的资料与决策项。 -- [数据库对比与修改建议.md](数据库对比与修改建议.md)：旧自营骑手表 vs 第三方快递表的改库建议。 -- [生产表说明_platform_express.md](生产表说明_platform_express.md)：生产环境 `platform_express_*` 三表用途、字段、约束/索引与写入查询建议。 -- [uni-push2_安卓联调与取CID说明.md](uni-push2_安卓联调与取CID说明.md)：安卓端 uni-push2 联调、CID 归属与推送验证闭环。 - -数据库： -- 生产环境（推荐执行）：[express_tracking_platform_upgrade.sql](express_tracking_platform_upgrade.sql) - - 仅包含平台侧 `platform_express_*` 三张表，供生产代码使用。 -- 联调/设计参考（不要用于生产直接落库）：[express_tracking_mock_platform.sql](express_tracking_mock_platform.sql) - - 包含平台侧表 + `mock_*` 测试表（故障注入/回放用），仅用于联调与文档说明。 - -测试/预发环境（不使用 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_` 开头），用于页面联调与排障演示（可随时清理）。 - - 说明：当前脚本会插入 10 条示例运单：其中 9 条 `tracking_no` 以 `TEST_` 开头，另 1 条 `ORDER_PLACED/已下单` 示例运单号为空；并为每条运单插入 1～3 条不等的轨迹事件（幂等，可重复执行）。 - -### Ubuntu 上的 Supabase（测试/预发）怎么执行 - -目标：在 Supabase 上只使用“生产同款”三表进行联调，不创建/不依赖任何 `mock_*` 表。 - -执行顺序（必须按顺序）： -1) 执行建表脚本：[express_tracking_platform_upgrade.sql](express_tracking_platform_upgrade.sql) -2) 执行种子数据脚本：[seed_platform_express_test_data.sql](seed_platform_express_test_data.sql) - -方式 A：Supabase Dashboard（推荐） -- 打开 Supabase 项目 -> SQL Editor -- 分别粘贴并执行以上两个 SQL 文件内容（先建表、后种子） -- 建议使用具备 DDL 权限的角色执行（通常 SQL Editor 以高权限执行） - -方式 B：Ubuntu 通过 psql 执行（适合自动化/脚本化） -1) 安装客户端：`sudo apt-get update && sudo apt-get install -y postgresql-client` -2) 从 Supabase 项目设置里复制连接串（Database -> Connection string），导出环境变量（示例）： - `export DATABASE_URL='postgresql://USER:PASSWORD@HOST:6543/postgres?sslmode=require'` -3) 在仓库根目录执行： - - `psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f pages/mall/delivery/doc/需求文档/express_tracking_platform_upgrade.sql` - - `psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f pages/mall/delivery/doc/需求文档/seed_platform_express_test_data.sql` - -清理测试数据： -- 种子脚本底部自带清理 SQL（按 `tracking_no LIKE 'TEST_%'` + raw `body->>'order_no'` 删除），需要时复制执行即可。 - -### 执行成功后的校验 SQL（建议） - -在 Supabase SQL Editor 执行以下查询，确认数据是否写入成功、事件是否按时间线可查： - -1) 查看全部示例运单（应看到 10 条）： -```sql -select - carrier, - tracking_no, - current_status_code, - current_status_text, - last_event_time, - last_synced_at, - created_at -from public.platform_express_waybills -where order_no like 'ORD_TEST_%' -order by created_at desc; -``` - -2) 按运单统计事件数量（确认每单都有事件）： -```sql -select - w.carrier, - w.tracking_no, - count(e.id) as event_count, - min(e.event_time) as first_event_time, - max(e.event_time) as last_event_time -from public.platform_express_waybills w -left join public.platform_express_tracking_events e - on e.waybill_id = w.id -where w.order_no like 'ORD_TEST_%' -group by w.carrier, w.tracking_no -order by last_event_time desc nulls last; -``` - -3) 查看单个运单时间线（按 event_time 升序）： -```sql -select - event_time, - event_code, - event_text, - status_code, - node_name, - node_location, - source, - dedupe_key -from public.platform_express_tracking_events -where tracking_no = 'TEST_YT_20260206_0002' -order by event_time asc; -``` - -4) 查看原始接收留痕（可选，用于排障/审计）： -```sql -select - received_at, - 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; -``` - -### 如何“伪造第三方推送到数据库”（无需后端） - -如果你暂时没有 webhook 接收服务，但希望测试环境表现得像“第三方已经推送了轨迹”，可以直接写数据库： -- 使用脚本 [simulate_third_party_to_db.sql](simulate_third_party_to_db.sql) - - 会同时写入： - - `platform_express_event_raw`（原始请求留痕/验签/排障） - - `platform_express_tracking_events`（时间线事件） - - `platform_express_waybills`（运单摘要） -- 用法：在 Supabase SQL Editor 打开脚本，修改顶部【参数区】后执行整段。 -- 建议：运单号使用 `TEST_` 前缀，便于按脚本底部清理 SQL 一键删除。 - -### 与数据库其他表是否“相通”（关联与校验） - -这套三表与平台业务表的关键“相通点”是： -- `public.platform_express_waybills.order_id` 外键引用 `public.ml_orders(id)`（订单主表）。 - -因此： -- 如果你的 Supabase（测试/预发）数据库里已经部署了完整商城库（包含 `public.ml_orders`），那么这三表可以直接和订单表联查/联动。 -- 如果你的 Supabase 只是一个“独立的轨迹联调库”，没有 `public.ml_orders`，那么执行建表脚本时会因为外键依赖缺失而失败；此时建议先导入/执行商城主库迁移（让 `ml_orders` 存在），或临时改为仅使用 `order_no` 关联（不建外键），待接入完整主库后再补外键。 - -在 Supabase SQL Editor 里可执行以下校验： - -1) 检查订单表是否存在： -```sql -select to_regclass('public.ml_orders') as ml_orders; -``` - -2) 检查外键是否创建成功（应该能看到 `platform_express_waybills_order_id_fkey` 或类似名称）： -```sql -select - conname as fk_name, - pg_get_constraintdef(c.oid) as fk_def -from pg_constraint c -join pg_class t on t.oid = c.conrelid -join pg_namespace n on n.oid = t.relnamespace -where c.contype = 'f' - and n.nspname = 'public' - and t.relname = 'platform_express_waybills'; -``` - -3) 联查示例（有真实订单时）： -```sql -select - o.id as order_id, - o.order_no, - w.carrier, - w.tracking_no, - w.current_status_code, - w.last_synced_at -from public.ml_orders o -left join public.platform_express_waybills w on w.order_id = o.id -order by o.created_at desc -limit 20; -``` - -建议下一步：在平台侧实现一个可切换的“Mock 数据源”开关（仅测试环境），并在 QA 用例中覆盖重复/乱序/验签失败等注入场景。 diff --git a/server/消息推送文档/README.md b/server/消息推送文档/README.md index c1ca11c8..edde2d3e 100644 --- a/server/消息推送文档/README.md +++ b/server/消息推送文档/README.md @@ -73,6 +73,7 @@ curl -X POST http://localhost:7301/api/v1/notifications -H "Content-Type: applic - push-server 源码： [server/push-server.js](../push-server.js) - 完整全链路数据流转分析：`DELIVERY_NOTIFICATION_DATA_FLOW.md` - 运行与变更记录：`PUSH_SERVER_README.md` +- 消息推送_数据库表结构需求文档：`../../pages/mall/delivery/doc/需求文档(现用)/db/消息推送后台_数据库表结构需求文档.md` - 消息生成Worker服务：`NOTIFY_WORKER_README.md` - 云函数集成指引：`UNI_PUSH2_CLOUD_FUNCTION.md` - 排错指南：`DELIVERY_E2E_TROUBLESHOOTING_20260310.md`