Sovi.AI UA Command Center

placeholder

—

placeholder

—

placeholder

—

placeholder

—

placeholder

—

placeholder

—

placeholder

—

placeholder

—

Spend / Install / CPI Trend

loading

—

Data Quality

—

Channel Performance

—

AI Daily Brief

—

Data Anomalies

—

Today Action Queue

—

Data Sources: BigQuery AppsFlyer Push (Primary) + Platform API (Cost). Incomplete days do not participate in budget decisions.

BQ 24h scan: —

iOS / Android UA Daily Report

HKT natural day; AF installs are authoritative. Allocated country cost is explicitly labelled.

Client Detail view

—

Country template matching Feishu

AF paid installs and ad conversions are separate; First-day photo (camera_photo_confirm_click) and First-day solve (solve_finalizing_show) are shown side-by-side. Hover over ℹ️ in the table header for underlying event definitions.

—

GPT Report Analysis & Recommendations

gpt-5.6-sol · high

—

Channel totals

—

Country / region detail

—

Metric basis and Obsidian preview

Obsidian Markdown

—

Channel Matrix

—

Google Ads Account Performance

—

Country × Channel Matrix

—

Campaign Performance

—

Creative Performance

—

ASA Keyword Performance

ASA keyword/search-term report waiting on ASA API credentials + fact_asa_keyword_daily. Scheduled for P1.

Google W2A Keyword Performance

—

Channel New Users

—

Module penetration

Main event UV / platform UV

—

Macro trend

PV · UV · Sessions

—

Adoption bands

Main event signal

—

Interaction preference

Feature usage share / platform UV

—

Module Key Funnels

User journey & step conversion rates

—

Daily module report

PV · UV · penetration

—

User Quality

Real AppsFlyer event aggregates: activation proxy, core actions, payer cohorts, and quality signals by channel.

real data

—

Core Actions by Channel

—

Cohort Revenue Proxy

—

Reviews sync automatically every four hours and reports share the inbox date range. Store APIs do not expose profile photos, so missing avatars use nickname initials. Google Play does not expose reviewer country; reports/appeals remain manual console workflows.

Written reviews

—

Average rating

—

5-star share

—

5-star reply rate

—

Low-rating share

—

Overall reply rate

—

Deep AI coverage

—

Avg response time

—

Store performance

Full 1–5 star distribution

Rating and review trend

5-star advocacy assets

5 ★

Low-rating risk topics

1–2 ★

App Store countries

Language performance

Version performance

Representative 5-star voices

AI growth brief

SEO · ASO · GEO · Product Ops

AI review operations weekly

Automatically analyzes the latest complete Monday–Sunday week against the preceding week.

Operations queues

Rating Reply status Sentiment Country Language Version Topic Analysis source Report status Sort Search reviews

Active filters

Review inbox

—

Select a review to inspect

Report workspace

manual only

Activation Quality

HKT install-cohort quality from AppsFlyer push data. First-day solve uses solve_finalizing_show and D1 retention requires app_launch, split by media source and geo.

BigQuery Live

—

By Channel

Installs / first-day solved users & rate / first-day pay users & subscribe rate / app_launch D1 retention (by first-touch media source).

—

By Channel × Geo

Media source drilled down to country — same metrics, searchable.

—

Weekly Growth Dashboard

Monday-anchored weekly reproduction of the Looker Studio Weekly-Active board. AppsFlyer Push behavior events cover iOS and allow-listed paid Android traffic; download and first-week-activation cohorts remain iOS-only because the Push install tables currently contain no Android rows.

BigQuery Live —

—

Weekly Trend

Active, downloads, retention and dormancy across the last 12 calendar weeks.

—

Monetization

Paywall funnel, purchase economics, subscription signals, and revenue by channel from AppsFlyer BigQuery events.

real data

Paywall Performance (Superwall)

Paywall opens, conversions, and A/B experiments from Superwall ClickHouse.

Superwall

Loading…

LTV & ROAS

Observed cohort revenue, current ROAS, payback status, and LTV:CAC by channel.

real data

Recovery Efficiency

Install-day cohort: ad cost vs. subscribe / paid / revenue, with CPI, CPS, CPP, RPD, expected 1-year revenue and 1-year ROAS by channel × campaign × country.

real data

—

Recovery Matrix

—

Web W2A

Proxy Web-to-App chain from Google Ads / Google W2A spend, clicks, app installs, and app-side purchase revenue.

proxy data

—

W2A Funnel Proxy

—

Google W2A Cohort Revenue

—

Ad Attribution

Resolve every registered user back to the AppsFlyer-attributed channel, campaign, ad ID and creative file. Forward lookup (ad → users) and reverse lookup (user → ad) over the last 30 days.

real data

—

Best Channel

—

Best Ad

—

Best Creative

—

Channel Leaderboard

—

Ad Leaderboard

—

Creative Leaderboard

—

Campaign Leaderboard

—

Creative Performance

