# 指标与维度

指标定义版本：`metrics-2026.09.1`。机器可读版本：[/api/v1/schema/metrics](/api/v1/schema/metrics)、[/api/v1/schema/dimensions](/api/v1/schema/dimensions)。

## 重要口径

- 每日 UV 不可相加为月 UV；各站 UV 相加只能称“各站 UV 合计”。
- 跳出率 = 已结算会话中单 PV 会话占比；未结算会话不进入分母。
- 收入以最小货币单位整数保存并按币种分列，不同币种不相加。
- 数值不可用时返回 `null` 并在 `meta.quality_by_metric` 说明原因（例如 PRIVACY_RESTRICTED、NOT_COLLECTED、OUTSIDE_RETENTION），不用 0 代替。
- 时间区间为 [start, end)，按 IANA 时区切日，正确处理夏令时与半小时时区。

## 指标

| id | 名称 | 数据集 | 单位 | 可加性 | 去重范围 | 隐私前提 | 权限 |
|---|---|---|---|---|---|---|---|
| `request_count` | HTTP 请求数 | http_requests | count | additive | workspace_id+site_id+event_id | none | summary:read |
| `human_likely_requests` | 疑似真人请求数 | http_requests | count | additive | workspace_id+site_id+event_id | none | summary:read |
| `ai_verified_requests` | 已验证 AI 请求数 | http_requests | count | additive | workspace_id+site_id+event_id | none | summary:read |
| `ai_claimed_requests` | 自称 AI 请求数（未验证） | http_requests | count | additive | workspace_id+site_id+event_id | none | summary:read |
| `other_automation_requests` | 其他自动化请求数 | http_requests | count | additive | workspace_id+site_id+event_id | none | summary:read |
| `unknown_requests` | 未知主体请求数 | http_requests | count | additive | workspace_id+site_id+event_id | none | summary:read |
| `ai_requests_combined` | AI 请求数（已验证+自称，合并口径） | http_requests | count | additive | workspace_id+site_id+event_id | none | summary:read |
| `error_requests` | 错误请求数（4xx/5xx） | http_requests | count | additive | workspace_id+site_id+event_id | none | summary:read |
| `redirect_requests` | 重定向请求数（3xx） | http_requests | count | additive | workspace_id+site_id+event_id | none | summary:read |
| `unique_paths` | 不同路径数 | http_requests | count | non_additive | range | none | summary:read |
| `page_views` | 页面浏览量（PV） | browser_events | count | additive | workspace_id+site_id+event_id | none | summary:read |
| `unique_visitors` | 独立访客（UV） | browser_events | count | non_additive | site+range | consented_mode | summary:read |
| `custom_events` | 自定义事件数 | browser_events | count | additive | workspace_id+site_id+event_id | none | summary:read |
| `clicks` | 区域点击数 | browser_events | count | additive | workspace_id+site_id+event_id | none | summary:read |
| `downloads` | 下载次数 | browser_events | count | additive | workspace_id+site_id+event_id | none | summary:read |
| `outbound_clicks` | 外链点击次数 | browser_events | count | additive | workspace_id+site_id+event_id | none | summary:read |
| `site_searches` | 站内搜索次数 | browser_events | count | additive | workspace_id+site_id+event_id | none | summary:read |
| `engaged_time_ms` | 有效停留时长合计（毫秒） | browser_events | ms | additive | workspace_id+site_id+event_id | none | summary:read |
| `avg_engaged_time_ms` | 平均有效停留（毫秒/PV） | browser_events | ms | ratio | range | none | summary:read |
| `avg_scroll_depth` | 平均最大滚动深度（%） | browser_events | percent | ratio | range | none | summary:read |
| `sessions` | 会话数 | sessions | count | additive | workspace_id+site_id+session_id | consented_mode | summary:read |
| `single_page_sessions` | 单页会话数 | sessions | count | additive | workspace_id+site_id+session_id | consented_mode | summary:read |
| `settled_sessions` | 已结束会话数（跳出率分母） | sessions | count | additive | workspace_id+site_id+session_id | consented_mode | summary:read |
| `bounce_rate` | 跳出率 | sessions | ratio | ratio | range | consented_mode | summary:read |
| `avg_session_duration_ms` | 平均会话时长（毫秒） | sessions | ms | ratio | range | consented_mode | summary:read |
| `pageviews_per_session` | 平均访问深度（PV/会话） | sessions | ratio | ratio | range | consented_mode | summary:read |
| `ai_referral_sessions` | AI 引荐会话数 | sessions | count | additive | workspace_id+site_id+session_id | consented_mode | summary:read |
| `session_visitors` | 会话访客数 | sessions | count | non_additive | site+range | consented_mode | summary:read |
| `conversions` | 转化次数 | conversions | count | additive | workspace_id+site_id+dedupe_key | none | conversions:read |
| `revenue_minor` | 收入（最小货币单位） | conversions | minor_currency | additive_per_currency | workspace_id+site_id+dedupe_key | none | revenue:read |

