アナリティクスとメトリクスAPI

1） APIレイヤーが独立している理由

KPIのための単一の真実：「zoo SQL」を除外します。
製品のスピード：フロント、パートナーパネル、モバイル顧客は、DWHに直接アクセスすることなく集計を取得します。
セキュリティとコンプライアンス：トークン化、マスク、地理的制限、RG/AMLフィルタ。
スケーリング：キャッシュ、プレレンダー、CDN、安定した契約。

2）分類： 指標、寸法、事実

事実：賭け、賞金、預金、KYCイベント、RG介入。
次元：日付/時間（カレンダー）、ゲーム/プロバイダー、ブランド/国、チャネル/デバイス、プレーヤー（トークン）。
指標：GGR、 NGR/NET、 ARPPU、 D1/D7/D30保持、預金頻度、不正防止FPR、 RGリスク。
単位：通貨（FX）、時間（TZ）、ボリューム/カウンタ（idempotent！）。
KPIセマンティクス：BIコントラクトの定義、KPIバージョンは修正されました。

3）データ&BI契約

スキーマ：フィールド、タイプ、nullable、列挙、単位、通貨。
メトリクスの意味：数式、ソース、集計ウィンドウ、フィルタ。
互換性（SEMVER）： MAJORブレーク、MINORフィールド追加、PATCH修正。
DQ/SLA：新鮮さ、完全性、一貫性、不一致の許容。
プライバシー：'pii： false'、 'tokenized： true'、 detokenizationの禁止。

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'/cubes/fichestore上のオンライン集計）。
Precompute API（スケジュールされたプレレンダー、実体化ビュー）。
イベントAPI（ストリームカウンタ/シグナル）。
エクスポートAPI（署名されたアップロード、監査のためのWORM）。
キャッシュ：メモリ内→Redis→CDN、 key=query hash+version。
一貫性：最終的な録音のための読書あなたのライト、集計のためのSLAの新鮮さ。

5）インターフェイスおよび要求

5.1フィルター/集計/ウィンドウ

'filter'：日付範囲（'from/to' UTC、タイムゾーン認識）、国、ブランド、ゲーム、チャンネル、デバイス。
'group_by'：寸法。
'metrics'： KPIのリスト。
'window'： 'DAY' WEEK 'MONTH' ROLLING_7D 'ROLLING_28D'。
'currency'： 'reporting' native'、FX strategy：' 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'（不透明）、寸法/日付によるソート。
タイムアウト/部分：非金融KPIのみに対する部分的な応答；金融-P200またはP504のいずれか。
料金制限：グローバル/キー別/テナント別;レスポンスには'X-RateLimit-'が含まれます。

7） Idempotenceおよびキャッシュ

Idempotent GET/POST-read （body付き）と'Idempotency-Key'。
キャッシュキー=ハッシュ（パラメータ+スキーマバージョン+ロール/テナント/geo）。
TTL： KPI依存（例：収益の'PT15M'、イベントの'PT5M'）、新しいスナップショットでリセットします。

8）時間の一貫性と通貨

回顧レポートのタイムトラベルフラグ（データバージョン）。
カットオフルール（曜日/週のクロージング）。
FX：私たちは戦略、答えのコースの日付を修正します。
クロック：すべてのタイムスタンプがISO-8601、 TZが必要です。

9）セキュリティとプライバシー

。 。3の要求/応答ボディ（MITM/replayの保護）のHMACの署名。
RBAC/ABAC/ReBAC：役割+国+ブランド+目的；デフォルトのマスク。
マルチテナント-スキーマ/キー/クォータを分離します。
識別子のトークン化；回答におけるPIIの禁止。
監査：不変リクエストログ（WORM）、 'trace_id'/'actor'/'purpose'。
同意/DSAR：マーケティング属性のフィルタ；「サブジェクト消去」フラグ。

10） RG/AML/Restrictionのantifrode

RG-policies：高リスクセグメントのための「積極的な」指標を発行することの禁止；ユニットは安全です。
AML/Antifraud：機密性の高いKPIへのアクセスが制限されています。調査のための別のエンドポイント。
説明：サポートのためのKPI/信号の説明の辞書。

11）観測可能性とSLO API

SLO： p95レイテンシー（たとえば、キャッシュヒットの場合は≤ 300ミリ秒、ヘビーの場合は≤ 2秒）、成功率≥ 99。5%.

DQ：新鮮さ/完全性/完全性；応答中のラベル。
使用法：QPSのキャッシュの打撃率、熱いキー、検証の間違い。
アラート：鮮度の低下、成長4xx/5xx、 KPI（予期しないゼロ/ピーク）による異常。
トレース：'trace_id'エンドツーエンドからDWH/fichestoreへ。

