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