hl-api-changelog/changelogs/2026-04/2026-04-21_brand-card-link-url-from-dict-remark.md

小程序主题卡片返回 linkUrl（从字典 remark 解析）

日期：2026-04-21（同日晚） PR：#1097 后端服务：hl-user-service（写/读）+ hl-mp-service（BFF 透传，必须同步重启，common-core DTO 改动） 影响：小程序首页第二屏 GET /mp/home-config/screen2 响应体

---

变更点

BrandCard DTO（小程序 data.cards[] 每一项）新增字段 linkUrl：

字段	类型	何时有值	说明
linkUrl	String	linkType ∈ {SEASON, CORE_LIST, MENGMA}	由后端从字典 theme_card_link_type.remark 解析得到的页面路径
linkUrl	null	linkType = PRODUCT 或字典未配	PRODUCT 前端自行按 linkTargetType + linkTargetId 拼

---

响应示例

{
  "code": 200,
  "data": {
    "brandStory": { ... },
    "cards": [
      {
        "title": "季节之旅",
        "coverUrl": "https://...",
        "linkType": "SEASON",
        "linkTargetType": null,
        "linkTargetId": null,
        "linkUrl": "packages/product/season/list/list"
      },
      {
        "title": "亲子游学",
        "coverUrl": "https://...",
        "linkType": "MENGMA",
        "linkTargetType": null,
        "linkTargetId": null,
        "linkUrl": "packages/product/mengma/list/list"
      }
    ]
  }
}

---

小程序端对接（可以大幅简化）

之前版本需要前端维护 code → 路径 switch：

// ❌ 旧做法，可以不再维护
const ROUTE = { SEASON: 'packages/product/season/list/list', ... };
wx.navigateTo({ url: '/' + ROUTE[card.linkType] });

新做法：

// ✅ 新做法，直接读 linkUrl
if (card.linkType === 'PRODUCT') {
  // PRODUCT 按 linkTargetType + linkTargetId 拼产品详情
  wx.navigateTo({ url: `/packages/product/${card.linkTargetType.toLowerCase()}/detail?id=${card.linkTargetId}` });
} else {
  wx.navigateTo({ url: '/' + card.linkUrl });
}

路径配置完全由后台字典 theme_card_link_type.remark 控制，未来换路径不用发版小程序，只改字典即可。

---

字典 remark 约定

dict_value=SEASON     remark="跳转: packages/product/season/list/list"
dict_value=CORE_LIST  remark="跳转: packages/product/core/list/list"
dict_value=MENGMA     remark="跳转: packages/product/mengma/list/list"
dict_value=PRODUCT    remark="指定产品详情..."（非路径，linkUrl=null）

后端只认 "跳转: " 开头的 remark 作为 URL。其它 remark 被当成描述文本，linkUrl=null。

---

降级行为

• 字典 theme_card_link_type 未配或查询异常 → linkUrl=null，前端可回退自维护映射或不跳转
• 老数据 linkType=null 被后端兜底为 SEASON，继续有 linkUrl（保持旧行为）

---

测试

• MpHomeConfigServiceTest 新增 3 个 case（SEASON/MENGMA 有 URL / PRODUCT null / 字典降级）
• 本地 API curl 已通过：/mp/home-config/screen2 → cards[].linkUrl 正确填充
• 测试服已部署 user + mp

---

重启

两个服务都要重启：

• hl-user-service（生成 BrandCard.linkUrl 的源头）
• hl-mp-service（透传 BrandCard，如果 fat jar 里带旧版 common-core class 不重启会丢字段）

参考经验：experience/test-server-admin/shared-common-core-dto-all-consumers-redeploy.md