feat: add video playback progress reporting

docs/refactor/backend-capability-status.md

@@ -82,7 +82,7 @@
 | 分数线字段/院校/专业/记录/趋势 | 可联调 | `/api/scoreline/*` |
 | 分数线 JSON 导入 | 可联调 | `/api/tenant-content/imports/preview/scoreline`、`/api/tenant-content/imports/scoreline`；支持字段、院校、专业、记录、动态字段值、逐行 issue、幂等和审计 |
 | 题目视频/批量预加载/搜索 | 可联调 | `/api/questions/*/videos`、`/api/videos/search`；付费视频列表不返回可播放 URL |
-| 视频会员播放次数 | 可联调 | `POST /api/videos/play` 支持 SVIP/视频次数校验、签名播放、次数扣减、播放日志和动态水印上下文；租户后台媒体报表已可按视频、用户、traceId 查询播放事件和汇总；深度防盗链、转码级水印和更细播放完成率统计继续补 |
+| 视频会员播放次数 | 可联调 | `POST /api/videos/play` 支持 SVIP/视频次数校验、签名播放、次数扣减、播放日志和动态水印上下文；`POST /api/videos/progress` 支持播放开始、心跳、完成上报；租户后台媒体报表已可按视频、用户、traceId 查询播放事件、观看秒数和完成率；深度防盗链和转码级水印继续补 |
 | 视频 JSON 导入和批量绑定 | 可联调 | `/api/tenant-content/imports/preview/videos`、`/api/tenant-content/imports/videos`；支持视频元数据、资源引用、播放模式、题目绑定和题目视频标记 |
 
 ## 资料与对象存储

docs/refactor/next-development-todo.md

@@ -103,7 +103,7 @@
 
 6. 视频会员控制
    - 已完成视频 SVIP 权限、播放次数扣减、签名播放和播放日志。
-   - 已补播放签名动态水印上下文、traceId 事件和租户后台播放事件查询；继续补深度防盗链、转码级水印、播放完成率和观看时长统计。
+   - 已补播放签名动态水印上下文、traceId 事件、播放进度上报和租户后台播放事件查询；继续补深度防盗链、转码级水印和更细观看行为分析。
    - 单题视频和通用知识视频混合推荐。
 
 7. 学习统计

docs/refactor/taro-frontend-integration.md

@@ -879,6 +879,7 @@ GET /api/learning/vocabulary/review-plan?unitId=<unitId>&reviewLimit=30&newLimit
 3. 后端校验当前 session 用户、租户、题目绑定关系、SVIP 权益或视频次数权益。
 4. 后端返回短期签名 URL、播放 token、权益来源和过期时间。
 5. 前端播放器只使用本次返回的 `playback.url`，不要缓存为长期资源地址。
+6. 播放器开始、周期心跳和播放完成时调用 `POST /api/videos/progress` 上报进度。
 
 请求示例：
 
@@ -921,6 +922,22 @@ GET /api/learning/vocabulary/review-plan?unitId=<unitId>&reviewLimit=30&newLimit
 - `VIDEO_ASSET_REQUIRED`：展示“视频暂不可播放”，同时上报前端日志。
 - 签名 URL 过期后必须重新调用 `/api/videos/play`，不要重试旧 URL。
 - 小程序/H5 不保存对象存储真实 key，不把播放 URL 写入本地持久缓存。
+- `playToken` 只用于当前播放会话进度上报，不写入长期缓存，不暴露到页面 URL。
+- H5 `video` 组件建议在 `play` 上报 `eventType=start`，每 15-30 秒或进度变化明显时上报 `heartbeat`，`ended` 或观看进度超过 90% 时上报 `complete`。
+
+进度上报示例：
+
+```json
+{
+  "playToken": "vp_...",
+  "eventType": "heartbeat",
+  "progressSeconds": 45,
+  "watchedSeconds": 48,
+  "durationSeconds": 90
+}
+```
+
+后端会校验 `playToken` 必须属于当前登录用户和当前租户，其他用户不能拿 token 改播放状态。返回的 `item.playback` 会包含 `watchedSeconds`、`completionRate`、`startedAt`、`completedAt`，租户后台媒体运营报表会读取这些字段计算完成率和观看时长。
 
 ## 资料上传、预览和下载契约