任务说明书：企微图片消息无法预览
版本: v1.1 | 日期: 2026-07-20
📋 基本信息
| 项目 |
内容 |
| 任务名称 |
企微图片消息无法预览 |
| 任务ID |
#80 |
| 优先级 |
🟠 P1 |
| 类型 |
Bug修复 |
| 状态 |
已部署，存在遗留问题 |
| 负责人 |
Duckula |
| 创建日期 |
2026-07-16 |
| 计划完成日期 |
2026-07-16 |
| 关联缺陷单 |
BUG-20260720-01（需刷新才显示） |
📥 输入项来源
问题反馈
| 来源 |
说明 |
| 用户反馈 |
用户通过企业微信发送的图片消息，坐席端无法预览也无法打开图片内容 |
技术分析
| 来源文档 |
相关章节 |
说明 |
backend/app/api/wecom_callback.py |
§图片消息处理 |
只保存 pic_url 临时URL，未下载到本地 |
frontend-agent/src/components/chat/MessageBubble.vue |
§图片渲染 |
使用 media_url 或 extra_data.pic_url |
2026-07-16 新增尝试
| # |
方法 |
结果 |
说明 |
| 1 |
修改上传路径为 uploads/images（使用 Docker volume） |
已部署 |
代码已更新到正确路径 |
| 2 |
WebSocket 广播添加 extra_data（含 local_media_url） |
已部署 |
前端已支持接收 |
| 3 |
Nginx 配置 /media/ 代理到后端 /media/ |
已部署 |
代理链路已配置 |
待排查问题
| # |
问题 |
状态 |
| 1 |
图片是否成功保存到 /app/uploads/images/ |
✅ 已验证 |
| 2 |
WebSocket 是否正确推送 local_media_url |
✅ 已验证 |
| 3 |
前端是否正确显示图片 |
⚠️ 部分验证 - 需刷新才显示 |
遗留问题 (BUG-20260720-01)
| 问题描述 |
现象 |
状态 |
| 首次加载不显示 |
坐席打开会话时图片空白/占位 |
待排查 |
| 需刷新才显示 |
刷新页面或切换会话后图片正常 |
待排查 |
遗留问题已创建缺陷单: docs/03-测试文档/05-缺陷单/BUG-坐席-图片预览刷新-001.md
📤 输出成果要求
交付物清单
| # |
交付物 |
类型 |
说明 |
| 1 |
wecom_service.py 新增 download_media 方法 |
代码 |
下载企微媒体文件到本地 |
| 2 |
wecom_callback.py 图片消息处理逻辑 |
代码 |
调用下载方法并保存本地URL |
| 3 |
后端部署验证 |
部署 |
重启后端容器验证功能 |
代码要求
🔧 验证方式
功能验证
| 验证项 |
验证方法 |
预期结果 |
| 企微发送图片 |
通过企微发送图片到IT服务台 |
坐席端可正常预览图片 |
| 图片下载 |
查看后端 media/images/ 目录 |
图片文件已保存 |
| 图片访问 |
点击图片查看大图 |
可正常打开 |
✅ 完成标准
验收条件
📊 工作分解
子任务
| 子任务 |
负责人 |
预估工时 |
状态 |
| 在 wecom_service.py 添加 download_media 方法 |
Duckula |
1h |
待开始 |
| 修改 wecom_callback.py 图片处理逻辑 |
Duckula |
1h |
待开始 |
| 部署后端并验证功能 |
Duckula |
0.5h |
待开始 |
📈 变更记录
| 日期 |
变更内容 |
变更人 |
说明 |
| 2026-07-16 |
创建任务 |
Duckula |
初始版本 |
Simon
44e77dcb0e