wecom_it_smart_desk/CURRENT-FOCUS.md

企微IT智能服务台 — 项目状态看板

📌 这个文件就是项目的"驾驶舱仪表盘"。任何时候新开 session,先读这个文件就懂上下文。

📝 更新规则:每次 Claude 完成 / 开始 / 阻塞重要任务,会主动更新本文件。你也可以自己改(纯 markdown,git 跟踪)。

最后更新:2026-06-21(Claude 自动维护,看板上一次刷新)

---

🎯 一句话总览

项目状态:v0.7.0 release 完成 — 扫码登录 + MFA 二次认证 + 高危操作守卫 + P0/P1 合规修复 全部合入 main(commit 8e748d1)+ tag 已打(v0.7.0)。 当前主线:等用户执行 docs/DEPLOY-QUICK-v0.7.0.md 6 步部署 + 35 项 E2E 验收(deadline 今晚 7:00 → 现已凌晨,部署后看观察期)。 待用户手动操作:撤销 Gitea token 5ad83d3...(已暴露过)+ 跑生产 migration + 应用 nginx access_log 脱敏 + push 新代码到 Gitea。

---

🟢 正在做(in_progress,1 件)

#	任务	我做什么	你做什么	完成定义
#29	启用测试环境(PG+Redis)+ 跑集成测试	用 SQLite 跑全量 pytest 后台跑	部署后用 PG 跑一遍真集成测试	470+ passed

---

🔴 P0 必做(下一个 sprint)

#	任务	重要程度	说明
#48	v1.0 收窄 set_real_ip_from	🔴 P0	现 allow 0.0.0.0/0 是临时方案,正式上线前必须改精确代理 IP
#81	v0.6.0 敏感词检测 + 语气优化	🔴 P0	下一个版本的核心功能
#80	v0.5.4 应急页 nginx 路由 + 部署	🔴 P0	当前生产缺路由,功能上了但用户访问不到

---

🟡 P1 重要(看时间做)

#	任务	说明
#73	修后端文件未真正覆盖	`yes
#86	排查流程图零依赖部分 review + 文档化	把 Mermaid 流程图从代码里剥离成可读文档
#88	管理后台 RBAC 角色权限	管理后台细粒度角色权限(大功能,2-3 天)
#83	澄清"OTM 跟项目关系"	已 2026-06-21 决策:走 TOTP+SMS 双引擎(MFA Phase 2 实施)
🆕	v0.7.0 部署 + 35 项 E2E 验收	看 docs/DEPLOY-QUICK-v0.7.0.md 6 步 + docs/E2E-CHECKLIST-v0.7.0.md
🆕	修 64 pre-existing 测试失败	Role.data_scope 缺字段 / WecomService DI / test_message_experience 等

🟢 P2 / 等用户决策

#	任务	卡在哪
🆕 服务器更新?	把 v0.7.0 部署到生产(扫码+MFA+高危+4 项 P0)	等你跑 DEPLOY-QUICK-v0.7.0.md 6 步
#31	推 docker 镜像到生产 registry	等你确认要走哪条路(自建 Harbor / 阿里云 / 别的)
#43	配置 HTTPS	等域名备案完成 + 证书到位
#53	用户在企微验证 /itportal/	等你去企微点一点
🆕 #23	清理 ~/Downloads/ patch1 包	部署观察期后拍板
🆕 #24	清理生产 patch1 回滚备份	1 周观察期后拍板
🆕 #48	收窄 set_real_ip_from 内网地址	部署后下一迭代(v1.0 前)

---

🟢 P2 / 等用户决策

#	任务	卡在哪
🆕 服务器更新?	把今天的 3 个 migration + 1 个 bug 修复部署到生产 v0.5.6	等你看这份看板后拍板
#31	推 docker 镜像到生产 registry	等你确认要走哪条路(自建 Harbor / 阿里云 / 别的)
#43	配置 HTTPS	等域名备案完成 + 证书到位
#53	用户在企微验证 /itportal/	等你去企微点一点

---

✅ 最近搞定(给你信心)

2026-06-21(凌晨 1 小时 sprint)

🆕 v0.7.0 release 收尾(8 个 worktree → main)

• ✅ #14 阶段 1.1:后端 auth_qrcode.py 4 端点(create/poll/scan/confirm)
• ✅ #15 阶段 1.2:前端 Login.vue + QrcodeLogin.vue 扫码 UI
• ✅ #16 阶段 1.3:坐席/管理员域名路由分发(/itagent/ /itadmin/)
• ✅ #17 阶段 2.1:后端 MFA 服务 + pyotp 集成
• ✅ #18 阶段 2.2:数据库 User MFA 字段 + Alembic migration 023
• ✅ #19 阶段 2.3:高危操作路由白名单 + 中间件(5 类白名单)
• ✅ #20 阶段 2.4:前端 MFA UI(绑定 + 验证 + 高危弹窗 + 管理表格)
• ✅ #21 集成测试 + E2E + 培训文档:E2E-CHECKLIST 176 行 + DEPLOY-QUICK 252 行

