2026-04-21 小程序主题卡片返回 linkUrl (#1097)

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`