直播

spring-open-module-live 提供直播业务模块首段 contract。当前版本已落地直播间、预告、开播状态、公开展示入口、用户预约、当前用户预约中心、直播间聊天室入口、直播聊天治理配置、禁言、消息体拦截、聊天举报、举报处理通知、聊天治理审计、举报 SLA 摘要、批量处置、通知模板运维目录、运营摘要、直播商品挂载、直播商品讲解中状态与讲解记录、商品讲解开始通知、带货本地转化报表、可信 Mall 下单 / 支付 / 退款事件登记、开播站内提醒、流媒体 Provider 骨架、Provider 本地 contract smoke、推拉流授权预览、录制 / 转码运维预览、录制任务提交、录制状态回写、录制任务取消和外部截图 / 转码回调；真实厂商流媒体能力后续沿 Provider contract 接入。

边界

Live 模块只保存直播业务状态和必要播放元数据，不保存第三方 SDK 私有对象。腾讯云、阿里云、SRS、WebRTC 等推流鉴权、播放鉴权、录制任务、回放转码和截图能力通过 Provider 扩展。

模块边界：

• API 前缀：/api/v1/live/**
• 配置前缀：spring.open.live.*
• 数据库表前缀：live_
• 权限码前缀：live:*

直播间状态

状态	值	说明
DISABLED	-1	已禁用，不对公开端展示
DRAFT	0	草稿，只能后台查看
SCHEDULED	1	直播预告，可公开展示
LIVE	2	直播中，可公开展示
ENDED	3	已结束，可公开展示回放入口

状态流转：

• 创建时未传预约时间默认 DRAFT，传了预约时间默认 SCHEDULED。
• DRAFT / SCHEDULED 可以开播为 LIVE。
• LIVE 可以结束为 ENDED。
• 非 LIVE 状态可以禁用为 DISABLED。

后台 API

方法	路径	权限	说明
GET	/api/v1/admin/live/rooms	live:room:view	分页查询直播间
GET	/api/v1/admin/live/rooms/{id}	live:room:view	查询直播间详情
POST	/api/v1/admin/live/rooms	live:room:create	创建直播间草稿或预告
PUT	/api/v1/admin/live/rooms/{id}	live:room:update	修改直播间基础信息
POST	/api/v1/admin/live/rooms/{id}/start	live:room:start	开播
POST	/api/v1/admin/live/rooms/{id}/end	live:room:end	结束直播
POST	/api/v1/admin/live/rooms/{id}/disable	live:room:disable	禁用非直播中直播间
GET	/api/v1/admin/live/rooms/stream/providers	live:room:view	查询流媒体 Provider 运维目录、配置状态和外部验收清单
GET	/api/v1/admin/live/rooms/stream/providers/smoke	live:room:view	执行流媒体 Provider 本地 contract smoke，检查必填配置、流地址预配、推拉流授权和录制计划
GET	/api/v1/admin/live/rooms/{id}/stream/authorization	live:room:view	基于当前 Provider 预览直播间推流 / 播放授权地址
GET	/api/v1/admin/live/rooms/{id}/stream/recording-plan	live:room:view	基于当前 Provider 预览直播间录制任务、回放、截图和转码档位
GET	/api/v1/admin/live/rooms/{id}/stream/recording-jobs	live:room:view	查询直播间录制任务提交、执行和回调状态
POST	/api/v1/admin/live/rooms/{id}/stream/recording-jobs	live:room:update	基于当前 Provider contract 提交录制任务并持久化本地审计记录
POST	/api/v1/admin/live/rooms/{id}/stream/recording-jobs/{jobId}/status	live:room:update	回写录制网关回调、人工复核或真实厂商验收后的任务状态
POST	/api/v1/admin/live/rooms/{id}/stream/recording-jobs/{jobId}/cancel	live:room:update	基于当前 Provider contract 取消录制任务并持久化本地取消审计
GET	/api/v1/admin/live/rooms/notifications/templates	live:room:view	查询 Live 通知模板运维目录、变量键和通知规则接入状态
GET	/api/v1/admin/live/rooms/operations/summary	live:room:view	查询 Live 运营摘要，聚合直播间、预约提醒、聊天举报、商品挂载和讲解记录
GET	/api/v1/admin/live/rooms/operations/commerce-report	live:room-product:view	查询 Live 带货本地转化报表，聚合商品曝光、点击、讲解记录和 Mall 订单事件验收状态
POST	/api/v1/admin/live/rooms/{id}/products/{productItemId}/commerce-events	live:room-product:update	登记可信 Live 带货交易事件，支持下单、支付成功和退款成功，并按 requestId 幂等
GET	/api/v1/admin/live/rooms/chat/audit	live:room-chat:view	跨直播间查询最近聊天举报、禁言和解除禁言审计事件
GET	/api/v1/admin/live/rooms/chat/reports/sla	live:room-chat:view	查询跨直播间聊天举报待处理、预警和超 SLA 摘要
GET	/api/v1/admin/live/rooms/chat/risk-report	live:room-chat:view	查询跨直播间聊天风险报表，聚合重复举报人、高风险目标用户和高频举报原因
GET	/api/v1/admin/live/rooms/{id}/chat/moderation	live:room-chat:view	查询直播间聊天治理配置和当前禁言列表
PUT	/api/v1/admin/live/rooms/{id}/chat/moderation	live:room-chat:moderate	保存直播间聊天开关、治理开关、公告和敏感词配置
POST	/api/v1/admin/live/rooms/{id}/chat/mutes	live:room-chat:moderate	禁言直播间用户
DELETE	/api/v1/admin/live/rooms/{id}/chat/mutes/{userId}	live:room-chat:moderate	解除直播间用户禁言
POST	/api/v1/admin/live/rooms/{id}/chat/members/{userId}/kick	live:room-chat:moderate	将用户踢出直播间聊天室
GET	/api/v1/admin/live/rooms/{id}/chat/reports	live:room-chat:view	查询直播间聊天举报
POST	/api/v1/admin/live/rooms/{id}/chat/reports/{reportId}/handle	live:room-chat:moderate	确认或驳回直播间聊天举报
POST	/api/v1/admin/live/rooms/{id}/chat/reports/batch-handle	live:room-chat:moderate	批量确认或驳回直播间待处理聊天举报
GET	/api/v1/admin/live/rooms/{id}/products	live:room-product:view	查询直播间商品挂载快照
POST	/api/v1/admin/live/rooms/{id}/products	live:room-product:update	新增直播间商品挂载
GET	/api/v1/admin/live/rooms/{id}/products/explanations	live:room-product:view	查询直播商品讲解记录
PUT	/api/v1/admin/live/rooms/{id}/products/{productItemId}	live:room-product:update	修改直播间商品挂载
DELETE	/api/v1/admin/live/rooms/{id}/products/{productItemId}	live:room-product:update	删除直播间商品挂载
POST	/api/v1/admin/live/rooms/{id}/products/{productItemId}/explaining	live:room-product:update	将直播间商品设为讲解中
DELETE	/api/v1/admin/live/rooms/{id}/products/{productItemId}/explaining	live:room-product:update	取消直播间商品讲解中状态

后台页面

Admin 已接入 /#/live/rooms 直播间管理页，对应菜单组件为 live/rooms。页面能力包括：

• 按关键词、主播用户 ID 和状态分页查询直播间。
• 新增 / 修改直播间基础信息，创建时支持草稿和预告状态。
• 查看直播间详情、推流地址、播放地址、回放地址和扩展 JSON。
• 预览当前流媒体 Provider 生成的推流 / 播放授权地址、授权模式、过期时间和外部验收状态。
• 预览当前流媒体 Provider 的录制任务入口、回放产物、截图产物、转码档位和外部验收状态。
• 创建直播录制任务，查看任务状态、Provider、外部任务 ID、回放产物和提交时间，并可人工回写录制中、成功或失败状态，也可通过 Provider contract 取消未终态任务。
• 对草稿 / 预告直播间执行开播，对直播中直播间执行结束，对非直播中直播间执行禁用。
• 查看当前流媒体 Provider、已注册 Provider、模板配置状态、本地 contract 状态和真实外部环境验收清单。
• 执行当前已注册流媒体 Provider 的本地 contract smoke，查看必填配置、流地址预配、推拉流授权、录制计划、失败原因和真实外部环境验收提示。
• 查看 Live 通知模板目录，包含事件编码、默认通道、默认标题 / 正文模板、变量键和是否接入通知规则。
• 查看 Live 运营摘要，汇总直播间状态、有效预约、已提醒预约、待处理举报、已处理举报、上架商品、讲解中商品和讲解记录。
• 查看 Live 带货本地转化报表，汇总直播商品曝光、点击、下单、支付、退款、点击率、讲解记录、Top 商品和 Mall 订单事件接入状态。
• 查看聊天治理审计，跨直播间追踪最近举报、禁言和解除禁言记录，便于运营先发现风险再进入具体直播间处理。
• 查看聊天举报 SLA，跨直播间展示待处理、接近超时、已超时、最早待处理时间、预警时限和 SLA 时限。
• 查看聊天风险报表，基于近期举报和有效禁言聚合风险等级、重复举报人、高风险目标用户和高频举报原因。
• 管理直播间聊天治理配置，支持聊天开关、治理开关、公告、敏感词配置、禁言用户、解除禁言、踢出聊天室用户、聊天举报查看、单条确认 / 驳回和待处理举报批量处置。
• 管理直播间商品挂载快照，支持商品 ID、SKU ID、商品名称、封面、卖点、跳转链接、排序、上 / 下架状态、讲解中状态和最近讲解记录。

页面不维护本地假数据；所有列表、详情、保存和状态动作均调用 /api/v1/admin/live/rooms 后端 contract。

流媒体 Provider

创建或更新直播间时，模块会按 spring.open.live.stream.provider 进行流地址预配；后台授权预览会基于同一个 Provider contract 生成推流 / 播放授权地址，录制 / 转码预览会基于同一个 Provider contract 返回录制任务入口、回放产物、截图产物和转码档位；录制任务提交会调用同一个 Provider contract 的 startRecording，取消任务会调用同一个 Provider contract 的 cancelRecording，外部网关可通过公开回调把截图、回放和转码结果写回本地任务审计记录：

• mock：默认 Provider。未传入地址时生成确定性的 mock 推流、播放、回放 URL；授权预览会生成带本地签名参数和过期时间的 mock 推流 / 播放地址，录制 / 转码预览会生成本地 mock 录制任务、截图、回放和转码档位；提交录制任务时会返回本地 mock 外部任务 ID 和 recording 状态，取消录制任务时返回 canceled 状态，便于本地联调和端到端页面闭环。
• custom：外部流媒体系统托管。模块只保留请求中写入的 URL，不生成占位地址。
• srs、tencent-cloud、aliyun：内置模板型 Provider。通过 spring.open.live.stream.<provider>.*-template 配置推流、播放、回放和额外 JSON 模板，通过 spring.open.live.stream.<provider>.push-authorize-url-template / play-authorize-url-template 配置推流 / 播放授权模板，通过 spring.open.live.stream.<provider>.recording-job-url-template / snapshot-url-template / transcoding-profile 配置录制 / 截图 / 转码运维预览，通过 spring.open.live.stream.<provider>.callback-token 配置外部回调令牌，适合接 SRS、自建签名网关或云厂商鉴权网关；提交录制任务时会返回 submitted 状态并标记 externalAcceptanceRequired=true，取消任务时返回 canceled 状态并继续标记外部验收，后续由外部网关回调或管理员人工复核状态；未配置推流 / 播放模板且直播间也未显式填写地址时会 fail-fast。Config 模块可用时，Provider 名称、模板、授权过期和回调令牌配置优先读取配置中心同名 key，未配置时回退本地配置文件。

推流 / 播放 / 回放 / 录制任务 / 截图模板占位符支持 {roomCode} 和 {title}。授权模板额外支持 {expiresAt} 和 {expiresEpochSecond}。授权默认有效期由 spring.open.live.stream.authorization-ttl-seconds 控制，默认 3600 秒，运行期优先读取配置中心。公开回调 POST /api/v1/live/stream/recording-callbacks 可按 jobId、provider + externalTaskId 或 roomId + operationKey 定位任务，回写 status、replayUrl、snapshotUrl、transcodingProfile、failureReason 和 callbackPayload；mock Provider 允许无令牌本地联调，真实 Provider 必须配置并携带 spring.open.live.stream.<provider>.callback-token。当前录制任务提交、取消和回调只闭口本地 mock 与模板网关 contract，不主动内置真实厂商 SDK；具体厂商 SDK 实现仍应作为独立 Provider 扩展，不写进 Controller 或 Live 业务服务。

后台 /#/live/rooms 会读取 /api/v1/admin/live/rooms/stream/providers 展示 Provider 运维目录：当前启用 Provider、每个 Provider 的运维模式、配置 key 是否已填、本地 contract 是否可用，以及真实推流、播放、授权过期校验、录制、截图、转码等外部验收清单。后台也可通过 /api/v1/admin/live/rooms/stream/providers/smoke 执行本地 contract smoke，逐个校验 Provider 必填配置、流地址预配、推拉流授权和录制计划，并在页面展示通过 / 失败状态、缺失配置和失败原因。直播间详情会读取 /api/v1/admin/live/rooms/{id}/stream/authorization 展示授权预览，读取 /api/v1/admin/live/rooms/{id}/stream/recording-plan 展示录制 / 转码预览，并读取 /api/v1/admin/live/rooms/{id}/stream/recording-jobs 展示录制任务提交、取消和回调状态。Provider 运维目录、Provider smoke、授权预览和录制计划只做本地诊断，不主动调用真实厂商网络，也不把没有真实账号 / 真实流媒体环境的场景标记为已验收；录制任务提交和取消只在本地记录可追踪的任务审计和状态，不伪装真实厂商验收。

公开 API

方法	路径	说明
GET	/api/v1/live/rooms	分页查询可公开展示的直播间
GET	/api/v1/live/rooms/{id}	查询可公开展示的直播间详情
GET	/api/v1/live/bookings/me	当前登录用户分页查询自己的有效直播预约
POST	/api/v1/live/rooms/{id}/bookings	当前登录用户预约直播间
DELETE	/api/v1/live/rooms/{id}/bookings	当前登录用户取消直播间预约
POST	/api/v1/live/rooms/{id}/chat	当前登录用户进入直播间聊天室
POST	/api/v1/live/rooms/{id}/chat/reports	当前登录用户举报直播间聊天用户或消息
GET	/api/v1/live/rooms/{id}/products	查询公开可见直播间的上架商品挂载快照
POST	/api/v1/live/rooms/{id}/products/{productItemId}/events	记录公开端直播商品曝光或点击事件，requestId 存在时保持幂等
POST	/api/v1/live/stream/recording-callbacks	接收外部流媒体 Provider 的录制、截图或转码回调；真实 Provider 必须携带配置中心中的 callback-token

公开端默认只展示 SCHEDULED、LIVE 和 ENDED 状态；草稿和禁用直播间按不存在处理。

预约入口要求当前用户已登录，只允许预约 SCHEDULED 和 LIVE 状态直播间。重复预约保持幂等；取消后会把预约状态置为已取消，用户仍可再次预约。/bookings/me 只返回当前用户仍有效的预约记录，并附带可公开展示的直播间摘要；如果预约对应直播间已下架、禁用或不可见，响应保留预约记录且 room 为空，避免用户中心整页失败。

后台把直播间从 DRAFT / SCHEDULED 切换到 LIVE 时，会发布 live.room.started 事件。模块会查询已预约用户，通过 Notification 的数据库通道发送“预约直播已开播”站内信，并回写预约记录的 reminded_at。

后台 /#/live/rooms 会读取 /api/v1/admin/live/rooms/notifications/templates 展示通知模板目录。当前目录覆盖 live.room.started、live.product-explaining.started、live.chat-report.pending-review 和 live.chat-report.status-changed，展示默认通道、默认模板、变量键和是否接入 Notification 规则链路。该目录是只读运维 contract，帮助管理员把事件编码同步配置到通知规则 / 文本模板，不直接替代 Template 模块的模板 CRUD。

直播间聊天室入口复用 Conversation / WebSocket 通用能力。Live 模块只负责校验直播间公开可见、确保稳定公开聊天室 roomKey=live-{roomId}、把当前用户加入聊天室并返回会话 ID 和当前用户聊天治理状态；ACK、撤回、成员状态和实时推送继续由 Conversation / WebSocket 承担。

后台聊天治理配置保存在 Live 自有表内，支持按直播间开关聊天、启用治理、设置公告、维护敏感词列表、禁言用户和处理聊天举报。公开聊天室响应只返回当前用户是否被禁言、禁言截止时间、禁言原因、公告和敏感词数量，不暴露敏感词明文。用户可提交聊天举报，后台可单条确认 / 驳回，也可对同一直播间待处理举报批量处置；批量接口只处理仍处于 pending 的举报，已处理或不存在的 ID 会返回 skipped，避免重复改写历史处理结果。举报 SLA 以 4 小时进入预警、24 小时超时作为当前运营基线，后台摘要跨直播间展示待处理、预警、超时和最早待处理时间。举报待审核事件会进入 Notification 规则链路，处理结果在无显式规则接收人时默认通知举报人。Live 已通过 Conversation conversation.message.send.prepare Pipeline 对 room:live-{roomId} 会话消息在落库前执行聊天开关、禁言和敏感词拦截，不在 Live 模块内重写完整 Conversation 消息管线。后台聊天治理审计和风险报表从现有举报和禁言表实时聚合最近事件、重复举报人、高风险目标用户和高频举报原因，不新增审计表或报表表。

直播商品挂载只保存 Mall 商品的轻量快照：productId、skuId、商品名称、封面、卖点、可选跳转链接、排序、上 / 下架状态和讲解中状态。Live 不直接依赖 Mall，也不负责库存、订单、支付或售后；公开端读取上架快照后按自身路由跳转商城详情。同一个直播间同一时间只允许一个上架商品处于讲解中，切换讲解商品时会自动取消同直播间其他商品的讲解中状态，把每次讲解开始 / 结束写入 Live 自有运营历史，并向已预约直播间的用户发送 live.product-explaining.started 站内信。

公开端可以通过 /api/v1/live/rooms/{id}/products/{productItemId}/events 上报 impression 和 click 两类直播商品事件。事件写入 live_room_product_event，包含直播间、商品挂载、商品快照、事件类型、可选 requestId、可选用户和来源页面；同一直播间、同一商品挂载、同一事件类型、同一 requestId 只记录一次，避免前端重试重复计数。

后台或可信业务模块可以通过 /api/v1/admin/live/rooms/{id}/products/{productItemId}/commerce-events 登记 order-created、payment-succeeded、refund-succeeded 三类交易事件，并可携带下单用户 ID。该 contract 用于 Mall / Cashier / Payment 等生产链路把直播带货结果回写给 Live 报表，Live 只保存事件摘要，不保存订单明细、支付流水、退款执行或库存状态。后台带货转化报表实时聚合 live_room_product_event 和 live_room_product_explanation，展示曝光、点击、下单、支付、退款、点击率、讲解记录、Top 商品和 Mall 事件接入状态；真实 Mall 生产链路只有按该 contract 写入事件后，才算外部验收通过。

公开端页面

App 已提供 /live/index、/live/detail 和 /live/bookings，覆盖公开直播浏览、详情播放 / 回放、预约 / 取消预约、进入聊天室、直播商品展示，以及当前用户有效预约列表。PC /live 频道页侧栏展示登录用户最近预约，/live/{id} 继续负责直播详情、播放 / 回放、预约、进入聊天室和直播商品跳转。

数据模型

当前直播间主表是 live_room，字段包括：

• 稳定编码：room_code
• 基础展示：title、description、cover_url
• 主播：anchor_user_id
• 状态与时间：status、scheduled_start_at、started_at、ended_at
• 流媒体入口占位：push_stream_url、play_url、replay_url
• 扩展：extra_json

room_code 逻辑上稳定唯一，用于后续公开链接、推流房间标识和运营追踪。删除 / 禁用不能把旧编码重新分配给无关业务。

预约表是 live_room_booking，字段包括：

• 关联：room_id、user_id
• 状态：status，1 表示已预约，0 表示已取消
• 提醒：reminded_at
• 取消：canceled_at

room_id + user_id 保持唯一，取消后通过状态恢复支持再次预约，避免逻辑删除和唯一键冲突。

商品挂载表是 live_room_product，字段包括：

• 关联：room_id、product_id、sku_id
• 快照：product_name、product_cover_url、selling_point、product_url
• 展示：sort_order、status、explaining、explaining_at

room_id + product_id + sku_id 保持唯一。product_url 可为空，公开端会按自身商城详情路由兜底。explaining=true 只表示当前直播间运营侧正在讲解该商品，不改变 Mall 商品、库存、订单、支付或售后状态。

商品讲解记录表是 live_room_product_explanation，字段包括：

• 关联：room_id、room_product_id、product_id、sku_id
• 快照：product_name
• 时间：started_at、ended_at

讲解记录由 Live 模块在后台切换讲解中商品、取消讲解、禁用或删除商品时维护。ended_at 为空表示当前仍在讲解；后台抽屉展示最近讲解记录，便于运营复盘。

聊天治理配置表是 live_room_chat_moderation，字段包括：

• 关联：room_id
• 开关：chat_enabled、moderation_enabled
• 内容：announcement、sensitive_words

禁言记录表是 live_room_chat_mute，字段包括：

• 关联：room_id、user_id
• 状态：status
• 时间：muted_until、released_at
• 操作：operator_id、reason

同一直播间同一用户只保留一条活跃禁言语义；新增禁言会先释放该用户旧的活跃禁言，再写入新记录，方便后台审计历史。

聊天举报表是 live_room_chat_report，字段包括：

• 关联：room_id、reporter_user_id、target_user_id、message_id
• 内容：reason、content
• 状态：review_status
• 处理：handled_by、handled_at、handling_remark

举报创建后默认 pending，后台处理后变为 confirmed 或 dismissed。Live 只保存举报和处理审计，不直接替代 Conversation 的消息体管线；举报相关通知通过 Notification 规则链路发送。

录制任务表是 live_room_stream_recording_job，字段包括：

• 关联：room_id、room_code
• Provider：provider、operation_key、external_task_id
• 状态：status，当前支持 submitted、recording、succeeded、failed、canceled
• 产物：recording_job_url、replay_url、snapshot_url、transcoding_profile
• 验收：external_acceptance_required、failure_reason、callback_payload
• 时间：submitted_at、recording_started_at、completed_at

room_id + operation_key 保持唯一，便于后台重试或外部网关回调时使用稳定幂等键。外部回调也可以用 provider + externalTaskId 或本地 jobId 定位任务，重复回调只更新同一条任务。mock Provider 会直接返回 recording / canceled 状态并允许无令牌回调；模板型 Provider 返回 submitted / canceled 并要求外部验收，后续状态通过公开回调或后台接口回写。

后续扩展

后续功能簇应保持模块可剥离，不建立业务模块间 Maven 强依赖：

• Provider：mock、custom、srs、tencent-cloud、aliyun 已有统一 contract、后台运维目录、本地 contract smoke、推拉流授权预览、录制 / 转码运维预览、录制任务提交、状态回写、取消任务和外部截图 / 转码回调；后续只在明确厂商、账号、凭据和真实环境验收条件后继续补真实厂商 SDK
• Live Chat：当前已具备进入直播间公开聊天室入口、后台聊天治理配置、用户禁言、用户踢出、消息体敏感词拦截、聊天举报、举报处理通知、跨直播间聊天治理审计、SLA 摘要、批量处理和风险报表；后续只在接入外部风控 Provider 或真实直播厂商审计源时继续拆分
• Live Commerce：当前已具备商品挂载快照、三端商品入口、直播间商品讲解中状态、讲解记录和本地曝光 / 点击 / 讲解转化报表；后续继续补真实 Mall 下单 / 支付 / 退款事件联动和真实交易转化验收
• Notifications：当前已具备开播提醒、商品讲解开始、聊天举报待审核、举报处理结果通知规则链路和后台通知模板运维目录；后续只在明确业务事件或真实渠道验收时继续拆分
• Public View：当前已具备公开直播列表、直播详情、预约入口、当前用户预约中心和播放 / 回放体验；后续仅在个性化推荐、历史回放归档或互动直播入口明确时继续拆分