访客统计 API
本模块所有接口均要求管理员登录鉴权,时间字段统一返回 UTC ISO-8601 字符串。
获取访客详情
返回完整访客画像、关联用户摘要、行为累计统计、关联订单摘要,以及最多 100 条最近事件。接口不会返回履约密钥、支付凭证或支付原始响应等敏感数据。
接口地址: GET /api/admin/stats/visitors/:visitor_id
路径参数:
visitor_id(必填):保存在visitor_idCookie 和访客统计表中的完整访客 ID。
响应示例:
{
"profile": {
"visitorId": "0d47f9aa-78a3-45c1-80d1-2d0e348923a7",
"userId": 42,
"ip": "203.0.113.10",
"firstSourceType": "campaign",
"firstSource": "google",
"firstMedium": "cpc",
"firstCampaign": "summer-launch",
"country": "CN",
"region": "上海",
"city": "上海",
"deviceType": "mobile",
"browser": "Chrome",
"os": "Android",
"firstSeenAt": "2026-07-28T08:00:00.000Z",
"lastSeenAt": "2026-07-28T09:30:00.000Z"
},
"user": {
"id": 42,
"email": "buyer@example.com",
"nickname": "买家",
"status": 1,
"createdAt": "2026-07-28T08:15:00.000Z"
},
"stats": {
"totalEvents": 18,
"pageViews": 10,
"productViews": 4,
"checkouts": 2,
"paid": 1,
"auth": 1,
"orders": 2
},
"orders": [
{
"id": "OT20260728123456ABCD",
"amount": 99,
"currency": "CNY",
"productId": 3,
"productName": "专业版套餐",
"payStatus": "paid",
"status": "active",
"createdAt": "2026-07-28T09:00:00.000Z",
"paidAt": "2026-07-28T09:02:00.000Z"
}
],
"recentEvents": [
{
"id": 120,
"eventName": "order_paid",
"path": "/payment/OT20260728123456ABCD",
"source": "google",
"medium": "cpc",
"campaign": "summer-launch",
"orderId": "OT20260728123456ABCD",
"productId": 3,
"productName": "专业版套餐",
"createdAt": "2026-07-28T09:02:00.000Z"
}
],
"recentEventsLimit": 100
}
错误响应:
400:访客 ID 无效或长度超限。404:访客画像不存在。
获取 IP 详情
返回指定统计时间范围内某个 IP 分组的聚合信息,包括全部匹配的访客身份、关联用户摘要、观测到的地域/设备环境,以及最多 100 条最近事件。
接口地址: GET /api/admin/stats/ip-details
查询参数:
ip:需要查看的 IP 地址;未传local=1时必填。local:设为1时查看无法获取 IP(NULL)的事件。preset:统计时间范围(today、yesterday、7d、30d或90d)。days:兼容自定义时间范围时使用的天数。
响应示例:
{
"ip": "203.0.113.10",
"range": { "preset": "today", "days": 1 },
"stats": {
"totalEvents": 32,
"uniqueVisitors": 3,
"registeredUsers": 1,
"pageViews": 20,
"productViews": 6,
"checkouts": 2,
"paid": 1,
"auth": 1,
"firstSeenAt": "2026-07-28T08:00:00.000Z",
"lastSeenAt": "2026-07-28T10:00:00.000Z"
},
"visitors": [
{
"visitorId": "0d47f9aa-78a3-45c1-80d1-2d0e348923a7",
"eventCount": 18,
"firstTouch": "google",
"user": { "id": 42, "email": "buyer@example.com" }
}
],
"visitorLimit": 100,
"contexts": [],
"recentEvents": [],
"recentEventsLimit": 100
}
错误响应:
400:IP 地址无效或长度超限。
统计概览与访问来源归因
接口地址: GET /api/admin/stats
报表依据配置时区内所选半开区间 [from, to) 的事件与订单事实,禁止用可变的访客画像 lastSeenAt 筛选历史活跃人群。range 时间统一输出 UTC ISO。
查询参数:
preset:today、yesterday、7d、30d或90d。预设本身决定天数,无需另外传days。days:没有已识别预设时使用的自定义天数,范围 1–90。
指标口径:
uniqueVisitors:期间内有页面、商品、结账、认证行为或关联成功订单的浏览器visitor_id去重数。包含仅有支付活动的身份,不等于真实人数或会话数。pageViewVisitors:期间有page_view的身份数;pageViews是页面事件次数。authVisitors / loginVisitors / registerVisitors:期间实际认证事件数对应的去重访客,不使用当前画像的登录或注册状态。新增认证事件由服务端记录。paidVisitors:按orders.paidAt选取期间内当前仍为paid的真实非零订单,再按已关联访客去重。浏览器order_paid事件不构成支付事实。paidOrders:真实非零已付款订单数,包含无访客 ID 的订单。零元已付款订单单列为freeOrders。conversionRate:paidVisitors / uniqueVisitors * 100;各来源行按该行的去重访客计算,不能用订单数除以访客数。revenue:通过共用订单币种解析器读取currencySnapshot.baseAmount/baseCurrency,只输出配置基础币种的金额。revenueByCurrency保留不同记账币种的独立汇总,不混加币种;旧订单没有快照时保留自己的实付币种分桶。- 没有
paidAt的历史成功订单不进入期间指标,不用创建时间代替支付时间,需要单独核查。 unattributedPaidOrders / unattributedRevenueByCurrency:没有visitorId的已付款订单。金额保留在总额中,不猜测来源归属。uniqueIps:原始事件的 IP 分组数,缺失 IP 单列一组;IP 排查与营销归因是不同口径。overview.comparisons:针对三项核心流量指标(pageViews、uniqueVisitors、uniqueIps)的同比/环比数据,每项包含{ current, previous, delta, deltaPercent, trend, fullDay?, predictedFullDay? }:today(mode: 'yesterday_same_time'):按配置时区对比「今日 00:00 至当前时刻」与「昨日同期(昨日 00:00 至昨日同一时刻)」,避免白天未满 24 小时导致涨跌幅失真,同时额外返回fullDay(昨日全天总量)与predictedFullDay(按昨日全天基数与今日相对昨日同期的增降倍率预估的今日全天总量,且不低于今日已发生值)供卡片参照。yesterday(mode: 'day_before_yesterday'):对比昨日全天与前日全天。7d / 30d / 90d(mode: 'previous_period'):对比前一个同跨度周期。
funnel:为兼容保留的响应字段,内容是各类行为的独立人数,不是按顺序、同批人验证的漏斗。页面显示为行为分布。
归因范围:
firstTouch:本期间活跃身份最初进入网站的获客来源,使用不可变首访信息(firstSource与firstReferrer在首次建档时冻结,后续回访的外部引荐不会补写篡改历史首次来源)。当前画像的地域、关联用户或末次来源不能决定历史活动。lastTouch:仅从本期间页面或商品入口提取最近可识别来源。站内导航不覆盖已识别来源;本期间没有证据时显示“直接 / 来源不可识别”,不能拿后来更新的画像补猜。categories:本期间lastTouch的渠道;external是其中非直接来源,包含带标签的活动。独立的externalVisitors卡片仅统计实际观测到外部引荐域名的访客,因此可能与external来源列表人数不同。geoConversions:与GET /api/admin/settings/seo-telemetry共享的「国家/地区 × AI/自然搜索渠道」交叉转化统计(buildVisitorGeoConversions)。转化率(conversionRate / aiConversionRate / searchConversionRate)统一按去重付款访客(paidVisitors / totalVisitors)计算,收入与客单价按记账币种分桶(revenueByCurrency / aovByCurrency),不跨币种相加。- 来源商业指标表示这些访客身份在期间内关联的订单,尚未使用每笔订单冻结的归因快照。来源
checkouts是发起结账的访客数;paid是paidVisitors的兼容别名,不是订单数。
来源渠道(sourceType):
direct:没有可识别的站外或活动证据;页面显示“直接 / 来源不可识别”。search / social / ai / email / referral:已识别引荐来源;明确的 UTM medium(如organic、social、organic_social、ai_referral、email、referral)进入对应渠道。campaign:广告点击 ID(gclid / wbraid / gbraid / ttclid / msclkid / twclid)或其他带标签的营销流量。UTM 活动名本身不表示付费广告;仅有fbclid归为 Facebook 社交流量,不能确定是付费活动。affiliate:明确的 affiliate medium 或支持的推广参数(invite / inv / promo / agent / ref / aff)。通用code也用于认证链接,不纳入推广识别。结佣关系仍独立于营销渠道分类。
UTM 优先于引荐域名推断;带标签但缺少 utm_source 时来源为 unknown,不能显示 Direct。未知引荐域名保留完整规范化主机名。搜索关键词(term)优先从落地页 utm_term、外部引荐 URL 的查询参数(如 q / wd / word / query / keyword / kw / p / text)以及带标签流量的搜索词参数中提取,站内纯搜索不构成外部获客。新来源的 source/medium/campaign/content/term 整组替换,同来源刷新或站内导航保留已捕获的外部引荐地址与搜索词。
来源行示例:
{
"key": "[\"social\",\"Telegram\",\"social\",\"launch\"]",
"label": "Telegram · social · launch",
"sourceType": "social",
"source": "Telegram",
"medium": "social",
"campaign": "launch",
"terms": ["tg-keyword"],
"referrers": ["https://t.me/apay_channel/42"],
"count": 20,
"visitors": 20,
"checkouts": 4,
"paid": 2,
"paidVisitors": 2,
"paidOrders": 3,
"revenue": 30,
"currency": "USD",
"revenueByCurrency": [{ "currency": "USD", "amount": 30 }],
"conversionRate": 10,
"percentage": 25
}
响应还包含 hourlyTrend(单日 days === 1 如 today / yesterday 时按配置时区返回 24 小时 UV/PV 分时趋势点,与按日 trend 并存)、topPages(热门受访页面排行,含 views / visitors / percentage)、topLandingPages(热门入口落地页排行,含 visitors / views / percentage)、browsers、operatingSystems、timezone / currency / attributionVersion: 1 / generatedAt。来源列表完整返回,不静默截掉低流量来源。
访客列表与来源明细
接口地址: GET /api/admin/stats/visitors
使用相同 preset / days,另支持 page(默认 1)、pageSize(1–100,默认 20)及:
attribution:first或last,默认last。sourceKey:来源行的精确key,作为查询参数进行 URL 编码;与点击列表的归因范围一同传递。分类行改用sourceType。sourceType:渠道、实际观测到外部引荐的external,或期间含活动 / 推广标签的tagged。type:page_view / product_view / begin_checkout / order_paid / auth。付款筛选读取真实非零已付款订单;事件与来源筛选取交集。source:兼容的来源 / 标签精确匹配。新客户端使用sourceKey,展示文案不能充当稳定标识,也不再做模糊包含匹配。search:可选关键词搜索,支持匹配visitorId、ip、country / region / city、deviceType / browser / os、landingPath / lastPath、firstReferrer / lastReferrer、来源与活动名称、搜索关键词(term)与内容标识(content),以及关联注册用户的email / nickname。
汇总与明细共用同一访客集合和来源解析器;pagination.totalItems 与点击来源的 count 一致。响应同时返回 summary(本期间 totalVisitors / pageViewVisitors / productVisitors / checkoutVisitors / paidVisitors / authVisitors / externalVisitors / campaignVisitors 汇总数)。明细行返回 firstSourceKey / lastSourceKey、source/medium/campaign/content/term(含 firstTerm / lastTerm / firstContent / lastContent)、外部来源链接 firstReferrer / lastReferrer、站内 landingPath / lastPath、country / region / city、deviceType / browser / os、ISO 时间和期间行为次数;明细 paid / paidOrders 表示真实非零已付款订单数。单个访客的生命周期详情是独立接口,其中 stats.paid 读取真实关联已付款订单。IP 详情使用期间来源,付款数表示该 IP 观测到的身份关联的期间已付款订单;同一身份可出现在多个 IP 下。
后台提供访客统计子页 /admin/stats/visitors(别名 /admin/visitors,不新增侧边栏菜单项,页头支持一键返回 /admin/stats),通过顶部 Tab 统一承载「独立访客(visitors) / 页面浏览(pageVisits) / 独立IP(ips)」三类明细视图(支持 ?tab=visitors|pageVisits|ips),共享时间范围与关键词搜索(GET /api/admin/stats/visitors、GET /api/admin/stats/page-visits、GET /api/admin/stats/events 均支持 search 参数),并展示可点击打开的外部来源地址、可点击访问的站内受访页面、完整国家省市地区以及设备浏览器信息;在 /admin/stats 统计概览页点击任意概览卡片或来源行均直接携带对应 Tab 与筛选参数跳转到该子页面。加载中、成功但无记录、请求失败分别显示;失败时提供重试入口,不显示成空表或零条分页。汇总请求失败也显示重试入口,不展示成全零图表。
公共页面埋点
接口地址: POST /api/analytics/track
仅接受 page_view / product_view,要求前端相对路径 path,可选 referrer 和正整数 productId。后台 / API 路径和浏览器提交的 auth / begin_checkout / order_paid 返回 400。用户身份从服务端会话读取,客户端不能提交认证或订单事实。
显式空 document referrer 保持为空,不回退成埋点 POST 请求自身的 Referer。SPA 导航传递上一页面作为引荐;mounted / finished 对同次导航去重,15 秒内真实回访仍计数。sendBeacon 无法排队时回退 keepalive fetch。
登录、结账及支付事件继承已有获客信息,不能改写来源。前端 /callback/** 页面(含语言前缀)仍计入访问行为,但不作为获客入口,避免支付平台覆盖原始来源。埋点失败记录告警并返回 success: false,不会中断认证、下单或履约。
后台首页口径对齐
GET /api/admin/dashboard?range=today|7d|30d 使用相同访客集合,转化率为 periodPaidVisitors / periodVisitors。periodRevenue / periodRevenueByCurrency / periodPaidOrders 及收入趋势点读取本期间支付的非零订单,包含之前创建的订单;periodOrders 和订单趋势点统计本期间创建的全部订单。除 chart.revenue 与 chart.orders 外,chart 同步返回相同时间桶(today 24 小时 / 7d / 30d)的 visitors(UV)与 pageViews(PV)趋势序列,并通过 trafficInsights 返回本期间流量来源分布(sources、topSources)、热门受访页面(topPages)、国家地区与设备占比(topCountries、devices)及最新活跃访客(recentVisitors),使无交易/非售卖站点自动切换展示流量走势与访客动态而不再留空。stats 同步返回用户增长与活跃指标(periodNewUsers、periodLoginVisitors、periodExternalVisitors、activeNewsletterSubscribers、totalPromoInvites、isCommerceActive),actionItems 补充通用运营待办与近 24 小时系统健康预警计数(pendingComments、pendingPromoApplications、failedEmails24h、errorLogs24h、paymentFailures24h)。期间按配置时区计算,包含当天,截止于请求时刻。全站 totalRevenue 保留现有全部已付款订单口径。
访客日汇总(统计读路径)
GET /api/admin/stats、GET /api/admin/dashboard、GET /api/admin/stats/visitors、GET /api/admin/stats/ip-details 与 GET /api/admin/settings/seo-telemetry(地理转化)默认读取访客日汇总,单次请求开销与所选天数无关;原始事件明细接口(stats/events、stats/page-visits、stats/visitors/:visitor_id)仍查原始事件。
数据与口径:
- 三张核心表:
visitor_rollup_days(每天一行的指针、口径版本、时区、本站域名与去重哈希集合)、visitor_day_facts(每访客每天一行)、visitor_daily_stats(每天 × 维度 × 维度值)。只沉淀不可变的访问事件事实;订单金额与状态每次请求实时读取,退款立即反映。 - 某一天的汇总由现有单日报表逻辑计算,单日报表与实时计算逐字段一致(守卫强制)。日期按
settings.timezone划分。 - 多日范围:
overview的 UV、独立 IP 与各行为人数用每日 32 位哈希集合合并去重(碰撞误差约 n/2³³,90 万访客约 0.01%,只会略少);趋势、漏斗、对比期与实时一致。来源 / 国家 / 设备 / 页面 / 落地页等**维度人数按「访客·天」**计(同一访客在 N 天出现计 N 次),末次来源按当天计算,订单归到付款当天该访客的记录,付费人数同样按访客·天计;百分比分母为访客·天总数。多日维度因此等于各日报表之和。 - 访客明细的每行是一位访客在某一天的记录(新增
statDate字段),pagination.totalItems与概览中来源count一致;多日范围下summary.totalVisitors为访客·天总数。 - 汇总后访客行集合固定:仅因订单成行的访客,订单后来退款时不再从当天访客数中消失(付款数与收入照常实时回落)。
- 「今日」汇总按需刷新,最多滞后 60 秒(
APAY_VISITOR_STATS_TODAY_REFRESH_SECONDS可调);日结束 5 分钟后定稿。「昨日同时段」对比仍实时查询昨天前半天。 - 响应新增
rollup字段:source(rollup/raw)、complete、pendingDays(本次时间预算内尚未生成的日期,这些天暂缺)、staleDays(口径已过期但原始事件已清理、无法重算而保留旧结果的日期)。后台首页在trafficInsights.rollup返回同样信息。
生成与维护:
- 请求时按需补算,每次请求的计算时间预算约 1.5 秒,超出部分进入
pendingDays。 - 定时任务
POST /api/cron/visitor-stats-rollup(CRON_SECRETBearer 鉴权)回填缺失日并按保留期分天清理:在/admin/scheduler登记为hourly并开启useCronSecret。 - 后台重建
POST /api/admin/stats/rollup,body{ from, to, force? }(YYYY-MM-DD,每次最多 31 天,超出部分在remainingDays返回);force只重算原始事件仍完整保留的日期,其余进入skippedDays。 - 修改时区、本站域名或计算口径版本后,保留期内的日期按需重算;原始事件已清理的日期保留旧结果并标为
staleDays。 - 本站域名优先取
settings.site_url,其次NUXT_PUBLIC_SITE_URL,再次后台请求域名;都无法确定时回退实时计算(定时任务返回 409)。 - 保留期:
settings.visitor_events_retention_days(原始事件,默认 90 天,0关闭)与settings.visitor_day_facts_retention_days(访客日事实,默认 180 天);visitor_daily_stats永久保留。原始事件只删除已最终汇总的日期,遇到未汇总日期即停止;手动清理接口POST /api/admin/stats/cleanup同样会先汇总,返回新增的requestedCutoff / limitedByRollup。已清理到的时间点记录在settings.visitor_events_cleaned_before。 APAY_VISITOR_STATS_ROLLUP=off时全部回退为实时逐访客计算(排障用;长范围的内存与耗时风险随之恢复)。
兼容、保留与验证
以上口径取代旧描述中的“站内导航属于新直接获客”“所有 UTM 都是付费投放”“来源 paid 是订单数”;旧描述仅属于历史,不能作为现行 API 规格。新增服务端事件限制不能证明旧客户端认证事件的真实性。
本批不迁移 Schema、不改订单状态、不改结佣、不改写历史数据;代码回滚恢复旧读取 / 捕获逻辑,不删数据。期间前的来源证据和已清理事件无法完全还原。金额当前读取仍处于 paid 状态的订单,退款会改变总额;按退款时间报告、净收入和不可变财务口径需要独立支付 / 退款台账。本报表不承担不可变财务流水职责。
统计读路径已切换为访客日汇总(见上一节);APAY_VISITOR_STATS_ROLLUP=off 的回退路径仍在应用内存读取期间事件。会话模型、矩阵来源配置、30 天归因窗口、订单冻结快照、主题事件覆盖和真正的顺序漏斗留待后续实现。
运行 npm run check:visitor-analytics,也已接入 prebuild。守卫使用临时 SQLite 执行真实接口,检查币种 / 时间 / 来源明细一致性、失败隔离、三方言 SQL 条件编码、SPA 埋点行为和 Vue 编译;还执行实际页面 setup,验证来源弹层的请求、加载、重试及重新打开。真实流量与支付网关仍需独立上线验证。