wecom_it_smart_desk/docs/CHANGELOG.md

# 变更日志 (Changelog)

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

格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/),
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。

## [未发布] - 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 修复
- 📈 性能 - 性能优化
- 🔐 安全 - 安全修复
- ⚠️ 弃用 - 即将移除
- 🏗️ 基础设施 - 部署/工具/流程
- 📚 文档 - 文档更新
- 🛠️ 工具链 - 工具脚本

[未发布]: 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