dingdanquanliucheng/deploy/实时推送部署指南.md

实时推送功能部署指南

📋 部署清单

1. 后端部署

# 1.1 进入后端目录
cd /path/to/dingdanquanliucheng/backend

# 1.2 安装依赖（redis 已在 requirements.txt 中）
pip install -r requirements.txt

# 1.3 确保 Redis 服务已安装并运行
# 检查 Redis 状态
redis-cli ping
# 如果返回 PONG 表示 Redis 正常运行

# 如果 Redis 未安装，可以使用以下命令安装（Ubuntu/Debian）：
# sudo apt update
# sudo apt install redis-server
# sudo systemctl start redis
# sudo systemctl enable redis

# 1.4 重启后端服务
# 如果使用 systemd：
sudo systemctl restart order-flow

# 如果使用 uvicorn 直接运行：
uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 --reload

2. 小程序部署

# 2.1 进入小程序目录
cd /path/to/dingdanquanliucheng/frontend/mini-app

# 2.2 使用微信开发者工具编译上传
# 注意：subscribe.js 中的模板ID已配置完成，无需修改

# 2.3 在微信公众平台确认以下模板已添加：
# - 订单状态变更通知
# - 订单待审批通知
# - 物流任务分配通知
# - 物流超时提醒
# - 欠款提醒
# - 客户沉默提醒

3. Web 端部署

# 3.1 编译管理员端
cd /path/to/dingdanquanliucheng/frontend/web-admin
npm run build
# 将 dist 目录部署到 dda.gaowenbu.cn

# 3.2 编译业务员端
cd /path/to/dingdanquanliucheng/frontend/web-sales
npm run build
# 将 dist 目录部署到 ddy.gaowenbu.cn

4. Nginx 配置

# 4.1 复制 Nginx 配置文件
sudo cp /path/to/dingdanquanliucheng/deploy/dda.gaowenbu.cn.conf /www/server/panel/vhost/nginx/
sudo cp /path/to/dingdanquanliucheng/deploy/ddy.gaowenbu.cn.conf /www/server/panel/vhost/nginx/

# 4.2 测试 Nginx 配置
sudo nginx -t

# 4.3 重新加载 Nginx
sudo nginx -s reload

---

🔍 验证部署

1. 检查后端 WebSocket 端点

# 访问 WebSocket 状态接口
curl https://dda.gaowenbu.cn/ws/status

# 应该返回：
# {"active_users":0,"connections":{}}

2. 检查 Redis 连接

# 在服务器上执行
redis-cli ping

# 应该返回：
# PONG

3. 检查 WebSocket 连接

打开浏览器开发者工具（F12），在 Console 中执行：

// 检查 WebSocket 是否连接
const ws = new WebSocket('wss://dda.gaowenbu.cn/ws/reminders?token=YOUR_TOKEN');
ws.onopen = () => console.log('连接成功');
ws.onmessage = (e) => console.log('收到消息:', e.data);
ws.onerror = (e) => console.error('连接错误:', e);

---

📊 功能说明

实时推送流程

业务事件触发
    ↓
event_bus.emit() 创建提醒记录
    ↓
┌───────────────────────────────────────┐
│  后台线程异步执行：                      │
│  1. Redis Pub/Sub → WebSocket 推送     │
│  2. 微信订阅消息 API → 小程序推送       │
└───────────────────────────────────────┘
    ↓
┌───────────────────────────────────────┐
│  客户端接收：                           │
│  - Web端：WebSocket + 声音 + 桌面通知   │
│  - 小程序：微信服务通知 + Tab角标        │
└───────────────────────────────────────┘

触发场景

场景	触发位置	通知对象
订单创建	order_service.create_order	管理层
订单审批通过	order_service.approve_order	业务员
订单审批拒绝	order_service.approve_order	业务员
订单发厂	order_service.confirm_supplier_text	业务员
物流任务分配	logistics_service.create_task	司机
物流状态更新	logistics_service._change_task_status	业务员+管理层
欠款超期	reminder_service.check_arrears	业务员
物流超时	reminder_service.check_logistics_timeout	业务员
沉默客户	reminder_service.check_inactive_customers	业务员

---

⚠️ 故障排查

1. WebSocket 连接失败

症状：Web端通知铃铛不更新，需要手动刷新

排查步骤：

# 1. 检查 Nginx 配置是否包含 WebSocket 代理
grep -r "location /ws/" /www/server/panel/vhost/nginx/

# 2. 检查后端是否启动
curl https://dda.gaowenbu.cn/health

# 3. 检查 Redis 是否运行
redis-cli ping

# 4. 查看后端日志
tail -f /path/to/backend/logs/app.log | grep -i "websocket\|redis"

2. 小程序收不到推送

症状：小程序没有收到微信服务通知

排查步骤：

1. 检查用户是否授权了订阅消息
2. 检查 .env 中的 WECHAT_APP_ID 和 WECHAT_APP_SECRET 是否正确
3. 检查模板ID是否与微信公众平台一致
4. 查看后端日志是否有微信API调用错误

# 查看微信通知相关日志
tail -f /path/to/backend/logs/app.log | grep -i "wechat\|subscribe"

3. Tab 角标不显示

症状：小程序 Tab 上没有显示数字

排查步骤：

1. 检查 badge.js 是否正确引入
2. 检查 API 接口是否正常返回数据
3. 在小程序开发者工具中查看 Console 日志

---

🔄 回滚方案

如果实时推送功能出现问题，可以快速回滚：

1. 禁用 WebSocket（保留原有功能）

编辑 backend/app/main.py，注释掉 WebSocket 路由：

# 挂载 WebSocket 路由（不通过 api_router，直接挂载）
# app.include_router(ws_router)  # 注释此行

2. 禁用微信推送

编辑 backend/.env，清空微信配置：

WECHAT_APP_ID=
WECHAT_APP_SECRET=

3. 重启服务

sudo systemctl restart order-flow

---

📝 配置文件清单

文件	说明	是否需要修改
backend/.env	后端环境变量	✅ 已配置完成
backend/app/core/pubsub.py	Redis Pub/Sub	❌ 无需修改
backend/app/api/ws.py	WebSocket 端点	❌ 无需修改
backend/app/services/event_bus.py	事件总线	❌ 无需修改
frontend/mini-app/utils/subscribe.js	订阅消息授权	❌ 已配置模板ID
frontend/mini-app/utils/badge.js	Tab角标管理	❌ 无需修改
frontend/web-admin/src/utils/websocket.js	Web端WebSocket	❌ 无需修改
frontend/web-sales/src/utils/websocket.js	Web端WebSocket	❌ 无需修改
deploy/dda.gaowenbu.cn.conf	Nginx配置	✅ 已添加WebSocket代理
deploy/ddy.gaowenbu.cn.conf	Nginx配置	✅ 已添加WebSocket代理

---

✅ 部署完成检查清单

• Redis 服务运行正常
• 后端服务重启完成
• Nginx 配置已更新并重新加载
• Web端已重新编译并部署
• 小程序已上传新版本
• 访问 https://dda.gaowenbu.cn/ws/status 返回正常
• 创建测试订单，检查是否收到实时通知