diff --git a/changelogs/2026-05/14_feat_admin_activity_season_admin_crud.md b/changelogs/2026-05/14_feat_admin_activity_season_admin_crud.md new file mode 100644 index 0000000..b27a79c --- /dev/null +++ b/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>` + +```json +{ + "code": 200, + "data": [ + { + "seasonId": 2054831396190347266, + "activityId": 2023705891743739905, + "seasonType": "spring", + "seasonName": "春日", + "monthStart": 3, + "monthEnd": 5, + "description": "春日体验", + "highlights": "春日亮点测试", + "playGuide": "

春日攻略

", + "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 | ❌ | 季节轮播图素材 ID 列表 | +| videoMaterialIds | List | ❌ | 季节视频素材 ID 列表 | + +**幂等**: 由 (activity_id, season_type) 唯一约束保证, 已存在 → 更新, 否则 → 插入。 + +`seasonType` 枚举: `spring/summer/autumn/winter` (其他值返 320401 ACTIVITY_SEASON_TYPE_INVALID)。 + +### 3. 删除 `DELETE /admin/activity/item/{activityId}/season/{seasonType}` + +**响应**: `Result` 成功返 `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) diff --git a/changelogs/2026-05/14_feat_admin_list_season_highlights_field.md b/changelogs/2026-05/14_feat_admin_list_season_highlights_field.md new file mode 100644 index 0000000..05c3f17 --- /dev/null +++ b/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) 沿用 #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) diff --git a/changelogs/2026-05/14_feat_mp_node_media_season_pipeline_through.md b/changelogs/2026-05/14_feat_mp_node_media_season_pipeline_through.md new file mode 100644 index 0000000..3b9ac57 --- /dev/null +++ b/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 | 季节轮播图素材 ID 列表 | +| seasonVideoMaterialIds | List | 季节视频素材 ID 列表 | +| videoMaterialIds | List | 视频素材 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 由前端控制保留 (独立快照), 资源/季节级媒体通过 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) diff --git a/changelogs/2026-05/14_frontend_admin_list_should_pass_seasons_param.md b/changelogs/2026-05/14_frontend_admin_list_should_pass_seasons_param.md new file mode 100644 index 0000000..3f121ce --- /dev/null +++ b/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)