wecom_it_smart_desk/docs/CHANGELOG.md

变更日志 (Changelog)

本项目的所有重要变更都会记录在此文件。

格式基于 Keep a Changelog, 本项目遵循 语义化版本。

未发布 - 2026-07-24

🎨 UI 调整 (UI Changes)

坐席端 AI 消息头像与名字位置对调 (2026-07-24 21:30 部署)

• 问题：AI 消息中达寇拉头像和名字的显示顺序不符合视觉习惯
• 调整：将头像移至名字左侧（头像 → 名字）
• 涉及文件：
  • frontend-agent/src/components/chat/MessageBubble.vue

---

🚀 功能增强 (Features)

坐席端接单按钮优化 (2026-07-24 18:30 部署)

• 问题：接单按钮在会话被其他坐席接走后消失，用户不知道按钮去向
• 修复：接单按钮改为持续显示，已接单时显示为禁用状态（灰色「已接单」）
• 涉及文件：
  • frontend-agent/src/components/chat/UserInfoBar.vue
• 任务说明书：docs/07-项目管理/任务说明书/任务说明书-124-接单按钮状态优化.md

---

未发布 - 2026-07-15

🐛 问题修复 (Bug Fixes)

坐席端 Ctrl+V 粘贴功能修复 (2026-07-15 10:00 部署)

• 问题：坐席端输入框（ReplyBox.vue / InputBox.vue）无法通过 Ctrl+V 粘贴文本
• 根因：handlePaste 函数在 clipboardData 为空时直接 return，阻止了默认粘贴行为
• 修复：添加 clipboardData 和 items.length 空检查，确保纯文本粘贴时让浏览器执行默认行为
• 任务说明书：docs/10-项目管理/任务说明书/任务说明书-79-坐席端粘贴功能修复.md

---

未发布 - 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 ✅

坐席端历史会话查询功能（2026-07-13 11:30 部署）

• 功能位置：UserInfoBar（员工信息栏）等级 chips 后方新增"历史会话"开关
• 跨会话聚合：查询该员工所有会话的消息，合并为一条时间线（按 created_at DESC 排序）
• 会话分隔条：ConversationSeparator.vue 组件，显示首条消息摘要（前20字）+ 当前会话高亮标记
• 游标分页：支持 before 游标参数，滚动到顶部自动加载更多历史消息
• 后端 API：GET /employees/{employee_id}/history-messages（需认证），返回 HistoryMessageListResponse（items + has_more + conversation_summaries）
• 前端状态管理：conversation.ts store 新增 historyMode/historyMessages/historyLoading/historyHasMore 等状态
• 只读模式：历史模式下隐藏回复框，显示"查看历史会话，仅供阅读"提示条
• 测试：28/28 全部 PASS（SOP 2轮）
• 验证：前端生产包 grep 检查通过 ✅，后端 API 权限校验生效 ✅

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/keyword）UPDATE
• 验证：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
• 答题插队：员工答题期间优先处理
• 五场景关闭：五种场景自动关闭会话
• 后端：迁移 052（6表+6列）/ queue_service / quiz_service / closing_service / seed_quiz / 每日3:00定时生成
• H5 前端：QueueWaiting / RightPanel 双Tab / InputBar 三态"人工"按钮 / ResolveConfirmCard
• 坐席前端：pending_close 结单流程；信息锁定（Dify 步骤完成 + 有效回答率≥70%）

坐席端布局优化 v2.0（2026-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 环境端口：后端 5002，Nginx 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 修复
• 📈 性能 - 性能优化
• 🔐 安全 - 安全修复
• ⚠️ 弃用 - 即将移除
• 🏗️ 基础设施 - 部署/工具/流程
• 📚 文档 - 文档更新
• 🛠️ 工具链 - 工具脚本

[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)