diff --git a/changelogs/2026-04/2026-04-21_theme-card-link-rollback-to-enum-paths-in-remark.md b/changelogs/2026-04/2026-04-21_theme-card-link-rollback-to-enum-paths-in-remark.md new file mode 100644 index 0000000..72043e4 --- /dev/null +++ b/changelogs/2026-04/2026-04-21_theme-card-link-rollback-to-enum-paths-in-remark.md @@ -0,0 +1,106 @@ +# 更正:主题卡片跳转字典回滚到枚举 + 路径存 remark + +**日期**:2026-04-21(同日晚) +**类型**:方案更正 / DB 回滚,**无后端代码变更** +**后端服务**:hl-user-service(不用重启) +**影响**:管理端「首页配置 → 品牌故事 → 主题卡片跳转类型」下拉 + +--- + +## 背景(请先读完再做事) + +今早同一个业务话题发过两份 changelog: +1. `2026-04-21_home-screen2-theme-card-link.md`(#1081)—— 字典 value=`SEASON/CORE_LIST/MENGMA/PRODUCT` 枚举 +2. `2026-04-21_topic-link-type-paths-and-product-payload.md`(#1085)—— 尝试把 value 改成完整路径 `packages/product/season/list/list` + +**本更正废弃第 2 份里关于「字典 value 改为路径」的部分**,恢复为第 1 份的枚举方案,路径改放到 `remark` 字段。 + +--- + +## 为什么回滚 + +- `AdminBrandStorySaveReqVO.Card.linkType` 上有 `@Pattern(regexp="^(SEASON|CORE_LIST|MENGMA|PRODUCT)$")` 硬校验 +- `HomeBrandStoryService.VALID_LINK_TYPES` 也是同名 4 个枚举白名单 +- 如果把字典 value 改成路径,前端下拉选中后提交 `linkType=packages/product/season/list/list` → 后端 `@Pattern` 拒绝 → **500 报错** `cards[].linkType: 跳转类型只能是 SEASON / CORE_LIST / MENGMA / PRODUCT` +- 权衡后:**代码不动、字典回滚到枚举、前端需要的路径放在 remark**,方案更稳(未来改路径只改字典 remark,不需要动后端代码) + +--- + +## 字典最终状态(本地 + 测试服 192.168.100.236 已同步) + +`sys_dict_type`:`theme_card_link_type`(dict_type_id=8090,category=BUSINESS,ACTIVE) + +`sys_dict_data`: + +| dict_data_id | dict_value | dict_label | remark(路径在这里) | +|--------------|-----------|-----------|------| +| 80901 | `SEASON` | 季节之旅 | `跳转: packages/product/season/list/list` | +| 80902 | `CORE_LIST` | 核心产品 | `跳转: packages/product/core/list/list` | +| 80903 | `MENGMA` | 亲子游学 | `跳转: packages/product/mengma/list/list` | +| 80904 | `PRODUCT` | 指定产品 | `指定产品详情(linkTargetType=CORE/GROUP + linkTargetId)` | + +--- + +## 前端对接要点(替换第 2 份 changelog 的相关章节) + +### 管理端下拉渲染 +- 拉 `/admin/dict/data?dictType=theme_card_link_type` 得到 4 条 +- **下拉 option 用 `dict_label` 做显示文案**、**`dict_value` 做表单值**(保持枚举) +- 如果前端需要跳转路径(例如预览 / 提示):**解析 `remark`**,去掉固定前缀 `"跳转: "` 得到路径;PRODUCT 的 remark 是说明文本,不是路径(需 linkTargetType+linkTargetId 动态拼) + +### 保存(POST/PUT brand-story) +请求体 `cards[].linkType` 仍然只能是 **4 个枚举值之一**: +```json +{ + "cards": [ + { + "title": "季节之旅", + "coverUrl": "https://...", + "linkType": "SEASON" + }, + { + "title": "亲子系列", + "coverUrl": "https://...", + "linkType": "PRODUCT", + "linkTargetType": "CORE", + "linkTargetId": 2001 + } + ] +} +``` +- `linkType` ∈ `{SEASON, CORE_LIST, MENGMA, PRODUCT}`(**不要**传路径) +- `linkType=PRODUCT` 时 `linkTargetType` + `linkTargetId` 必填;其它 linkType 不用传 / 传了也会被后端清空 + +### 小程序侧 +- Feign/聚合接口返回的 `BrandCard.linkType` 仍然是 4 个枚举之一(#1081 原样) +- 小程序自己维护一张 code → 路径的 switch: + ```js + const ROUTE_BY_LINK_TYPE = { + SEASON: 'packages/product/season/list/list', + CORE_LIST: 'packages/product/core/list/list', + MENGMA: 'packages/product/mengma/list/list', + // PRODUCT 运行时按 linkTargetType + linkTargetId 拼 + }; + ``` +- 路径单一真相源:字典 `remark` 字段;改路径只需改字典,无须发版 + +--- + +## 第 2 份 changelog 的哪些内容仍然有效 + +`2026-04-21_topic-link-type-paths-and-product-payload.md` 里关于 **`/admin/topic` 接口**的变动(`TopicRequest` / `TopicVO` 新增 `productId` + `productType`)**仍然有效**,那是独立的一套(PR #1085 已合并部署),和本次 brand-story 无关。但 topic 那套 `linkType` 也应该按枚举传(和 brand-story 口径统一),不要传长路径。 + +--- + +## 验证 + +- 本地 DB(127.0.0.1:3306/hl_user_service)已回滚 ✅ +- 测试服 DB(192.168.100.236/hl_user_service)已回滚 ✅ +- `sys_topic.link_type` 列宽留在 VARCHAR(200),不回滚(多出的空间不占事) +- 后端 `@Pattern` 和 `VALID_LINK_TYPES` 与字典 value 再次一致,保存不再 500 + +--- + +## 重启 + +无后端代码改动,**不需要重启任何服务**。前端刷新页面即可看到正确下拉。