—

Ad ID Performance

—

Channel → Business User IDs

Exact user-source mapping from fact_user_attribution. Open a channel to list the business user IDs acquired by that channel.

—

Reverse Lookup — User → Ad

Attributed Users

—

Ad-User Grade Cohort

Which educational segment do ad-acquired users belong to? Maps iOS ad installs from AppsFlyer BigQuery Push to the onboarding profile (grade level), and exposes per-user email, business ID and AppsFlyer ID with full filtering.

BigQuery Live

—

Grade Distribution (ad users)

—

Grade Cohort by Channel

Installs / matched / fill rate / grade counts (by first-touch channel)

—

Grade Distribution Breakdown

Aggregated by the selected dimension — grade counts and share (uses the top date range; first-touch attribution)

—

User Detail (Grade / Email / Business ID / AFID)

Per-user detail of ad-acquired users; filter by channel, grade, email and keyword

—

Aggregate

—

Worst of 8 checks

Green / 8

—

Yellow / 8

—

Red / 8

—

Check Matrix

—

Active Anomalies

—

BigQuery Cost — last 24h

—

Local registry only Actions here update the Sovi.AI incident registry only; they do not pause ads, submit appeals, or change live ASA / Google / TikTok resources. View button impact guide

Policy Incident List

—

Incident Maintenance

Platform Status Severity Delivery State Detected At Owner Next Follow-up Appeal Deadline Account ID Account Name Entity Type Entity ID Entity Name Countries/Regions

Policy Topic Rejection/Suspension Reason

Response Advice (one per line) Checklist (one per line)

Handling Notes Resolution

Response Advice

—

Advertising Automation Control

Read live Google Ads values and validate approved changes through the official validate-only API. No live delivery changes are applied.

GOOGLE VALIDATE ONLY

Production safety mode

The server forces validateOnly=true on every Google Ads mutate request. Permissions, ownership, snapshot freshness, account allowlists, and budget limits are checked without applying changes.

Latest change preview

No controlled actions yet.

Action queue

—

Language Settings

Personal API Keys

Use API keys to programmatically query marketing, attribution, and growth datasets via REST API.

—

Open Data API Quick Start & Documentation

Supports Bearer token or X-API-Key HTTP headers for authentication.

View OpenAPI Spec

📊 GET /api/v1/data/raw-metrics

Query raw daily metrics with filtering and direct CSV export.

?start_date=2026-08-01&end_date=2026-08-31&format=csv

📥 GET /api/v1/data/export

Universal dataset export for channels, countries, campaigns, and attribution.

?dataset=channels&format=csv

🚀 GET /api/cockpit & /api/daily-report

Core cockpit and daily report APIs accessible via personal API Key.

Authorization: Bearer pci_ak_...

Python Code Example:

import requests
import pandas as pd

API_KEY = "pci_ak_your_personal_key_here"
headers = {"Authorization": f"Bearer {API_KEY}"}

# 1. 读取渠道投放指标 JSON
url = "https://mysovi.ai/apps/ua-command-center/api/ua/channels?start_date=2026-08-01&end_date=2026-08-31"
res = requests.get(url, headers=headers).json()
df = pd.DataFrame(res["data"]["channels"])
print(df[["channel", "spend", "af_installs_bq", "cpi"]])

# 2. 直接下载 CSV 格式原始数据
csv_url = "https://mysovi.ai/apps/ua-command-center/api/v1/data/raw-metrics?format=csv&start_date=2026-08-01"
csv_data = requests.get(csv_url, headers=headers).text
with open("sovi_metrics.csv", "w", encoding="utf-8") as f:
    f.write(csv_data)

Data Sources

—

Connection Configuration

Fill in the required configuration for each channel. Secret fields will not be echoed; leave blank to keep current value.

It is still recommended to use Cloudflare Worker secrets in production. Saved here to D1 as a fallback for Cloudflare page configuration, used to fix missing_credentials and let sync tasks read the config.

—

AI Model

—

TikTok Business OAuth

Creative Assets in R2

Pull ad-platform creative media into Cloudflare R2 and expose stable public URLs via sovi-ua-command-center-assets.mysovi.ai.

—

Recent Audit Log

—

Add User

Gmail Address

Note: Currently all added users are granted standard access. Only @gmail.com or Google Workspace emails are supported for Google SSO login.

Users

—

System Overview

Sovi.AI UA Command Center is an automated BI system that integrates data from mainstream ad channels and attribution platforms to support daily business operations.

8 大操作说明书聚合传送门 (8 Core Guides Bento Grid)

EX

经营驾驶舱 (Cockpit)

面向管理层与增长负责人的 30 秒高管决策大盘，高度聚合核心 KPI，指导高频预算执行。

阅读说明 → 进入大盘

UA

UA 买量表现 (UA Performance)

细分渠道、国家、计划与素材维度，提供媒体自称与 MMP 归因的偏差比率，精确定位算力。

