111 行
3.3 KiB
Markdown
111 行
3.3 KiB
Markdown
# 小程序主题卡片返回 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`
|