2026-04-21 更正: 主题卡片跳转字典回滚枚举 + 路径存 remark (废弃 #1085 字典部分)

2026-04-21 15:06:23 +08:00 · 2026-04-21 15:06:23 +08:00 · 43446b0528
--- 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
@ -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
+
+---
+
+## 重启
+
+无后端代码改动，**不需要重启任何服务**。前端刷新页面即可看到正确下拉。