API Changelog Bot 7bcc0c07a6 docs(mp): banner changelog 修正 seasons 为小写字典值 (spring/summer/autumn/winter)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-19 01:23:19 +08:00

3.9 KiB

原始文件 Blame 文件历史

小程序首页 Banner - 响应新增 linkTarget 嵌套对象

日期: 2026-04-19
PR: #890 (Closes #889)
类型: FEATURE
状态: 已合并到 dev + 测试环境部署完成
服务: hl-user-service + hl-product-service-v2
接口: GET /mp/banner/active
兼容性: 向后兼容（仅新增字段，旧字段全部保留）

一、背景

小程序拿到 /mp/banner/active 列表后，当用户点到某条 Banner，前端还要再发一次产品/产品线详情请求才能展示封面、季节、产品类型，白屏等待感明显。

后端一把返回 Banner 展示所需的关联目标轻量信息，前端零二次请求。

二、响应新增字段

顶层新增 `linkTarget`

Banner 列表每个元素在原有字段基础上新增：

{
  "id": "1",
  "title": "小蒙马亲子专题",
  "imageUrl": "https://cdn.example.com/banner1.jpg",
  "linkType": "PRODUCT_LINE",
  "linkId": "1001",
  "linkTargetType": "GROUP",        // 保留,兼容旧前端
  "linkTargetName": "小蒙马亲子",    // 保留,admin 填的展示名

  // ⬇⬇⬇ 新增嵌套对象
  "linkTarget": {
    "type": "PRODUCT_LINE",
    "id": 1001,
    "name": "小蒙马亲子",
    "subtitle": null,
    "coverImageUrl": "https://cdn.example.com/line-cover.jpg",
    "productType": "GROUP",
    "seasons": ["spring", "summer"],
    "lineId": null
  }
}

`linkTarget` 字段明细

字段	类型	说明	产品线	产品
`type`	string	`PRODUCT` \| `PRODUCT_LINE`	✅	✅
`id`	long	目标 ID（产品 ID 或产品线 ID）	✅	✅
`name`	string	名称	✅	✅
`subtitle`	string \| null	副标题	null	✅
`coverImageUrl`	string \| null	封面图 URL	✅	✅
`productType`	string	`CORE` / `GROUP` / `CUSTOM`	✅	✅
`seasons`	string[]	适用季节，字典 `product_season`：`spring` / `summer` / `autumn` / `winter`（小写）	✅	✅
`lineId`	long \| null	所属产品线 ID	null	✅

`linkTarget=null` 的情况

以下场景 linkTarget 整体为 null，前端按「无卡片详情可展示」处理即可（原有字段 title / imageUrl / linkType / linkId 照常渲染和跳转）：

linkType 不是 PRODUCT 或 PRODUCT_LINE（例如 SCENIC / PAGE / WEBVIEW / NONE）
关联目标已被删除或下架
后端 Feign 降级（产品服务短暂不可用）

三、前端集成建议

卡片展示

// 列表渲染时
banners.forEach(banner => {
  const target = banner.linkTarget;
  if (target) {
    // 可直接用 target.name / target.coverImageUrl / target.seasons 渲染副卡
    renderTargetCard({
      cover: target.coverImageUrl,
      title: target.name,
      subtitle: target.subtitle,
      tags: target.seasons,  // ['SPRING', 'SUMMER']
    });
  } else {
    // 仅渲染 Banner 主图,点击跳 linkType + linkId
  }
});

季节文案映射（前端字典）

const SEASON_LABEL = {
  spring: '春季',
  summer: '夏季',
  autumn: '秋季',
  winter: '冬季',
};
// target.seasons.map(s => SEASON_LABEL[s]) → ['春季', '夏季']

跳转路径

跳转规则不变：继续用外层的 linkType + linkId 决定跳转目标路由。linkTarget 只用于 Banner 上的视觉展示。

四、其它说明

旧字段全部保留：linkType / linkId / linkTargetType / linkTargetName 行为不变，前端原有兼容逻辑不用动
缓存：Banner 列表带 30 分钟 Redis 缓存 + 事务提交后自动 evict，管理员改完 Banner 小程序下次拉取就能看到最新 linkTarget
admin 管理端接口未受影响：banner 创建/编辑/列表接口未变（admin 只用 linkTargetType 做合法性提示，不返回 linkTarget）

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