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

# 实时推送功能部署指南

## 📋 部署清单

### 1. 后端部署

```bash
# 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. 小程序部署

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

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

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

### 3. Web 端部署

```bash
# 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 配置

```bash
# 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 端点

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

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

### 2. 检查 Redis 连接

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

# 应该返回：
# PONG
```

### 3. 检查 WebSocket 连接

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

```javascript
// 检查 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端通知铃铛不更新，需要手动刷新

**排查步骤**：
```bash
# 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调用错误

```bash
# 查看微信通知相关日志
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 路由：

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

### 2. 禁用微信推送

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

```env
WECHAT_APP_ID=
WECHAT_APP_SECRET=
```

### 3. 重启服务

```bash
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` 返回正常
- [ ] 创建测试订单，检查是否收到实时通知