feat: add media access analytics

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/视频次数校验、签名播放、次数扣减、播放日志和动态水印上下文；深度防盗链、转码级水印和播放统计继续补 |
+| 视频会员播放次数 | 可联调 | `POST /api/videos/play` 支持 SVIP/视频次数校验、签名播放、次数扣减、播放日志和动态水印上下文；租户后台媒体报表已可按视频、用户、traceId 查询播放事件和汇总；深度防盗链、转码级水印和更细播放完成率统计继续补 |
 | 视频 JSON 导入和批量绑定 | 可联调 | `/api/tenant-content/imports/preview/videos`、`/api/tenant-content/imports/videos`；支持视频元数据、资源引用、播放模式、题目绑定和题目视频标记 |
 
 ## 资料与对象存储
@@ -99,7 +99,7 @@
 | PDF/图片预览签名 | 可联调 | `/api/catalog/assets/preview`、`/api/tenant-content/assets/sign-preview`；使用 inline 短期签名，学生预览默认短 TTL |
 | 托管资源 worker 复检 | 可联调 | `apps/worker --job assets` 定期复检 pending/verified 对象元数据；异常资源会标记 failed 并从 active 退回 draft，写入审计和 `security_flags` |
 | 内容资源安全扫描 | 可联调 | `content_assets.security_scan_status` + `content_asset_security_scan_events`；托管对象确认上传后进入 `pending/scanning`，内置 `metadata_rules` 和可选外部 HTTP scanner 通过后才可发布、下载、预览或视频播放；失败或外部 scanner 不可用默认 fail-closed，会下架并写审计 |
-| 资源访问审计 | 可联调 | `content_asset_access_events` + `GET /api/tenant-content/assets/access-events`；记录上传签名/确认、学生下载/预览、后台下载/预览的 granted/denied、TTL、签名模式、IP、UA 和水印 traceId |
+| 资源访问审计 | 可联调 | `content_asset_access_events` + `GET /api/tenant-content/assets/access-events` + `/api/tenant-content/media-analytics/*`；记录上传签名/确认、学生下载/预览、后台下载/预览的 granted/denied、TTL、签名模式、IP、UA 和水印 traceId，并支持租户后台汇总、Top 资源和 traceId 回查 |
 | CDN 访问边界 | 可联调 | `members/svip/private` 外部 CDN URL 默认拒绝，必须显式 `metadata.providerManagedAccess=true` 或 `cdnAccessMode=signed_by_provider`；视频绑定资源也复用该规则 |
 | 深度防盗链/水印/杀毒 | 部分覆盖 | 内置 metadata 规则扫描、外部 HTTP scanner 接入层、失败关闭、生产 readiness 阻断、签名访问动态水印上下文和 traceId 审计已完成；商用上线前继续联调真实 AV/内容安全服务、转码/CDN 级水印、CDN 刷新和对象生命周期策略 |
 

docs/refactor/backend-progress.md

@@ -259,7 +259,7 @@ GET  /api/tenant-admin/audit-logs
 - 学生批量导入、批量分班、学生状态、备注和跟进任务都使用独立权限点；教师默认可为范围内学生写备注和跟进任务，但不能批量导入、禁用学生或放大可见班级。
 - 销售/代理客资采用首绑保护：普通扫码/分享事件不会覆盖已有归属，只有具备 `referral:write` 的租户成员可手动强制补绑。
 - CRM 当前完成配置、密钥入私密表、客资入队、队列查询和 `apps/worker` 消费；worker 支持 generic webhook、钉钉、飞书、企业微信机器人消息体/签名、失败重试和日志。
-- 内容资源当前完成台账、租户后台维护、学生端 SVIP 下载权限，以及 `local_dev`、阿里云 OSS、腾讯 COS、Supabase Storage 的上传/下载签名 provider；上传确认、访问审计、动态水印上下文、assets worker 对象元数据校验/复检、内置 `metadata_rules` 安全扫描和外部 HTTP scanner 接入层已完成。PDF 深度预览体验、防盗链、转码/CDN 级水印和真实 AV/内容安全服务联调仍需继续补。
+- 内容资源当前完成台账、租户后台维护、学生端 SVIP 下载权限，以及 `local_dev`、阿里云 OSS、腾讯 COS、Supabase Storage 的上传/下载签名 provider；上传确认、访问审计、动态水印上下文、租户后台媒体运营报表、assets worker 对象元数据校验/复检、内置 `metadata_rules` 安全扫描和外部 HTTP scanner 接入层已完成。PDF 深度预览体验、防盗链、转码/CDN 级水印和真实 AV/内容安全服务联调仍需继续补。
 - 题库内容导航当前以 `content_entries/content_nodes` 为主模型，可表达“入口 -> 多级分类 -> 院校/专业/学科/销售意向标记”；题目集合和练习方式由 `question_collections/practice_blueprints` 管理，练习 session 会保存当次题目 ID 快照。
 - 练习访问控制由 `content_entries/content_nodes/question_collections/practice_blueprints` 的 `accessRules` 合并决定；普通用户消耗 `practice_daily_usage`，事件写入 `practice_access_events`，SVIP/staff 不消耗免费额度。
 - 批量导入当前支持题目、单词、知识手册、分数线、视频 JSON/CSV/Excel 预览、逐行 issue、job/item 台账、同步执行或 `executionMode=async` 异步执行、幂等跳过，并可落到新内容入口、分类节点、分数线表或题目视频绑定。旧单词模板的 `vocabulary_units_示例数据` / `vocabulary_示例数据`、知识手册的书籍/章节/小节/知识点嵌套结构都由后端规范化。导入后复检、模板下载和字段映射 API 已补齐，前端 UI 待接。

