API分析和指标

1）为什么单独的API层

KPI的统一真理：我们排除"SQL"动物园。
产品速度：前端、合作伙伴面板、移动客户无需直接访问DWH即可接收设备。
安全性和合规性：标记化，掩码，地理限制，RG/AML过滤器。
缩放：缓存、预渲染器、CDN、稳定合同。

2）分类法： 度量,测量,事实

事实：投注，获胜，存款，KYC事件，RG干预。
测量：日期/时间（日历），游戏/提供商，品牌/国家/地区，频道/恶作剧，玩家（代币）。
度量标准：GGR，NGR/NET，ARPPU，D1/D7/D30保留，存款频率，反亲和力，RG风险。
单位：货币（FX）,时间（TZ）,体积/计数器（idempotent!）。
KPI语义：BI合同中的定义，KPI版本是固定的。

3）API合同（数据和BI合同）

Schema： 字段,类型,nullable, enum,单位,货币.

语义指标： 公式,源,聚合窗口,过滤器.

兼容性（SEMVER）： MAJOR断裂,MINOR添加字段,PATCH固定。
DQ/SLA：新鲜，完整，一致性，差异公差。
隐私："pii：false"，"tokenized：true"，禁止排毒。

yaml api: analytics. v2 resource: /metrics/revenue kpi: GGR schema_version: 2. 1. 0 dimensions: [date, brand, country, provider, game]
metrics: [ggr, stakes, wins, bets_count]
sla: {freshness: PT15M, completeness: ">=99. 9%"}
privacy: {pii: false, tokenized: true}

4）体系结构

Query API（在"gold"/cubs/fichestor之上的在线聚合）。
Precompute API（时间表预渲染，材料化视图）。
事件API（流计数器/信号）。
Export API（签名的上载，用于审核的WORM）。
缓存：多层（内存→ Redis → CDN），键=请求哈希+版本。
一致性：阅读你的写作的最终记录，SLA新鲜的集合。

5）接口和查询

5.1过滤器/聚合/窗口

"过滤器"：日期范围（"from/to" UTC，timezone aware），国家/地区，品牌，游戏，频道，设备。
'group_by'：测量。
"metrics"：KPI列表。

`window`: `DAY|WEEK|MONTH|ROLLING_7D|ROLLING_28D`.

'currency'：'reporting' native'，FX策略：'eod'intraday'txn'。
"sampling"：对于重请求（仅在允许的情况下）。

5.2查询示例

json
POST /v2/metrics/revenue
{
"range": {"from":"2025-10-01","to":"2025-10-31","tz":"Europe/Kyiv"},
"group_by": ["date","brand","country"],
"metrics": ["ggr","bets_count","net_revenue"],
"filters": {"country":["EE","LT","LV"],"brand":["alpha","beta"]},
"currency": "reporting",
"window": "DAY"
}

5.3响应示例

json
{
"schema_version":"2. 1. 0",
"kpi_definitions":["ggr@1. 7. 0","net_revenue@1. 3. 2"],
"range":{"from":"2025-10-01","to":"2025-10-31","tz":"Europe/Kyiv"},
"data":[
{"date":"2025-10-01","brand":"alpha","country":"EE","ggr":12450. 72,"bets_count":182342,"net_revenue":10732. 11},
{"date":"2025-10-01","brand":"beta","country":"EE","ggr":...}
],
"fx":{"strategy":"eod","rate_date":"2025-10-31"},
"dq":{"freshness_sec":420,"completeness":0. 9992},
"trace_id":"3d1a-...-c79"
}

6）分离，限制，分类

分割："limit"（≤10k），"cursor"（opaque），按测量/日期排序。
时间/部分：仅针对非金融KPI的部分响应；金融-P200或P504。
利率限制：全局/按键/按特南特；答案包含"X-RateLimit-"。

7）相似性和缓存

带有"Idempotency-Key"的偶发GET/POST阅读（带身体）。
缓存键=哈希（选项+模式版本+角色/tenant/geo）。
TTL：依赖KPI（例如，"PT 15 M"用于复制，"PT5M"用于事件），重置为新的快照。

8）一致性和时间货币

回顾性报告（数据版本）的时间旅行标志。
切断规则（白天/周结束）。
FX：记录策略,回复中的课程日期。
时钟：所有时钟都是ISO-8601，TZ指示是必需的。

9）安全和隐私

mTLS/TLS1.3、HMAC签名请求/响应主体（MITM/replay保护）。
RBAC/ABAC/ReBAC：角色+国家/地区+品牌+目标；默认掩码。
多范围（multi-tenant）：隔离电路/键/配额。
身份标记化；在答复中禁止PII。
审计：不可更改的查询逻辑（WORM），"trace_id"/"actor"/"purpose"。
Consent/DSAR：营销属性的过滤器；标志"主体已取消"。

10） RG/AML/Antifrod限制

RG政策：禁止为高风险细分市场发布"激进"指标；装置是安全的。
AML/Antifrod：对敏感的KPI的访问有限，按角色划分；单独的调查终端。
Explainability：札幌的KPI/信号解释词典。

11）可观察性和SLO API

SLO： p95 latency（例如，高速缓存命中≤ 300毫秒；重量为≤ 2 c），成功率≥ 99。5%.

DQ：新鲜/完整/完整性；答桉中的标签。
使用：QPS，高速缓存，热键，验证错误。
Alerts：新鲜度降解，4xx/5xx生长，KPI异常（未排除的zeros/peaks）。
跟踪："trace_id"直通到DWH/fichestor。

