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。