feat: 2026-07-12~13 全量更新 - AI对话链路改造+H5 v4/v5+坐席端v5+上下文感知诊断+知识库迭代3

## H5 员工端 v4 (2026-07-13 00:48 已部署) - 人工按钮三态文案统一为"人工坐席" - 按钮位置移至发送键和语音按钮上方(垂直堆叠) - 点按钮直接调 store.shakeAgent()，删除 CallAgentModal 弹窗动画 - 截图快捷键提示改为"截图->粘贴：Alt+Shift+A-Ctrl+V ---> Ctrl+V" - 移动端隐藏截图提示(CSS 媒体查询) - AI转人工提示改为"已为您呼叫人工坐席，请稍等!" - 坐席接入提示改为"坐席正在查看您的信息，请等待处理回复！" - 删除"摇铃呼叫坐席"入口和文案 - 删除孤儿组件 MessageList.vue + shake 动画 CSS ## H5 员工端 v5 (2026-07-13 02:08 已部署) - RightPanel v2.1：删除"软件安装"和"资源权限"标签页 - 移除标签栏，智能推荐(DynamicRecommend)直接展示 - 删除 SoftwareDownloads/ApprovalLinks 引用和相关 CSS ## AI 对话链路全栈改造 Phase 1-6 (已部署) - Phase 1: Dify JSON输出 + 后端blocking解析 + 双WS推送 + 错误降级 - Phase 2: 关键词收窄(~25强意图词) + 两级分类Prompt + 删除前端checkApprovalIntent - Phase 3: WS扩展(ai_thinking+dynamic_recommend) + ai_structured气泡 + RightPanel v2 + 选项回传 - Phase 4: VisionService接入 + 图片消息融合(5秒窗口) + 降级策略 - Phase 5: 坐席端ai_thinking指示器 + ai_structured/byod_card渲染 + handleNewMessage修复 - Phase 6: diagnosis_stage(6值) + response_time_ms计时 + 慢响应告警(>10s) ## 坐席端 v5 (2026-07-13 01:38 已部署) - ai_structured/byod_card 只读渲染 - AI思考指示器 UI - handleNewMessage 透传 msg_type/extra_data 修复 - 布局优化v2.0: QuickReplyBar L1+L2悬浮 + ReplyBox左右分区 + 右栏260/560px切换 - 键盘快捷键v2.3: 纯数字路由 + ESC分层撤销 + Shift+Space用event.code ## 上下文感知智能诊断闭环 (2026-07-12 已部署) - 三层诊断(API→Script→AI) + 三段排队(VIP→info_locked→not locked) - 答题插队 + 五场景关闭 - 迁移052(6表+6列) + queue_service + quiz_service + closing_service - H5前端: QueueWaiting + RightPanel双Tab + InputBar三态 + ResolveConfirmCard - 坐席前端: pending_close结单流程 + 信息锁定(Dify步骤完成+有效回答率≥70%) ## 知识库迭代3 (2026-07-12 已部署) - 分诊交互(H5+坐席+Dify独立应用) - 拓扑预览(ECharts只读) - 代答排除(4种匹配器: keyword/regex/intent/category) - 迁移051 + 44文件43测试通过 ## 后端变更 - 6个Python文件改造(h5_ai_task.py/h5.py/ai_service.py/closing_service.py等) - funny_phrase_service.py: shake/connected/keyword 默认文案更新 - session_service.py: 企微消息文案同步 - 新增: queue.py/quiz.py/triage.py/exclusion_rules.py 等API端点 - 新增: diagnostic.py/quiz.py/triage_session.py 等模型 - 新增: closing_service/queue_service/quiz_service/triage_service 等服务 ## 文档更新 - CHANGELOG.md: 新增 [未发布] 区全部变更记录 - 项目管理主文档 v2.5: 新增v0.7.3版本 + 已完成看板 + 最近搞定 - 版本记录: 新增v0.7.3条目 - AI对话链路实施计划: Phase 1-6 全部标记✅已实施 - 新增架构图/时序图/类图(mermaid) ## 部署路径修正 - 服务器项目根路径: /opt/wecom-it-desk/ - 所有前端dist均为ro bind mount，只能在宿主机源路径操作 - 服务器nginx /h5/ 是静态文件服务(非proxy_pass) - elFinder上传二进制不可靠(MD5不匹配)，改用base64分块上传
2026-07-13 02:17:03 +08:00
parent bea288e414
commit 449c6d4875
176 changed files with 46637 additions and 4805 deletions
@@ -1,11 +1,48 @@
 # 智能IT服务台 - 版本记录