阅读说明 → 进入大盘

UQ

用户质量与激活 (User Quality)

衡量留存率、激活天数 and 核心动作转化。监控高粘性交互，防范机器或低质虚假买量。

阅读说明 → 进入大盘

MR

变现表现 (Monetization)

聚合 Superwall 漏斗、购买经济学和套餐占比。扣除渠道分成与税率，反映真实实收。

阅读说明 → 进入大盘

LV

投资回报周期 (LTV & ROAS)

观察 Cohort 财务回收周期与 LTV 拟合曲线。严格按时区归集，精确算清回本天数。

阅读说明 → 进入大盘

W2

网页跨端归因 (Web W2A)

专门对齐 H5 落地页广告花费、点击，并跨端关联 App 内的首购。对齐归因防预算漏损。

阅读说明 → 进入大盘

DQ

数据质量监控 (Data Quality)

一站式运行 8 项关键数据校验指标的健康盾。秒级感知数据断流、订单重复和金额偏差。

阅读说明 → 进入大盘

PI

政策事件与资源预警 (Policy Incidents)

说明账号、素材、关键词等资源如何通过接口只读监控，并列清 Generate Advice、Move 等按钮是否会影响线上投放。

阅读说明 → 进入页面

工具与对账百科 (KPI Reference & FAQ)

指标口径字典 (KPI Reference Manual) ▶

指标名称	数据来源	计算方法	指标意义	常规范围
Total Spend	各广告平台 API 实时回调	SUM(spend_usd)	反应实际获客花费	$1k - $20k / 天
CPI	广告平台 Cost + MMP Installs	Spend / AF BQ Installs	衡量真实平均获客价格	$2 - $6 / 安
Paywall CVR	Superwall / AppsFlyer SDK	first_purchase_users / pay_page_show_users	评估产品内付费墙转化效率	5% - 15%
ROAS (D0/D7/D30)	D1 orders net_price + daily cost	Cumulative Cohort Revenue / Cost	核心回本指标	D0: 1-3%, D30: 25-45%

🚦 数据质量状态说明 (Data Quality States) ▶

系统会在“经营驾驶舱”和“数据质量”模块中展示不同的状态标识，含义如下：

正常 (Green)

指标处于健康阈值内，无需干预。例如：归因覆盖率 > 95%。

警告 (Yellow)

指标偏离最佳范围但未造成严重断层。建议持续观察或手动定位原因。

异常 (Red)

指标严重异常，通常意味着 API Token 过期、数据流水线断流或归因发生断裂。需立即排查。

未知 (Unknown)

系统尚在等待底层数据聚合，或该指标的前置依赖条件（如对齐延时窗口）尚未就绪。

数据同步与时区标准 (Data Sync & Timezones) ▶

数据同步与聚合标准:

平台默认每天夜间/凌晨自动定时拉取各渠道的最新数据（业务日历统一对齐为香港时间 HKT / UTC+8）。

回溯机制 (Backfill): 每晚定时同步任务不仅拉取前一天，还会对过去 7 天的历史成本与归因订单流水进行全面校准重刷，抹平媒体归因延迟引起的账期偏差。

资源状态监控与按钮影响 (Resource Watch & Button Impact) ▶

可以通过接口做统一资源状态监控，建议第一阶段全部采用只读模式。系统可从 Moloco、TikTok、Meta、Google Ads、Apple Search Ads、AppsFlyer、GA4 / BigQuery 等数据源同步账号、Campaign、Ad Group、Ad、Creative、素材文件、ASA 关键词、W2A 关键词 / UTM / 落地页等对象，统一归一为在投、停投、禁用、拒登、受限、审核中、未知等状态。

AI 预警可以基于状态变化和业务异常触发：账号被封、活跃资源突然 0 消耗、高消耗计划被拒登、关键词点击或安装断崖、素材同步失败、W2A 关键词漏斗断裂、API 数据延迟、政策高危词命中等。命中后先生成 Policy Incident 或预警，不直接改平台。

页面动作	调用接口	是否影响线上平台	说明
KPI / 筛选 / 搜索 / Refresh	GET 本地查询	否	只过滤或刷新 Sovi.AI 数据。
Generate Advice	无写入	否	只在当前页面套用建议文案，不保存，不提交申诉。
Save Incident	POST / PATCH 本地事件	否	只写 D1 事件台账和审计，不调用广告平台。
Move · Appeal Ready / Resolve	PATCH 本地事件	否	只推进事件状态、跟进时间和本地投放状态字段。

查看完整 Policy Incidents 操作说明 →

常见问题咨询 (FAQ Helpdesk) ▶

1. 为什么我的账号无法登录？

系统目前仅支持通过 Google SSO 授权登录。如果您未在授权组织白名单内，请联系系统管理员 sbin 申请加入白名单。

2. 媒体自称转化数 and AppsFlyer BQ 安装数为什么总有细微差别？

