# resource: admin 列表 ScenicSpotListVO/ActivityListVO 加 seasonHighlights 字段

> **服务**: hl-resource-service (端口 8082)
> **PR**: #2269
> **Issue**: #2267
> **日期**: 2026-05-14
> **影响范围**: 管理端 产品设计「补充信息 → 产品卖点」节点弹窗预览

---

## ⚠️ 关键变化

紧接 #2229/#2232/#2250/#2263 季节系列。

产品设计弹窗调 `/admin/scenic/spots`, `/admin/activity/items` 列表时, 当前 VO 只有 `highlights` (本体) + `seasons[]` (4 季列表), 没有 `seasonHighlights` (按 query.seasons[0] 命中季节亮点)。前端拿不到「当前产品季节对应的亮点文本」, 无法在弹窗预览或自动带入。

本次加字段, 由 query.seasons 入参驱动后端返回对应季节的 highlights。

---

## 影响接口

| # | 接口 | 方法 | 路径 | 变更 |
|---|------|------|------|------|
| 1 | 景区列表 | GET | `/admin/scenic/spots` | VO 加 `seasonHighlights: String` |
| 2 | 游玩项目列表 | GET | `/admin/activity/items` | VO 加 `seasonHighlights: String` |

入参字段 `seasons` (List<String>) 沿用 #2229/#2232 已有。

---

## 装配规则 (字段独立, 复用现有 Map 零额外 SQL)

```
query.seasons 非空 → 取 seasons[0] 命中的 scenic_season/activity_season.highlights → seasonHighlights
未命中 → seasonHighlights = null (前端回落显示本体 highlights)
query.seasons 为空/null → seasonHighlights = null (向前兼容)
```

复用 PR #2229/#2232 已建的 `seasonsByScenicId` / `seasonsByActivityId` Map 和 `firstSeason` 变量, 零额外查询。

---

## 响应示例

### GET /admin/scenic/spots?page=1&pageSize=3&status=1&seasons=autumn

```json
{
  "code": 200,
  "data": {
    "records": [
      {
        "scenicId": 3001000000000000019,
        "name": "中俄边境公路（卡线）",
        "highlights": "中国最美边境自驾路，200公里移动的画廊",
        "seasons": ["spring","summer","autumn","winter"],
        "seasonHighlights": "秋色画廊边境公路,五彩斑斓,最佳自驾季",
        "coverUrl": "https://images.unsplash.com/photo-XXX-autumn.jpg",
        "...": "..."
      }
    ]
  }
}
```

### GET /admin/scenic/spots?page=1&pageSize=3&status=1 (无 seasons)

```json
{
  "data": {
    "records": [
      {
        "scenicId": 3001000000000000019,
        "name": "中俄边境公路（卡线）",
        "highlights": "中国最美边境自驾路，200公里移动的画廊",
        "seasons": ["spring","summer","autumn","winter"],
        "seasonHighlights": null,
        "coverUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/.../本体.jpg"
      }
    ]
  }
}
```

---

## 测试服三态对比已验证

同一景区 scenicId=3001000000000000019 (中俄边境公路):

| seasons 参数 | seasonHighlights 值 |
|---|---|
| 无 | `null` |
| seasons=summer | `中国最美边境公路,草原河流白桦林,自驾天堂` |
| seasons=autumn | `秋色画廊边境公路,五彩斑斓,最佳自驾季` |

✓ 字段切换符合预期, 内容语义匹配季节。

`/admin/activity/items` 同款字段已暴露, 当前数据为空 (activity_season 表无配置, 等运营通过 PR #2262 接口配后才有值)。

---

## 前端使用建议 (@mmg)

弹窗调用列表接口时:

1. **从当前编辑产品 productLine.seasons 取首个季节, 拼入 query 参数** `seasons=spring/summer/autumn/winter`
2. **优先级显示**: `seasonHighlights ?? highlights` (`seasonHighlights` 非空时用季节亮点, null 时回落本体)
3. 不必关心后端装配细节, 字段返 null 直接走旧 UI 即可

如果前端弹窗调用时没传 seasons 参数, 后端会保留旧行为返 `seasonHighlights: null`, **不会破坏现有展示**。

---

## 不影响范围

- **仅影响**: 管理端景区/游玩项目列表 VO 加 1 字段
- **零影响**: 小程序 C 端、订单、价格、admin 详情 API、其他列表

---

## 风险评估

- 极低: 装配只读已有 Map, 零额外 SQL, 零 DB 改动, 零 Flyway
- 向前兼容: 旧调用方拿到 null 不报错

---

## 相关历史 PR

| PR | Issue | 说明 |
|----|-------|------|
| #2229 | #2227 | 景区列表加 seasons 字段 + 封面按 seasons[0] 切换 |
| #2234 | #2232 | 游玩项目同款 |
| #2250 | #2243 | 节点 description 按 seasons[0] 回落 highlights |
| #2263 | #2256 | 节点 ResourceDetailDTO 加 seasonCover/seasonBanner/seasonVideo |
| **#2269** | **#2267** | **本 PR**: 列表 VO 加 seasonHighlights |

---

## 相关文档

- Issue: [wx/HL#2267](https://git.1814.love:8443/wx/HL/issues/2267)
- PR: [wx/HL#2269](https://git.1814.love:8443/wx/HL/pulls/2269)
