播控管理业务文档

适用于 PC 播控端 + VR 客户端的播放授权。播控端生成机器码，后台直接把这串机器码作为授权标识，并为它设置剩余播放次数和到期日期。

项目要求

后台创建项目时，项目类型选择 播控管理
播控端启动后调用状态接口展示剩余次数和到期时间
每次真正开始体验时调用开始播放接口，次数会在开始时扣减

客户端接口

POST /api/license/status

用播控端机器码查询授权状态、剩余次数和到期时间。

POST /api/play/start

开始一次播放，服务端校验通过后扣减一次播放次数并返回 session_id。

POST /api/play/heartbeat

播放中可选心跳，用于后台判断客户端是否仍在运行。

POST /api/play/end

正常结束一次播放，写入结束时间和播放时长。

请求示例

查询授权状态

{
    "project_name": "VR Playback Project", // 必填：播控管理项目名称
    "machine_code": "PC-ABCD-001"          // 必填：播控端生成的机器码，也是授权标识
}

开始播放

{
    "project_name": "VR Playback Project", // 必填：播控管理项目名称
    "machine_code": "PC-ABCD-001",         // 必填：播控端生成的机器码
    "device_ip": "121.236.12.240",         // 可选兜底：后台优先记录API请求来源IP
    "client_version": "1.0.0"              // 可选：客户端版本，便于日志排查
}

结束播放

{
    "session_id": "返回的 session_id" // 必填：/api/play/start 返回的播放会话ID
}

返回示例

查询授权状态成功

{
    "valid": true,                    // 客户端主要判断字段：true 表示当前可播放
    "id": 8,                          // 授权记录ID
    "key": "PC-ABCD-001",            // 授权标识，播控项目中等同机器码
    "project_id": 5,                  // 项目ID
    "project_name": "VR Playback Project", // 项目名称
    "project_type": "playback",      // 项目类型：播控管理
    "is_active": true,                // 后台是否启用
    "auth_type": "count_date",       // 授权方式：count/date/count_date/unlimited
    "remaining_plays": 20,            // 剩余可播放次数，按次数类授权要重点显示
    "valid_until": "2026-12-31",     // 到期日期，按日期类授权要重点显示
    "machine_code": "PC-ABCD-001",   // 播控端机器码
    "last_play_started_at": null,     // 最近一次开始播放时间
    "playable": true,                 // 综合次数、日期、启用状态后的可播放结果
    "expired": false,                 // 是否已过期
    "message": "授权可用"             // 状态说明
}

开始播放成功

{
    "success": true,                  // 是否成功开始播放
    "message": "播放已开始",          // 服务端提示信息
    "session_id": "8d2b7f8e1e6a4b74b2974f8f2a3c9d10", // 本次播放会话ID，结束/心跳必须携带
    "id": 8,                          // 授权记录ID
    "key": "PC-ABCD-001",            // 授权标识，播控项目中等同机器码
    "project_id": 5,                  // 项目ID
    "project_name": "VR Playback Project", // 项目名称
    "project_type": "playback",      // 项目类型：播控管理
    "is_active": true,                // 后台是否启用
    "auth_type": "count_date",       // 授权方式
    "remaining_plays": 19,            // 开始播放后已扣减 1 次
    "valid_until": "2026-12-31",     // 到期日期
    "machine_code": "PC-ABCD-001",   // 播控端机器码
    "last_play_started_at": "2026-05-28T16:30:00", // 本次开始播放时间
    "playable": true,                 // 扣减后是否仍可继续播放
    "expired": false                  // 是否已过期
}

心跳成功

{
    "success": true,                  // 心跳是否记录成功
    "message": "心跳已记录"           // 服务端提示信息
}

结束播放成功

{
    "success": true,                  // 是否成功结束播放
    "message": "播放已结束",          // 服务端提示信息
    "session_id": "8d2b7f8e1e6a4b74b2974f8f2a3c9d10", // 已结束的播放会话ID
    "duration_seconds": 360           // 本次播放时长，单位：秒
}

播放失败

{
    "success": false,                 // false 表示播放开始失败
    "message": "剩余播放次数不足"      // 失败原因，可展示给播控端用户
}

接入说明

次数在 /api/play/start 成功时扣减，避免崩溃或断电导致漏扣。
后台会把长期没有结束记录的播放标记为超时，便于排查异常退出。
机器码就是播控项目的授权标识，不需要再额外传 key。