# 消息推送与物流发货后台 —— 需求与架构文档总览

> **更新日期**：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`