docs: 更新草原指南自动推荐分页契约
这个提交包含在：
API Changelog Bot
父节点
6ed33870b9
当前提交
edcf5a27ca
@ -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 均按字符串处理。
|
||||
|
||||
正在加载...
x
在新工单中引用
屏蔽一个用户