diff --git a/changelogs/2026-04/2026-04-21_brand-card-link-url-from-dict-remark.md b/changelogs/2026-04/2026-04-21_brand-card-link-url-from-dict-remark.md new file mode 100644 index 0000000..9793e72 --- /dev/null +++ b/changelogs/2026-04/2026-04-21_brand-card-link-url-from-dict-remark.md @@ -0,0 +1,110 @@ +# 小程序主题卡片返回 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` 拼 | + +--- + +## 响应示例 + +```json +{ + "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: +```js +// ❌ 旧做法,可以不再维护 +const ROUTE = { SEASON: 'packages/product/season/list/list', ... }; +wx.navigateTo({ url: '/' + ROUTE[card.linkType] }); +``` + +新做法: +```js +// ✅ 新做法,直接读 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`