媒体（如 TikTok、Facebook）使用的是各自的专属自归因模型（Self-Attribution），会倾向于夸大自己的战绩；而 AppsFlyer 采用的则是去重归因模型。指标看板提供的“归因偏差率”旨在帮助我们定量评估并发现超出正常范围（通常为 ≤10%）的数据异常风险。

经营驾驶舱 (Executive Cockpit) 操作说明书

返回大盘 (Back)

设计意义 (Business Significance)
面向管理层、增长负责人、以及投放小白的 30 秒高管决策大盘。它屏蔽复杂的维度细节，聚合展示大盘的核心健康指标（Total Spend, Installs, Blended CPI, ROAS, Revenue），指导高频决策（加减/停投预算）。

100% 完整数据种类清单与定义 (Data Definitions)

Total Spend (总消耗)：所有广告渠道（Moloco, TikTok, ASA, Meta, Google Ads）换算为 USD 后的花费汇总。
AF Paid Installs (付费安装量)：AppsFlyer 归因到非自然买量（is_organic=0）的真实去重新安装。
Organic Installs (自然安装量)：未归因于任何广告渠道的自然下载安装。
Total Installs (总安装量)：付费安装 + 自然安装的总和。
Blended CPI (综合获客单价)：Total Spend / Paid Installs。反映平均买量成本。
Cohort D0 Revenue (首日收入)：新增用户在安装当天触发的真实支付订单金额。
Data Quality Status (数据质量状态)：大盘数据的红黄绿灯综合可信度评分。
Active Anomalies Count (活跃异常数)：今日系统监测到未解决的同步和归因等警报数量。

派生指标计算公式与数据来源

指标	公式 / 计算方法	数据来源
Blended CPI	Total Spend / Paid Installs	D1 daily_metrics
Overall ROAS	Cohort Cumulative Net Revenue / Spend	D1 fact_orders + fact_ad_cost_daily

关联后端 Connection 密钥与参数配置

metric_cost_source: 成本拉取的主口径设定。
metric_install_primary_source: 归因安装数的主数据源（默认 BigQuery AF Push）。
incomplete_day_rule: “今天”未完结天数据的对账占位规则。

运营与技术对账 FAQ

Q: 为什么“今天 (Today)”大盘的数据和官方后台有细微出入？
A: 今天属于未完结业务日，数据是以小时级进行实时增量拉取快照，部分渠道归因回传存在延迟，大盘会显式展示“未完结 (Incomplete)”黄色角标，不建议用今日数据进行长线预算执行决策。

Q: 首日 (D0) 收入显示为“—”是什么原因？
A: 说明当前查询日期范围内尚无支付订单，或今日账期未结，系统采取优雅占位防崩溃，不影响历史完整天数据。

UA 买量表现 (UA Performance) 操作说明书

返回大盘 (Back)

设计意义 (Business Significance)
买量优化专家最高频使用的核心看板。该页面从渠道 (Channels)、国家 (Countries)、计划 (Campaigns)、素材 (Creatives) 和 ASA 关键词 (ASA Keywords) 五个细分维度，提供精细化的买量表现、转化漏斗以及媒体侧与 MMP 侧的归因核对，实现对每一分广告预算的精确定位。

100% 完整数据种类清单与定义 (Data Definitions)

Spend (消耗)：各广告平台侧实际花费金额，换算为 USD。
Impressions (展示)：广告被用户看到的次数。
Clicks (点击)：用户点击广告的次数。
CTR (点击率)：Clicks / Impressions，衡量广告素材的吸引力。
CPC (单次点击成本)：Spend / Clicks。
CPM (千次展示成本)：(Spend / Impressions) * 1000。
Platform Conversions (媒体转化)：广告媒体自称的用户转化数。
AF BQ Installs (MMP 归因安装)：AppsFlyer 官方 SDK 统计去重后并在 BigQuery 中校准的付费安装数。
AF CPI (归因获客成本)：Spend / AF BQ Installs。评估真实买量获客单价。
Platform vs MMP Diff (归因偏差率)：|Platform Conversions - AF BQ Installs| / AF BQ Installs。

派生指标计算公式与数据来源

CTR = Clicks / Impressions (百分比)
AF CPI = Spend / AF BQ Installs
Platform vs MMP Diff = ABS(Platform Conversions - AF BQ Installs) / AF BQ Installs (若分母为0，显示“—”)

关联后端 Connection 密钥与参数配置

google_ads_status: Google Ads API 连接项配置与状态。
tiktok_app_id: TikTok 开发者 App ID 与 OAuth 状态。
target_countries: 首批国家分析筛选预置列表。

运营与技术对账 FAQ

Q: 什么是“Platform vs MMP Diff (归因偏差率)”？该如何控制？
A: 这是广告媒体宣称的转化与 AppsFlyer 实际归因去重安装数之间的绝对差值比。若该比值 > 10% (黄灯) 或 > 20% (红灯)，说明存在数据漏发、重复订单或者刷单，需下载 AF 原始明细交叉核查。