12）バージョン管理と互換性

パス：'/v1'、'/v2'；マイグレーションウィンドウで非推奨。
スキーマ：応答中の'schema_version'；MAJOR→dual-read、移行ガイド。
KPIバージョン：ディレクトリ内のリンクを持つレスポンス'kpi_definitions'；隠された数式の変更を防ぎます。

13）エラーとステータス

'400'検証（存在しないメトリック/測定/フィルタの組み合わせ）。
'401/403'認証/承認。
'409' version/policy incompatibility。
'42'プライバシー/同意違反。
'429'クォータ。
'5xx'プラットフォームエラー（trace_idと再試行seq。）。

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

14）統合とインタフェース

BI：事前に説明されたセマンティックモデル、コネクタ（Looker/Power BI/Tableau）→ソースとしてのAPI。
ML：フィーチャーユニットの軽量エンドポイント（ポイント・イン・タイム、PIIなし）。
パートナー：制限されたキー/クォータ、ジオフィルタ、集計ブロックでのみレポート。
Webhook/Push：通知「スナップショット準備」、「壊れたSLO/KPI範囲」。

15）リソースエンドポイントの例

15.1収益/リターン

'POST/v2/metrics/revenue'→GGR/NGR、 bets/wins、 'date、 brand、 country、 provider、 game'で測定。

15.2保持および漏斗

'POST/v2/metrics/retention'→D1/D7/D30、 'group_by=［cohort_week、 brand、 country］'。

15.3支払い方法

'POST/v2/metrics/payments'→入金/出金、平均小切手、チャージバック率。

15.4責任あるゲーム

'POST/v2/metrics/rg'→介入回数、高リスクの割合、平均反応時間。

15.5アンチフラウド

'POST/v2/metrics/antifraud'→FPR/TPR、ケース、損失防止。

16）テストおよび質

契約テスト：enum/nullable/type、通貨/タイムゾーンの整合性。
DQテスト：範囲、単調さおよび完全性の制御。
回帰：公差のv1/v2比較。
ロード：ピークプロファイル（トーナメント/プロバイダイベント）。
セキュリティ：署名、アンチリプレイ、ファジング要求、ログのゼロPII。

17）デフォルトでのプライバシー

最小Nレコード（k-anonymity）のしきい値で集計します。
生の識別子はありません。トークン/カテゴリのみ。
DSAR：特権ループを介してトークンをアンロード/削除するAPI。

18）成功指標（API KPI）

採用：直接SQLではなくAPIを使用したレポート/ウィジェットの割合。
一貫性-BIとAPI ≤許容差。
SLO：遅延/成功/鮮度の遵守。
セキュリティ：応答/ログのゼロ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+cache+mTLS/HMACを実装します。
4.SLOダッシュボード（レイテンシ/成功/鮮度）、監査/trace_id。

30-90日

1.Precompute人気のストアフロント、CDNキャッシュ。
2.バージョン管理'/v2'、dual-read、 migration guide。
3.署名されたアップロードとWORMでAPIをエクスポートします。
4.BI/MLとの統合；クォータ/テナント/ジオアイソレータ。

3〜6ヶ月

1.KPIタクソノミとウィジェットライブラリを完了します。
2.スマートなヒント/オートコンプリートのフィルター、クエリリンタ。
3.自動リリースノートKPI、公差v1/v2の制御。
4.制限されたキーとRGポリシーを持つ外部パートナー・ループ。

21）アンチパターン

新しいバージョンとリリースノートなしで隠されたKPI数式が変更されます。
集計/トークンの代わりにPII/原材料を返します。
キャッシュ/プレレンダーの不足→高価で遅い。
特定のデータベースへのハードバインディング（レイヤー抽象化なし）。
一貫性のない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/regressionテストグリーン
• キャッシュキー/TTL、プリレンダー設定
• ドキュメントとサンプルリクエスト/レスポンス
• SLOとクォータアラートが含まれています
• テストされたRG/AML制約

23）関連セクション

DataOpsプラクティス、監査とバージョン管理、セキュリティと暗号化、アクセス制御、データトークン化、保持ポリシー、データ起源とパス、MLOps：モデルの搾取、データ倫理。

合計

アナリティクスとメトリクスAPIは、ゴールドデータとKPIへのアクセスの契約された安全で高速な層です。内部ダッシュボードからパートナーパネル、MLまで、均一な意味論、安定したバージョン、デフォルトのプライバシー、製品レベルのパフォーマンスを保証します。