12）转化与兼容性

路径：'/v1'，'/v2'；带有迁移窗口的递解。
模式：答案中的"schema_version"；MAJOR →双读，迁移海德。
KPI版本：在目录引用的"kpi_definitions"响应中；禁止对公式进行隐藏更改。

13）错误和状态

'400'验证（不存在的度量/测量/过滤器组合）。
"401/403"身份验证/授权。
"409"版本不兼容/策略。
"422"侵犯隐私/同意。
"429"配额。

"5xx"平台故障（trace_id和retry-i.）.

json
{
"error":"VALIDATION_FAILED",
"message":"Unknown metric: ngrx",
"hint":"metrics allowed: ggr, net_revenue,...",
"trace_id":"..."
}

14）集成和接口

BI：预先描述的半模型，连接器（Looker/Power BI/Tableau）→ API作为源。
ML： Fich聚合物的轻量级终结（点对点时间,没有PII）。
合作伙伴：有限密钥/配额，地理过滤器，仅通过聚合单元报告。
Webhook/Push："snapshot goot"符号化，"SLO/KPI范围中断"。

15）资源结束的例子

15.1收入/收益

"POST/v2/metrics/revenue" → GGR/NGR，投注/获胜，按"日期，品牌，国家，提供者，游戏"衡量。

15.2保持和漏斗

`POST /v2/metrics/retention` → когорты D1/D7/D30, `group_by=[cohort_week, brand, country]`.

15.3付款

"POST/v2/metrics/payments" →存款/结算，平均支票，收费率。

15.4 Responsible Gaming

"POST/v2/metrics/rg" →干预次数，高风险比例，平均反应时间。

15.5 Antifrod

"POST/v2/metrics/antifraud" → FPR/TPR，案例，防止丢失。

16）测试和质量

合同测试：enum/nullable/类型，货币/时区一致性。
DQ测试：控制范围、单调性和完整性。
倒退：根据tolerans比较v1/v2。
负载：峰值配置文件（锦标赛/提供商）。
安全性：签名,反重播,fuzzing查询,Zero-PII在日志中。

17）默认隐私性

具有"最低N记录"阈值的单元（k匿名）。
没有raw ID；仅限令牌/类别。
DSAR：用于通过特权环路通过令牌卸载/卸载的API。

18）成功指标（KPI API）

Adoption：使用API而非直接SQL的报告/小部件的比例。
一致性：BI和API ≤公差之间的差异。
SLO：遵守latency/success/freshness。
安全：响应/逻辑中的零PII实例。
成本：高速缓存的命中率,请求成本,预渲染器的百分比。

19） RACI（示例）

产品/分析（A）-KPI定义、需求。
数据平台（R）-实现，缓存，SLA，观察能力。
域所有者（R）-来源/合同。
安全/DPO（A/R）-隐私，可用性，审核。
SRE（R）-配额，汽车轨道，事件。
财务（C）是GGR/NGR/NET的财务语义。

20）实施路线图

0-30天（MVP）

1.选择3-5 KPI （GGR、存款、D7保留）。
2.描述合同和KPI语义；启用DQ/SLA。
3.实现'/v1' Query API+缓存+mTLS/HMAC。
4.SLO（latency/success/freshness），审计/trace_id。

30-90天

1.流行店面的预渲染（Precompute），CDN缓存。
2.转化"/v2"，双读，迁移海德。
3.导出带有签名上载和WORM的API。
4.与BI/ML的集成；配额/tenant/地理隔离器。

3-6个月

1.完整的KPI分类法和小部件库。
2.智能提示/自动滤波器,linter查询。
3.自动发行注释KPI，tolerans v1/v2控制。
4.具有有限密钥和RG策略的外部合作伙伴环路。

21）反模式

KPI公式的隐藏更改，没有新版本和发行说明。
回收PII/原材料而不是单元/令牌。
缺乏缓存/预渲染器→昂贵且缓慢。
硬绑定到特定的DB（没有图层抽象）。
不一致的TZ/FX →不可比数字。
"DDOS自己的"→没有等级限制/配额。

22）模板（准备使用）

22.1 SLO API策略（片段）

yaml api: analytics. v2 slo:
p95_latency_ms: 300 success_rate: 0. 995 freshness_sec_max: 900 quotas:
per_key_qps: 50 burst: 200 privacy:
min_group_size: 25 pii_in_response: false

22.2个OpenAPI（片段）

yaml paths:
/v2/metrics/revenue:
post:
requestBody:
content:
application/json:
schema: {$ref: '#/components/schemas/RevenueQuery'}
responses:
'200': {description: 'OK', content: {application/json: {schema: {$ref:'#/components/schemas/RevenueResponse'}}}}
'422': {description:'Privacy/Consent violation'}

22.3张发行支票清单

• 更新了KPI语义并升级了版本
• 目录中的合同/计划；DQ/回归测试绿色
• 缓存密钥/TTL、预渲染器配置
• 文件和请求/答复实例
• Alerta的SLO和配额包括
• RG/AML限制验证

23）相关部分

DataOps实践,审核和验证,安全和加密,访问控制,数据令牌化,存储策略,数据来源和路径,MLOps：模型操作,数据伦理。

底线

分析和度量API是对"黄金"数据和KPI的合同，安全和快速访问层。它保证了单一语义，稳定版本，默认隐私和产品级性能-从内部行车记录仪到合作伙伴面板和ML。