Q: 为什么 Google 渠道拆成了 Google W2A、general 和 ainote 三行？
A: 为了精确监控 Web W2A (网页跨端) 转化和不同 App 子账号的获客效率，系统按 Google Ads 的 Client Customer ID 进行了行级精确解析，防止花费和大盘混淆。

用户质量与激活表现 (User Quality) 操作说明书

返回大盘 (Back)

设计意义 (Business Significance)
User Quality 看板衡量了所获取流量的实际参与度、健康度与产品体验转化流失情况。通过实时对齐用户在 App 内部的关键交互（留存率、激活天数、核心动作转化），可以直观暴露低质渠道或机器虚假流量，防止买入垃圾流量。

100% 完整数据种类清单与定义 (Data Definitions)

D1 / D7 / D30 Retention (留存率)：在指定日期安装的用户中，第 1 / 7 / 30 天仍然打开 App 的去重设备比率。
Activation Rate (激活率)：新安装用户中成功触发“激活行为”（如完成首次扫描、创建首个公式）的比率。
Time To Activate Median (TTA P50)：用户从“安装”到“成功触发激活行为”的中间耗时（中位数，通常单位为分钟/秒）。
Core Action Rate (核心动作率)：用户触发最高频、最具粘性的核心工具的转化比例（如：使用 AI Notes 生成、触发数学解答）。

派生指标计算公式与数据来源

D1 Retention = COUNT(DISTINCT user_id WHERE active_on_day(1)) / COUNT(DISTINCT user_id IN COHORT)
Activation Rate = COUNT(DISTINCT appsflyer_id WHERE activated_time IS NOT NULL) / Total Installs
TTA P50 = MEDIAN(activated_time - install_time)

关联后端 Connection 密钥与参数配置

user_events_tracking: 触发激活和核心行为关联的埋点事件名配置。
retention_cohort_size: 最低计算留存的初始 Cohort 样本大小限制，低于该阀值显示 “—”。

运营与技术对账 FAQ

Q: 为什么“近 7 天”的 D7 留存率经常显示为“—”？
A: 因为 Cohort 机制需要满足完整的天数。如果用户是近 7 天内刚下载的，他们的“第 7 天（Day 7）”还没有到，系统会自动优雅占位为“—”，防止产生数据断裂或由于部分到期导致的百分比失真。

Q: 激活定义在 Android 和 iOS 上是一致的吗？
A: 激活行为基于 AppsFlyer 统一回传事件和 GA4 日志，对于双端埋点事件进行了统一清洗，因此公式完全对齐，保证数据一致性。

变现表现与付费转化 (Monetization) 操作说明书

返回大盘 (Back)

设计意义 (Business Significance)
Monetization 看板展示了最为核心的付费转化与营收指标，是平台商业化变现的晴雨表。它涵盖从“付费墙曝光”、“订阅点击”到“试用开始”、“首购成功”的全付费链路漏斗，用以衡量产品内变现效率（Paywall CVR, ARPPU）和买量成本回收（CPP, Net Revenue）。

100% 完整数据种类清单与定义 (Data Definitions)

Paywall Exposure Rate (付费墙曝光率)：看到付费墙的用户数 / 初始下载安装数。
Subscribe Click Rate (订阅点击率)：在付费墙上点击了购买/试用按钮的用户数 / 看到付费墙的用户数。
Trial Start Rate (试用开始率)：成功开启免费试用（如 3 天/7 天免费试用）的用户数 / 付费墙展现数。
First Purchase Rate (首购率)：成功首购付费的用户数 / 初始下载安装数（通过 original_transaction_id 深度去重）。
Paywall CVR (付费页转化率)：首购付费人数 / 看到付费墙的用户数。反映付费墙的变现效率。
Net Revenue (总净收入)：去除 App Store/Google Play 商店分成（store_fee）及退税后的财务实收金额。
Paying Users (总购买人数)：在查询日期范围内，产生成功支付订单的去重用户数。
CPP (新增付费成本)：Spend / First Purchase Users。买入一个首购付费用户所需的实际广告花费。
ARPPU (付费用户平均贡献)：Net Revenue / Paying Users。衡量高付费用户的客单价贡献。

派生指标计算公式与数据来源

Paywall CVR = first_purchase_users / pay_page_show_users
ARPPU = Net Revenue / Paying Users
CPP = Total Spend / first_purchase_users (仅对已知成本渠道计算)

Metric Catalog (单一真理 / Single Source of Truth)

下表自 src/metrics/definitions.ts 加载，覆盖所有公式、数据源、去重键、行业基准。

关联后端 Connection 密钥与参数配置

superwall_api_key: 用于读取 Superwall ClickHouse API 汇总变现漏斗数据的 Org-Key。
store_fee_rate: 预估应用商店分成比例（如 15% 或 30%），用于从 gross 换算 net。
tax_deduction_rule: 财务层针对增值税、销售税等扣除比率的静态参数设置。

