wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

docs(api): 补充草原指南产品绑定与登录鉴权

浏览代码
这个提交包含在：
API Changelog Bot 2026-07-13 16:31:24 +08:00
父节点 5b1659a048
当前提交 b3a59759a6
共有 1 个文件被更改，包括 46 次插入 和 8 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

54
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)、[HL #4922](https://git.1814.love:8443/wx/HL/issues/4922)、[HL #4927](https://git.1814.love:8443/wx/HL/issues/4927)、[HL #4940](https://git.1814.love:8443/wx/HL/issues/4940)
> 后端 Issue：[HL #4919](https://git.1814.love:8443/wx/HL/issues/4919)、[HL #4922](https://git.1814.love:8443/wx/HL/issues/4922)、[HL #4927](https://git.1814.love:8443/wx/HL/issues/4927)、[HL #4940](https://git.1814.love:8443/wx/HL/issues/4940)、[HL #4949](https://git.1814.love:8443/wx/HL/issues/4949)
>
> 后端 PR：[HL #4921](https://git.1814.love:8443/wx/HL/pulls/4921)、[HL #4924](https://git.1814.love:8443/wx/HL/pulls/4924)、[HL #4929](https://git.1814.love:8443/wx/HL/pulls/4929)、[HL #4930](https://git.1814.love:8443/wx/HL/pulls/4930)、[HL #4946](https://git.1814.love:8443/wx/HL/pulls/4946)、[HL #4948](https://git.1814.love:8443/wx/HL/pulls/4948)
> 后端 PR：[HL #4921](https://git.1814.love:8443/wx/HL/pulls/4921)、[HL #4924](https://git.1814.love:8443/wx/HL/pulls/4924)、[HL #4929](https://git.1814.love:8443/wx/HL/pulls/4929)、[HL #4930](https://git.1814.love:8443/wx/HL/pulls/4930)、[HL #4946](https://git.1814.love:8443/wx/HL/pulls/4946)、[HL #4948](https://git.1814.love:8443/wx/HL/pulls/4948)、[HL #4953](https://git.1814.love:8443/wx/HL/pulls/4953)
>
> 测试分支：`dev-v3`
>
@ -25,6 +25,9 @@
- 相关推荐由后端自动计算，并提供独立分页接口供前端滑动加载；后台不再手工选择推荐内容。
- 视频时长和首次发布时间均为只读字段：时长从视频素材派生，发布时间在首次发布时由后端生成。
- 原型没有“呼籁出品”角标开关，管理端和小程序端均不提供 `showProducedBadge` 字段；前端不要提交、读取或展示该字段。
- 管理端可以通过 `loginRequired` 控制单条视频是否要求小程序用户登录；未设置时默认为 `false`。
- 草原指南内容可以绑定产品；小程序卡片返回 `linkedProductId` 和后端聚合出的 `linkedProductType`。
- 前端不参与数据库乐观锁，创建、更新、发布、下架均不提交 `version`；发布和下架接口没有请求体。
前端必须删除旧版草原指南 VOD 方案中的以下内容：
@ -175,7 +178,7 @@ OSS 自动封面格式：
| `GET` | `/admin/grassland-guide/videos` | 分页列表 |
| `GET` | `/admin/grassland-guide/videos/{videoId}` | 详情 |
| `POST` | `/admin/grassland-guide/videos` | 创建草稿 |
| `PUT` | `/admin/grassland-guide/videos/{videoId}` | 全量更新，必须传当前 `version` |
| `PUT` | `/admin/grassland-guide/videos/{videoId}` | 全量更新，不传 `version` |
| `PUT` | `/admin/grassland-guide/videos/{videoId}/publish` | 发布/重新发布 |
| `PUT` | `/admin/grassland-guide/videos/{videoId}/offline` | 下线 |
@ -191,12 +194,12 @@ OSS 自动封面格式：
"contentImageMaterialIds": [],
"featured": true,
"sortWeight": 3,
"linkedProductId": null,
"version": 2
"linkedProductId": "2076196082752155649",
"loginRequired": false
}
```
`version` 只在更新时必填。创建草稿允许内容暂时不完整，发布时必须满足：
创建和更新使用同一组业务字段，均不提交 `version`。创建时不传 `loginRequired` 按 `false` 处理；更新时不传则保留原值。`publish`、`offline` 只传路径参数 `videoId`，不要发送空对象或版本请求体。创建草稿允许内容暂时不完整，发布时必须满足：
- 标题、视频素材和有效封面完整。
- 视频素材为正常状态的 `grassland_guide` OSS MP4。
@ -220,7 +223,9 @@ OSS 自动封面格式：
"coverSource": "CUSTOM",
"effectiveCoverUrl": "https://.../cover.jpg",
"durationSeconds": 61,
"publishTime": "2026-07-12 14:44:56"
"publishTime": "2026-07-12 14:44:56",
"linkedProductId": "2076196082752155649",
"loginRequired": false
}
```
@ -256,10 +261,27 @@ OSS 自动封面格式：
"durationSeconds": 61,
"coverSource": "CUSTOM",
"coverUrl": "https://.../cover.jpg",
"contentHtml": "<p>正文内容</p>"
"contentHtml": "<p>正文内容</p>",
"linkedProductId": "2076196082752155649",
"linkedProductType": "CORE",
"loginRequired": false
}
```
首页、列表、详情和推荐卡片均返回以下业务字段：
- `linkedProductId`：字符串，可空；绑定的产品 ID。
- `linkedProductType`：`CORE`、`GROUP`、`CUSTOM` 之一，可空。未绑定、产品不存在或产品服务暂时不可用时为空，草原指南内容仍正常返回。
- `loginRequired`：布尔值；为 `true` 时必须先登录才能读取详情和播放。
鉴权规则：
- 首页、分页列表、相关推荐分页继续允许匿名访问，卡片只返回展示字段，不返回正文和播放地址。
- 详情接口使用可选登录：`loginRequired=false` 时匿名返回 `200`；为 `true` 时匿名返回业务码 `401`，合法用户 JWT 返回 `200`。
- 前端遇到详情业务码 `401` 时拉起小程序登录，成功后携带新 token 重试原详情请求。
- 客户端提交的 `X-User-Id`、`X-User-Type`、`X-Auth-Level` 和管理员身份头均不可信，网关会删除后仅依据有效 JWT 重建身份。
- MP 详情不使用跨用户缓存，防止受保护视频的详情或 `videoUrl` 被匿名请求复用。
详情不再返回固定数组 `relatedVideos`。进入相关推荐区域时，请求独立分页接口：
```json
@ -337,6 +359,8 @@ OSS 自动封面格式：
- 4K 内容使用独立上传的 JPEG 封面，详情返回 `coverSource=CUSTOM`；推荐分页返回 3 条上架内容且排除了当前视频。
- 当前测试桶默认域名同时返回 `Content-Disposition: attachment` 和 `x-oss-force-download: true`。HTTP Range 能正常工作，但小程序仍须做真机播放验收。2026-07-13 最终决定保持默认 OSS 域名，不切换自定义域名；前端不得自行改写域名，若原生 `<video>` 真机播放失败，保留错误码与设备信息后反馈后端处理。
- 2026-07-13 已从管理端和小程序端完整删除 `showProducedBadge`：Resource/MP OpenAPI 均无该字段，首页、列表、详情、推荐 4 个实际接口均返回 `200` 且无该字段；Resource Flyway `20260713.001` 执行成功，遗留数据库列已删除。
- 2026-07-13 PR #4953 已合入 `dev-v3`，并按 `hl-gateway` → `hl-mp-service` → `hl-resource-service` 部署测试环境；三项服务均完成双实例滚动升级。该 PR 补齐产品绑定字段、单条内容登录鉴权并移除前端 `version` 契约。
- 音画同步不能仅凭 OSS `HEAD` 或 `Range 206` 判定通过。当前仍为 OSS 4K 原片直出，目标机型真机播放验收须单独记录；未经真机验证不得标记“音画同步已修复”。
## 8. 2026-07-14 正式环境 Nacos 部署清单
@ -369,6 +393,16 @@ file:
若正式目标分支已经同时包含 #4946 和 #4948，不得直接按该分支首次启动旧实例集群；应先准备仅包含 #4946 的中间发布版本完成步骤 1～3，再切换到包含 #4948 的最终版本。该变更不涉及 Nacos 配置修改。
### 8.2 登录鉴权与产品字段正式发布门禁
PR #4953 不新增 Nacos 配置。正式发布最终版本时按以下顺序滚动：
1. `hl-mp-service`：先移除详情缓存并上线产品字段聚合。
2. `hl-gateway`：上线草原详情 `OPTIONAL` 鉴权和客户端身份头清洗。
3. `hl-resource-service`：最后执行 Flyway `20260713.002` 并启用单条内容登录判断。
所有 Resource 实例完成升级前，不得把任何正式视频设置为 `loginRequired=true`。回滚旧 Resource 前应先把受保护视频改为公开或下架，否则旧代码不识别该字段，可能重新暴露详情。正式 `main` 尚未发布时，本节仅作为发布门禁，不代表已部署。
## 9. 前端改造检查单
- [ ] 新增“草原指南管理”列表、编辑和发布页面。
@ -378,10 +412,14 @@ file:
- [ ] 支持单独上传/选择图片作为自定义封面，并允许清空后恢复自动封面。
- [ ] 草原指南内容保存 `videoMaterialId`，不保存 VOD 字段。
- [ ] 不展示“呼籁出品”开关或角标，不提交、不读取 `showProducedBadge`。
- [ ] 创建/编辑页增加“需要登录后查看”开关并提交 `loginRequired`，默认关闭。
- [ ] 删除草原指南所有 `version` 状态、请求参数和发布/下架请求体。
- [ ] 保存关联产品 ID；按小程序返回的 `linkedProductId`、`linkedProductType` 跳转对应产品。
- [ ] 发布日期只读：草稿显示未发布，首次发布成功后刷新详情回显后端时间。
- [ ] 删除管理员手工选择相关推荐的控件，不提交 `relatedVideoIds`。
- [ ] 小程序列表接入分页参数和分页结果。
- [ ] 小程序详情直接使用 `videoUrl` 播放。
- [ ] 卡片读取 `loginRequired`；进入受保护详情前触发登录，详情返回业务码 `401` 时登录后重试。
- [ ] 将 `videoUrl` 作为 OSS 原始 MP4 点播地址处理，不接 `live-player`、直播 SDK、FLV/HLS/M3U8 转换或自定义域名替换逻辑。
- [ ] 相关推荐通过独立分页接口滑动加载，并按 `videoId` 去重追加。
- [ ] 删除 VOD SDK、`play-auth` 调用和清晰度切换 UI。