feat: add video playback progress reporting

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`，租户后台媒体运营报表会读取这些字段计算完成率和观看时长。
 
 ## 资料上传、预览和下载契约