hl-api-changelog/changelogs/2026-04/2026-04-23_mp-order-staff-avatar-fix.md

微信小程序 · 订单详情领队/摄影师头像 avatarUrl 之前为 null — 已修复

• 变更日期: 2026-04-23
• PR: #1309
• 端: 微信小程序（管理端不涉及）
• 影响面: 订单详情「领队」「摄影师」弹窗 / 卡片的头像展示
• 兼容性: 字段结构零变化，原本 null 的字段现在会填充有效 URL

---

变化一句话

微信小程序订单详情相关接口中的员工头像 avatarUrl 字段之前恒为 null，现在会返回有效的头像 OSS URL。

---

涉及接口

下列接口返回体中的 avatarUrl 字段：

接口	返回体中的位置
GET /mp/order/{orderId}/guide	guide.avatarUrl
GET /mp/order/{orderId}/photographer	photographer.avatarUrl

---

头像生成规则（前端可了解优先级）

1. 优先取员工档案 coverMaterialId 对应的物料库封面（OSS URL）
2. 若无，fallback 取员工相册 photoUrls 的第一张
3. 都没有 → avatarUrl 为 null（前端走默认占位图即可）

---

生效范围（⚠️ 重要）

订单类型	是否生效
新下单的小蒙马（GROUP）订单	✅ 立即生效
历史已下单的 GROUP 订单	❌ 下单时已固化的员工快照未补头像，avatarUrl 仍为 null（如需回填可后台批量补修，本次未做）
CORE（核心/自驾/自助游）订单	N/A（本来就不含领队/摄影师）

---

不影响范围

• 领队/摄影师接口的其它字段（staffName / staffPhone / staffRole / remark 等）零变化
• 下单请求体、订单详情主体零变化
• 管理端员工档案（/admin/staff/**）零变化
• 订单班期员工列表接口（/mp/order/{orderId}/staff-list 等）同步生效

---

相关

• PR：wx/HL#1309
• 部署：hl-product-service-v2（8093）+ hl-resource-service（8082）