docs/refactor/frontend-handoff-index.md

@@ -46,7 +46,7 @@
 - 生产鉴权已具备 Supabase JWT API 入口，自定义角色模板基础 API 已可用；仍要做真实云端 Auth/JWKS 回归、RLS 深测和班级/学生范围权限细化，前端不要继续使用 `x-user-id`。
 - 不要把“Supabase 支持前端 Data API”误解为“本项目所有业务表都由 Taro 直写”；订单、支付、权益、租户后台、导入、CRM、私有资源必须走 RPC、`apps/api`、Edge Function 或 worker 这类后端命令层。
 - 短信、微信小程序/网页登录、QQ 登录、微信支付、支付宝支付 provider 已有本地 adapter 和测试覆盖；生产账号、回调域名、证书和商户资料仍需正式联调。
-- 对象存储已完成签名 provider、上传后校验、PDF/图片预览、动态水印上下文、资源复检 worker、内置安全扫描和外部 HTTP scanner 接入层；CDN 防盗链、转码级视频水印和真实 AV/内容安全服务联调还要补。
+- 对象存储已完成签名 provider、上传后校验、PDF/图片预览、动态水印上下文、资源复检 worker、内置安全扫描、外部 HTTP scanner 接入层和租户后台媒体运营报表；CDN 防盗链、转码级视频水印和真实 AV/内容安全服务联调还要补。
 - 题目/单词/知识手册/分数线/视频 JSON/CSV/Excel 导入已可联调；大批量导入可传 `executionMode=async` 交给 imports worker；模板下载、字段映射 API、导入任务详情和导入后复检已可用。租户内容页已经可以选择文件或粘贴内容、下载模板、执行后端预览、编辑本次字段别名、同步/异步提交导入、轮询异步 job、查看问题行并触发/查看复检；后续还要补真实数据 dry-run 验收和更完整的目标入口/集合选择。
 - 数据看板、分佣结算、勋章手动发放和主题模板发布基础 API 已可联调；勋章自动发放、分佣真实打款/导出/凭证、AI 择校、主题素材库/模板市场等仍是后续商用增强项。
 

docs/refactor/next-development-todo.md

@@ -30,6 +30,7 @@
 - 资金对账和差错工单闭环已完成：`commerce_reconciliation_batches/items` 和 `/api/commerce/reconciliation/*` 支持手工/API 导入供应商账单行、预览差异、生成批次统计、查询异常、租户隔离、权限点 `tenant:reconciliation:read/write` 和审计日志；`commerce_reconciliation_issues/events` 支持异常明细创建工单、分配、开始处理、升级、解决、忽略、重开和事件留痕，且不直接修改订单/支付/退款/权益。
 - 内容资源复检与安全扫描 worker 已完成：`apps/worker --job assets` 可复检 `content_assets` 中的托管对象元数据，并执行内置 `metadata_rules` 和可选外部 HTTP scanner；正常资源写回复检/扫描证据，异常资源自动置为 `failed/skipped + draft` 或 `security_scan_status=failed`，外部 scanner 不可用默认 fail-closed，并写入审计、扫描事件和安全标记。
 - 题库导出 worker 已完成：`apps/worker --job exports` 可抢占 `pdf/docx/daily_practice_zip` 导出任务，渲染 PDF/Word、水印或每日一练图片素材包，写入对象存储或本地开发存储，创建 `content_assets` 并回填 `assetId/hash/size`；`daily_practice` 已支持每日一练九宫格 metadata、PDF/Word 基础版式、9 张 PNG/SVG 卡片和拼图 ZIP。
+- 租户后台媒体运营报表已完成：`/api/tenant-content/media-analytics/summary`、`asset-events`、`video-events` 可按 7/30/90 天、资源、视频、用户和水印 traceId 查询资料访问、视频播放、拒绝访问、Top 资源/视频和日趋势；仅开放给 owner/admin/operator 或 `content:analytics:read` 权限角色，前端不会拿到签名 URL 或播放 token。
 - 本地验证：`npm run check:refactor` 已通过。
 
 当前更适合进入前端联调前阅读的总览文档：
