wecom_it_smart_desk/CHANGELOG.md

# 变更日志 (Changelog)

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

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

## [未发布] - 2026-07-05

### 🐛 缺陷修复 (Bug Fixes)

### 🚀 功能增强 (Features)
- 蓝绿部署支持：新增 docker-compose-green.yml、switch-blue-green.sh、nginx-green-upstream.conf
- Green 环境端口：后端 5002，Nginx 5080/5443

### 🐛 缺陷修复 (Bug Fixes)
- 修复：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)
- Gitea 自托管部署(Synology 套件 8418 端口)
- Tailscale Funnel 暴露给 workbuddy 沙箱
- 分支保护:main 需 PR + 1 reviewer
- workbuddy-claude 配 access token + 自动跑批
- 备份脚本(7 天保留 + cron 3 点)

### 📚 文档 (Documentation)
- 新增 8 份审计/设计报告(Dockerfile / ER / 依赖 / 健康检查 / CORS / 一键部署 / 健康度 / 惊喜汇总)
- 4 份 ADR(ADRs 001-004)
- 4 份 SOP(SOPs 001-004)
- 2 份路线图(阶段 1 盘点 + 阶段 4-5 规划)
- Wingman 设计文档
- 4 前端审计 + 16 项统一优化路线

### 🛠️ 工具链 (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