管理端产品详情扩展档位起步价 + Step5 模板展开字段

日期: 2026-04-17
服务: hl-product-service-v2（端口 8083）
PR: wx/HL#763
Issue: wx/HL#760
类型: feat（非破坏性扩展，纯字段新增）
影响: 管理端产品编辑/查看页可直接拿到起步价与 Step5 补充模板展开内容，无需二次查模板接口

变更类型

非破坏性扩展：对已有接口 GET /admin/product/item/{id} 的响应体新增若干字段。

所有老字段不变、含义不变、类型不变
旧前端客户端忽略新字段即可继续运行
无需迁移

受影响接口

`GET /admin/product/item/{id}`

管理端产品详情接口。签名与请求参数不变。响应 VO ProductDetailRespVO 新增以下字段。

新增字段清单

Step4 价格/班期区块（3 个字段）

字段	类型	含义	可能为 null 的情况
`startPrice`	BigDecimal	起步价（未来可售最低成人售价）	没有未来可售价格日历时为 `null`
`tierPrices`	`List<TierPriceInfo>`	各档位起步价（管理端即使单档产品也会返回）	全部档位价格已过期时为 `[]`（空数组，不是 null）
`priceCalendars`	`List<PriceCalendarRespVO>`	价格日历全量回显（含已过期、含零价，不做过滤）	从未配置价格日历时为 `[]`

管理端 vs 小程序端：小程序端通常会过滤掉过期与零价，管理端此处返回全量，方便后台编辑/校对。

Step5 补充信息区块（5 个字段，模板 ID 自动展开）

前端无需再发 GET 模板详情请求，后端已根据 supplement.xxxTemplateId / supplement.xxxId 展开内容：

字段	类型	含义	展开自	可能为 null 的情况
`guaranteeItems`	Object/Array（透传 JSON）	行程保障项	`supplement.guaranteeTemplateId` 对应模板的 `items` JSON	`guaranteeTemplateId` 为 null 或模板不存在时为 `null`
`safetyItems`	Object/Array（透传 JSON）	安全保障项	`supplement.safetyTemplateId` 对应模板的 `items` JSON	`safetyTemplateId` 为 null 或模板不存在时为 `null`
`faqItems`	Object/Array（透传 JSON）	FAQ 问答	`supplement.faqTemplateId` 对应模板的 `items` JSON	`faqTemplateId` 为 null 或模板不存在时为 `null`
`bookingTermsContent`	String	预订条款内容（富文本）	`supplement.bookingTermsId` 对应的 `content`	`bookingTermsId` 为 null 或记录不存在时为 `null`
`warmTipsContent`	String	温馨提示内容（富文本）	`supplement.warmTipsId` 对应的 `content`	`warmTipsId` 为 null 或记录不存在时为 `null`

设计原则：若对应 ID 为 null，后端不会查询无意义的数据，直接回空。

内部类结构：`TierPriceInfo`

tierPrices 数组的元素结构：

{
  "tierSeq": 1,
  "tierName": "标准档",
  "tierDescription": "标间 / 四人桌",
  "startPrice": 2980.00
}

字段	类型	说明
`tierSeq`	Integer	档位序号（1、2、3…）
`tierName`	String	档位名称
`tierDescription`	String	档位描述（房型/餐标等）
`startPrice`	BigDecimal	该档位未来可售最低成人售价

响应示例（节选，只展示新增部分）

{
  "code": 200,
  "data": {
    "productId": 1001,
    "name": "呼伦贝尔6日游",

    "startPrice": 2980.00,
    "tierPrices": [
      { "tierSeq": 1, "tierName": "标准档", "tierDescription": "标间",   "startPrice": 2980.00 },
      { "tierSeq": 2, "tierName": "豪华档", "tierDescription": "大床房", "startPrice": 3480.00 }
    ],
    "priceCalendars": [
      { "date": "2026-05-01", "tierSeq": 1, "adultPrice": 2980.00, "childPrice": 1980.00, "stock": 20 }
    ],

    "supplement": {
      "guaranteeTemplateId": 11,
      "safetyTemplateId": 12,
      "faqTemplateId": 13,
      "bookingTermsId": 21,
      "warmTipsId": 22
    },
    "guaranteeItems": [ { "title": "全程WIFI", "desc": "..." } ],
    "safetyItems":    [ { "title": "随车医药箱", "desc": "..." } ],
    "faqItems":       [ { "q": "可以加床吗？", "a": "可以，需付费" } ],
    "bookingTermsContent": "<p>下单后 24 小时内完成支付...</p>",
    "warmTipsContent":     "<p>请携带身份证原件...</p>"
  }
}

使用建议

场景	推荐字段
列表页/卡片展示"起步价￥xxx"	`startPrice`
编辑页档位 tab 切换展示各档起价	`tierPrices`
价格日历编辑/核对（含过期、含零价）	`priceCalendars`
Step5 预览页面渲染"行程保障/安全保障/FAQ"	`guaranteeItems` / `safetyItems` / `faqItems`
Step5 预览页面渲染"预订条款/温馨提示"富文本	`bookingTermsContent` / `warmTipsContent`

编辑模板 ID 选择时仍然使用 supplement.xxxTemplateId / supplement.xxxId 字段；本次新增的展开字段仅用于展示。

迁移建议

无需迁移。纯新增字段，老字段与老行为完全保持。

后端需重启的服务

hl-product-service-v2（端口 8083）

拉最新 dev 分支后重启该服务即可生效，其它服务不受影响。

5.3 KiB 原始文件 Blame 文件历史 Unescape Escape

管理端产品详情 扩展 档位起步价 + Step5 模板展开字段