wecom_it_smart_desk/docs/09-部署运维/会议室预定-部署指南.md

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

> **日期**: 2026-07-11  
> **版本**: v2.0（新增报修+指南+二维码+移动端适配）  
> **代码状态**: 待部署  
> **预估部署时间**: 45-60 分钟

---

## 一、部署前置条件

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

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

### 1.3 终端设备
- [ ] 确认小鱼易联终端型号（NE90/NE60 支持 H5 应用，NE2005 需二维码降级）
- [ ] 终端浏览器支持 WebSocket + ES6
- [ ] 小鱼管理后台可访问（配置 H5 应用入口）

---

## 二、部署步骤

### Step 1: 数据库迁移

```bash
# 进入后端容器执行迁移（050 会议室基础表 + 051 报修+指南表）
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('terminal_room_bindings' in tables)   # 应为 True（050）
print('meetingroom_guide' in tables)         # 应为 True（051）
print('meetingroom_repair' in tables)        # 应为 True（051）
"
```

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

在 `.env` 中添加：
```bash
# 终端页面基础URL（用于NE2005二维码生成）
TERMINAL_BASE_URL=https://itsupport.servyou.com.cn/itterminal/
```

在 `docker-compose.yml` 的 backend environment 中已添加：
```yaml
- TERMINAL_BASE_URL=${TERMINAL_BASE_URL:-https://itsupport.servyou.com.cn/itterminal/}
```

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

### Step 3: 后端验证

```bash
# 验证会议室 API（已存在）
curl -sk https://localhost/itportal/meetingroom/list

# 验证报修 API（新增）
curl -sk -X POST https://localhost/itportal/meetingroom/repair \
  -H "Content-Type: application/json" \
  -d '{"terminal_sn":"TEST-SN","meetingroom_id":1,"meetingroom_name":"测试","device_type":"projector","fault_description":"测试报修"}'

# 验证指南 API（新增）
curl -sk https://localhost/itportal/meetingroom/guides

# 验证二维码 API（新增）
curl -sk https://localhost/itportal/meetingroom/terminal/TEST-SN/qrcode -o /tmp/qr.png
file /tmp/qr.png  # 应为 PNG image
```

### Step 4: 终端前端构建与部署

```bash
# 1. 本地构建
cd frontend-terminal
npm install  # 安装新增的 qrcode 依赖
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/
rm -rf dist  # 删除旧 dist（bind mount 铁律：rm后重建必须重启容器）
tar -xzf /tmp/terminal-dist.tar.gz
```

### Step 5: Nginx 配置更新

`nginx/nginx.conf` 已更新，新增以下 location（两个 server 块均已添加）：

```nginx
# 小鱼终端大屏 — /itterminal/
location /itterminal/ {
    alias /usr/share/nginx/html/itterminal/;
    index index.html;
    try_files $uri /itterminal/index.html;
}

# 会议室 API — /itportal/meetingroom/
# 必须在 /itportal/ 静态文件之前匹配（nginx 最长前缀优先）
location /itportal/meetingroom/ {
    proxy_pass http://backend_api;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_connect_timeout 60s;
    proxy_send_timeout    300s;
    proxy_read_timeout    300s;
}
```

`docker-compose.yml` nginx volumes 已添加：
```yaml
- ./frontend-terminal/dist:/usr/share/nginx/html/itterminal:ro
```

重启 Nginx：
```bash
docker compose restart nginx
```

### Step 6: 终端前端验证

```bash
# 验证终端页面可访问
curl -sk https://localhost/itterminal/ | head -5

# 验证 API 代理（通过 nginx 访问后端）
curl -sk https://localhost/itportal/meetingroom/guides

# 验证静态资源
curl -sk -o /dev/null -w "%{http_code}" https://localhost/itterminal/assets/index-*.js
```

---

## 三、小鱼管理后台 H5 应用配置

### 3.1 支持型号确认

| 型号 | H5 应用支持 | 配置方式 |
|------|------------|---------|
| NE90 | ✅ 支持 | 小鱼管理后台配置 H5 应用入口 |
| NE60 | ✅ 支持 | 同上 |
| NE20 | ✅ 支持 | 同上 |
| AE2060 | ✅ 支持 | 同上 |
| ME55S | ⚠️ 部分固件支持 | 需确认固件版本 |
| NE2005 | ❌ 不支持 | 使用二维码降级方案 |

### 3.2 H5 应用入口配置（NE90/NE60/NE20/AE2060）

1. 登录**小鱼易联管理后台**（`https://mt.xylink.com`）
2. 进入 **应用管理 > 自定义应用**
3. 创建新应用：
   - **应用名称**: `IT智能服务台`
   - **应用类型**: H5 网页应用
   - **访问地址**: `https://itsupport.servyou.com.cn/itterminal/{终端SN}/`
   - **展示方式**: 终端主界面快捷入口
4. 推送应用到目标终端
5. 在终端上验证 H5 应用可正常打开

### 3.3 终端 SN 绑定

在管理后台（`/itadmin/`）的终端绑定页面中：
1. 添加终端 SN 与会议室的绑定关系
2. 每个终端 SN 对应一个企微会议室 ID
3. 绑定后终端页面自动加载对应会议室状态

### 3.4 NE2005 二维码降级方案

对于不支持 H5 应用的 NE2005 终端：

1. **生成二维码**：
   ```bash
   # 通过 API 生成终端访问二维码
   curl -sk https://itsupport.servyou.com.cn/itportal/meetingroom/terminal/{SN}/qrcode -o qr.png
   ```
   或直接在浏览器访问：
   `https://itsupport.servyou.com.cn/itportal/meetingroom/terminal/{SN}/qrcode`

