# resource: 加 ActivitySeasonController admin CRUD (补 #2232 漏做配置入口)

> **服务**: hl-resource-service (端口 8082)
> **PR**: #2262
> **Issue**: #2257
> **日期**: 2026-05-14
> **影响范围**: 管理端 游玩项目编辑 季节内容配置（admin 前端需加同款"季节内容" tab）

---

## ⚠️ 关键变化

PR #2232 (游玩项目季节过滤+节点标签) 加了 activity_season 表 + Entity + Mapper + ListVO 装配, 但**漏做 admin 配置入口** — 运营无处填数据 → /admin/activity/items 接口 seasons 字段恒返 `[]` → 前端弹窗无季节标签。

本次补全, 对照 ScenicSeasonController 同款实现 admin CRUD。

---

## 接口清单

| # | 接口 | 方法 | 路径 |
|---|------|------|------|
| 1 | 获取游玩项目全部季节内容 | GET | `/admin/activity/item/{activityId}/seasons` |
| 2 | 保存/更新季节内容 (upsert) | PUT | `/admin/activity/item/{activityId}/season/{seasonType}` |
| 3 | 删除季节内容 | DELETE | `/admin/activity/item/{activityId}/season/{seasonType}` |

路径风格走 `/admin/activity/item/` 前缀对齐 ActivityController 现有风格 (scenic 走 `/spot/`)。

---

## 接口详情

### 1. 获取季节内容 `GET /admin/activity/item/{activityId}/seasons`

**响应**: `Result<List<ActivitySeasonVO>>`

```json
{
  "code": 200,
  "data": [
    {
      "seasonId": 2054831396190347266,
      "activityId": 2023705891743739905,
      "seasonType": "spring",
      "seasonName": "春日",
      "monthStart": 3,
      "monthEnd": 5,
      "description": "春日体验",
      "highlights": "春日亮点测试",
      "playGuide": "<p>春日攻略</p>",
      "tips": "春日注意",
      "coverMaterialId": null,
      "bannerMaterialIds": null,
      "videoMaterialIds": null,
      "createdAt": "2026-05-14T15:43:00",
      "updatedAt": "2026-05-14T15:43:00"
    }
  ]
}
```

无数据返 `data: []`。

### 2. 保存/更新季节内容 `PUT /admin/activity/item/{activityId}/season/{seasonType}`

**入参** `SeasonSaveRequest`:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| seasonName | String | ❌ | 季节别名("赏秋季"/"冰雪季") |
| monthStart | Integer | ✅ | 开始月份 1-12 |
| monthEnd | Integer | ✅ | 结束月份 1-12 (可跨年如冬季 12-2) |
| description | String | ❌ | 该季节简介 |
| highlights | String | ❌ | 该季节亮点 (短文案, ≤500 字) |
| playGuide | String | ❌ | 该季节游玩攻略 (富文本) |
| tips | String | ❌ | 该季节注意事项 |
| coverMaterialId | Long | ❌ | 季节封面素材 ID |
| bannerMaterialIds | List<Long> | ❌ | 季节轮播图素材 ID 列表 |
| videoMaterialIds | List<Long> | ❌ | 季节视频素材 ID 列表 |

**幂等**: 由 (activity_id, season_type) 唯一约束保证, 已存在 → 更新, 否则 → 插入。

`seasonType` 枚举: `spring/summer/autumn/winter` (其他值返 320401 ACTIVITY_SEASON_TYPE_INVALID)。

### 3. 删除 `DELETE /admin/activity/item/{activityId}/season/{seasonType}`

**响应**: `Result<Void>` 成功返 `code=200, data=null`。

---

## 数据库行为

- 表: `activity_season` (PR #2232 V20260514_001 已建)
- 雪花 ID 主键
- 上 (activity_id, season_type) 唯一约束保证幂等
- updated_at 字段自动刷新

---

## 边界

- activityId 不存在 → 404 (校验 activity 主表存在)
- seasonType 非 spring/summer/autumn/winter → 320401
- monthStart > monthEnd 在冬季跨年场景合法 (如 12-2)
- 删除不存在的 season → 静默成功 (幂等)

---

## 测试服已验证 (round-trip PASS)

```
selected activityId: 2023705891743739905 (满洲里草原篝火晚会)
GET seasons (初): []                                                    ✓
PUT season/spring (highlights="春日亮点测试"): 200, seasonId 返回         ✓
GET seasons (中): 1 条 spring                                            ✓
GET /admin/activity/items records[X].seasons: ["spring"] (联动 list)     ✓
DELETE season/spring: 200                                                ✓
GET seasons (终): []                                                    ✓
```

---

## 前端待补 (@mmg)

游玩项目编辑页加同款"季节内容" tab (对照景区编辑页), 调上面 3 个 admin API CRUD 4 季内容。运营配数据后, `/admin/activity/items` 接口的 `seasons` 字段才会有数据, `seasonHighlights` (PR #2269) 才会非空。

---

## 不影响范围

- **仅影响**: 管理端游玩项目维护 (新增 admin 路径) + 数据基础供 PR #2269 / #2271 季节回落
- **零影响**: 小程序 C 端、订单、价格、算价

---

## 相关历史 PR

| PR | Issue | 说明 |
|----|-------|------|
| #2234 | #2232 | 游玩项目季节过滤 + 节点季节标签 (但漏做 admin 入口) |
| #2229 | #2227 | 景区同款 + ScenicSeasonController (对照范本) |
| **#2262** | **#2257** | **本 PR**: 补 ActivitySeasonController |

---

## 相关文档

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