运营与技术对账 FAQ

Q: 什么是“真实订单 Net Revenue”？如何核实？
A: Net Revenue 是剔除了退款、假收据、测试沙盒以及苹果 30% 商店 fee 后的财务实际流水。系统底层通过 fact_orders 的 'price_net' 字段累加计算，差异率通常与 App Store Connect 官方后台数据误差在 0.1% 以内。

Q: 为什么 CPP 算出来比 CPI 贵这么多？
A: CPI 是买入一个下载用户的成本，而 CPP (Cost Per Payer) 是买入一个真实付费用户的成本。如果一个渠道的付费率是 5%，那么 CPP 将大约是 CPI 的 20 倍。

投资回报周期与 LTV 模型 (LTV & ROAS) 操作说明书

返回大盘 (Back)

设计意义 (Business Significance)
LTV & ROAS 页面提供了对流量投资回报周期的终极评估，直接关系到未来买量渠道预算的加减、停投和生命周期估值。由于涉及大额资金分配和渠道扩量策略，数据复核工作采用最严格的 HKT 香港时间 Cohort 归集。

100% 完整数据种类清单与定义 (Data Definitions)

D0 / D7 / D30 ARPU (用户价值)：在 install_date_hkt 当天及后续 7 / 30 天内，该批 Cohort 用户人均产生的累积财务净收入 (USD)。
D0 / D7 / D30 ROAS (投资回收率)：该批 Cohort 用户在安装后 0 / 7 / 30 天内的累计付费总额 / 该批用户产生的当天初始广告总消耗。
Payback Days (回本天数)：累积 ROAS 达到并稳定在 100% 时的最小天数。
LTV:CAC Ratio (终极获客比值)：用户预计终身生命周期价值 (Projected LTV) 与其获客成本 (Blended CPI / CAC) 的比值。该比值 > 3 证明买量模型十分健康，具备大规模扩量潜力。

派生指标计算公式与数据来源

Dn ARPU = cohort_d0_to_dn_cumulative_net_revenue / cohort_installs
Dn ROAS = cohort_d0_to_dn_cumulative_net_revenue / cohort_spend
LTV:CAC = projected_ltv / af_cpi

Metric Catalog (LTV / ROAS / Subscription)

下表自 src/metrics/definitions.ts 加载，含 D0/D7/D14 观测值与 D30/D90/D365 预测值的成熟度标签。

关联后端 Connection 密钥与参数配置

cohort_days_window: 跟踪 Cohort 的最长追溯天数限制（默认最长 365 天）。
ltv_projection_algorithm: LTV 未来生命周期对数拟合回归模型的算法标识。

运营与技术对账 FAQ

Q: 为什么在筛选近 30 天自定义日期时，D30 ROAS 展现为“—”？
A: 如果用户的安装时间距离今天不足 30 天，他们的 D30 数据还无法结算。为了保持数据严谨性，系统在此类由于时间跨度未到期产生的部分天节点上采取优雅降级占位，不会让程序抛出 NaN 或负值。

Q: 为什么大盘 ROAS 和 LTV 趋势对折线图偶有断裂？
A: 如果某一天数据同步任务异常导致 D1 数据未入库，系统会由 Data Quality 面板触发红灯报警，并优雅占位折线图，排除脏数据对拟合曲线精度的污染。

网页跨端归因与转化漏斗 (Web W2A) 操作说明书

返回大盘 (Back)

设计意义 (Business Significance)
专注于追踪并通过 H5 网页端广告导入、在网页内实现注册/试用，并最终在 App 内实现首购或付费转化的全链路跨平台归因对账。此链路是买量最复杂也是最高价值的增长引擎，用以防范网页端花费与 App 端付费对不齐的巨额资金漏洞。

100% 完整数据种类清单与定义 (Data Definitions)

Web Impressions / Clicks (网页广告数据)：Google Web 广告等渠道媒体侧回传的真实展示和点击（访客）量。
Web Spend (网页消耗)：媒体侧花在 W2A 落地页上的广告费用 (USD)。
Registrants (注册用户数)：用户在落地页 H5 端成功提交手机/邮箱并完成注册的数量。
Trial Users (网页试用数)：用户在 Web 端或落地页点击进入试用流程的人数。
App Active Users (App 激活数)：在 H5 端注册的用户，下载 App 并成功拉起绑定的设备数。
App First Purchase Users (App 首购人数)：网页 W2A 来源的用户最终在 App 内支付成功的首购人数。
W2A ROAS (网页跨端回收率)：App 内 W2A 付费收入 / Web 广告端消耗。

派生指标计算公式与数据来源

Web CVR = Registrants / Clicks
W2A Overall CVR = App First Purchase Users / Clicks (落地页至 App 最终付费流转化率)
W2A ROAS = App First Purchase Revenue / Web Spend

关联后端 Connection 密钥与参数配置

