wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

feat: 季节系列 4 份 changelog (PR #2262/#2263+#2271/#2269 + 前端补传 seasons 通知 @mmg)

浏览代码 
- 14_feat_admin_activity_season_admin_crud.md (PR #2262, Issue #2257):
  补 ActivitySeasonController admin CRUD, 修 PR #2232 漏做配置入口

- 14_feat_admin_list_season_highlights_field.md (PR #2269, Issue #2267):
  ScenicSpotListVO/ActivityListVO 加 seasonHighlights 字段

- 14_feat_mp_node_media_season_pipeline_through.md (PR #2263+#2271, Issue #2256+#2268):
  节点封面/轮播图/视频按 productLine.seasons[0] 季节回落, MP Assembler 接通

- 14_frontend_admin_list_should_pass_seasons_param.md:
  前端补传 seasons 参数给 /admin/scenic/spots 和 /admin/activity/items
  后端能力早做了 (PR #2229/#2234), 前端没传所以一直没生效

notify @mmg

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
这个提交包含在：
API Changelog Bot 2026-05-14 16:30:23 +08:00
父节点 9947af26d0
当前提交 36a4f810b0
共有 4 个文件被更改，包括 542 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

149
changelogs/2026-05/14_feat_admin_activity_season_admin_crud.md 普通文件
查看文件

@ -0,0 +1,149 @@
# 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)

145
changelogs/2026-05/14_feat_admin_list_season_highlights_field.md 普通文件
查看文件

@ -0,0 +1,145 @@
# 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)

127
changelogs/2026-05/14_feat_mp_node_media_season_pipeline_through.md 普通文件
查看文件

@ -0,0 +1,127 @@
# resource + product-v2: 节点封面/轮播图/视频按产品线 seasons[0] 季节回落 (基础设施 + MP 消费侧接通)
> **服务**: hl-resource-service (端口 8082) + hl-product-service-v2 (端口 8083)
> **PR**: #2263 (基础设施) + #2271 (MP 消费侧接通)
> **Issue**: #2256 + #2268
> **日期**: 2026-05-14
> **影响范围**: 小程序 C 端 产品详情节点封面/轮播图按当前产品线季节自动切换
---
## ⚠️ 关键变化
紧接 #2243/#2250 节点 description 季节回落。把同款规则推广到节点的 3 个媒体字段:
> 「产品中也要显示对应季节的封面图轮播图视频啥的, 季节没有才显示景区/游玩项目自己的」 — wx 2026-05-14
**取数链路 (回落顺序, 字段独立)**:
```
节点 cover = scenic_season.cover_material_id WHERE seasons[0] || scenic_spot.cover_material_id || null
节点 images (banner) = scenic_season.banner_material_ids WHERE seasons[0] || scenic_spot.banner_material_ids || []
节点 videos (ID 列表) = scenic_season.video_material_ids WHERE seasons[0] || scenic_spot.video_material_ids || []
```
ACTIVITY 节点同款 (activity_season → activity)。产品线 seasons 为 null/空 → 走旧行为(本体), 向前兼容。
季节匹配规则: 取**产品对应产品线** `productLine.seasons[0]` (首个季节), 与封面切换 #2229/#2234 行为一致。
---
## 实现方案 (选 B: 详情装配动态计算, 不写节点表)
`ProductItineraryNodeDO` 本来就没 cover_material_id / banner_material_ids / video_material_ids 列, 加列代价大且与现有资源层季节子表设计正交。
改在 ResourceBatchDetailService 装配 ResourceDetailDTO 时, SCENIC/ACTIVITY 节点的 cover 优先用季节素材 URL → 回落本体, images 优先用季节轮播列表 → 回落本体。下游消费方 (product-v2 toNodeItem) **零改动**自动拿到季节切换值。
PR #2263 改基础设施 + DTO; PR #2271 改 product-v2 MP Assembler 接通 season 参数 (实时路径取 productLine.seasons[0], 快照路径取 snapshot.seasons[0] 符合冻结语义)。
---
## 接口字段变化
### Internal: ResourceDetailDTO 新增 4 字段 (PR #2263)
| 字段 | 类型 | 说明 |
|------|------|------|
| seasonCoverMaterialId | Long | 季节封面素材 ID (按入参 season 命中) |
| seasonBannerMaterialIds | List<Long> | 季节轮播图素材 ID 列表 |
| seasonVideoMaterialIds | List<Long> | 季节视频素材 ID 列表 |
| videoMaterialIds | List<Long> | 视频素材 ID 列表(本体, 补全字段) |
调用方 `GET /internal/resource/batch-details` 加 `season` 入参, 命中时填新字段, 本体 cover/images 同步替换为季节素材 URL。
### MP 端节点透明改善
调用方/前端**无字段变化**, MP `/mp/product/{id}` 返回的节点 `resourceCover` / `resourceImages` 已是季节素材 URL (前端无任何改动)。
---
## 测试服真测 (PASS)
样本产品 `2047216096724873217` 「呼伦贝尔周边摄影季」, productLine `2047215799055118338` 「快乐摄影季」 `seasons=['summer']`, Day 2 SCENIC 节点引用 scenicId=3001000000000000019 (中俄边境公路):
```json
{
"nodeType": "SCENIC",
"resourceId": "3001000000000000019",
"resourceName": "中俄边境公路（卡线）",
"resourceCover": "https://images.unsplash.com/photo-1472214103451-9374bd1c798e?w=800&q=80",
"resourceImages": [
"https://images.unsplash.com/photo-1472214103451-9374bd1c798e?w=800&q=80",
"https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=800&q=80"
]
}
```
- `resourceCover` / `resourceImages` 注入了 summer 季节图 (与产品线 seasons[0]='summer' 匹配, 非本体 OSS 图)
- PR #2229 测试数据脚本配的 summer unsplash URL 命中 ✓
---
## 边界
| 场景 | 节点 cover/images 实际值 |
|------|--------------------------|
| productLine.seasons=`["spring"]` + 景区有 spring scenic_season cover | scenic_season(spring).cover_material_id URL |
| productLine.seasons=`["winter"]` + 景区无 winter season | 回落 scenic_spot.cover 本体 |
| productLine.seasons null/空 | 回落本体 (向前兼容) |
| ACTIVITY 节点 | 同款 (activity_season → activity) |
| Snapshot (订单已下单) | 取 snapshot.seasons[0] (锁定下单时刻, 不实时查产品线 — 快照语义) |
| 节点 description 字段 | 仍走 PR #2250 独立快照(保存时为空才回填), 非空保护用户手填 |
---
## 兼容性
- ResourceDetailDTO `@AllArgsConstructor` 参数顺序变了, 已 grep 全仓库无位置参数 new 调用, 全用 builder 模式
- 老服务消费 DTO 时 Jackson 默认 ignore unknown, 新字段不影响老版本反序列化
- 节点级 images: List<String> 由前端控制保留 (独立快照), 资源/季节级媒体通过 DTO 动态切换, 解耦清晰
---
## 不影响范围
- **仅影响**: 节点详情媒体字段 (cover/images/videoMaterialIds) 装配来源
- **零影响**: 节点 description (走 #2250 链路) / 节点 emojiIcon / 订单创建 / 算价 / 历史已生成的 snapshot (snapshot.seasons 不存在时走 null 兼容)
---
## 相关历史 PR
| PR | Issue | 说明 |
|----|-------|------|
| #2229 | #2227 | 景区列表/封面 season 切换 + scenic_season 表 |
| #2234 | #2232 | 游玩项目同款 + activity_season 表 |
| #2250 | #2243 | 节点 description 按季节回落 highlights |
| **#2263** | **#2256** | 节点媒体基础设施 (ResourceDetailDTO + ResourceBatchDetailService) |
| **#2271** | **#2268** | **MP Assembler 消费侧接通 season 参数** |
---
## 相关文档
- Issue #2256: [wx/HL#2256](https://git.1814.love:8443/wx/HL/issues/2256)
- Issue #2268: [wx/HL#2268](https://git.1814.love:8443/wx/HL/issues/2268)
- PR #2263: [wx/HL#2263](https://git.1814.love:8443/wx/HL/pulls/2263)
- PR #2271: [wx/HL#2271](https://git.1814.love:8443/wx/HL/pulls/2271)

121
changelogs/2026-05/14_frontend_admin_list_should_pass_seasons_param.md 普通文件
查看文件

@ -0,0 +1,121 @@
# [前端] 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)