simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5311a526af4e354aa125b82c216c5cafc3604049
wecom_it_smart_desk/docs/CHANGELOG.md
T
Simon facc04aa65 chore: docs 结构整改 + compose 双目录对齐（合并重建提交） 
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交
（5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。

一、docs 结构整改（整改 #14）
根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入，
随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录
树并存于 docs/，共 791 文件、双分类体系冲突。

修复动作：
- b2 同名异主题文件改名迁移保全 9 个
- C 类 39 个孤立文件按主题正确归类
- A/B1 类 222 个重复文件删除（新结构已有内容副本）
- 9 个旧独有空目录删除
- 270 处内部引用按 verified 映射改写
- 整改记录 #14 登记于 04-运维文档/部署运维

结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。
残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。

二、compose 双目录对齐（消除踩坑 A）
- docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist
  改为 src/frontend-*/dist（h5 / agent / admin / terminal）
- docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/
- 效果：本地 docker compose up 不再把根目录 stale dist 挂回，
  与线上一致，分叉隐患消除（已 docker compose config 校验通过）

防复发铁律：
- 重构须提交；仓库修复须 git stash -u 或先 commit
- 新结构须 git add 并提交，避免再次 untracked 复活
- H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
2026-08-07 22:31:32 +08:00

18 KiB
Raw Blame History

变更日志 (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/otp.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)
Reference in New Issue View Git Blame Copy Permalink