181 行
5.3 KiB
Markdown
181 行
5.3 KiB
Markdown
# 小程序首页第二屏 v2 - 去蒙层 + 内嵌卡片 + 类型校验
|
||
|
||
- **日期**: 2026-04-18
|
||
- **PR**: [#823](https://git.1814.love:8443/wx/HL/pulls/823) (Closes #822)
|
||
- **状态**: 已合并 + 测试环境 DDL/服务全就绪 + E2E 通过
|
||
|
||
---
|
||
|
||
## 变更概览
|
||
|
||
1. 删 `coverMaskType` 字段（全链路）
|
||
2. 品牌故事内嵌 2 张主题卡片（`cards` 数组，最多 2 张）
|
||
3. 修 PR #811 缓存失效 bug
|
||
4. 链接目标（产品/产品线）只允许 **CORE/GROUP** 类型，响应加 `linkTargetType`
|
||
|
||
---
|
||
|
||
## 1. Admin `PUT /admin/home-config/brand-story` 请求体变更
|
||
|
||
### 删除字段
|
||
- ~~`coverMaskType`~~
|
||
|
||
### 新增字段
|
||
- `cards`: `BrandCard[]`（最多 2 张）
|
||
|
||
```json
|
||
{
|
||
"title": "每一条线路，我们都亲自走过。",
|
||
"subtitle": null,
|
||
"description": "整个呼伦贝尔...",
|
||
"coverUrl": "https://cdn.1814.love/home/team-photo.jpg",
|
||
"publish": true,
|
||
"cards": [
|
||
{
|
||
"title": "季节之旅",
|
||
"subtitle": "夏·秋·冬三季体验",
|
||
"coverUrl": "https://cdn.1814.love/cards/season.jpg",
|
||
"linkType": "PRODUCT_LINE",
|
||
"linkTarget": "2045004175602868226"
|
||
},
|
||
{
|
||
"title": "亲子研学",
|
||
"subtitle": "边玩边学·深度体验",
|
||
"coverUrl": "https://cdn.1814.love/cards/study.jpg",
|
||
"linkType": "NONE",
|
||
"linkTarget": ""
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**BrandCard 字段**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|------|-----|
|
||
| title | String | ✓ | 标题（如"季节之旅"） |
|
||
| subtitle | String | - | 副标题 |
|
||
| coverUrl | String | ✓ | 背景图 URL（必须 https） |
|
||
| linkType | String | ✓ | NONE/PRODUCT/PRODUCT_LINE/ARTICLE/URL/MINI_PAGE |
|
||
| linkTarget | String | - | 跳转目标（id 或 url） |
|
||
|
||
### 业务校验
|
||
|
||
- `cards` 最多 2 张（`@Size(max=2)`）
|
||
- **PRODUCT/PRODUCT_LINE 时 linkTarget 对应的产品/产品线类型必须是 `CORE` 或 `GROUP`**，其他类型返回：
|
||
|
||
```json
|
||
{"code":500, "message":"卡片只能关联核心或小蒙马类型的产品/产品线", "data":null, "success":false}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Admin/MP GET 响应新增
|
||
|
||
### 响应结构
|
||
- Admin `GET /admin/home-config/brand-story` 返回的 `data` 里，`coverMaskType` 字段**已移除**，新增 `cards`
|
||
- MP `GET /mp/home-config/screen2` 返回 `data.cards`（原 `data.topics` **移除**）
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"brandStory": {
|
||
"title": "每一条线路，我们都亲自走过。",
|
||
"subtitle": null,
|
||
"description": "...",
|
||
"coverUrl": "..."
|
||
},
|
||
"cards": [
|
||
{
|
||
"title": "季节之旅",
|
||
"subtitle": "夏·秋·冬三季体验",
|
||
"coverUrl": "...",
|
||
"linkType": "PRODUCT_LINE",
|
||
"linkTarget": "2045004175602868226",
|
||
"linkTargetType": "CORE"
|
||
},
|
||
...
|
||
]
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
**`linkTargetType`** 字段说明：
|
||
- `CORE` / `GROUP` / `null`
|
||
- 仅 PRODUCT/PRODUCT_LINE 类型时填充，其他返 null
|
||
- 批量回填（Feign 调 product-v2 一次性批查），避免 N+1
|
||
|
||
---
|
||
|
||
## 3. 轮播图 `/admin/banner` 变更
|
||
|
||
### 请求（保存）
|
||
- linkType=PRODUCT/PRODUCT_LINE 时后端校验 linkId 的 productType 必须 CORE/GROUP，否则返：
|
||
```
|
||
{"code":500, "message":"轮播图只能关联核心或小蒙马类型的产品/产品线", ...}
|
||
```
|
||
|
||
### 响应
|
||
- BannerVO 新增 `linkTargetType` 字段（CORE/GROUP/null）
|
||
- 列表查询也批量回填，前端展示"核心"/"小蒙马"标签不用二次查询
|
||
|
||
---
|
||
|
||
## 4. MP 缓存
|
||
|
||
- Key: `home:screen2:mp:{env}`
|
||
- TTL 30 分钟
|
||
- **修复**: PR #811 发布后不失效的 bug 已修（`HomeBrandStoryService.publish()` 现在真正调用 `evictAfterCommit()`）
|
||
|
||
---
|
||
|
||
## 5. 前端改造清单
|
||
|
||
### 管理端 (hl-ui)
|
||
|
||
1. **品牌故事表单**：
|
||
- 删除"蒙层类型"下拉
|
||
- 新增"主题卡片"section，固定 2 张子表单（每张：标题/副标题/背景图/跳转类型/跳转目标）
|
||
- 跳转类型选择器选中 PRODUCT/PRODUCT_LINE 时，目标选择器**只显示 `productType=CORE` 或 `GROUP`** 的产品/产品线
|
||
- 展示页可读取 `linkTargetType` 显示标签（"核心"/"小蒙马"）
|
||
|
||
2. **轮播图表单 (`/mp-config/home/banner`)**：
|
||
- 选择器同上：只显示 CORE/GROUP
|
||
- 列表页展示 `linkTargetType` 标签（当 linkType=PRODUCT/PRODUCT_LINE）
|
||
|
||
### 小程序端
|
||
|
||
- 首页第二屏渲染：
|
||
- `data.brandStory` 是主文案块
|
||
- `data.cards` 是 2 张卡片（如原来的 `data.topics` 结构，但字段略不同）
|
||
- 卡片点击按 `linkType` + `linkTarget` 跳转
|
||
|
||
---
|
||
|
||
## 6. 产品/产品线选择器接口
|
||
|
||
前端选择器可用现有接口过滤 `productType`，或调新内部接口（如果暴露到管理端）：
|
||
|
||
- 管理端已有 `GET /admin/product-line/enabled`（列表接口）— 按 `productType` filter
|
||
- 如需求进一步精确，可联系后端加 `GET /admin/product-line/enabled?productTypes=CORE,GROUP`
|
||
|
||
---
|
||
|
||
## 7. 测试环境验证
|
||
|
||
- [x] DDL 已跑（sys_home_brand_story 无 cover_mask_type，有 cards JSON）
|
||
- [x] E2E: PUT cards → MP GET 立即可见（缓存 evict 生效）
|
||
- [x] E2E: cards linkType=PRODUCT_LINE linkTarget=假 id → 抛业务异常 "卡片只能关联核心或小蒙马类型的产品/产品线"
|
||
- [x] Admin GET 响应无 coverMaskType，MP GET 响应 `cards` 替代 `topics`
|
||
|
||
---
|
||
|
||
## 8. 关联 PR
|
||
|
||
- #811 首页第二屏 v1
|
||
- #813 Gateway 路由补丁
|
||
- #815 菜单 + 轮播图 PRODUCT_LINE 字典
|
||
- **#823 本 PR (v2)**
|