Simon
bea288e414
== 已部署上线 (9项) == - 代办事项真实数据源集成 (企微审批API 8bug修复链) - H5/坐席端 Logo样式统一+绿色背景 - 视频引导页修复 (localStorage key v2) - 坐席端 v9 Vue版本修复 (ElMessage._context) - 截图按钮 v10 修复 (getDisplayMedia user gesture) - 扫码样式恢复+H5扫码登录跳转修复 - H5截图快捷键提示 == 代码完成待部署 (3项) == - 知识迭代3Bug修复 (#8 POST端点/#7 MERGE幂等/#6 过期检查) - 会议室预定-小鱼易联终端 (40文件, 40/40测试通过) - IT资产升级审批推送 (asset_service.py) == 需求文档 (2项) == - 坐席端AI辅助消息框-PRD (4项新功能确认) - 坐席端布局优化建议 v2.0 (7天计划) == 新增文档 == - 日报-2026-07-11.md - 知识迭代Bug修复报告-20260711.md - 会议室预定-部署指南.md - CHANGELOG.md 更新 == 测试 == - test_todo_integration.py: 40/40 - test_meetingroom.py: 40/40 - test_bugfix_ki_suggestions.py: 21/21
209 lines
5.4 KiB
Markdown
209 lines
5.4 KiB
Markdown
# 会议室预定-小鱼易联终端 部署指南
|
|
|
|
> **日期**: 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 | - |
|