hl-api-changelog/changelogs/2026-03/26_0905_xmm_detail_fields.md

小蒙马详情页字段补全 + 产品接口优化

日期: 2026-03-26 服务: hl-product-service 环境: 测试环境已部署，需重启: product-service

---

一、小蒙马(GROUP)详情页新增字段

产品详情接口 GET /product/{productId} 和小程序 GET /internal/mp/product/{productId} 新增以下字段：

1. 数据统计（自动计算，无需配置）

字段	类型	说明
batchCount	Integer	历史期数（非散团状态的批次数，仅GROUP产品）
hotelSummary	Array	住宿安排汇总（连住合并，仅显示连住2晚及以上，仅GROUP产品）

hotelSummary 每项结构（连续住同一酒店自动合并）：

{
  "dayStart": 3,
  "dayEnd": 4,
  "hotelId": "3001000000000000005",
  "hotelName": "兰其果娃",
  "coverUrl": "https://xxx/hotel.jpg",
  "roomTypeName": "亲子房",
  "nights": 2,
  "label": "连住2晚"
}

注意：只住1晚的酒店不会出现在 hotelSummary 中（设计图只展示连住）。前端可直接用 label 字段显示标签，用 dayStart-dayEnd 显示日期范围（如 "Day3-4"）。

2. 年龄说明（后台可配）

字段	类型	说明	示例
ageMin	Integer	适合最小年龄	5
ageMax	Integer	适合最大年龄	12
ageDescription	String	年龄说明文案	"5-12岁儿童专属，课程按年龄分组"

3. 摄影跟拍（后台可配）

字段	类型	说明
photographyTags	String[]	摄影标签 如 ["200+精修照片", "1对1跟拍"]
photographyImages	String[]	摄影作品展示图URL列表

4. 餐饮亮点（后台可配）

字段	类型	说明
diningHighlights	Array	餐饮亮点列表

每项结构：

{
  "name": "手把肉",
  "coverImage": "https://xxx/cover.jpg",
  "subtitle": "蒙古特色必吃",
  "detailImages": ["https://xxx/detail1.jpg", "https://xxx/detail2.jpg"]
}

• coverImage: 封面图（列表展示，name叠在图上）
• detailImages: 详情图列表（点击查看大图）

5. 安全保障（后台可配）

字段	类型	说明
safetyItems	Array	安全保障列表

每项结构：

{ "icon": "insurance", "title": "保险", "description": "中国人保50万，含意外医疗" }

6. 价格档位表（自动计算，无需配置）

字段	类型	说明
priceTiers	Array	价格档位列表（从套餐combo自动取每种组合的最低售价，仅GROUP产品）

每项结构：

{ "label": "1大1小", "price": 12800, "adultCount": 1, "childCount": 1 }

数据来源：自动从产品的套餐（GroupBatchCombo）中按 comboCode 分组，取每组跨所有批次的最低 sellPrice。无需后台手动配置。

---

二、推荐餐厅封面图自动补全

行程节点中 DINING_RECOMMEND 类型的 recommendedRestaurants 列表，coverUrl 现在会自动从餐厅资源中补全。前端无需改动，原有字段结构不变。

---

三、上架校验优化

• 移除了上架时商户号（mchId）的强制校验，不再报"商户号不能为空"
• GROUP（小蒙马）产品上架新增校验：至少需要1个可报名的团期（状态为报名中/已确认，且出发日期在未来）。不满足会提示具体原因

---

四、产品人员配置增加备选人员

人员配置接口 POST /product/{productId}/staff-config 和 PUT /product/staff-config/{id} 新增字段：

字段	类型	说明
staffIds	String[]	备选人员ID列表（从人员资源中选取）

• 数量（quantity）是出行时实际需要的人数，备选人员可以多于此数量
• 团期创建时从备选池中选人分配

领队介绍（自动填充，仅GROUP产品）

字段	类型	说明
leaderInfoList	Array	领队详情列表（从人员配置中LEADER类型的staffIds查询）

每项结构：

{
  "staffId": "123",
  "name": "巴特尔老师",
  "avatar": "https://xxx/avatar.jpg",
  "title": "首席研学导师 · 蒙古族",
  "experience": "10年儿童户外教育经验",
  "description": "...",
  "certificateTags": ["急救证书", "导游证", "教师资格证"]
}

前端可滚动展示多个领队。

人员资源新增字段

人员资源 POST /staff 和 PUT /staff/{id} 新增：

字段	类型	说明
certificateTags	String[]	证书标签，如 ["急救证书", "导游证"]

---

五、预订须知（所有产品类型通用）

小程序产品详情已返回以下字段（点击展开纯文字内容）：

字段	位置	说明
product.bookingTermsContent	ProductVO	预订条款全文
product.warmTipsContent	ProductVO	温馨提示全文
refundPolicies	MpProductDetailVO	取消政策（按支付方式分组）

取消政策（退款政策）返回结构

refundPolicies 按支付方式分组，每个政策新增 description 纯文字字段：