-> **最后更新**：2026-07-05
+> **最后更新**：2026-07-13

 ---

 ## 版本历史

+### v0.7.3 (2026-07-12~13)
+
+**更新内容**：
+
+1. **AI 对话链路全栈改造 Phase 1-6**（#59-#69）
+   - Dify Prompt JSON 输出 + 后端 blocking + JSON 解析 + 双 WS 推送
+   - 审批关键词收窄（~40→~25）+ 两级分类 Prompt v4.0 + 删除前端 checkApprovalIntent
+   - WS 扩展（ai_thinking + dynamic_recommend）+ MessageBubble ai_structured 渲染 + RightPanel v2
+   - VisionService 接入（图片分析 + 5秒消息融合）+ 降级策略
+   - 坐席端 ai_thinking 指示器 + ai_structured/byod_card 渲染
+   - diagnosis_stage 字段 + response_time_ms 计时 + 慢响应告警
+
+2. **上下文感知智能诊断→修复闭环**
+   - 三层诊断（API→Script→AI）+ 三段排队（VIP→info_locked→not locked）
+   - 答题插队 + 五场景关闭 + 迁移 052（6表+6列）
+
+3. **坐席端布局优化 v2.0**
+   - QuickReplyBar L1+L2 悬浮 / ReplyBox 左右分区 / 右栏 260↔560px
+   - 键盘快捷键 v2.3（纯数字路由 / ESC 分层撤销 / IME 守卫）
+
+4. **知识库迭代 3**
+   - 分诊交互 + 拓扑预览（ECharts）+ 代答排除（4种匹配器）+ 迁移 051
+
+5. **H5 v4 人工坐席交互改造**（#116）
+   - 三态文案统一"人工坐席" / 按钮位置上移 / 删除 CallAgentModal 弹窗
+   - 截图提示改版 / 移动端 CSS 隐藏 / DB 同步 funny_phrases 表
+
+6. **部署路径修正**
+   - 确认服务器项目根路径 `/opt/wecom-it-desk/`
+   - 所有前端 dist 均为 ro bind mount，只能在宿主机源路径操作
+
+**部署方式**：后端 `docker compose restart backend` / 前端宿主机 tar 解压 + `nginx -s reload`
+
+**验证**：JS hash 更新确认 / JS 包内容检查 / API 200 / Nginx healthy
+
+---
+
 ### v0.7.1 (2026-06-23)

 **更新内容**：
@@ -40,6 +77,11 @@

 ## 问题修复记录

+### 2026-07-13
+
+- H5 v4 部署路径修正（`/opt/wecom-it-desk/frontend-h5/dist` ro bind mount）
+- 服务器 Docker 挂载配置与本地仓库不一致问题定位
+
 ### 2026-07-05

 - Nginx upstream 配置修复
@@ -1,9 +1,9 @@
 # 会议室预定-小鱼易联终端 部署指南

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

 ---

@@ -15,14 +15,15 @@
 - [ ] 确认会议室 `meetingroom_id` 列表

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

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

 ---

@@ -31,7 +32,7 @@
 ### Step 1: 数据库迁移

 ```bash
-# 进入后端容器
+# 进入后端容器执行迁移（050 会议室基础表 + 051 报修+指南表）
 docker compose exec backend alembic upgrade head

 # 验证新表
@@ -40,21 +41,23 @@ 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
+print('terminal_room_bindings' in tables)   # 应为 True（050）
+print('meetingroom_guide' in tables)         # 应为 True（051）
+print('meetingroom_repair' in tables)        # 应为 True（051）
 "
 ```

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

-在 `docker-compose.yml` 中添加：
+在 `.env` 中添加：
+```bash
+# 终端页面基础URL（用于NE2005二维码生成）
+TERMINAL_BASE_URL=https://itsupport.servyou.com.cn/itterminal/
+```
+
+在 `docker-compose.yml` 的 backend environment 中已添加：
 ```yaml
-backend:
-  environment:
-    - WECOM_MEETINGROOM_SECRET=<your_secret>
-    - MEETINGROOM_CACHE_TTL_ROOMS=600
-    - MEETINGROOM_CACHE_TTL_BOOKING=30
-    - MEETINGROOM_CACHE_TTL_STATUS=10
+- TERMINAL_BASE_URL=${TERMINAL_BASE_URL:-https://itsupport.servyou.com.cn/itterminal/}
 ```

 重启后端：
