# 会议室预定-小鱼易联终端 部署指南

> **日期**: 2026-07-11  
> **版本**: v1.0  
> **代码状态**: 40/40 测试通过，待部署  
> **预估部署时间**: 30-45 分钟

---

## 一、部署前置条件

### 1.1 企微配置
- [x] 企微会议室 Secret 已申请
- [x] 企微会议室已在管理后台创建
- [ ] 确认会议室 `meetingroom_id` 列表

### 1.2 服务器环境
- [ ] PostgreSQL 可用（需执行 Alembic 迁移）
- [ ] Redis 可用（会议室缓存依赖）
- [ ] Nginx 可用（终端前端静态文件）
- [ ] Docker Compose 可用

### 1.3 终端设备
- [ ] 确认小鱼易联终端型号（当前按浏览器方案设计）
- [ ] 终端浏览器支持 WebSocket + ES6

---

## 二、部署步骤

### Step 1: 数据库迁移

```bash
# 进入后端容器
docker compose exec backend alembic upgrade head

# 验证新表
docker compose exec backend python -c "
from app.database import engine
from sqlalchemy import inspect
insp = inspect(engine)
tables = insp.get_table_names()
print('meetingroom_booking_snapshots' in tables)  # 应为 True
print('terminal_room_bindings' in tables)          # 应为 True
"
```

### Step 2: 环境变量配置

在 `docker-compose.yml` 中添加：
```yaml
backend:
  environment:
    - WECOM_MEETINGROOM_SECRET=<your_secret>
    - MEETINGROOM_CACHE_TTL_ROOMS=600
    - MEETINGROOM_CACHE_TTL_BOOKING=30
    - MEETINGROOM_CACHE_TTL_STATUS=10
```

重启后端：
```bash
docker compose up -d backend
```

### Step 3: 后端验证

```bash
# 验证 API 端点注册
curl -sk https://localhost/api/itportal/meetingroom/rooms \
  -H "Authorization: Bearer $TOKEN"

# 验证 WS 端点
wscat -c "wss://localhost/ws/terminal/TEST-SN-001"

# 验证管理端绑定 API
curl -sk https://localhost/api/itportal/admin/terminal-bindings \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

### Step 4: 终端前端部署

```bash
# 1. 本地构建
cd frontend-terminal
npm run build

# 2. 打包
tar -czf terminal-dist.tar.gz dist/

# 3. 上传到服务器（通过堡垒机）
python C:\Users\simon\.workbuddy\skills\jumpserver-ops\scripts\jms_ops.py \
  pack-upload ./terminal-dist.tar.gz /opt/wecom-it-desk/frontend-terminal/

# 4. 服务器解压
cd /opt/wecom-it-desk/frontend-terminal/
tar -xzf /tmp/terminal-dist.tar.gz

# 5. Nginx 配置
# 在 nginx.conf 中添加：
location /itterminal/ {
    alias /usr/share/nginx/html/terminal/;
    try_files $uri $uri/ /itterminal/index.html;
}
```

### Step 5: Nginx 重启

```bash
docker compose restart nginx
```

### Step 6: H5 端入口验证

H5 端已内置会议室入口（`MeetingroomView.vue`），无需额外部署。
验证：
```bash
curl -sk https://localhost/ith5/ | grep -o 'meetingroom'
```

---

## 三、部署后验证

### 3.1 功能验证清单

| # | 验证项 | 验证方法 | 预期结果 |
|---|--------|---------|---------|
| 1 | 会议室列表 | `GET /api/itportal/meetingroom/rooms` | 返回会议室列表 |
| 2 | 会议室状态 | `GET /api/itportal/meetingroom/rooms/{id}/status` | 返回当前状态 |
| 3 | 预定会议室 | `POST /api/itportal/meetingroom/bookings` | 创建预定成功 |
| 4 | 时间线 | `GET /api/itportal/meetingroom/rooms/{id}/timeline` | 返回当日时间线 |
| 5 | 终端绑定 | `POST /api/itportal/admin/terminal-bindings` | 绑定终端-会议室 |
| 6 | 终端WS | `WS /ws/terminal/{sn}` | 终端状态实时推送 |
| 7 | 终端前端 | 浏览器打开 `/itterminal/` | 深色主题大屏页面 |
| 8 | H5入口 | H5 端点击会议室入口 | 跳转 MeetingroomView |
| 9 | 扫码登录 | 终端扫码 | 企微扫码登录成功 |
| 10 | 状态同步 | 终端修改状态 → H5 实时更新 | WS 推送正常 |

### 3.2 Redis 缓存验证

```bash
# 会议室 token
redis-cli -a $REDIS_PASSWORD get wecom:meetingroom_access_token

# 会议室列表缓存
redis-cli -a $REDIS_PASSWORD get meetingroom:room_list

# 预定缓存
redis-cli -a $REDIS_PASSWORD get "meetingroom:booking:{room_id}:{date}"

# 状态缓存
redis-cli -a $REDIS_PASSWORD get "meetingroom:status:{room_id}"
```

---

## 四、回滚方案

### 4.1 数据库回滚
```bash
# 回退迁移 050
docker compose exec backend alembic downgrade -1
```

### 4.2 后端回滚
```bash
# 恢复 .py 文件（bind mount 自动生效）
git checkout HEAD~1 -- backend/app/api/meetingroom.py
git checkout HEAD~1 -- backend/app/services/meetingroom_service.py
# ... 其他文件
docker compose restart backend
```

### 4.3 前端回滚
```bash
# 恢复旧 dist
mv /opt/wecom-it-desk/frontend-terminal/dist /opt/wecom-it-desk/frontend-terminal/dist.bak
# 恢复上一版本
docker compose restart nginx
```

### 4.4 Nginx 配置回滚
```bash
# 移除 /itterminal/ location 块
docker compose restart nginx
```

---

## 五、已知限制

1. **企微API时间限制**: 会议室预定查询范围限制 31 天
2. **终端身份**: 当前按访客可查看设计，管理操作需扫码登录
3. **WS重连**: 终端断线后自动重连（指数退避），超过 5 次降级为轮询（10s间隔）
4. **缓存TTL**: 会议室列表 600s / 预定 30s / 状态 10s，手动刷新可跳过缓存

---

## 六、配置参数速查

| 参数 | 默认值 | 环境变量 |
|------|--------|---------|
| 会议室Token TTL | 6900s | - |
| 会议室列表缓存 | 600s | `MEETINGROOM_CACHE_TTL_ROOMS` |
| 预定缓存 | 30s | `MEETINGROOM_CACHE_TTL_BOOKING` |
| 状态缓存 | 10s | `MEETINGROOM_CACHE_TTL_STATUS` |
| WS重连次数 | 5 | - |
| WS降级轮询间隔 | 10s | - |