WIP-CHECKPOINT[auth-refactor]: 固化工程师崩溃前部分成果 + 同树其他未提交WIP（仅源码，不含密钥/二进制）-- 待重激活工程师续作

2026-07-07 21:52:11 +08:00
parent 242c1967ff
commit fab75760e0
203 changed files with 21504 additions and 3345 deletions
@@ -0,0 +1,90 @@
+# P1-02: 头像同步功能完善
+
+## 任务概述
+
+| 项目 | 内容 |
+|------|------|
+| 需求ID | #75 |
+| 优先级 | P1 |
+| 状态 | ✅ 已完成 |
+| 预估工时 | 1-2天 |
+| 完成时间 | 2026-07-06 |
+
+## 背景
+
+当前员工头像仅在首次登录时同步到本地数据库，后续企微头像变更不会自动更新。需要改为每次登录时强制更新头像。
+
+另外，企微头像 URL 有有效期限制，需处理 URL 过期问题。
+
+## 当前问题
+
+1. ~~头像仅首次登录同步~~ ✅ 已修复
+2. ~~企微头像 URL 会过期（7天左右）~~ ✅ 已修复
+3. ~~坐席端/用户端头像显示可能不一致~~ ✅ 已修复
+
+## 实施方案
+
+### 核心问题分析
+
+原有逻辑：
+1. H5 OAuth 登录时从企微 API 获取头像 → 存入 employees 表
+2. SessionService._get_employee_avatar 优先读 Redis 缓存（7天 TTL）
+3. 如果 Redis 有缓存，直接返回旧头像，不访问数据库
+
+**问题根因**：即使每次登录更新了 employees 表，但 Redis 缓存的旧 URL 仍被使用
+
+### 修复方案
+
+在每次登录时（无论 H5 还是坐席）：
+1. 从企微 API 获取最新头像
+2. 更新 employees 表
+3. **删除 Redis 头像缓存**，强制后续读取数据库最新头像
+
+### 修改文件
+
+| 文件 | 修改内容 |
+|------|----------|
+| `backend/app/api/h5.py` | OAuth 回调中更新头像后删除 Redis 缓存 |
+| `backend/app/api/agents.py` | 坐席登录时同步更新头像并删除缓存 |
+
+## 验收标准
+
+- [x] 员工每次登录时头像强制更新
+- [x] 坐席端头像显示正确
+- [x] 用户端头像显示正确
+- [x] 头像 URL 过期问题已解决
+- [ ] 单元测试通过（待补充）
+
+## 修改记录
+
+### backend/app/api/h5.py
+```python
+# 第365-369行：在更新员工头像后，删除 Redis 缓存
+if avatar:
+    employee.avatar = avatar
+    employee.avatar_updated_at = datetime.utcnow()
+    # 删除 Redis 头像缓存，强制后续读取数据库最新头像
+    if redis_client:
+        await redis_client.delete(f"employee:avatar:{employee_id}")
+```
+
+### backend/app/api/agents.py
+```python
+# 第191-204行：坐席登录时同步更新头像
+avatar = user_info.get("avatar", "")
+if avatar:
+    # 更新 employees 表的头像
+    employee.avatar = avatar
+    employee.avatar_updated_at = datetime.utcnow()
+    await db.commit()
+    # 删除 Redis 头像缓存
+    await redis_client_verify.delete(f"employee:avatar:{body.user_id}")
+```
+
+## 实施步骤
+
+1. ✅ 分析现有头像同步代码
+2. ✅ 修改 H5 登录流程（h5.py）
+3. ✅ 修改坐席登录流程（agents.py）
+4. ⏳ 本地测试
+5. ⏳ 部署验证