## 计算方式

- **request_count**：去重后（工作区+网站+event_id）当前可观测范围内的 HTTP 事件数量（不等于：页面浏览量(PV)；图片/接口/CSS/重定向请求都计入 HTTP 请求但不计入 PV）
- **human_likely_requests**：actor_class = 'human_likely' 的去重 HTTP 事件数
- **ai_verified_requests**：actor_class = 'ai_verified' 的去重 HTTP 事件数
- **ai_claimed_requests**：actor_class = 'ai_claimed' 的去重 HTTP 事件数
- **other_automation_requests**：actor_class = 'other_automation' 的去重 HTTP 事件数
- **unknown_requests**：actor_class = 'unknown' 的去重 HTTP 事件数
- **ai_requests_combined**：ai_verified 与 ai_claimed 之和。合并口径：包含未经验证的自称请求，展示时必须标注（不等于：训练次数、AI 回答引用次数或模型收录量（日志无法得知））
- **error_requests**：status >= 400 的去重 HTTP 事件数
- **redirect_requests**：300 <= status < 400 的去重 HTTP 事件数
- **unique_paths**：范围内 COUNT(DISTINCT path)，不可跨时间桶相加
- **page_views**：去重 browser page_view 事件数；图片、接口、CSS、重定向请求不算 PV
- **unique_visitors**：范围内站点级可观测访客标识 COUNT(DISTINCT visitor_id)。不等于自然人数；每日 UV 不可相加为月 UV；各站 UV 相加只能叫“各站 UV 合计”（不等于：自然人数、IP 数、跨站独立人数）
- **custom_events**：event_type = 'custom_event' 的去重浏览器事件数
- **clicks**：event_type = 'click' 的去重浏览器事件数
- **downloads**：event_type = 'download' 的去重浏览器事件数
- **outbound_clicks**：event_type = 'outbound_click' 的去重浏览器事件数
- **site_searches**：event_type = 'site_search' 的去重浏览器事件数
- **engaged_time_ms**：page_engagement 事件上报的“页面可见且有活动”区间之和；单次心跳间隔封顶 60 秒；隐藏页面不累计
- **avg_engaged_time_ms**：engaged_time_ms / page_views（PV 为 0 时为 null）
- **avg_scroll_depth**：page_engagement 事件最大滚动深度的平均值
- **sessions**：按 session_id 划分（SDK 以 30 分钟无活动切分会话）；跨午夜的会话归属开始时间所在的桶；迟到事件会重算所属会话
- **single_page_sessions**：已结束（最后活动超过 30 分钟）且仅 1 个 PV 的会话数
- **settled_sessions**：最后活动距数据时间点超过 30 分钟且至少 1 个 PV 的会话
- **bounce_rate**：single_page_sessions / settled_sessions；未结束会话不进入分母；分母为 0 时为 null
- **avg_session_duration_ms**：已结束会话 (last_activity - started_at) 的平均值
- **pageviews_per_session**：会话 PV 合计 / 会话数
- **ai_referral_sessions**：会话入口来源精确匹配已维护的 AI 平台来源域名（channel=ai_referral）；与 AI 抓取无关（不等于：AI 抓取请求数、AI 回答引用次数）
- **session_visitors**：会话中 COUNT(DISTINCT visitor_id)；不可跨桶相加
- **conversions**：按 (工作区, 网站, 去重键=订单号或事件 ID) 去重后的转化数；订单重放不重复计
- **revenue_minor**：明确业务事件或导入的整数最小货币单位之和，必须按 currency 分组；多币种不直接相加

