docs: 补充景区季节清空前端联调说明 #5123

changelogs-v2/2026-07/79_5123_景区季节全量清空与标签同步-前端待处理-管理后台.md

@@ -0,0 +1,111 @@
+# 【前端待处理·管理后台】景区季节全量清空与标签同步（#5123）
+
+## 目标前端
+
+- 端类型：管理后台（Web）
+- 目标仓库：`mmg/hl-ui`
+- 目标分支：按前端仓库当前发布流程执行
+- 后端工单：`wx/HL #5123`
+- 小程序：无需改页面，但必须参与接口与缓存回退验收
+
+## 问题与根因
+
+`src/views/resource/scenic/SeasonDrawer.vue` 的 `handleSave()` 目前只在
+`isSeasonConfigured(form)` 为 true 时调用 PUT。已存在的季节被全部清空后，
+该判断变为 false，前端既不发 PUT，也没有调用后端已有 DELETE，数据库旧记录仍在，
+因此重新打开抽屉会回显旧内容，页签“已配置”和景区列表季节标签也不会消失。
+
+后端同时修复了可空字段写入 null、季节素材引用解绑，以及管理后台/小程序相关缓存依赖失效。
+前端不能继续用“不发请求”表达删除已存在季节。
+
+## 接口契约
+
+### 查询季节列表
+
+```http
+GET /admin/scenic/spot/{scenicId}/seasons
+```
+
+### 保存仍有内容的季节
+
+```http
+PUT /admin/scenic/spot/{scenicId}/season/{seasonType}
+Content-Type: application/json
+```
+
+### 删除已全量清空的季节
+
+```http
+DELETE /admin/scenic/spot/{scenicId}/season/{seasonType}
+```
+
+`seasonType` 取 `spring`、`summer`、`autumn`、`winter`。DELETE 无请求体，沿用现有管理后台鉴权。
+
+## 前端改动要求
+
+### 1. API 封装
+
+在 `src/api/scenic.js` 新增并导出删除方法，例如：
+
+```js
+export function deleteScenicSeason(scenicId, seasonType) {
+  return http.delete(`/scenic/spot/${scenicId}/season/${seasonType}`)
+}
+```
+
+### 2. 记录初始已配置季节
+
+`SeasonDrawer.vue` 每次打开并成功加载季节列表后，记录后端实际返回过的 `seasonType` 集合。
+
+- 加载前清空该集合，避免切换景区时串数据。
+- 只以后端列表是否存在记录作为“初始已配置”依据，不要用当前编辑中的
+  `isSeasonConfigured()` 反推。
+- 查询失败时不得把未知状态当成“从未配置”；应阻止保存或保留错误状态，避免误判删除。
+
+### 3. 保存判定
+
+遍历四季时按以下规则处理：
+
+| 初始状态 | 当前表单 | 请求 |
+| --- | --- | --- |
+| 不存在 | 全空 | 不请求 |
+| 不存在 | 有内容 | PUT |
+| 已存在 | 有内容 | PUT |
+| 已存在 | 全空 | DELETE |
+
+所有文本字段都按 `trim()` 后判断是否为空；素材按有效 `id` 判断，空壳对象不能让季节继续显示为已配置。
+
+同一次保存中任一季节请求失败时，不得关闭抽屉或显示“全部保存成功”；应保留编辑内容并明确提示失败季节。
+全部请求成功后重新 GET 季节列表，再触发父级景区列表刷新，确保以下状态以服务端结果收敛：
+
+- 当前抽屉内容不再回显已删除季节。
+- 对应页签“已配置”标记消失。
+- 景区列表对应季节标签消失。
+- 其他季节和景区基础信息不变。
+
+## 小程序链路说明
+
+小程序产品详情会经 product-service 和 resource-service 读取季节亮点及季节媒体。
+后端已为实时产品详情、订单快照、mp-service 产品聚合和景区详情缓存补齐
+`table:scenic_season` / `table:scenic_spot` 依赖。
+
+季节删除后，小程序不得继续显示旧 `seasonHighlights`、封面、轮播图或视频；未命中季节时应回退景区本体媒体和节点快照描述。前端管理后台无需主动清小程序 Redis，也不得新增清缓存接口。
+
+## 验收清单
+
+- [ ] 仅配置描述和亮点的季节，两项全部清空并保存后，重新打开不再回显。
+- [ ] 对应页签“已配置”标记消失。
+- [ ] 保存成功并刷新景区列表后，对应季节标签消失。
+- [ ] 保留其他内容时，可单独清空描述、亮点、封面、轮播图和视频。
+- [ ] 清空一个季节不影响其他季节及景区基础信息。
+- [ ] 从未配置且仍为空的季节不发 PUT 或 DELETE。
+- [ ] 查询季节列表失败时不会误发 DELETE。
+- [ ] 部分请求失败时抽屉保留，且不会提示全部成功。
+- [ ] 小程序产品详情不再返回已删除季节的亮点或媒体。
+- [ ] 小程序在季节未命中时正确回退景区本体媒体和节点快照描述。
+
+## 发布说明
+
+- 本文是前端修复与联调通知，不代表已修改或发布 `mmg/hl-ui`。
+- 前端完成后须创建并指派自身工单，走分支、PR、测试和发布流程，并关联 `wx/HL #5123`。
+- 测试环境验收必须通过网关使用真实管理员鉴权完成 PUT、DELETE、GET 回读；记录不得包含 token、Cookie 或真实隐私数据。