Video 视频模块
受众：开发者、二次开发 Agent 摘要：Video 模块用于视频内容、付费观看、内容安全摘要、基础互动、举报处理和创作者商业化分发。当前提供公开读侧、基础内容流筛选、关注流、分类 / 话题 / 搜索流、商城带货入口、直播间联动入口、互动规则热榜、规则推荐分组、用户个性化推荐、推荐 Provider 接入 contract、后台内容运营、后台举报处理、后台创作者收益结算摘要、购买订单、Cashier 支付 / 退款回调、Entitlement 解锁、互动 contract、创作者概览和作品列表，以及 App / PC 视频入口和创作者中心首段入口。
模块定位
- Maven：
spring-open-module-video - Java 包：
com.springopen.module.video - API 前缀：
/api/v1/video/** - 配置前缀：
spring.open.video.* - 表前缀：
video_
Video 与 Blog、CMS、Mall、Reading、Live 平级，是可剥离业务模块。跨模块只保存标量 ID，不直接写资金账本。当前后端 contract、Admin 内容运营 / 举报处理 / 创作者收益结算摘要入口、用户端视频入口、基础内容流筛选、关注流、分类 / 话题 / 搜索流、商城带货入口、直播间联动入口、互动规则热榜、规则推荐分组、用户个性化推荐、推荐 Provider 接入 contract 和创作者概览 / 作品列表卡片已落地，默认 application 会装配 Video；真实外部推荐服务、真实打款 Provider 和媒体处理真实 Provider 按 Provider 验收清单执行，不在本地 contract 中伪装完成。
spring.open.video.enabled 已由 VideoServiceProvider 声明到 lifecycle 配置 schema；后台配置中心可发现 Video 模块启停开关。
当前能力
| 能力 | 说明 |
|---|---|
| 视频内容 | video_content 保存标题、简介、封面、播放地址、创作者、时长、访问类型、解锁价格、发布状态和内容安全摘要 |
| 基础内容流 | 公开内容分页支持 feed=latest/hot/following/free/paid/vip/member，App / PC 视频页提供最新、热门、关注、免费、付费、VIP 和会员内容切换；following 基于 IAM 当前用户关注关系筛选创作者，未登录或未关注时返回空分页，hot 只按点赞、收藏、分享互动分排序，不宣称个性化算法推荐 |
| 分类 / 话题 / 搜索流 | GET /api/v1/video/contents 支持 keyword、categoryCode、topicCode 查询；分类和话题读取 video_content.extra_json 中的 categoryCode、topicCode、topicCodes、topics 或 tags，不提前拆专用元数据表 |
| 商城带货 | VideoContentVO.commerceLinks 从 video_content.extra_json 中的 mallProductId / mallSkuId / mallProductTitle / mallProductCoverUrl 等标量引用投影；App / PC 展示关联商品并跳转 Mall 商品详情，Video 不查询 Mall 商品表 |
| 直播联动 | VideoContentVO.liveLinks 从 video_content.extra_json 中的 liveRoomId / liveRoomCode / liveRoomTitle / liveRoomCoverUrl 等标量引用投影；App / PC 展示关联直播间并跳转 Live 详情或直播频道，Video 不查询 Live 直播间、聊天或流媒体表 |
| 规则推荐分组 | GET /api/v1/video/contents/recommendations 按 latest / hot / free / paid / vip / member 生成稳定推荐分组，继续复用已发布和内容安全过滤；hot 是互动规则热榜，不虚构播放量 |
| 用户个性化推荐 | GET /api/v1/video/contents/me/recommendations 会先尝试已注册 VideoRecommendationProvider#recommend 返回的候选内容 ID，再过滤未发布 / 内容安全拒绝 / 已互动内容并保序装配详情；Provider 返回空或异常时自动回退内置互动偏好规则，结果仍按付费和内容安全规则隐藏播放地址 |
| 推荐 Provider 接入 | Admin GET /api/v1/admin/video/recommendation-providers 返回内置 rule-feed、interaction-preference 和项目自定义 Provider 描述；项目自定义 Provider 可同时提供 descriptor() 和 recommend(request)，用于接入真实外部推荐召回 / 排序服务 |
| 内容安全 | safety_action、safety_risk_level、safety_reason、safety_checked_at 保存检测结果；reject 内容不进入公开详情，review 内容展示状态但隐藏播放地址 |
| 后台运营 | Admin /video/contents 支持视频内容列表、详情、创建、编辑、发布状态、访问类型、价格、内容安全摘要维护，并展示创作者收益摘要和推荐 Provider 目录 |
| 举报处理 | Admin /video/reports 支持按内容、用户和处理状态查询举报，处理时可确认 / 驳回举报、记录备注，并同步维护内容状态和内容安全摘要 |
| 购买订单 | video_purchase_order 保存用户视频购买订单、金额、币种、支付 Provider 和支付状态；创建购买单时同步登记 Cashier scene=video-content 支付订单，退款回调或后台登记退款失效会把订单置为 refunded |
| 付费锁定 | 免费视频直接返回播放地址；付费视频无已支付订单或 Entitlement 解锁凭证时隐藏 videoUrl，有已支付订单或对应凭证后返回播放地址；订单退款后不再作为播放凭证 |
| 视频互动 | video_interaction 保存点赞、收藏、分享、举报记录；点赞 / 收藏可取消，分享 / 举报按事件留痕 |
| 创作者中心 | /api/v1/video/creator/overview 返回当前创作者内容数、已发布数、付费内容数、已支付 / 已退款订单数、互动量、举报量、待处理举报、总收益、退款金额和净收益；/api/v1/video/creator/contents 返回当前创作者自己的作品分页 |
| 创作者收益摘要 | Admin /video/creator-settlements 按创作者和币种聚合已支付 / 已退款视频购买订单，展示总收益、退款金额、净收益和外部打款待处理标记；该入口只读，不写 Money / Distribution 账本 |
| 推荐运维目录 | Admin /video/contents 页面调用 /api/v1/admin/video/recommendation-providers，展示内置规则、互动偏好和项目自定义推荐 Provider 的个性化能力、外部服务标记和运维说明 |
| 用户入口 | PC /video 和 App video/index 提供“我的推荐”、推荐分组、视频列表、搜索、分类 / 话题筛选、关联商品和关联直播间跳转、关注流、内容流切换、播放区、付费锁定、内容安全状态展示和当前登录创作者运营概览卡片 |
API
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /api/v1/video/contents | 分页查询已发布且未被拒绝的视频，支持 feed=latest/hot/following/free/paid/vip/member、keyword、categoryCode、topicCode 筛选；following 基于当前用户关注创作者过滤，未登录或无关注关系返回空分页；hot 按点赞 / 收藏 / 分享互动分生成规则热榜，并按付费和内容安全状态决定播放地址是否返回 |
GET | /api/v1/video/contents/recommendations | 查询基础视频推荐分组，按 latest / hot / free / paid / vip / member 聚合安全可展示内容；这是规则排序入口，不代表个性化推荐 |
GET | /api/v1/video/contents/me/recommendations | 查询当前登录用户的视频个性化推荐；已注册外部 Provider 可先返回候选内容 ID，Video 再统一过滤、保序和装配详情；Provider 不可用时回退内置互动偏好规则，并继续遵守内容安全和付费解锁规则 |
GET | /api/v1/video/contents/{id} | 查询视频详情；被内容安全拒绝的视频按不存在处理，待复核或未解锁时不返回 videoUrl |
POST | /api/v1/video/contents/{id}/purchases | 创建付费视频购买订单 |
GET | /api/v1/video/creator/overview | 查询当前登录创作者的视频数量、付费内容数量、已支付 / 已退款订单数、互动量、举报量、待处理举报、总收益、退款金额和净收益 |
GET | /api/v1/video/creator/contents | 分页查询当前登录创作者自己的作品，支持关键词、访问类型和发布状态筛选；后端固定使用当前登录用户 ID，不接受前端传入 creatorUserId 越权 |
GET | /api/v1/video/contents/{contentId}/interactions/summary | 查询视频点赞、收藏、分享、举报汇总和当前用户态 |
POST | /api/v1/video/contents/{contentId}/interactions | 提交点赞、收藏、分享或举报；点赞 / 收藏可传 active=false 取消 |
GET | /api/v1/admin/video/contents | Admin 分页查询视频内容，支持关键词、创作者、状态、访问类型和安全动作筛选 |
GET | /api/v1/admin/video/contents/{id} | Admin 查询单条视频内容详情，运营视角会返回真实播放地址 |
POST | /api/v1/admin/video/contents | Admin 创建视频内容，支持发布状态、访问类型、价格、内容安全摘要和扩展 JSON |
PUT | /api/v1/admin/video/contents/{id} | Admin 更新视频内容 |
GET | /api/v1/admin/video/creator-settlements | Admin 分页查询创作者收益结算摘要，可按 creatorUserId 筛选；无付费订单的创作者也会返回 0 收益记录，方便运营排查 |
GET | /api/v1/admin/video/recommendation-providers | Admin 查询当前应用可用的视频推荐 Provider 目录，包含显示名、说明、是否外部服务、是否个性化、支持内容流、配置键和运维提示 |
POST | /api/v1/admin/video/content-purchases/{orderNo}/refund-invalidate | Admin 按视频购买订单号登记退款失效，撤销付费视频播放权限 |
GET | /api/v1/admin/video/reports | Admin 分页查询举报记录，支持内容 ID、举报用户和处理状态筛选 |
POST | /api/v1/admin/video/reports/{id}/handle | Admin 处理举报，可确认 / 驳回并同步内容状态与内容安全摘要 |
购买接口会创建 pending 业务订单，并同步在 Cashier 登记 scene=video-content 的支付订单。Cashier 支付成功回调命中该场景后会按 outTradeNo 幂等标记 Video 购买单为 paid；Cashier 退款回调或 Admin 手动登记退款失效会把购买单标记为 refunded。读侧只认 paid 订单或 Entitlement 内容解锁凭证，不因 pending 或 refunded 订单解锁。
Entitlement 内容解锁复用中性 ContentAccessPolicyService：consumerCode=video、ownerType=user，已支付购买单作为 directUnlock，付费内容默认查询 itemCode=video-paid，VIP / 会员内容默认查询 itemCode=video-vip。调用方可以用 Entitlement 套餐编码或套餐项编码授予对应用户解锁能力，Video 模块不复制作者直读、直接解锁和权益匹配逻辑。
视频响应会返回 contentSafetyAction、contentSafetyRiskLevel、contentSafetyReason、contentSafetyCheckedAt、contentSafetyReviewRequired 和 contentSafetyRejected。前端应优先使用这些字段展示状态；播放按钮是否可用仍以 contentReadable 和 videoUrl 为准。
互动请求 actionType 支持：
| actionType | 语义 |
|---|---|
like | 点赞；用户对同一内容只有一个可切换状态 |
favorite | 收藏；用户对同一内容只有一个可切换状态 |
share | 分享事件；每次提交都会记录一次有效事件 |
report | 举报事件；可携带 reason、remark 和 extraJson 留痕 |
举报记录默认 pending，后台处理后落为 confirmed 或 dismissed。举报处理只写 Video 自有 video_interaction 与 video_content 表，不跨模块处罚账号或资金；如果需要更重的风控、封禁或通知联动，应通过 Risk、IAM、Notification 等模块补独立业务规则。
开发边界
- Video 不直接依赖 Mall、Money 或具体 Payment Provider；支付创建、支付成功和退款失效只通过 Cashier 中性 Service / SPI 与
scene=video-content对接。 - 资金类动作必须通过订单状态和 Cashier 支付回调推进，不在 Video 中私写余额流水。
- 创作者收益摘要只聚合 Video 自有购买订单，真实外部打款、分成规则、税务、提现和风控补偿必须走 Money / Distribution / 具体 Provider，不在 Video Controller 内直连三方打款 SDK。
- 商城带货只保存商品标量引用和跳转参数，商品详情、库存、购物车、订单、支付、售后和分佣仍归 Mall / Cashier / Money / Distribution；Video 不引入 Mall Maven 依赖。
- 直播联动只保存直播间标量引用和跳转参数，开播、流媒体、回放、聊天室、直播商品和聊天治理仍归 Live；Video 不引入 Live Maven 依赖。
- 内容安全 starter 只提供检测结果与 Provider；Video 自己负责内容状态、公开过滤和播放地址隐藏。
- 推荐 Provider 是候选内容召回 / 排序 contract，不代表框架内置真实外部算法服务；项目需要接入外部推荐时，实现
VideoRecommendationProvider暴露目录描述并返回候选内容 ID，Video 模块统一负责内容安全过滤、已互动内容排除、付费隐藏和详情装配。 - 基础内容流筛选、关注流、分类 / 话题 / 搜索流、商城带货入口、互动规则热榜、规则推荐分组、用户个性化推荐、推荐 Provider 接入 contract、创作者运营概览指标、创作者收益结算摘要和付费订单退款失效已落地。真实外部推荐服务和真实打款 Provider 验收使用
./scripts/release video-provider-acceptance --recommendation-provider <provider> --payout-provider <provider>生成记录模板，并由部署负责人按授权账号、真实凭据和外部交易证据完成。
外部 Provider 验收
Video 的本地 contract 只证明模块能接入推荐 Provider、展示创作者收益摘要并保持付费 / 内容安全 / 举报处理规则一致；真实推荐服务和真实打款需要单独验收：
./scripts/release video-provider-acceptance \
--recommendation-provider <provider> \
--payout-provider <provider> \
--creator-user-id <creator-user-id>该命令只输出只读 runbook，不调用外部推荐服务、不移动资金、不修改数据库。验收记录应包含推荐请求 traceId、候选内容 ID、SpringOpen 本地过滤后的最终响应 ID、创作者收益摘要、外部打款 / 发票 ID、回滚方案和下一责任人。