# 更正：主题卡片跳转字典回滚到枚举 + 路径存 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

---

## 重启

无后端代码改动，**不需要重启任何服务**。前端刷新页面即可看到正确下拉。