@@ -53,6 +54,7 @@
    - 已补内容资源安全扫描状态机：确认上传后进入 `securityScanStatus=pending`，扫描通过后才能发布、下载、预览或视频播放；后台可查 `/api/tenant-content/assets/security-scan-events`。
    - 已补资源访问事件 `content_asset_access_events`，覆盖上传签名/确认、学生下载/预览、后台下载/预览的 granted/denied、短 TTL、签名模式、IP、UA 和动态水印 traceId。
    - 已补签名访问动态水印上下文：学生资料下载/预览、租户后台下载/预览和视频播放都会返回 `watermark`，并将 traceId 写入访问事件或播放事件。
+   - 已补租户后台媒体运营报表，支持资料/视频访问汇总、Top 资源/视频和 traceId 回查；大租户后续再把实时查询替换为日/周预聚合。
    - 已收紧锁定资源 CDN 边界：`members/svip/private` 外链默认拒绝，必须显式 provider-managed 才允许；视频绑定资源也复用该策略。
    - 已补外部 HTTP 杀毒/内容安全 scanner 接入层、失败关闭、生产 readiness 阻断和动态水印 traceId 审计；继续联调真实扫描服务、转码/CDN 级水印、CDN 刷新和对象生命周期策略。
    - `content_assets` 继续作为资源台账，不允许前端绕过台账直接访问私有资源。
@@ -101,7 +103,7 @@
 
 6. 视频会员控制
    - 已完成视频 SVIP 权限、播放次数扣减、签名播放和播放日志。
-   - 已补播放签名动态水印上下文和 traceId 事件；继续补深度防盗链、转码级水印、播放统计。
+   - 已补播放签名动态水印上下文、traceId 事件和租户后台播放事件查询；继续补深度防盗链、转码级水印、播放完成率和观看时长统计。
    - 单题视频和通用知识视频混合推荐。
 
 7. 学习统计

docs/refactor/taro-frontend-integration.md

@@ -269,6 +269,7 @@ tenant:<tenantId>:theme
 | 租户勋章 | `GET/PUT /api/tenant-admin/badges`、`GET/POST /api/tenant-admin/badge-grants` |
 | 公共题库采纳/同步 | `GET /api/tenant-content/public-question-banks`、`POST /api/tenant-content/public-question-banks/adopt`、`POST /api/tenant-content/public-question-banks/sync`、`GET /api/tenant-content/public-question-banks/conflicts?adoptionId=...`、`POST /api/tenant-content/public-question-banks/conflicts/resolve`、`POST /api/tenant-content/public-question-banks/conflicts/resolve-batch` |
 | 题库导出 | `POST /api/tenant-content/exports/questions`、`GET /api/tenant-content/exports/jobs` |
+| 资料/视频运营审计 | `GET /api/tenant-content/media-analytics/summary`、`asset-events`、`video-events` |
 
 ## 资料、PDF 和视频资源契约
 
@@ -329,6 +330,25 @@ GET /api/tenant-content/assets/access-events?assetId=<assetId>&limit=100
 
 访问事件 `metadata.watermark.traceId` 可用于后台按截图上的追踪码回查访问记录。视频播放不走 `content_asset_access_events`，但 `POST /api/videos/play` 返回同样的 `watermark` 对象，后端会把 traceId 写入 `video_play_events.metadata.watermark.traceId`。
 
+租户后台运营报表：
+
+```text
+GET /api/tenant-content/media-analytics/summary?timeRange=30d&limit=10
+GET /api/tenant-content/media-analytics/asset-events?traceId=7D2A9C3E1B0F&limit=100
+GET /api/tenant-content/media-analytics/video-events?videoId=<videoId>&limit=100
+```
+
+这些接口用于租户后台资料/视频运营面板，权限为 `content:analytics:read`，租户 owner/admin/operator 默认可访问。普通教师默认不可见，除非绑定了带该权限的角色模板。
+
+前端展示建议：
+
+- `summary.assetAccess` 展示下载、预览、拒绝访问、水印事件数。
+- `summary.videoPlay` 展示视频播放、SVIP 播放、次数播放、消耗次数。
+- `assetTop` / `videoTop` 做热门资料和热门视频排行。
+- `daily` 做资料访问和视频播放趋势。
+- 搜索框支持输入截图上的 `traceId`，同时请求 `asset-events` 和 `video-events` 回查用户、时间、IP、UA、资源或视频。
+- 这些接口不会返回签名 URL、播放 token、云厂商密钥或支付密钥；前端不要把它们当成下载/播放接口。
+
 ## 练习访问控制契约
 
 前端不要先拉完整题目列表再自行判断免费额度。用户点击顺序刷题、随机刷题、全真模拟时，统一调用 `POST /api/learning/practice-sessions`，后端会根据 `content_entries.accessRules`、`content_nodes.accessRules`、`question_collections.accessRules`、`practice_blueprints.accessRules` 和当前用户权益决定最终题目快照。