API Changelog Bot 178fe3d5a4 feat(product-v2,order-v2,mp): EquipmentItem 补 icon + color 字段契约 (PR #1273 )

2026-04-23 11:28:22 +08:00

4.2 KiB

原始文件 Blame 文件历史

装备建议条目 EquipmentItem 补 icon + color 字段

日期: 2026-04-23 PR: #1273 (Closes #1272) 服务: hl-product-service-v2 / hl-order-service-v2 / hl-mp-service 类型: feat（新增字段，向后兼容）

背景

PR #1259 上线后前端实现装备建议条目 UI，发现需要后端结构化传图标标识和颜色，不希望纯靠前端按 text 关键词猜图标。本次补字段。

字段扩展

EquipmentItem 结构

interface EquipmentItem {
  text:   string;   // 必填，1-50 字
  icon?:  string;   // 可选，图标 key，≤64 字
  color?: string;   // 可选，颜色值，≤16 字（建议 #RRGGBB）
}

约束总表（JSR-303 现已生效）

字段	必填	长度	错误消息
text	✅	1-50 字	`equipmentList[N].text: 装备文案不能为空` / `装备文案长度需在 1-50 字符之间`
icon	❌	≤64 字	`equipmentList[N].icon: 图标标识长度不能超过 64 字符`
color	❌	≤16 字	`equipmentList[N].color: 颜色值长度不能超过 16 字符`

color 格式：后端不硬校验 #RRGGBB 格式，前端可传任意 ≤16 字符串（如 red / #FFA726 / rgb(255,167,38)）。推荐 #RRGGBB 以便 admin/mp 渲染一致。

影响接口（5 处响应 + 1 处请求）

接口	变化
`PUT /admin/product/item/{id}/supplement`	请求 `equipmentList[].icon` / `[].color` 可选
`GET /admin/product/item/{id}`	响应 `supplement.equipmentList[].icon/color` 新增
`GET /mp/product/{id}`	响应 `equipmentList[].icon/color` 新增
`GET /mp/order/{id}`	响应 `equipmentList[].icon/color` 新增（订单快照固化）
`GET /mp/order/{orderId}/supplies-checklist`	响应 `equipmentList[].icon/color` 新增

示例

保存（带图标和颜色）

PUT /admin/product/item/123/supplement
{
  "equipmentList": [
    {"text": "防晒霜 SPF50+", "icon": "sunscreen", "color": "#FFA726"},
    {"text": "长袖防晒衣", "icon": "shirt"},
    {"text": "运动鞋"}
  ]
}
→ 200 {"code":200, "success":true}

MP 详情回显

{
  "equipmentList": [
    {"text":"防晒霜 SPF50+", "icon":"sunscreen", "color":"#FFA726"},
    {"text":"长袖防晒衣", "icon":"shirt", "color":null},
    {"text":"运动鞋",      "icon":null,      "color":null}
  ]
}

超限 400

PUT .../supplement
{"equipmentList":[{"text":"x","icon":"aaaa...(65字)"}]}
→ 400 {"code":400, "message":"equipmentList[0].icon: 图标标识长度不能超过 64 字符"}

前端适配建议

1. icon 字段

推荐约定：前后端商量一份 iconKey 表（如 sunscreen/shirt/jacket/shoe/bug/hat/sunglasses/water-bottle/umbrella/camera/headlamp/...），前端内置图标库按 iconKey 查表渲染。

降级逻辑：

icon 有值 → 前端按 key 查图标库渲染
icon 为 null → 前端按 text 关键词硬匹配图标（PR #1259 方案）
都没匹配上 → 显示默认占位图标

2. color 字段

color 有值 → 应用到图标颜色/文字颜色/背景色等
color 为 null → 使用主题默认色

3. admin 编辑器

图标选择：内置 iconKey 下拉选择器（下拉源是前端约定的图标库）
颜色选择：内置色板选择器（el-color-picker 等）
两字段都可留空（提交时对应字段不传或传 null）

向后兼容

现有调用方不传 icon/color：后端接受，DB 存 JSON 不含这两个键
老订单快照：JSON 内条目没有 icon/color 键 → 反序列化后 EquipmentItem.icon/color = null
前端可直接升级，旧数据 null 兼容性零风险

验证

测试服网关已 curl 6 场景全过：

混合保存（含 icon+color+只 text）→ 200
Admin 详情回显 → 3 条字段精确
MP 详情 icon/color 透传 → 正确
icon 超 64 字 → 400
color 超 16 字 → 400
老数据 null → 自然降级，无回归

部署

测试服已部署完毕:

product-v2 task f7952e0c success
order-v2 task e94c50cd success
mp-service task 5b005209 success

正式环境部署：无需 DDL（equipment_list 列已在 PR #1259 DDL 时加，新字段存在同一 JSON 列内）。

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