google_ads_web_cid: W2A 的 Google Ads Customer Client ID 绑定参数。
ga4_web_stream_id: Google Analytics 4 用于统计 W2A 落地页用户行为的数据流 ID。
appsflyer_onelink_id: AppsFlyer 用于在 Web 落地页向 App 内跳转传递归因参数的 OneLink 模板。

运营与技术对账 FAQ

Q: 网页落地页的注册数据是如何和 App 内的付费对齐的？
A: 系统底层通过 dim_user_identity 标识打通表，将落地页 GA4 采集到的 web_user_id (与 Google Ads gclid 关联) 与 App 端在安装拉起时上传的 customer_user_id 进行关联映射。数据对齐误差不超过 0.05%。

Q: 跨端归因是否存在时间延迟？
A: Google Ads 接口花费和 BigQuery GA4 日志由于离线计算会有 3~6 小时更新延迟。系统每天夜间自动进行 7 天内数据的回溯补数 (Backfill)，校准一切延迟误差。

数据质量监控与八大检查 (Data Quality) 操作说明书

返回大盘 (Back)

设计意义 (Business Significance)
Data Quality 看板是整个 UA Command Center 数据对账系统的护城河。它通过实时及定时运行 8 项关键数据校验指标，精准抓取同步延迟、汇率损失、归因偏差以及异常大额支出，防止前端数据指标“失真”或发生严重的误导决策。

八项核心红绿灯校验指标定义

Cost Coverage Rate (广告花费覆盖率)：有广告曝光的渠道中，被 D1 spend_usd 覆盖完整天数的比例。≥ 95% 绿灯。
Attribution Coverage Rate (归因覆盖率)：AppsFlyer 归因渠道不为 unknown 的比重。≥ 95% 绿灯。
Platform vs MMP Diff (媒体 vs MMP 偏差率)：媒体转化数与 MMP 安装数的差值比。≤ 10% 绿灯。
Event Freshness (事件新鲜度)：最新入库记录距今的小时延迟。≤ 6h 绿灯。
Revenue Match Rate (收入一致率)：MMP 汇总收入与后端真实实收订单的差异率。≤ 5% 绿灯。
Duplicate Order Rate (订单重复率)：排查财务库中 transaction_id 重复的比重；0 为绿灯，≤ 0.1% 为黄灯，> 0.1% 为红灯。
Unknown Country Rate (未知国家比例)：统计未知/空国家归因的用户占比。≤ 5% 绿灯。
Missing Campaign Rate (丢失 Campaign 比例)：有消耗但无 CampaignID 标识记录的比例。≤ 2% 绿灯。

关联后端 Connection 密钥与参数配置

dq_rerun_schedule: 每天定时触发数据质量复核的 Cron schedule 配置。
anomaly_alerts_webhook: 异常警报触达（飞书/Slack/钉钉）的 Webhook URL 地址。

运营与技术对账 FAQ

Q: 为什么“收入一致率 (Revenue Match Rate)”和“重复订单率 (Duplicate Order Rate)”之前显示为 Unknown 状态？
A: 之前的测试中，后端对该两项 P1 指标的检测引擎硬编码返回为了 null，且缺少 mock 订单种子数据。我们目前已重构 dq.ts 并补充了 fact_orders 的 mock 财务流水，系统现已成功实现 100% 数据实查和状态绿灯更新！

Q: 如果遇到红灯报警该如何处理？
A: 异常明细（Anomaly Logs）中会提供具体的渠道、时段、错误原因和“修复指引”（例如：点击同步面板的“立即重试”以重新调用 API）。

政策事件与资源状态监控 (Policy Incidents) 操作说明书

返回 Policy Incidents

设计意义 (Business Significance)
Policy Incidents 应该成为“资源状态监控 + 政策风险预警 + 处理台账”的统一入口。它可以把各平台账号、计划、广告组、广告、素材、ASA 关键词、W2A 关键词和落地页状态接入统一资源库存；AI 负责提前发现风险，但默认只生成预警和事件，不直接改动线上广告平台。

1. 可以通过接口监控哪些资源？

资源类型	典型来源	统一状态	产品口径
账号 / Business / App	Google Ads、TikTok、Meta、Moloco、ASA 平台 API	在投、受限、禁用、授权失效、未知	优先发现账号级封禁、Token 失效、余额 / 授权问题。
Campaign / Ad Group / Ad	平台层级对象 API + 成本报表	在投、停投、预算受限、审核中、拒登、归档	用对象状态结合花费、展示、点击判断“应该跑但没跑”的异常。
Creative / 素材资源	平台素材 API、R2 素材库、creative_assets.status	可用、同步中、失败、拒登、失效、未知	监控素材审核、文件同步、素材引用断链和政策高危内容。
ASA 关键词 / Search Terms	Apple Search Ads 关键词报表与对象元数据	在投、暂停、删除、受限、无数据、未知	列出关键词层级消耗、点击、安装和突然断流风险。
W2A 关键词 / UTM / 落地页	Google Ads Keyword、GA4、AppsFlyer OneLink、BigQuery	在投、停投、漏斗断裂、落地页异常、归因缺失	监控 Web 点击到 App 安装 / 首购链路，提前发现预算漏损。

