wecom_it_smart_desk/docs/10-任务说明/P1-02-头像同步功能完善.md

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	坐席登录时同步更新头像并删除缓存

验收标准

• 员工每次登录时头像强制更新
• 坐席端头像显示正确
• 用户端头像显示正确
• 头像 URL 过期问题已解决
• 单元测试通过（待补充）

修改记录

backend/app/api/h5.py

# 第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

# 第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. ⏳ 部署验证