Files
wecom_it_smart_desk/CHANGELOG.md
Simon 449c6d4875 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

328 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 变更日志 (Changelog)
本项目的所有重要变更都会记录在此文件。
格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/),
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
## [未发布] - 2026-07-13
### 🚀 功能增强 (Features)
#### Agent 坐席端 v5 — AI 结构化消息 + 思考指示器(2026-07-13 01:38 部署)
- **ai_structured 只读渲染**:坐席端 `MessageBubble.vue` 新增 AI 结构化消息渲染分支(文字 + 只读选项标签 + 推荐摘要)
- **byod_card 渲染**:补全之前缺失的 `byod_card` 消息类型渲染分支
- **AI 思考指示器**`ChatArea.vue` 新增 `aiThinkingText` 计算属性 + 脉冲动画 CSS,坐席可实时看到 AI 正在思考
- **handleNewMessage 透传修复**:修复 `msg_type``extra_data` 硬编码为 `'text'` 的问题,正确透传消息类型
- **ai_thinking 双推**:后端 `ai_thinking` WS 消息同时推送给员工端和坐席端
- 验证:JS hash `index-2BTn4SZz.js` ✅,5 容器全部 healthy ✅
#### H5 员工端 v4 — 人工坐席交互改造(#116, 2026-07-13 部署)
- **人工按钮三态文案统一**为"人工坐席"(原"人工(需更多对话)"等多态文案)
- **按钮位置调整**:移至发送键 + 语音转文字图标上方(`.input-bar__controls` 容器内垂直堆叠)
- **删除 CallAgentModal 弹窗动画**:点击按钮直接调用 `store.shakeAgent()`,无中间浮窗
- **截图快捷键提示改版**:改为"截图->粘贴:Alt+Shift+A-Ctrl+V ---> Ctrl+V",排列在工具图标后
- **移动端隐藏截图提示**CSS `@media (max-width: 768px)` 媒体查询
- **AI 转人工提示**:"已为您呼叫人工坐席,请稍等!"(原"少主,折旧为您去摇人,稍等….")
- **坐席接入提示**:"坐席正在查看您的信息,请等待处理回复!"(原"坐席已为您服务,请稍后….")
- **删除"摇铃呼叫坐席"入口和文案**
- **清理孤儿组件** `MessageList.vue`(全项目无引用)
- **删除 CSS** `@keyframes shake` 动画及相关变量
- **DB 同步**PostgreSQL `funny_phrases` 表 3 条记录(shake/connected/keywordUPDATE
- 验证:JS hash `index-eQVEQIDL.js``index-B6dzwk-X.js` ✅,JS 包内容检查通过
#### AI 对话链路全栈改造 Phase 1-6#59-#69, 2026-07-13 01:38 生产部署)
- **Phase 1 ✅**Dify Prompt JSON 输出 + 后端 blocking + JSON 解析 + 双 WS 推送 + 错误降级(30s 超时 / 15s still_thinking
- **Phase 2 ✅**:审批关键词收窄(~40→~25 强意图词)+ 两级分类 Prompt v4.0(4粗→12细)+ 删除前端 `checkApprovalIntent()`
- **Phase 3 ✅**WS 扩展(`ai_thinking` + `dynamic_recommend`+ `MessageBubble` ai_structured 渲染 + `RightPanel` v2(手风琴 + 底部标签)+ `DynamicRecommend.vue`(新建)+ `sendOptionSelect` WS 回传
- **Phase 4 ✅**`VisionService` 接入(`_enrich_image_content` + `_fetch_recent_employee_text` 5秒融合)+ 图片消息跳过关键词拦截 + 降级策略
- **Phase 5 ✅**:坐席端 `ai_thinking` WS + 指示器 UI + `MessageBubble` ai_structured/byod_card 渲染 + `handleNewMessage` 修复
- **Phase 6 ✅**`diagnosis_stage` 字段(6种值)→ `closing_service` 辅助方法 + `response_time_ms` 计时 + 慢响应告警(>10s)
#### 上下文感知智能诊断→修复闭环(2026-07-12 部署)
- **三层诊断**API → Script → AI 递进式诊断
- **三段排队**VIP → info_locked → not locked
- **答题插队**:员工答题期间优先处理
- **五场景关闭**:五种场景自动关闭会话
- 后端:迁移 0526表+6列)/ `queue_service` / `quiz_service` / `closing_service` / `seed_quiz` / 每日3:00定时生成
- H5 前端:`QueueWaiting` / `RightPanel` 双Tab / `InputBar` 三态"人工"按钮 / `ResolveConfirmCard`
- 坐席前端:`pending_close` 结单流程;信息锁定(Dify 步骤完成 + 有效回答率≥70%)
#### 坐席端布局优化 v2.02026-07-12 部署)
- 8 新增 + 7 修改 + 3 删除
- `QuickReplyBar` L1+L2 悬浮;`ReplyBox` 左右分区;右栏 260↔560px 模式切换
- **键盘快捷键 v2.3**:纯数字 1~9 上下文路由(AI/L1/L2);ESC 分层撤销;Shift+Space 用 `event.code` 匹配(不受 IME 影响)
- `useKeyboardShortcuts.ts` 中央管理器,IME/ScreenCapture 守卫
#### 知识库迭代 3 功能(2026-07-12 部署)
- 分诊交互(H5+坐席+Dify 独立应用)
- 拓扑预览(ECharts 只读)
- 代答排除(4种匹配器)
- 44 文件 43 测试通过;迁移 051
### 🐛 缺陷修复 (Bug Fixes)
- 修复:代办事项企微审批 API 返回空列表(8 个问题逐一修复)
1. `WECOM_APPROVAL_SECRET` 未注入容器 → docker-compose.yml 添加环境变量
2. Redis 无密码认证 → Redis command 添加 `--requirepass`
3. Docker bind mount `./app:/app/app` 丢失 → 恢复卷挂载
4. 企微 `getapprovaldata` API 已废弃(404) → 改用 `getapprovalinfo` 新 API`new_cursor` 分页 + `sp_no_list`
5. `token_manager.py` 两处 `cached.decode("utf-8")` 报错 → `isinstance` 安全检查(Redis `decode_responses=True` 返回 str
6. errcode=60020 IP 不在"审批"应用白名单 → 改用 `TokenManager`IT 支持应用 Secret,IP 已在白名单)
7. errcode=301025 invalid filter → 企微 API 每个 filter key 只能出现一次,去掉 API 层 template_id 过滤,改代码层过滤
8. `_extract_current_approver` 字段名全错 → `record.status``record.sp_status``record.approver[]``record.details[].approver.userid`(经 JSON dump 确认实际 API 返回结构)
- 修复:验证通过,sxn 名下 2 条审批待办正确返回(IT 资产外修申请)
- 修复:nginx 容器配置丢失导致页面加载失败
- 修复:后端 h5.py `_require_wework_ua` NameError 导致 OAuth 认证失败
### 🔐 安全 (Security)
- P0:WS token 改走 `Sec-WebSocket-Protocol` subprotocol(已修)
- P0:坐席登录加 `password_hash` bcrypt 字段
- P0:`/ws/` 路径 nginx access_log 关闭
- P0:5 鉴权漏洞全部修复(消息 5 端点)
- WECOM_SECRET 集中化(待 NAS Vault)
- Gitea 凭据走 wincred,不入文件
### 🏗️ 基础设施 (Infrastructure)
- 蓝绿部署支持:新增 docker-compose-green.yml、switch-blue-green.sh、nginx-green-upstream.conf
- Green 环境端口:后端 5002Nginx 5080/5443
- Gitea 自托管部署(Synology 套件 8418 端口)
- Tailscale Funnel 暴露给 workbuddy 沙箱
- 分支保护:main 需 PR + 1 reviewer
- workbuddy-claude 配 access token + 自动跑批
- 备份脚本(7 天保留 + cron 3 点)
- **服务器部署路径修正**:确认服务器项目根路径 `/opt/wecom-it-desk/`,所有前端 dist 均为 ro bind mount
- **前端部署命令模板**`H5_DIR=/opt/wecom-it-desk/frontend-h5/dist && cp -r $H5_DIR ${H5_DIR}_bak && rm -rf $H5_DIR/* && tar -xzf /tmp/h5-dist-vX.tar.gz -C $H5_DIR/ && docker exec wecom_it_nginx nginx -s reload`
### 📚 文档 (Documentation)
- 新增 8 份审计/设计报告(Dockerfile / ER / 依赖 / 健康检查 / CORS / 一键部署 / 健康度 / 惊喜汇总)
- 4 份 ADR(ADRs 001-004)
- 4 份 SOP(SOPs 001-004)
- 2 份路线图(阶段 1 盘点 + 阶段 4-5 规划)
- Wingman 设计文档
- 4 前端审计 + 16 项统一优化路线
- AI 对话链路全栈改造实施计划 v1.0(`docs/02-产品需求/AI对话链路全栈改造实施计划-v1.0.md`
### 🛠️ 工具链 (Tooling)
- `scripts/pre-commit-check.sh`:4 件套预检(鉴权+依赖+alembic+配置)
- `scripts/backup-gitea.sh`:Gitea 备份 + 恢复
- `scripts/security-audit.sh`:5 工具集成审计
- `scripts/generate-api-docs.sh`:OpenAPI + Swagger UI + ReDoc
- `scripts/dashboard.py`:项目健康度仪表盘
- `scripts/oneclick-deploy.sh`:一键部署
---
## [0.5.0] - 2026-05-30
### ✨ 新增 (Added)
- 阶段 1 完成度 66%(47 项功能盘点)
- H5 员工端完整功能(11 组件)
- 坐席工作台三栏(23 组件)
- 管理后台 13+ 视图
- 统一入口 portal
- WebSocket 实时通信
- WebSocket fallback 轮询
- Dify AI 集成(基础)
- 4 个外部系统集成(火绒/联软/aTrust/eHR)
- 快速回复 + 排障模板 + 待办事项
### 🐛 修复 (Fixed)
- 5 鉴权漏洞
- WS token 泄露到 URL 和日志
- 坐席登录缺 password
- Mock login bypass
### 📈 性能 (Performance)
- 4 前端路由级代码分割
- WebSocket 长连接(替代轮询)
- 模板缓存(Redis)
---
## [0.4.0] - 2026-04-15
### ✨ 新增
- RBAC 角色管理(user/agent/admin)
- 角色自动映射(企微标签 + eHR 字段)
- 配置变更日志(审计)
- 趣味话术(摇人/等待/接入)
- 审批流程链接
- 软件下载入口
### 🐛 修复
- 部门权限粒度
- 紧急度评分算法
- VIP 标记自动匹配
---
## [0.3.0] - 2026-03-01
### ✨ 新增
- AI 草稿回复(坐席采纳)
- AI 实质性回复计数
- 紧急度评分(1-5)
- 标签系统(举手/情绪/需介入)
- 影响范围评估
- 阻断性标记
---
## [0.2.0] - 2026-01-15
### ✨ 新增
- 4 前端基础架构(Vue 3 + Vite + TS + Pinia)
- 16 张数据表
- 核心 API(40+ 端点)
- OAuth2 企微登录
- 消息收发(文本/图片/文件/语音)
- 会话分配/抢单/转接
- 协作坐席(摇人)
- 邀请功能(P0-09~11)
---
## [0.1.0] - 2025-12-01
### ✨ 初始版本
- 项目初始化
- 基础 FastAPI 框架
- SQLAlchemy 2.0 + async
- Alembic 迁移
- Docker Compose 编排
- 4 前端工程搭建
- 企微回调基础
---
## 版本说明
- **0.x.y** - 阶段 1-5 演进(0.1-0.5 已发布,0.6+ 阶段 2 启动)
- **1.0.0** - 正式版目标(预计 2026-12,阶段 5 完成后)
> 📌 **文档同步说明**:各版本的详细变更记录请参考 `docs/archive/RELEASE_NOTES_*.md`,本文档仅保留版本概览。
## 图例
- ✨ 新增 - 新功能
- 🐛 修复 - Bug 修复
- 📈 性能 - 性能优化
- 🔐 安全 - 安全修复
- ⚠️ 弃用 - 即将移除
- 🏗️ 基础设施 - 部署/工具/流程
- 📚 文档 - 文档更新
- 🛠️ 工具链 - 工具脚本
[未发布]: https://gitea.simon.local/simon/wecom/wecom_it_smart_desk/compare/v0.7.0...HEAD
## [v0.7.1] - 2026-06-23(规划中)
> **决策背景**(2026-06-22):v0.7.0.1-hotfix1(QR 码生成)上线后,生产仍报 2 个 bug:
> - 员工/坐席扫码登录报错(`/api/auth_qrcode/scan` 失败)
> - 管理员 sxn 登录报错(`agents.otp_secret` 列不存在 — alembic 010 未跑)
> 用户决策:**不再修 7.0.1**,直接进 v0.7.1 统一治理。
### 🔧 修复 (Fixed)
#### P0 — 登录失败
- **管理员 sxn 登录报错**:根因 — alembic 010 `agents.otp_secret` 列未在生产数据库创建
- 修复:合并 `otp_secret/otp_enabled`(010)与 `mfa_secret/mfa_enabled`(023)双字段,模型统一引用 `mfa_secret/mfa_enabled`
- migration:重写 021_rbac(原文件丢失),统一 010-025 chain
- **员工/坐席扫码登录报错**:根因待查(预计 ticket 状态机 / WecomService 初始化 / 高并发 session)
- 修复:在 dev 复现,出 patch
#### P0 — 基础设施
- **修 `/api/ready` import error**(原 defer to v0.7.1)
- **审计 alembic chain**:`021_rbac` 缺失 / 022-025 chain 错乱,出 `docs/alembic_history_audit.md`
### 🆕 新增 (Added)
#### P1 — 体验优化
- **企微入口 SSO**(原 v0.7.1+ backlog):识别 WeChat Work User-Agent,自动识别员工身份 + 跳对应端点,扫码登录降级为 fallback
#### P1 — 权限
- **管理后台 RBAC 细粒度角色权限**:5 角色 + 4 资源 + 4 操作 + 3 数据范围
### 📝 文档 (Documentation)
- `docs/DEPLOY-QUICK-v0.7.1.md` — 一键部署操作包(基于 7.0 模板)
- `docs/alembic_history_audit.md` — chain 审计报告
- `docs/USER-GUIDE-WECOM-SSO.md` — 企微 SSO 用户手册
---
## [v0.7.0] - 2026-06-21
### 🎉 新增 (Added)
#### 扫码登录(阶段 1.1-1.3)
- 后端 `app/api/auth_qrcode.py` (236 行) — 4 端点 create / poll / scan / confirm
- 后端 `app/services/qrcode_service.py` (487 行) — 业务逻辑 + dev 模式 mock OAuth
- 后端 `app/schemas/qrcode.py` (127 行) — Pydantic 模型
- 后端 alembic migration 022_qrcode_login(数据存 Redis,无 schema 变更)
- 前端 `frontend-agent/src/views/Login.vue` — ElementPlus 扫码 UI + 倒计时
- 前端 `frontend-portal/src/views/QrcodeLogin.vue` — 角色自动分发
- 前端 `useQrcodeLogin.ts` composable (agent + portal 双端) — 2s 轮询 + 120s TTL
- 前端 `frontend-portal/src/router/index.ts` — 默认 `/``/qrcode-login`
- 文档 `docs/NGINX-DOMAIN-ROUTING.md` — 单域名 + 多路径架构
- 文档 `docs/USER-GUIDE-QRCODE-MFA.md` — 员工/坐席/管理员用户手册
#### MFA 二次认证(阶段 2.1-2.4)
- 后端 `app/api/mfa.py` (389 行) — 6 端点:status / bind/start / bind/confirm / verify / disable / admin/reset
- 后端 `app/services/mfa_service.py` (179 行) — pyotp TOTP + Redis verified TTL 1800s
- 后端 `app/models/agent.py` — mfa_secret / mfa_enabled / mfa_bound_at / mfa_last_verified_at
- 后端 alembic migration 023_mfa_fields — User MFA 4 列
- 前端 `frontend-agent/src/api/mfa.ts` — 5 个用户端 API
- 前端 `frontend-agent/src/views/MfaBind.vue` — 4 步绑定流程
- 前端 `frontend-agent/src/composables/useHighRiskOtp.ts` — 高危弹窗 30 分钟超时
- 前端 `frontend-admin/src/api/mfa.ts` — 管理员视角 API
- 前端 `frontend-admin/src/views/MfaManage.vue` — MFA 管理表格(搜索/过滤/分页)
#### 高危操作守卫(阶段 1.3 task #19)
- 后端 `app/services/high_risk_guard.py` (291 行) — HighRiskGuard service 类
- 后端 `app/api/high_risk_routes.py` (327 行) — 演示端点 + 白名单查询
- 后端 `app/dependencies.py` — HIGH_RISK_OPERATIONS 5 类白名单 + require_high_risk_otp 依赖
- 5 类高危操作:改权限 / 改配置 / 导出数据 / 封号 / 新增账号或重置
### 🐛 修复 (Fixed)
- WS endpoint `missing argument 'request'` 错误(加 8 个回归测试)
- messages.id VARCHAR → UUID(migration 025,加 8 个兼容测试)
- wordfilter API 适配(1.0.6:Wordfilter 实例 + addWords + blacklisted)
- conftest SQLite ARRAY/JSONB 编译补丁(quiz.keywords / themes.palette)
- conftest autouse 业务表清理(feedback 事务隔离)
- h5_client 用 127.0.0.1 跳过企微 UA 检测
- test_conversation_grab wecom mock 默认 name 不覆盖 body.name
- Gitea push token 从 URL 清理(`http://workbuddy-claude@...`)
### 🔐 安全 (Security)
- 高危操作必须过 OTP 二次验证(管理员 30 分钟内)
- WS 推送端点签名保护(防 request: Request 加回去)
- nginx access_log 脱敏脚本(删 Authorization / Cookie)
- 5 鉴权漏洞已修(2026-06-14 评审清单)
### 📚 文档 (Documentation)
- `docs/E2E-CHECKLIST-v0.7.0.md` (176 行) — 35 项 E2E 验收清单
- `docs/DEPLOY-QUICK-v0.7.0.md` (252 行) — 一键部署操作包(分步+回滚+预计时间)
- `docs/DEPLOY-LOGIN-MIGRATION-v0.7.0.md` (220 行) — 部署手册
- `docs/NGINX-DOMAIN-ROUTING.md` (256 行) — nginx 域名分发
- `docs/USER-GUIDE-QRCODE-MFA.md` (165 行) — 用户手册
### 📈 测试 (Test)
- 新增 78 测试全过(扫码 13 + MFA 21 + 高危 28 + WS/UUID 16)
- 4 xfailed(端点路径不一致 pre-existing,已标 xfail)
- 修 5 处 pre-existing 失败(+27 测试):content_moderation / conversation_grab / feedback / h5_oauth / SQLite 编译
- 全量 pytest: 470 passed, 4 xfailed, 64 failed(pre-existing 设计问题)
### 📦 Commits(本次 session 5 个)
- `1255e95` docs: v0.7.0 一键部署操作包
- `c33abb6` fix(tests): h5_client 用 127.0.0.1 跳过企微 UA 检测
- `a9b97de` fix(tests): wordfilter API 适配 + SQLite ARRAY/JSONB 补丁 + 事务隔离
- `e96fbb2` docs: v0.7.0 E2E 验收清单
- `bf872da` feat(merge): 4 个 worktree 合入 main(扫码+MFA+高危+P0)
[0.7.0]: https://gitea.simon.local/simon/wecom_it_smart_desk/compare/v0.6.0...v0.7.0
[0.5.0]: https://gitea.simon.local/simon/wecom_it_smart_desk/releases/tag/v0.5.0
[0.4.0]: https://gitea.simon.local/simon/wecom_it_smart_desk/releases/tag/v0.4.0
[0.3.0]: https://gitea.simon.local/simon/wecom_it_smart_desk/releases/tag/v0.3.0
[0.2.0]: https://gitea.simon.local/simon/wecom_it_smart_desk/releases/tag/v0.2.0
[0.1.0]: https://gitea.simon.local/simon/wecom_it_smart_desk/releases/tag/v0.1.0