2. 推荐数据流

平台只读同步：定时拉取账号、计划、广告、素材、关键词等对象状态和最近指标。
统一资源库存：落到统一表，例如 resource_type、platform、account_id、resource_id、status、delivery_state、last_seen_at、spend_7d、installs_7d。
状态归一：把各平台原始状态映射为在投、停投、禁用、拒登、受限、审核中、未知。
AI 风险判断：结合状态突变、花费断崖、政策词、素材审核、数据延迟、W2A 漏斗断裂生成风险等级和处理建议。
事件化跟进：高风险进入 Policy Incidents，由 UA / 运营负责人推进，所有动作写入本地台账。

3. AI 预警触发示例

账号风险
账号状态从 active 变为 suspended / disabled，或 API 授权连续失败。

投放断流
过去 7 天有稳定消耗的资源突然 0 展示 / 0 点击 / 0 花费。

素材政策
素材审核失败、被拒登，或命中平台政策高危表达。

关键词异常
ASA / W2A 关键词仍在投但点击、安装、首购链路异常下滑。

归因断裂
Google Ads 有 Web 点击，但 GA4 / AppsFlyer 无注册、安装或 OneLink 归因。

数据陈旧
平台报表或 BigQuery 最近更新时间超过阈值，避免误判投放状态。

4. 当前页面按钮影响说明

按钮 / 操作	实际行为	会不会操作广告平台接口？	会不会影响线上投放？
KPI 卡片：处理中 / 严重 / 今日跟进 / 申诉	调用本地 GET 查询并切换列表 scope。	不会	不会
Refresh、筛选器、搜索框	重新读取 Sovi.AI 本地事件列表。	不会	不会
点击列表行 / Edit	选中事件并回填表单，方便查看或编辑。	不会	不会
Generate Advice	根据平台和拒登原因，把处理建议和 checklist 套用到当前页面。	不会	不会；它不会保存，也不会提交申诉。
Save Incident	POST / PATCH 到 Sovi.AI 的 D1 事件台账。	不会调用 TikTok / Google / ASA / Meta / Moloco 接口	不会；只保存内部事件记录。
Move · Appeal Ready / Move · Appealed / Move · Monitoring	PATCH 本地事件状态、下一步跟进时间和 delivery_state 字段。	不会	不会；不提交申诉、不恢复广告、不暂停广告。
Resolve	把 Sovi.AI 本地事件标记为已解决。	不会	不会；不代表平台侧资源已自动恢复。

安全边界：当前 Policy Incidents 是本地运营台账，不具备外部平台写操作。后续如果要加入“暂停广告”“提交申诉”“恢复投放”等线上操作，产品上必须单独做外部动作按钮、权限校验、二次确认、影响范围预览和审计日志，不能复用当前 Move / Generate Advice 按钮。

—

Sovi.AI Command Center

Command Cockpit

Spend / Install / CPI Trend

Data Quality

Channel Performance

AI Daily Brief

Data Anomalies

Today Action Queue

iOS / Android UA Daily Report

Country template matching Feishu

Meta business regions (not reported countries)

GPT Report Analysis & Recommendations

Channel totals

Country / region detail

Channel Matrix

Google Ads Account Performance

Country × Channel Matrix

Campaign Performance

Creative Performance

ASA Keyword Performance

Google W2A Keyword Performance

Channel New Users

Module penetration

Macro trend

Adoption bands

Interaction preference

Module Key Funnels

Daily module report

User Quality

Core Actions by Channel

Cohort Revenue Proxy

Store performance

Full 1–5 star distribution

Rating and review trend

5-star advocacy assets

Low-rating risk topics

App Store countries

Language performance

Version performance

Representative 5-star voices

AI growth brief

AI review operations weekly

Review inbox

Report workspace

Activation Quality

By Channel

By Channel × Geo

Weekly Growth Dashboard

Weekly Trend

Monetization

Paywall Performance (Superwall)

Funnel by Placement

A/B Experiments

LTV & ROAS

Recovery Efficiency

Recovery Matrix

Web W2A

W2A Funnel Proxy

Google W2A Cohort Revenue

Ad Attribution

Best Channel

Best Ad

Best Creative

Channel Leaderboard

Ad Leaderboard

Creative Leaderboard

Campaign Leaderboard

Creative Performance

Ad ID Performance

Channel → Business User IDs

Reverse Lookup — User → Ad

Attributed Users

Ad-User Grade Cohort

Grade Distribution (ad users)

Grade Cohort by Channel

Grade Distribution Breakdown

User Detail (Grade / Email / Business ID / AFID)

Check Matrix

Active Anomalies

BigQuery Cost — last 24h