@@ -65,23 +68,28 @@ docker compose up -d backend
 ### Step 3: 后端验证

 ```bash
-# 验证 API 端点注册
-curl -sk https://localhost/api/itportal/meetingroom/rooms \
-  -H "Authorization: Bearer $TOKEN"
+# 验证会议室 API（已存在）
+curl -sk https://localhost/itportal/meetingroom/list

-# 验证 WS 端点
-wscat -c "wss://localhost/ws/terminal/TEST-SN-001"
+# 验证报修 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/api/itportal/admin/terminal-bindings \
-  -H "Authorization: Bearer $ADMIN_TOKEN"
+# 验证指南 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: 终端前端部署
+### Step 4: 终端前端构建与部署

 ```bash
 # 1. 本地构建
 cd frontend-terminal
+npm install  # 安装新增的 qrcode 依赖
 npm run build

 # 2. 打包
@@ -93,50 +101,139 @@ python C:\Users\simon\.workbuddy\skills\jumpserver-ops\scripts\jms_ops.py \

 # 4. 服务器解压
 cd /opt/wecom-it-desk/frontend-terminal/
+rm -rf dist  # 删除旧 dist（bind mount 铁律：rm后重建必须重启容器）
 tar -xzf /tmp/terminal-dist.tar.gz
+```

-# 5. Nginx 配置
-# 在 nginx.conf 中添加：
+### Step 5: Nginx 配置更新
+
+`nginx/nginx.conf` 已更新，新增以下 location（两个 server 块均已添加）：
+
+```nginx
+# 小鱼终端大屏 — /itterminal/
 location /itterminal/ {
-    alias /usr/share/nginx/html/terminal/;
-    try_files $uri $uri/ /itterminal/index.html;
+    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;
 }
 ```

-### Step 5: Nginx 重启
+`docker-compose.yml` nginx volumes 已添加：
+```yaml
+- ./frontend-terminal/dist:/usr/share/nginx/html/itterminal:ro
+```

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

-### Step 6: H5 端入口验证
+### Step 6: 终端前端验证

-H5 端已内置会议室入口（`MeetingroomView.vue`），无需额外部署。
-验证：
 ```bash
-curl -sk https://localhost/ith5/ | grep -o 'meetingroom'
+# 验证终端页面可访问
+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 功能验证清单
+### 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 /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 推送正常 |
+| 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 推送正常 |

-### 3.2 Redis 缓存验证
+### 4.2 Redis 缓存验证

 ```bash
 # 会议室 token
@@ -145,33 +242,37 @@ 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 数据库回滚
+### 5.1 数据库回滚
 ```bash
-# 回退迁移 050
+# 回退迁移 051（报修+指南表）
 docker compose exec backend alembic downgrade -1
+
+# 完全回退（含 050）
+docker compose exec backend alembic downgrade -2
 ```

-### 4.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
 ```

-### 4.3 前端回滚
+### 5.3 前端回滚
 ```bash
 # 恢复旧 dist
 mv /opt/wecom-it-desk/frontend-terminal/dist /opt/wecom-it-desk/frontend-terminal/dist.bak
@@ -179,24 +280,52 @@ mv /opt/wecom-it-desk/frontend-terminal/dist /opt/wecom-it-desk/frontend-termina
 docker compose restart nginx
 ```

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

 ---

-## 五、已知限制
+## 六、新增功能说明

-1. **企微API时间限制**: 会议室预定查询范围限制 31 天
-2. **终端身份**: 当前按访客可查看设计，管理操作需扫码登录
-3. **WS重连**: 终端断线后自动重连（指数退避），超过 5 次降级为轮询（10s间隔）
-4. **缓存TTL**: 会议室列表 600s / 预定 30s / 状态 10s，手动刷新可跳过缓存
+### 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）
+  → 用户手机扫码
+  → 手机浏览器打开终端页面（移动端自适应）
+  → 功能与终端大屏一致（状态/预定/报修/指南）
+```

 ---

-## 六、配置参数速查
+## 七、配置参数速查

 | 参数 | 默认值 | 环境变量 |
 |------|--------|---------|
@@ -206,3 +335,16 @@ docker compose restart nginx
 | 状态缓存 | 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