# [前端] admin 列表弹窗调用 /admin/scenic/spots 和 /admin/activity/items 应传 seasons 参数

> **服务**: 前端 hl-ui (管理端)
> **后端 PR**: 无独立后端 PR (后端能力 #2229/#2232 已就绪 + #2269 加 seasonHighlights)
> **日期**: 2026-05-14
> **影响范围**: 管理端 产品设计「补充信息 → 产品卖点」节点弹窗的封面图/标签/亮点展示

---

## ⚠️ 关键变化

**后端能力早就做了, 前端没传参数, 所以一直没生效**:

- PR #2229 commit 注明: "封面优先级: 若 query.seasons 非空,取首个季节匹配该景区 scenic_season 的 coverMaterialId"
- PR #2234 同款给游玩项目
- PR #2269 加 seasonHighlights 字段同款规则

前端弹窗 `/admin/scenic/spots?page=1&pageSize=20&status=1` 当前**没传** `seasons` 参数 → 后端走默认路径返回本体封面 + 不切换 seasonHighlights。

---

## 测试服后端能力已验证 (前端 fetch 同款 URL 即可看到效果)

```
# 无 seasons (当前前端行为):
GET /admin/scenic/spots?page=1&pageSize=3&status=1
→ records[0].coverUrl = oss 本体封面
→ records[0].seasonHighlights = null

# 带 seasons=autumn (期望前端行为):
GET /admin/scenic/spots?page=1&pageSize=3&status=1&seasons=autumn
→ records[0].coverUrl = unsplash 秋色封面 (按 scenic_season(autumn).cover_material_id 切换)
→ records[0].seasonHighlights = "秋色画廊边境公路,五彩斑斓,最佳自驾季"

# 带 seasons=summer:
GET /admin/scenic/spots?page=1&pageSize=3&status=1&seasons=summer
→ records[0].coverUrl = unsplash 夏景封面
→ records[0].seasonHighlights = "中国最美边境公路,草原河流白桦林,自驾天堂"
```

三态各异 ✓ 已通过 round-trip 测试验证。

---

## 前端需要做的事 (@mmg)

### 1. 找到调用 /admin/scenic/spots 和 /admin/activity/items 的弹窗代码

可能在产品编辑页 → 补充信息 → 产品卖点 → "添加节点" 弹窗组件。

### 2. 从当前编辑产品上下文取 productLine.seasons

- 编辑产品时, 已经知道 `lineId`
- 调 `/admin/product-line/{lineId}` 或当前产品详情拿 `productLine.seasons`
- 实际产品上下文应该已经有这个字段缓存 (PR #2229 上线后)

### 3. 拼参传给列表接口

```ts
// 伪代码
const seasons = currentProduct.productLine?.seasons ?? [];
const firstSeason = seasons[0]; // "spring"/"summer"/"autumn"/"winter"

const params = {
  page: 1,
  pageSize: 20,
  status: 1,
  ...(firstSeason && { seasons: firstSeason })  // 仅在有值时拼
};
fetch('/admin/scenic/spots?' + qs.stringify(params));
fetch('/admin/activity/items?' + qs.stringify(params));
```

### 4. 弹窗 UI 渲染

- **封面图**: 直接用 `coverUrl` (后端已按 seasons[0] 切换)
- **季节标签**: 用 `seasons[]` 字段渲染 4 季色块
- **卖点预览**: 优先 `seasonHighlights`, 为 null 时回落 `highlights`

---

## 前端不需要做的事

- ❌ **不要**改后端
- ❌ **不要**手动拼接两个字段 (后端已统一返回)
- ❌ **不要**在产品线 seasons 为空时省略字段 — 直接不传 seasons 参数即可, 后端会走旧行为

---

## 不影响范围

- **仅影响**: admin 产品编辑节点弹窗 (景区/游玩项目选择器)
- **零影响**: 其他 admin 列表 (产品列表/订单/酒店等不用季节维度)、小程序 C 端

---

## 验证

前端改完后, 测试场景:

1. 产品线 `seasons=['summer']` 的产品 → 弹窗景区封面变 summer 季节图, seasonHighlights 显示夏季亮点
2. 切到产品线 `seasons=['autumn']` 的产品 → 弹窗景区封面变 autumn, seasonHighlights 改秋季亮点
3. 产品线无 seasons → 弹窗景区显示本体封面 + seasonHighlights 为 null 时回落 highlights

---

## 相关历史

| PR/Issue | 说明 |
|---|------|
| #2229/#2227 | 景区季节过滤 + 封面切换 + 标签 (后端) |
| #2234/#2232 | 游玩项目同款 |
| #2269/#2267 | 列表加 seasonHighlights |

---

## 相关文档

- 后端能力 PR #2229: [wx/HL#2229](https://git.1814.love:8443/wx/HL/pulls/2229)
- 后端能力 PR #2234: [wx/HL#2234](https://git.1814.love:8443/wx/HL/pulls/2234)
- 后端能力 PR #2269: [wx/HL#2269](https://git.1814.love:8443/wx/HL/pulls/2269)
