# 小程序主题卡片返回 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`