行为采集与访问统计

CMS 的访问统计由前台行为采集驱动：已发布页面加载 analytics SDK 的 CMS 采集器（island analytics），按站点签名的页面上下文上报事件；服务端把可信事实写入与「数据分析」共用的 user_events 事件库，CMS 统计页只读带可信标记的 v2 事实。预览页、爬虫、探针与非法上下文一律拒收，因此发布版与候选版构建不产生运营指标。

管理入口：/cms/stats（权限 cms:stat:view）。采集开关与统计时区属于站点配置（站点管理行内「访问采集配置」直达统计页「质量」Tab），表：cms_telemetry_receipts（接收/拒收/重复诊断）、cms_telemetry_outbox（转化投递），事件落 user_events。

采集链路

1. 服务端签名页面上下文：渲染时由渲染管线签发不可篡改的上下文令牌（cms-telemetry-context meta + cms-telemetry-config），固化站点、站点统计键、页面类型、规范路径、内容与修订、栏目、作者、发布版本与搜索上下文；静态产物在构建与激活时重绑 releaseId / deploymentId。
2. 浏览器采集：island 启动 CmsTracker（@zenith/analytics-sdk）。访客标识按站点隔离存 localStorage（Web Locks 防多标签首屏竞态），会话 30 分钟无活动切分，可见时 15 秒心跳，正文阅读深度与活跃时长按「最后一次人为活动」计量（后台标签页与空闲不计入活跃）。
3. 批量上报：事件先入浏览器侧持久化 outbox（localStorage，24 小时过期、最多 500 条），按上下文令牌分组批量 POST /api/public/cms/telemetry（每批 ≤ 20 条 / 48KB），失败按指数退避重试（上限 60s）；页面隐藏时改用 sendBeacon 尽力发送，因 beacon 无回执，这些事件仍留在 outbox 等待幂等重试。只有拿到逐个接收 / 拒收回执的事件才会出队。页面可通过 cms:telemetry-status 自定义事件观察投递状态。
4. 服务端受理：校验令牌与站点、采集开关、已激活部署（releaseId + deploymentId 必须一致）、内容仍存在、同源/绑定域名、live 环境，并做 IP 限流（300 次/分钟）与事件时效校验（回传时间在 24 小时内、不超过未来 5 分钟）；search 事件只接受第一页关键词，read 要求活跃 ≥ 10 秒且深度 ≥ 50%。拒收原因落 cms_telemetry_receipts，不写入指标。
5. 计数回写：本批次首次落库的 cms.page_view 在同一事务里累加 cms_contents.view_count，重试与重复上报不会重复计数。

只有 live 环境采集：草稿预览、候选部署预览与工作台预览不初始化访客存储、不发事件，服务端也会把预览环境的事件整批拒收。

事件目录

客户端事件（CMS_TELEMETRY_CLIENT_EVENTS，由采集器产生）：

事件	触发
cms.page_view	每次可见页面浏览（PV 唯一来源）
cms.engagement	心跳、隐藏、离开与销毁时的活跃时长/深度快照
cms.read	有效阅读达成（活跃 ≥10s 且深度不低于阈值；短文需读完）
cms.search	搜索结果页首屏一次（带关键词、结果数，cmsSearchId 贯穿翻页）
cms.search_click	从搜索结果点击进入内容
cms.component_impression / cms.component_click	版位（首页区块、专题按钮、部件）曝光与点击
cms.media_start / cms.media_progress / cms.media_error	音视频播放、25/50/75/100% 里程碑与错误
cms.download_click / cms.form_start / cms.form_error	附件下载点击、表单开始填写与校验失败（只记错误码，不含填写内容）

服务端转化事件（CMS_TELEMETRY_SERVER_EVENTS，由业务写入，不依赖浏览器）：

事件	触发
cms.form_complete	自定义表单提交成功
cms.vote_complete	互动问卷提交成功
cms.comment_complete	评论提交成功
cms.follow_complete	会员订阅成功
cms.download_delivered	附件下载实际取回文件（授权通过且存储读取成功）

转化与归因

• 转化事实在业务事务内写入 cms_telemetry_outbox（按站点+事件+业务引用派生幂等 eventId），worker 分批排空并交付到事件库；失败只累计重试，不阻塞也不回滚业务写入。待投递与失败记录不会被保留期任务清理。
• 归因窗口 30 分钟：转化回溯同一访客同一会话内最近一次内容浏览，把内容/栏目/作者/形态/修订/发布版本记为 origin* 属性，并补齐同会话的搜索点击关键词；无法建立来源的转化保留为未归因，而不是丢弃。
• 转化事件使用服务端时间，因此不受浏览器时钟影响；下载只统计成功交付的响应。
• 「互动与转化」视图对外展示的名字与采集事件不是一一对应：cms.page_view 展示为「页面入口」、cms.component_click 展示为「专题按钮」、cms.download_delivered 展示为「资料下载」，事件库中不另存别名。