## 维度

| id | 名称 | 数据集 | 高基数 | 隐私前提 |
|---|---|---|---|---|
| `site_id` | 网站 | http_requests, browser_events, sessions, conversions | 否 | none |
| `time_minute` | 分钟 | http_requests, browser_events, sessions, conversions | 否 | none |
| `time_hour` | 小时 | http_requests, browser_events, sessions, conversions | 否 | none |
| `time_day` | 日 | http_requests, browser_events, sessions, conversions | 否 | none |
| `time_week` | 周（周一开始） | http_requests, browser_events, sessions, conversions | 否 | none |
| `time_month` | 月 | http_requests, browser_events, sessions, conversions | 否 | none |
| `actor_class` | 主体分类 | http_requests, browser_events, sessions | 否 | none |
| `provider` | AI/机器人提供方 | http_requests | 否 | none |
| `client_name` | 客户端名称 | http_requests | 否 | none |
| `declared_purpose` | 声明用途 | http_requests | 否 | none |
| `verification_status` | 验证状态 | http_requests | 否 | none |
| `automation_subtype` | 自动化子类 | http_requests | 否 | none |
| `status_code` | 状态码 | http_requests | 否 | none |
| `status_class` | 状态码分类 | http_requests | 否 | none |
| `resource_type` | 资源类型 | http_requests | 否 | none |
| `method` | 请求方法 | http_requests | 否 | none |
| `host` | 主机 | http_requests | 否 | none |
| `path` | 路径 | http_requests, browser_events | 是 | none |
| `collection_source` | 采集来源 | http_requests, conversions | 否 | none |
| `trust_level` | 信任等级 | http_requests | 否 | none |
| `country` | 国家/地区 | http_requests, browser_events, sessions | 否 | none |
| `asn` | ASN | http_requests | 是 | none |
| `browser` | 浏览器 | http_requests, browser_events, sessions | 否 | none |
| `os` | 操作系统 | http_requests, browser_events, sessions | 否 | none |
| `device_type` | 设备类型 | http_requests, browser_events, sessions | 否 | none |
| `language` | 语言 | browser_events | 否 | none |
| `title` | 页面标题 | browser_events | 是 | none |
| `page_group` | 页面分组 | browser_events | 否 | none |
| `referrer_host` | 来源域名 | browser_events, sessions | 否 | none |
| `channel` | 来源渠道 | browser_events, sessions, conversions | 否 | none |
| `source_name` | 来源名称 | browser_events, sessions | 否 | none |
| `search_term` | 搜索词 | browser_events | 是 | none |
| `utm_source` | UTM 来源 | browser_events, sessions, conversions | 否 | none |
| `utm_medium` | UTM 媒介 | browser_events, sessions, conversions | 否 | none |
| `utm_campaign` | UTM 活动 | browser_events, sessions, conversions | 否 | none |
| `utm_term` | UTM 关键词 | browser_events, sessions | 否 | none |
| `utm_content` | UTM 内容 | browser_events, sessions | 否 | none |
| `event_type` | 事件类型 | browser_events | 否 | none |
| `event_name` | 事件名称/类别 | browser_events | 否 | none |
| `event_action` | 事件操作 | browser_events | 否 | none |
| `event_label` | 事件标签 | browser_events | 是 | none |
| `region` | 点击区域 | browser_events | 否 | none |
| `target_host` | 目标域名（下载/外链） | browser_events | 否 | none |
| `entry_path` | 入口页 | sessions | 是 | none |
| `exit_path` | 出口页 | sessions | 是 | none |
| `visitor_type` | 新老访客 | sessions | 否 | consented_mode |
| `depth_bucket` | 访问深度 | sessions | 否 | none |
| `ai_provider` | AI 引荐平台 | sessions | 否 | none |
| `goal` | 目标 | conversions | 否 | none |
| `currency` | 币种 | conversions | 否 | none |