{
  "FULL": {
    "policyId": 1,
    "policyName": "标准退款政策",
    "description": "出发前30天以上取消，退全款；出发前15-30天取消，退80%；出发前15天内取消，不可退",
    "rules": [
      { "ruleId": 1, "minDays": 30, "refundRatio": 100 },
      { "ruleId": 2, "minDays": 15, "refundRatio": 80 },
      { "ruleId": 3, "minDays": 0, "refundRatio": 0 }
    ]
  },
  "DEPOSIT": { ... }
}

前端可直接用 description 展示文字，无需自己拼接规则。按产品的 pricing.paymentType 显示对应的退款政策：

• FULL → 显示 FULL 的 description
• DEPOSIT → 显示 DEPOSIT 和 BALANCE 的 description

---

前端对接要点

1. batchCount / hotelSummary / priceTiers / leaderInfoList: 自动计算字段，无需后台录入，GROUP产品详情自动返回
2. 年龄/摄影/餐饮/安全: 需要在管理后台"编辑产品"时配置对应数据，否则返回 null
3. 所有新字段向后兼容: 未配置时返回 null，不影响已有字段
4. 保存/更新产品接口同步支持: POST /product/save、PUT /product/{id} 都可传入新字段

---

六、人员管理校验增强

服务: hl-resource-service

创建/更新人员时，如果填写了 certificateTags（证书标签），则 certificateUrls（证书文件）不能为空。否则报错：

添加了证书标签，必须同时上传对应的证书文件

前端在提交人员表单时，如果用户添加了证书标签但没上传证书文件，建议在前端也做提示拦截。

---

七、人员证书改为结构化列表

服务: hl-resource-service

新增字段 certificates（替代旧的 certificateTags + certificateUrls）

人员创建/更新接口新增 certificates 字段，标签和附件一一对应：

[
  { "tag": "急救证书", "url": "https://xxx/cert1.jpg" },
  { "tag": "导游证", "url": "https://xxx/cert2.jpg" },
  { "tag": "教师资格证", "url": "https://xxx/cert3.jpg" }
]

校验规则：每项的 tag 和 url 必须同时存在，缺一报错（如"第1个证书'急救证书'缺少证书附件"）。

兼容：旧字段 certificateUrls / certificateTags 保留可用，但建议前端迁移到 certificates。

领队介绍：小程序详情 leaderInfoList 中的 certificateTags 优先从 certificates 提取，同时也返回完整的 certificates 列表。

---

八、安全保障改为模板机制

服务: hl-product-service

模板管理接口

方法	路径	说明
GET	/product/safety-template	模板列表
GET	/product/safety-template/{id}	模板详情
POST	/product/safety-template	创建模板
PUT	/product/safety-template/{id}	更新模板
DELETE	/product/safety-template/{id}	删除模板（默认模板不可删）

请求体：

{
  "name": "标准安全保障",
  "items": [
    { "icon": "insurance", "title": "保险", "description": "中国人保50万，含意外医疗" },
    { "icon": "vehicle", "title": "车辆", "description": "营运资质、儿童安全座椅、司机驾龄10年" },
    { "icon": "emergency", "title": "应急", "description": "24h客服，医院30分钟可达" }
  ],
  "isDefault": true
}

产品关联

产品保存/更新时可传 safetyTemplateId 指定模板。不传则自动使用默认模板，定制师无需手动配置。

详情返回逻辑

safetyItems 字段填充优先级：产品指定模板 → 产品自身旧数据 → 默认模板。前端无需改动，safetyItems 返回格式不变。

系统已内置默认模板"标准安全保障"（保险/车辆/应急三项）。

---

九、价格档位改为最近一期可报名团期价格

服务: hl-product-service

priceTiers 不再取所有团期的最低价，改为只取最近一期可报名团期（ENROLLING/CONFIRMED 且出发日期在未来）的 combo 价格。

返回格式不变：

[
  { "label": "1大1小", "price": 12800, "adultCount": 1, "childCount": 1 },
  { "label": "1大2小", "price": 15800, "adultCount": 1, "childCount": 2 }
]

如果没有可报名团期，priceTiers 返回 null。

---

十、人员证书上传说明

上传流程：使用通用文件上传接口，和上传其他图片一样。

步骤：

1. POST /file/upload/token → 获取预签名URL

{ "fileName": "急救证书.jpg", "bizType": "staff" }

2. 用返回的预签名URL上传文件到OSS
3. POST /file/upload/confirm → 确认上传，拿到最终URL
4. 将URL填入 certificates[].url

保存人员时传 certificates 字段：

{
  "certificates": [
    { "tag": "急救证书", "url": "https://xxx/cert1.jpg" },
    { "tag": "导游证", "url": "https://xxx/cert2.jpg" }
  ]
}

每项 tag 和 url 必须同时填，缺一报错。旧字段 certificateTags/certificateUrls 仍可用但建议迁移。

---

补充：行程酒店封面图自动补全

行程天的酒店（itineraryDays[].hotels[].coverUrl）如果为空，后端会自动从酒店资源的封面素材中补全。前端无需改动。