指标与维度

统计接口（均带 siteId，执行站点与栏目数据范围校验）：

接口	内容
GET /api/cms/stats/overview	概览：区间指标、对比周期、连续趋势
GET /api/cms/stats/report	分页报告：按维度分组的指标行 + 排序
GET /api/cms/stats/quality	采集质量：配置状态、接收/拒收/重复、延迟、待投递
GET /api/cms/stats/options	当前范围内的内容 / 栏目 / 作者 / 发布版本筛选项
GET /api/cms/stats/visits	访问概览视图：今日/昨日卡片、PV·UV 趋势、内容 TOP、来源与设备分布
GET /api/cms/stats/search	搜索分析视图：搜索量趋势、热搜词、无结果词榜

指标：PV / UV / 会话 / 新访客 / 回访访客 / 有效阅读数与阅读率 / 活跃时长（总与均值）/ 平均阅读深度 / 参与会话与参与率 / 跳出率 / 转化数与转化访客、转化率 / 搜索数、无结果搜索数、关键词数与无结果关键词数、搜索点击数、搜索点击率 / 下载点击与交付 / 表单开始、错误、完成 / 投票、评论、关注 / 版位曝光、点击与点击率 / 媒体开始与 25·50·75·100% 里程碑、媒体错误。

口径：

• 会话：同站点 30 分钟无活动开启新会话；参与会话 = 活跃 ≥ 10 秒、或达成阅读、或发生转化、或浏览 ≥ 2 页
• UV 在整个区间去重，不累加每日值；趋势按站点统计时区的自然日/小时补齐空缺分桶
• 爬虫（设备类型 bot）与预览流量从不进入指标

维度（CMS_STAT_DIMENSIONS）：内容、栏目、作者、内容形态、发布版本、入口来源、入口路径、来源域名、UTM（来源/媒介/活动/关键词/内容）、设备、浏览器、操作系统、国家/地区，以及行为维度：搜索、媒体、版位、表单、互动。

查询参数：统计时区（站点默认值，可临时切换）、days（1–90）、显式 startTime/endTime（区间上限 90 天）、粒度 day / hour、对比 previous_period / previous_year / none，以及内容、栏目、发布版本、部署、作者、形态、来源、设备筛选。概览返回的 watermark 是本次统计快照上界，翻页与导出应复用它，保证同一快照内数据一致。

后台页面

「访问统计」页按六个 Tab 组织，共用站点切换器与筛选条（站点统计时区决定自然日与分桶）：

Tab	内容
总览	指标卡（对比周期）、流量与有效参与趋势、受众分布（设备 / 浏览器 / 操作系统 / 国家）
内容	按内容、栏目、作者、形态、发布版本分组的内容效果明细，可下钻
来源与入口	会话来源与入口：入口来源/路径、来源域名、UTM（来源固定为会话首次入口，后续跳转不覆盖）
搜索	搜索次数、独立搜索词、无结果率、搜索点击与点击率，以及搜索需求→后续阅读/转化的明细
互动与转化	入口转化归因：cms.entry / cms.read / cms.topic_click / cms.download / cms.form_complete / cms.vote_complete 计数与访客数，以及按内容 × 发布版本的旅程明细
采集质量	采集状态（未启用 / 待发布 / 采集中 / 无数据 / 需关注）、配置与线上生效配置差异、接收·拒收·重复、事件类型分布、延迟 P95、待投递与失败转化、缺页面/缺访客事件

采集设置（PUT /api/cms/telemetry/{id}，权限 cms:site:update）只有两项：启用访问采集与站点统计时区。保存写回站点配置后，需发布站点配置才会进入线上页面，因此质量 Tab 会显示 pending_publication 直到新配置随发布单激活。stats/visits 与 stats/search 两个概览视图、“数据看板”的累计浏览量均读取同一批事实。

数据保留

数据	保留
user_events 中 CMS v2 可信事件	至少 400 天（支持同比对比），其余事件沿用数据分析租户策略
cms_telemetry_receipts	默认 90 天
cms_telemetry_outbox	已投递记录默认 90 天；待投递与失败记录保留以便重试

保留策略在「系统运维 → 数据保留」中按模块维护，data-retention 周期任务按批清理。