hl-api-changelog/changelogs/2026-05/12_frontend_notice_admin_resource-product-icon-selling-point.md

资源服务 + 产品行程节点: 新增「图标」「卖点简介」2 字段

服务: hl-resource-service (端口 8082) + hl-product-service-v2 (端口 8083) PR: #2076 — 已合并 dev + 测试服部署 PR (hotfix admin VO 补字段): #2081 — 已合并 dev + 测试服部署 PR (hotfix Flyway pilot marker 解锁): #2077 — 与本功能间接相关 Issue: #2068 日期: 2026-05-12 影响范围: 管理端「资源管理 → 景区/活动/服务」 + 「产品编辑 → 行程编排/产品卖点」 + 小程序「今日体验」 状态: ✅ 测试服已验证 (api.test.1814.love:9443)

---

⚠️ 关键变化

资源端 3 类资源(景区 scenic-spot / 活动 activity / 服务 service-item) + 产品行程节点 product_itinerary_node,各新增 2 个字段:

• iconMaterialId — 图标素材 ID(指向素材库)
• sellingPoint — 卖点简介(VARCHAR 500)

业务联动:

• 资源端有这两个字段就是默认值
• 产品行程节点保存时,前端如果不传这两字段,后端自动从资源端拷贝默认值到节点快照
• 产品行程节点保存时,前端如果显式传值,以前端为准(产品端可改)
• 产品端改了节点的 icon/selling 也不回写资源(资源端永远是真相源)

---

一、测试服已验证 (硬性凭证)

hl-resource-service 测试服:
  POST/PUT/GET /admin/scenic/spot     iconMaterialId + sellingPoint 能存能取 ✓
  POST/PUT/GET /admin/activity/item   iconMaterialId + sellingPoint 能存能取 ✓
  POST/PUT/GET /admin/service/item    iconMaterialId + sellingPoint 能存能取 ✓
  GET .../page (列表)                  ListVO 含 iconMaterialId/iconUrl/sellingPoint ✓

hl-product-service-v2 测试服:
  POST /admin/product/item/.../itinerary  节点 SAVE 落库 ✓
  GET /admin/product/item/{id}             节点 VO 返回 iconMaterialId + sellingPoint ✓
  「资源默认值复制」: 前端不传 → 节点字段=资源端 iconMaterialId/sellingPoint ✓
  「前端覆盖优先」: 前端传值 → 节点字段=前端值 ✓
  「不回写资源」: 改节点后资源端字段不变 ✓

异常路径:

sellingPoint 传 501 字符 → HTTP 200 code=400 "卖点简介不能超过500个字符" ✓

---

二、变更接口清单

资源端

#	接口	方法	路径	变更类型	说明
1	景区 创建	POST	/admin/scenic/spot	请求体新增 2 字段	iconMaterialId, sellingPoint
2	景区 更新	PUT	/admin/scenic/spot	请求体新增 2 字段	同上
3	景区 详情	GET	/admin/scenic/spot/{id}	响应体新增 3 字段	iconMaterialId, iconUrl, sellingPoint
4	景区 列表	GET	/admin/scenic/spots	响应体新增 3 字段	列表项含 3 字段
5-8	活动 同上	-	/admin/activity/item*	同景区 4 接口	-
9-12	服务 同上	-	/admin/service/item*	同景区 4 接口	-

产品端

#	接口	方法	路径	变更类型	说明
13	行程保存	PUT	/admin/product/item/{id}/itinerary	节点 NodeItem 入参新增 2 字段	iconMaterialId, sellingPoint(可选)
14	产品详情	GET	/admin/product/item/{id}	节点 NodeRespVO 响应新增 3 字段	iconMaterialId, iconUrl, sellingPoint
15	mp 详情	GET	/mp/product/{id}	节点 NodeInfo 响应新增 3 字段	同上,小程序「今日体验」用

---

三、前端字段约束

字段	类型	必填	约束	备注
iconMaterialId	Long(产品节点) / String(资源端,String 表示的 BIGINT)	否	-	指向素材库的素材 ID
iconUrl	String	否(仅 Resp)	-	后端解析素材后的 OSS URL,前端只在响应中读,不传
sellingPoint	String	否	最多 500 字符	卖点简介文字

---

四、UI 层面建议(参考)

资源管理页

3 类资源(景区/活动/服务)的新建/编辑表单新增 2 个字段:

• 图标: 素材库选择器(选小尺寸图,推荐 64x64),保存 materialId
• 卖点简介: 多行文本框,提示"最多 500 字"

详情页/列表卡片可直接展示这两字段(用 iconUrl + sellingPoint)。

产品编辑页

行程编排 步骤(图1 的「活动安排」红框):

• 节点点击图标时弹出素材选择器 → 选完保存到节点的 iconMaterialId
• 节点详情面板新增卖点简介输入框(多行,500 字)
• 新建节点时,选完资源(景区/活动/服务) → 后端自动用资源端默认值预填,前端可改
• 修改节点的 icon/卖点 不会回写到资源,只影响当前产品的这个节点

产品卖点页(图2 的「快速理解」红框):

• 这个页面和「行程编排」共用同一份 product_itinerary_node 数据
• 也就是说在「行程编排」改了节点的 icon/卖点,「产品卖点」页面会立刻看到更新

---

五、风险/兼容性

• 不破坏现有调用: 只追加字段,旧请求不传 → null,旧响应消费方忽略新字段无影响
• Bean Validation: sellingPoint 后端用 @Size(max=500) 校验,前端最好也加前置校验避免 round-trip
• 不回写资源铁规: 后端 ProductItineraryService.convertNode() 已硬保证,前端无需关心

---

六、需要前端做的事

1. ⏰ 3 类资源管理页 加 2 个字段:图标素材选择器 + 卖点简介文本框(都不必填)
2. ⏰ 产品编辑 → 行程编排 加节点的 icon/卖点编辑(都不必填,空就用资源默认)
3. ⏰ 产品编辑 → 产品卖点 页面如果是独立路由,字段读取同 product_itinerary_node 节点
4. ⏰ 「今日体验」小程序节点前显示图标(iconUrl 字段) + 节点卖点(sellingPoint)
5. 如有疑问可直接对照 swagger: https://api.test.1814.love:9443/hl-resource-service/v2/api-docs?group=资源服务 以及 https://api.test.1814.love:9443/hl-product-service-v2/v2/api-docs?group=产品服务(账号 hulalv / HuLaLv@Doc2026)