🔐 P0/P1 合规修复(#30)

• ✅ WS endpoint missing argument 'request'(签名 + 8 个回归测试)
• ✅ messages.id VARCHAR → UUID(migration 025)
• ✅ nginx access_log 脱敏脚本(删 Authorization/Cookie)
• ✅ Gitea token 撤销流程已文档化(token 5ad83d3... 已暴露过)

🐛 测试修复(#32)

• ✅ wordfilter 1.0.6 API 适配(Wordfilter() 实例 + addWords() + blacklisted())
• ✅ SQLite ARRAY/JSONB 编译补丁(quiz.keywords / themes.palette)
• ✅ conftest autouse 业务表清理(feedback 事务隔离)
• ✅ h5_client 用 127.0.0.1 跳过企微 UA 检测
• ✅ wecom mock 默认 name 不覆盖 body.name
• ✅ 测试基线:570 ERROR → 470 passed, 4 xfailed, 64 failed

📦 提交记录

• 8e748d1 docs: CHANGELOG.md 添加 v0.7.0 release 节
• 1255e95 docs: v0.7.0 一键部署操作包
• c33abb6 fix(tests): h5_client UA 检测
• a9b97de fix(tests): wordfilter API + SQLite 编译补丁 + 事务隔离
• e96fbb2 docs: v0.7.0 E2E 验收清单
• bf872da feat(merge): 4 个 worktree 合入 main
• tag v0.7.0 已打

历史(2026-06-16 选重点)

🛠️ Dev 环境(本地链路全通)

• ✅ 本地 dev 4 端链路跑通(#89-92):
  • backend (8000) + h5 (5174) + agent (5173) + admin (5175) + portal (5176) 全起
  • Mock 企微 OAuth 全通(/api/dev/login 给 token)
  • portal → H5 / 坐席 / 管理员 跳转正常
• ✅ 修了 3 个 dev 启动坑:
  1. pydantic==2.7.5 → 2.7.4(2.7.5 被 PyPI yank)
  2. docker-compose 加 PYTHONPATH=/app(alembic 1.13+ 不再默认 prepend cwd)
  3. dev 启动必须用 --env-file .env.dev(根 .env 冲突)

🐛 Bug 修复

• ✅ #93 修 portal dev 模式跳错端口:import.meta.env.DEV 判断,生产走相对路径,dev 走完整 URL
• ✅ #97 修 require_role 装饰器:@wraps 让 FastAPI 看到 __wrapped__ 签名,Depends 未被解析 → current_user 实际是 Depends 对象。用 inspect 合并 signature + 手动设 wrapper.__signature__ 修
• ✅ #99 dev 模式短路企微推送:避免 .env.dev 用 dev_corp_id_xxxxx 调企微 API 返 invalid corpid 噪音

🗃️ 数据库 migration(3 个)

• ✅ #94 alembic 010:加 agents.otp_secret + agents.otp_enabled
• ✅ #94 alembic 011:加 conversations.impact_scope + is_blocking + emotion_state(用户坐席发消息 500 的真因)
• ✅ #96 alembic 012:加 conversations.dify_conversation_id + employees.it_level + it_level_source + notes

🛡️ 防错工具(留底用)

• ✅ #95 dev-check-schema-drift.ps1:对比 SQLAlchemy 模型 vs Postgres schema,漂移 exit 1。以后模型加字段忘 migration 一跑就发现(用 docker exec,免去 Python 依赖)

📋 其他

• ✅ #68 H5 空白页闪一下:dev 模式验证不再白屏(生产未复测)

历史(选重点)

• ✅ v0.5.5:应急页 v0.5.4 + 移除 IT 设备升级 + admin 登录修复 + 内容审核架构
• ✅ v0.5.3:重打后端部署包(5 IT + 2 HR + 1 行政 + 1 财务 = 9 条)
• ✅ v0.5.6-dev-tooling 已 tag + push gitea(本地 dev 工具集)
• ✅ messages.id varchar=UUID SQL bug 修了(#60)+ 10 个回归测试通过
• ✅ nginx /api/admin/ 和 /itadmin/ 修复 403/allow(#57)

---

🚀 怎么跑起来(3 步)

1. 后端 dev(已经在跑 ✅)

cd D:\资料\03-项目开发\wecom_it_smart_desk-claude
docker compose -f docker-compose.dev.yml --env-file .env.dev up -d
curl http://localhost:8000/api/dev/health

2. 前端 dev(已经在跑 ✅)

# 一次性装 4 个前端依赖(已装好)
.\scripts\dev-frontend-install.ps1

# 之后:一起起所有前端
.\scripts\dev-frontend-start.ps1
# 单独停:.\scripts\dev-frontend-start.ps1 -Stop

3. 浏览器验证

• portal:http://localhost:5176/itportal/select
• H5:http://localhost:5174/itdesk/
• 坐席:http://localhost:5173/itagent/
• 管理员:http://localhost:5175/itadmin/

---

📌 怎么读这份文档

你是运维小白,不需要懂代码。看这个文件就能 1 分钟懂:

1. "现在在干嘛?" → 看「正在做」表
2. "接下来要干嘛?" → 看「P0 必做」表
3. "我需要做什么?" → 看「正在做」表里的「你做什么」列
4. "今天有啥进展?" → 看「最近搞定」

---

🤖 Claude 怎么帮你

每次开新 session 我会:

1. 第一件事:读这个文件 + TaskList,告诉你"上次到这了"
2. 完成一件重要事:更新这个文件(改状态、加完成项)
3. 遇到阻塞:写在「P2 / 等用户决策」里,等你回话
4. 新需求进来:跟当前 in_progress 比较,看是接着做还是并行加(参考你的"并行处理"反馈)

---

这个文件就是你和 Claude 之间的"工作交接本"。有问题改这里就行。