3.5 KiB
3.5 KiB
消息推送与物流发货后台 —— 需求与架构文档总览
更新日期：2026年03月16日 核心职责：管理商城发货物流对接、Webhook状态更新接受、基于消息队列模型的异步应用内推送（UniPush 2.0）。
本目录包含了本系统从“接收物流消息”到“完成终端设备 APP 推送”的全核心链路设计与需求规范。我们采用了免 Redis 的高可靠去中心化架构（基于 PostgreSQL Transactional Outbox 模式）。
🎯 必读核心文档（从 0 到 1 快速理解本套系统）
- 📂 数据库表结构设计（全系统基石）
- 消息推送后台_数据库表结构需求文档.md (核心！详述了从快递节点到通知排队流转经过的 5 张关键表)
- 🔄 数据流向与演进架构
- 见
server/消息推送文档/DELIVERY_NOTIFICATION_DATA_FLOW.md(全局架构数据泳道流转图与为什么不使用 Redis 的技术选型解说)
- 见
- 📦 业务推送机制文档
- 物流消息推送方案_用户端与商家端.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（指导客户端童鞋如果提取各厂手机独立推送凭证）
- 后台页面结构：后台页面设计说明.md
- 数据流与展示字段：前端字段清单.md
- 前后端快递状态映射：状态映射表.md (如：快递参数如何转为本系统枚举类型代码)
3. 测试与沙盘联调 (Mock 专属)
因接入第三方（如快递100）需签约，本系统也内置了一套模拟联调能力。
- 接口规范.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