From edcf5a27ca5a43ea6c7a3bd62c1122c0d9988cb9 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Sun, 12 Jul 2026 15:50:13 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E8=8D=89=E5=8E=9F?=
 =?UTF-8?q?=E6=8C=87=E5=8D=97=E8=87=AA=E5=8A=A8=E6=8E=A8=E8=8D=90=E5=88=86?=
 =?UTF-8?q?=E9=A1=B5=E5=A5=91=E7=BA=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../12_feat_grassland_guide_admin_mp_oss.md   | 73 +++++++++++++++----
 1 file changed, 60 insertions(+), 13 deletions(-)

diff --git a/changelogs/2026-07/12_feat_grassland_guide_admin_mp_oss.md b/changelogs/2026-07/12_feat_grassland_guide_admin_mp_oss.md
index eca6b22..b2a8fb1 100644
--- a/changelogs/2026-07/12_feat_grassland_guide_admin_mp_oss.md
+++ b/changelogs/2026-07/12_feat_grassland_guide_admin_mp_oss.md
@@ -2,9 +2,9 @@
 
 > 日期：2026-07-12
 >
-> 后端 Issue：[HL #4919](https://git.1814.love:8443/wx/HL/issues/4919)
+> 后端 Issue：[HL #4919](https://git.1814.love:8443/wx/HL/issues/4919)、[HL #4922](https://git.1814.love:8443/wx/HL/issues/4922)
 >
-> 后端 PR：[HL #4921](https://git.1814.love:8443/wx/HL/pulls/4921)
+> 后端 PR：[HL #4921](https://git.1814.love:8443/wx/HL/pulls/4921)、[HL #4924](https://git.1814.love:8443/wx/HL/pulls/4924)
 >
 > 测试分支：`dev-v3`
 >
@@ -21,6 +21,8 @@
 - 视频和封面都只能由后台管理员上传；小程序用户没有上传接口和上传权限。
 - 视频可以单独上传一张图片作为封面；未指定时由 OSS 自动截取视频首帧。
 - 小程序列表支持分页，详情直接把 `videoUrl` 交给原生 `<video>` 组件播放。
+- 相关推荐由后端自动计算，并提供独立分页接口供前端滑动加载；后台不再手工选择推荐内容。
+- 视频时长和首次发布时间均为只读字段：时长从视频素材派生，发布时间在首次发布时由后端生成。
 
 前端必须删除旧版草原指南 VOD 方案中的以下内容：
 
@@ -86,6 +88,8 @@ export async function readVideoDurationSeconds(file: File): Promise<number> {
 
 草原指南视频的 `durationSeconds` 必填且必须大于 0。后端不会下载完整视频计算时长。
 
+该值由前端代码自动读取并提交，不能提供手工输入框。素材确认后，编辑页只读展示后端返回的时长。
+
 ### 3.2 获取素材上传凭证
 
 `POST /admin/material/upload/token`
@@ -178,10 +182,8 @@ OSS 自动封面格式：
   "contentImageMaterialIds": [],
   "featured": true,
   "showProducedBadge": true,
-  "sortWeight": 300,
-  "publishTime": null,
+  "sortWeight": 3,
   "linkedProductId": null,
-  "relatedVideoIds": ["2076196084920610817", "2076196086652858370"],
   "version": 2
 }
 ```
@@ -192,7 +194,13 @@ OSS 自动封面格式：
 - 视频素材为正常状态的 `grassland_guide` OSS MP4。
 - 视频存在 `ossUrl`、`thumbnailUrl` 和正数时长。
 - 正文包含有效文字或正文图片。
-- 配置 2～3 条不重复、非自身的相关推荐。
+
+管理端不再提交 `publishTime`、`durationSeconds`、`relatedVideoIds`：
+
+- `durationSeconds` 从当前 `videoMaterialId` 对应的视频素材自动派生。
+- `publishTime` 在首次点击发布时由后端写入；后续编辑、下架和重上架都保留首次值。
+- 相关推荐在小程序查询时自动生成，没有其他候选也不阻止当前内容发布。
+- `sortWeight` 数值越小越靠前，影响精选 Hero 位及相关内容同分时的弱排序。
 
 后台详情返回新增字段：
 
@@ -203,21 +211,25 @@ OSS 自动封面格式：
   "customCoverMaterialId": "2076196060279070722",
   "coverSource": "CUSTOM",
   "effectiveCoverUrl": "https://.../cover.jpg",
-  "durationSeconds": 61
+  "durationSeconds": 61,
+  "publishTime": "2026-07-12 14:44:56"
 }
 ```
 
+`durationSeconds`、`publishTime` 在 Knife4j 中均标记为只读。
+
 所有雪花 ID 在 JavaScript 中都按字符串处理，避免超过安全整数范围。
 
 ## 6. 小程序接口
 
-小程序只保留三个只读接口：
+小程序提供四个只读接口：
 
 | 方法 | 路径 | 说明 |
 |---|---|---|
 | `GET` | `/mp/grassland-guide/home?page=1&pageSize=20` | 精选区与视频分页 |
 | `GET` | `/mp/grassland-guide/videos?page=1&pageSize=20` | 视频分页列表 |
 | `GET` | `/mp/grassland-guide/videos/{videoId}` | 视频详情 |
+| `GET` | `/mp/grassland-guide/videos/{videoId}/recommendations?page=1&pageSize=20` | 自动推荐分页，供滑动加载 |
 
 分页规则：
 
@@ -236,11 +248,40 @@ OSS 自动封面格式：
   "durationSeconds": 61,
   "coverSource": "CUSTOM",
   "coverUrl": "https://.../cover.jpg",
-  "contentHtml": "<p>正文内容</p>",
-  "relatedVideos": []
+  "contentHtml": "<p>正文内容</p>"
 }
 ```
 
+详情不再返回固定数组 `relatedVideos`。进入相关推荐区域时，请求独立分页接口：
+
+```json
+{
+  "records": [
+    {
+      "videoId": "2076196084920610817",
+      "title": "草原指南测试｜Caminandes 3：Llamigos",
+      "summary": "Blender 官方真实短片",
+      "coverUrl": "https://.../auto-cover.jpg",
+      "coverSource": "AUTO",
+      "durationSeconds": 151
+    }
+  ],
+  "total": 2,
+  "page": 1,
+  "pageSize": 1
+}
+```
+
+推荐排序规则：
+
+1. 仅使用 `PUBLISHED` 内容，排除当前视频、已删除内容和重复项。
+2. 同一 `linkedProductId`（关联行程/产品）优先。
+3. 再按标题、摘要内容相似度排序。
+4. `featured`、`sortWeight`、`publishTime` 只做弱排序。
+5. 其余已上架内容使用稳定随机顺序兜底。
+
+候选集合不变时各页顺序稳定且不重不漏。若管理员恰好在用户翻页期间发布或下架内容，标准 offset 分页边界可能变化，前端应按 `videoId` 去重后追加。
+
 小程序直接使用原生组件：
 
 ```html
@@ -258,7 +299,7 @@ OSS MP4 支持 Range 请求，原生 `<video>` 能从 MP4 元数据读取并显
 - `hl-gateway`：`8080/8180`，Nacos `2/2` 健康。
 - `hl-user-service`：`8081/8181`，Nacos `2/2` 健康。
 - User Flyway `20260712.005` 执行成功；Resource Flyway `20260712.001` 执行成功。
-- Knife4j 已展示草原指南管理接口、素材上传接口及 `durationSeconds`；小程序文档只剩上述 3 个接口。
+- Knife4j 已展示草原指南管理接口、素材上传接口及只读字段；小程序文档为上述 4 个 GET。
 
 真实数据：
 
@@ -276,18 +317,24 @@ OSS MP4 支持 Range 请求，原生 `<video>` 能从 MP4 元数据读取并显
 - MP4 Range 请求均返回 `206 video/mp4`。
 - 自定义封面和 OSS 自动封面均返回 `200 image/*`。
 - 小程序 `pageSize=2` 实测分页为第 1 页 2 条、第 2 页 1 条，无重复。
-- 三个详情均直接返回 `videoUrl`、正确时长和 2 条相关推荐。
+- 三个详情均直接返回 `videoUrl` 和正确时长，且不再包含 `relatedVideos`。
+- 三个推荐分页均为 `total=2`；按 `pageSize=1` 加载两页，无自身、无重复，重复请求顺序一致。
+- 实测下架其中一条后推荐 `total` 从 2 变为 1，候选中不含下架内容；重上架后恢复为 2。
+- 故意提交伪造 `publishTime=2000年`、`durationSeconds=9999` 和旧 `relatedVideoIds`，后端均未采纳；下架重上架后首次发布时间保持不变。
 - 旧 `/play-auth` 接口已不可用。
 
 ## 8. 前端改造检查单
 
 - [ ] 新增“草原指南管理”列表、编辑和发布页面。
 - [ ] 素材库展示顶级分类“草原指南”，隐藏系统分类删除/停用/改码操作。
-- [ ] 选择 MP4 后通过 `loadedmetadata` 获取时长并 `Math.ceil`。
+- [ ] 选择 MP4 后通过 `loadedmetadata` 获取时长并 `Math.ceil`，界面只读展示，不允许手填。
 - [ ] 使用素材库通用上传接口处理 `PRESIGNED_URL` 和 `STS_MULTIPART`。
 - [ ] 支持单独上传/选择图片作为自定义封面，并允许清空后恢复自动封面。
 - [ ] 草原指南内容保存 `videoMaterialId`，不保存 VOD 字段。
+- [ ] 发布日期只读：草稿显示未发布，首次发布成功后刷新详情回显后端时间。
+- [ ] 删除管理员手工选择相关推荐的控件，不提交 `relatedVideoIds`。
 - [ ] 小程序列表接入分页参数和分页结果。
 - [ ] 小程序详情直接使用 `videoUrl` 播放。
+- [ ] 相关推荐通过独立分页接口滑动加载，并按 `videoId` 去重追加。
 - [ ] 删除 VOD SDK、`play-auth` 调用和清晰度切换 UI。
 - [ ] 所有雪花 ID 均按字符串处理。