Merge pull request 'docs: 草原指南视频文件夹选择器显示规则' (#9) from docs/grassland-video-folder-selector-visibility into main

changelogs/2026-07/15_fix_grassland_guide_video_folder_selector_visibility.md

@@ -0,0 +1,57 @@
+# 草原指南管理：视频素材选择器显示文件夹树
+
+> **管理端 PR**: [wx/hl-ui#8](https://git.1814.love:8443/wx/hl-ui/pulls/8)
+> **关联后端工单**: [wx/HL#4999](https://git.1814.love:8443/wx/HL/issues/4999)
+> **日期**: 2026-07-15
+> **影响范围**: 管理后台草原指南新增/编辑页的视频素材选择弹窗
+> **当前状态**: 已合入 `v2.1` 并部署测试环境
+
+---
+
+## 一、修复原因
+
+封面图素材选择器能够显示分类树，但视频选择器锁定在 `grassland_guide` 后，错误地以“根分类必须存在子节点”作为下拉显示条件。分类接口暂时只返回根节点时，视频弹窗会完全隐藏文件夹下拉。
+
+该问题只影响管理端显示，不涉及后端接口或数据。
+
+---
+
+## 二、最终交互
+
+- 视频素材弹窗始终显示文件夹下拉，根节点名称为“草原指南”。
+- 有子文件夹时，以树形层级挂在“草原指南”根节点下，可选择任意层级子文件夹。
+- 选择“草原指南”根节点时，查询该顶级分类自身及全部后代素材。
+- 选择子文件夹时，查询该文件夹及其全部后代素材。
+- 视频选择器继续锁定在草原指南分类内，不能切换到其他业务顶级分类。
+- 普通素材选择器和封面图选择器行为不变。
+
+对应请求规则：
+
+```http
+# 选择“草原指南”根节点
+GET /admin/material/list?categoryCode=grassland_guide&fileType=video&includeDescendants=true
+
+# 选择具体子文件夹
+GET /admin/material/list?categoryCode=grassland_guide&subCategoryId={文件夹ID}&fileType=video&includeDescendants=true
+```
+
+---
+
+## 三、接口与配置影响
+
+- 不新增或修改 API 字段。
+- 不修改数据库、字典、菜单或 Nacos 配置。
+- 不修改素材上传、小程序接口或草原指南保存逻辑。
+
+---
+
+## 四、验证记录
+
+- [x] Vitest：1 个测试文件、3 项测试通过。
+- [x] 覆盖根分类没有子文件夹时仍显示下拉。
+- [x] 覆盖选择子文件夹后继续提交 `subCategoryId`。
+- [x] 相关 ESLint 通过。
+- [x] Vite 生产构建通过。
+- [x] 独立代码复核无阻断项。
+- [x] 测试环境部署任务 `36ee2a2e` 成功。
+- [x] 测试环境静态包已确认包含新的根节点与子文件夹树逻辑。