docs: 告知草原指南免登录只读接口 #5005

changelogs/2026-07/16_feat_grassland_guide_public_detail.md

@@ -0,0 +1,19 @@
+# 草原指南管理端免登录详情接口
+
+- 工单：`wx/HL#5005`
+- 测试环境：已部署 `dev-v3`
+- 鉴权：不需要登录
+- 数据范围：只允许查询 `PUBLISHED`
+
+## 接口
+
+`GET /admin/grassland-guide/public/videos/{videoId}`
+
+返回列表字段，并增加：`videoMaterialId`、`videoUrl`、
+`customCoverMaterialId`、`contentHtml`、`contentImageMaterialIds`、
+`createdBy`、`updatedBy`、`createdAt`、`updatedAt`。
+
+说明：管理端免登录预览不受 `loginRequired` 限制；该字段只表达小程序用户是否需要登录。
+草稿、下架、删除或不存在的视频统一按不存在处理。
+
+测试网关实测：HTTP 200，业务码 `200`。

changelogs/2026-07/16_feat_grassland_guide_public_list.md

@@ -0,0 +1,26 @@
+# 草原指南管理端免登录列表接口
+
+- 工单：`wx/HL#5005`
+- 测试环境：已部署 `dev-v3`
+- 鉴权：不需要登录
+- 数据范围：仅返回 `PUBLISHED`，不会返回草稿、下架或已删除数据
+
+## 接口
+
+`GET /admin/grassland-guide/public/videos`
+
+查询参数：
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| keyword | string | 否 | - | 匹配标题或简介 |
+| featured | boolean | 否 | - | 是否精选 |
+| page | integer | 否 | 1 | 最小 1 |
+| pageSize | integer | 否 | 20 | 1～100 |
+
+`data` 为分页对象：`records`、`total`、`page`、`pageSize`。列表项包含：
+`videoId`、`title`、`summary`、`effectiveCoverUrl`、`coverSource`、
+`durationSeconds`、`featured`、`loginRequired`、`sortWeight`、`status`、
+`publishTime`、`linkedProductId`。
+
+测试网关实测：HTTP 200，业务码 `200`。

changelogs/2026-07/16_feat_grassland_guide_public_play.md

@@ -0,0 +1,25 @@
+# 草原指南管理端免登录播放接口
+
+- 工单：`wx/HL#5005`
+- 测试环境：已部署 `dev-v3`
+- 鉴权：不需要登录
+- 数据范围：只允许播放 `PUBLISHED`
+
+## 接口
+
+`GET /admin/grassland-guide/public/videos/{videoId}/play`
+
+`data` 字段：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| videoId | string | 视频业务 ID |
+| title | string | 标题 |
+| videoUrl | string | OSS MP4 直出地址 |
+| durationSeconds | integer | 素材自动解析的时长（秒） |
+| effectiveCoverUrl | string | 自定义封面或 OSS 自动截帧封面 |
+
+该接口是播放最小响应，不返回正文、创建人或操作信息。管理端免登录预览不受
+`loginRequired` 限制；小程序端仍按该字段执行登录鉴权。
+
+测试网关实测：HTTP 200，业务码 `200`，真实素材返回播放地址与时长。

changelogs/2026-07/16_feat_grassland_guide_public_recommendations.md

@@ -0,0 +1,22 @@
+# 草原指南管理端免登录推荐接口
+
+- 工单：`wx/HL#5005`
+- 测试环境：已部署 `dev-v3`
+- 鉴权：不需要登录
+- 数据范围：源视频和推荐结果都必须是 `PUBLISHED`，推荐结果自动排除自身
+
+## 接口
+
+`GET /admin/grassland-guide/public/videos/{videoId}/recommendations`
+
+查询参数：
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| page | integer | 否 | 1 | 最小 1 |
+| pageSize | integer | 否 | 20 | 1～100 |
+
+`data` 为分页对象：`records`、`total`、`page`、`pageSize`；`records` 字段与列表接口一致。
+推荐继续使用后端推荐算法，相关性不足时随机兜底，不需要前端拼装。
+
+测试网关实测：HTTP 200，业务码 `200`。