2. **打印二维码**：将二维码打印为贴纸（建议尺寸 10×10cm）

3. **张贴二维码**：贴在 NE2005 终端的显眼位置

4. **用户使用流程**：
   - 用户用企业微信/微信扫描二维码
   - 手机浏览器打开终端页面（移动端自适应布局）
   - 可查看会议室状态、预定、报修、查看指南

---

## 四、部署后验证

### 4.1 功能验证清单

| # | 验证项 | 验证方法 | 预期结果 |
|---|--------|---------|---------|
| 1 | 会议室列表 | `GET /itportal/meetingroom/list` | 返回会议室列表 |
| 2 | 会议室状态 | `GET /itportal/meetingroom/{id}/status` | 返回当前状态 |
| 3 | 预定会议室 | `POST /itportal/meetingroom/book` | 创建预定成功 |
| 4 | 终端绑定 | `GET /itportal/meetingroom/terminal/{sn}/binding` | 返回绑定信息 |
| 5 | 终端WS | `WS /ws/terminal/{sn}` | 终端状态实时推送 |
| 6 | **设备报修** | `POST /itportal/meetingroom/repair` | 创建工单+通知管理员 |
| 7 | **指南列表** | `GET /itportal/meetingroom/guides` | 返回指南列表(5条种子) |
| 8 | **指南按类型** | `GET /itportal/meetingroom/guides/projector` | 返回投影仪指南 |
| 9 | **终端二维码** | `GET /itportal/meetingroom/terminal/{sn}/qrcode` | 返回PNG图片 |
| 10 | 终端前端 | 浏览器打开 `/itterminal/{sn}/` | 深色主题大屏页面 |
| 11 | **报修页面** | 终端点击"设备报修"按钮 | 显示报修表单 |
| 12 | **指南页面** | 终端点击"操作指南"按钮 | 显示指南列表+二维码 |
| 13 | **移动端适配** | 手机访问 `/itterminal/{sn}/` | 垂直布局自适应 |
| 14 | 扫码登录 | 终端扫码 | 企微扫码登录成功 |
| 15 | 状态同步 | 终端修改状态 → H5 实时更新 | WS 推送正常 |

### 4.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:status:{room_id}"
```

---

## 五、回滚方案

### 5.1 数据库回滚
```bash
# 回退迁移 051（报修+指南表）
docker compose exec backend alembic downgrade -1

# 完全回退（含 050）
docker compose exec backend alembic downgrade -2
```

### 5.2 后端回滚
```bash
# 恢复 .py 文件（bind mount 自动生效）
git checkout HEAD~1 -- backend/app/api/meetingroom.py
git checkout HEAD~1 -- backend/app/services/repair_service.py
git checkout HEAD~1 -- backend/app/services/meetingroom_service.py
git checkout HEAD~1 -- backend/app/models/meetingroom_guide.py
git checkout HEAD~1 -- backend/app/models/meetingroom_repair.py
git checkout HEAD~1 -- backend/app/schemas/meetingroom.py
git checkout HEAD~1 -- backend/app/config.py
docker compose restart backend
```

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

### 5.4 Nginx 配置回滚
```bash
# 移除 /itterminal/ 和 /itportal/meetingroom/ location 块
docker compose restart nginx
```

---

## 六、新增功能说明

### 6.1 设备报修流程

```
终端用户点击"设备报修"
  → 选择设备类型（投影仪/视频会议/空调/桌椅/网络/其他）
  → 填写故障描述
  → 提交报修
  → 后端创建:
    1. MeetingroomRepair 记录
    2. Conversation（IT工单会话，状态=排队，紧急度=3）
    3. Message（系统消息，含故障描述）
    4. 企微消息通知管理员
    5. WS广播给在线坐席
  → 终端显示"报修已提交"
  → 3秒后自动返回状态页
```

### 6.2 操作指南双模式

- **终端展示**：指南的 `brief` 字段在终端大屏上直接显示简要操作步骤
- **二维码详情**：指南的 `detail_url` 生成二维码，用户手机扫码查看完整文档
- 管理员可在数据库中添加/修改指南内容

### 6.3 NE2005 降级流程

```
NE2005 终端（不支持H5应用）
  → 管理员生成二维码贴纸（API: /itportal/meetingroom/terminal/{sn}/qrcode）
  → 用户手机扫码
  → 手机浏览器打开终端页面（移动端自适应）
  → 功能与终端大屏一致（状态/预定/报修/指南）
```

---

## 七、配置参数速查

| 参数 | 默认值 | 环境变量 |
|------|--------|---------|
| 会议室Token TTL | 6900s | - |
| 会议室列表缓存 | 600s | `MEETINGROOM_CACHE_TTL_ROOMS` |
| 预定缓存 | 30s | `MEETINGROOM_CACHE_TTL_BOOKING` |
| 状态缓存 | 10s | `MEETINGROOM_CACHE_TTL_STATUS` |
| WS重连次数 | 5 | - |
| WS降级轮询间隔 | 10s | - |
| **终端页面URL** | `https://itsupport.servyou.com.cn/itterminal/` | `TERMINAL_BASE_URL` |
| **二维码尺寸** | 300px | API 参数 `size` |
| **二维码缓存** | 1小时 | HTTP `Cache-Control` |

---

## 八、已知限制

1. **企微API时间限制**: 会议室预定查询范围限制 31 天
2. **终端身份**: 管理操作需扫码登录，报修支持匿名提交
3. **WS重连**: 终端断线后自动重连（指数退避），超过 5 次降级为轮询（10s间隔）
4. **NE2005**: 不支持 H5 应用，仅能通过二维码扫码方式使用
5. **指南管理**: 当前通过数据库直接管理，后续可增加管理后台 UI