mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-21 22:32:22 +03:00

Files

Diego Rodrigues de Sa e Souza 8feea123bb feat(docs): mirror every docs/ page in all 65 locales (#14106 )

* feat(docs): mirror every docs/ page in all 65 locales

Extends the documentation mirrors from the 22-page core set (#13940) to
every Markdown page under docs/: 152 sources x 65 locales = 9,880 mirrors
(6,208 new), language bars rewritten for the full locale list, state
adopted so the blocking drift gate now covers all 152 pages.

run-translation.mjs: an oversized block made only of table rows or list
items (PROVIDER_REFERENCE.md 244-row table, FREE_TIERS.md 71-item list) is
cut at item boundaries and rejoined without a blank line — the single
16-40 KB request outlived the backend socket for verbose scripts. 48
older mirrors whose tables had lost rows were retranslated with --force.

* docs(i18n): refresh mirrors for the sources the base changed since the branch cut

Section-level retranslation of the 29 docs (and README.md) whose source
or mirrors moved on release/v3.8.51 during the run, then state adoption;
the drift gate is green again on the merged tree.

2026-09-18 13:16:46 -03:00

85 KiB

Raw Blame History

Gamification & Leaderboard System (తెలుగు)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

ప్రామాణిక మూలం: src/lib/gamification/, src/lib/db/gamification.ts, src/app/api/gamification/ చివరిగా నవీకరించబడింది: 2026-06-28 — v3.8.40

OmniRoute, ప్లాట్ఫారమ్తో పరస్పర చర్య చేసినందుకు వినియోగదారులకు రివార్డ్లను అందించే లోకల్-ఫస్ట్ గేమిఫికేషన్ లేయర్ను కలిగి ఉంది — అభ్యర్థనలు చేయడం, ప్రొవైడర్లను మార్చడం, కాంబోలను సృష్టించడం, టోకెన్లను పంచుకోవడం మరియు కమ్యూనిటీకి సహకరించడం వంటివి ఇందులో ఉన్నాయి. స్థితి మొత్తం SQLiteలో ఉంటుంది; కమ్యూనిటీ సర్వర్లతో ఫెడరేషన్ ఐచ్ఛికం మరియు పుష్-ఆధారితమైనది.

ఈ సిస్టమ్ హాట్ పాత్లో జీరో-లేటెన్సీ ఉండేలా రూపొందించబడింది — గేమిఫికేషన్ ఈవెంట్లు అభ్యర్థన పైప్లైన్ నుండి ఫైర్-అండ్-ఫర్గెట్ పద్ధతిలో పంపబడతాయి మరియు LLM ప్రతిస్పందనను ఎప్పుడూ నిరోధించవు.

అవలోకనం

ఉద్దేశ్యం

కనిపించే పురోగతి (XP, లెవెల్లు, బ్యాడ్జ్లు), సామాజిక ప్రమాణం (లీడర్బోర్డ్లు) మరియు ఆర్థిక ప్రోత్సాహకాలు (టోకెన్ షేరింగ్, ఆహ్వాన రివార్డ్లు) అందించడం ద్వారా వినియోగదారుల భాగస్వామ్యాన్ని మరియు నిలుపుదలను పెంచడం.

పరిధి

ఫీచర్	వివరణ
XP & లెవెల్లు	ప్రతి చర్యకు XP సంపాదించండి; పాలినోమియల్ కర్వ్ ప్రకారం లెవెల్ పెంచుకోండి
బ్యాడ్జ్లు	4 అరుదుదన స్థాయిలతో 5 వర్గాలలో 20+ విజయాలు
స్ట్రీక్లు	ప్రస్తుత/అత్యధిక స్ట్రీక్తో రోజువారీ సక్రియ వినియోగ ట్రాకింగ్
లీడర్బోర్డ్లు	గ్లోబల్, వారపు, నెలవారీ, టోకెన్-షేరింగ్ మరియు కాంట్రిబ్యూషన్ స్కోప్లు
టోకెన్ షేరింగ్	డబుల్-ఎంట్రీ లెడ్జర్ ద్వారా వినియోగదారుల మధ్య క్రెడిట్లను బదిలీ చేయడం
ఆహ్వానం & రీడీమ్	SHA-256 హ్యాష్ చేసిన స్టోరేజ్తో రెఫరల్ కోడ్లు
కమ్యూనిటీ సర్వర్లు	బాహ్య OmniRoute ఇన్స్టాన్స్లతో ఫెడరేట్ అవడం
యాంటీ-చీట్	సర్వర్-సైడ్ స్కోరింగ్, రేట్ లిమిటింగ్, z-score అసాధారణత గుర్తింపు

రూపకల్పన సూత్రాలు

లోకల్-ఫస్ట్ — స్థితి మొత్తం SQLiteలో ఉంటుంది, బాహ్య సేవలు అవసరం లేదు.
నాన్-బ్లాకింగ్ — ఈవెంట్లు ఫైర్-అండ్-ఫర్గెట్ పద్ధతిలో ఉంటాయి; LLM ప్రతిస్పందన పాత్ గేమిఫికేషన్ లాజిక్ కారణంగా ఎప్పుడూ ఆలస్యం కాదు.
సర్వర్-అథారిటేటివ్ — XP సర్వర్-సైడ్లో మాత్రమే లెక్కించబడుతుంది; క్లయింట్లు స్కోర్లను కృత్రిమంగా పెంచలేరు.
గోప్యతను గౌరవించేది — లీడర్బోర్డ్లో పాల్గొనడం ఐచ్ఛికం; వినియోగదారులు తమ ప్రొఫైల్ను దాచవచ్చు.
ఫెడరేషన్కు సిద్ధం — కమ్యూనిటీ సర్వర్లు సంతకం చేసిన API ద్వారా స్కోర్లను పుష్ చేయగలవు; సింక్ అనేది ఓవర్రైట్ పద్ధతిలో జరుగుతుంది, అదనంగా కలపడం కాదు.

ఆర్కిటెక్చర్

ఉన్నత-స్థాయి ప్రవాహం

క్లయింట్ అభ్యర్థన
  → /v1/chat/completions
    → handleChatCore()                      [open-sse/handlers/chatCore.ts]
      → ... (ఇప్పటికే ఉన్న పైప్లైన్) ...
      → అప్స్ట్రీమ్ ప్రతిస్పందన క్లయింట్కు పంపబడుతుంది
      → setImmediate (ఫైర్-అండ్-ఫర్గెట్):
        → emitGamificationEvent()           [src/lib/gamification/events.ts]
          → awardXp()                       [src/lib/gamification/xp.ts]
          → updateStreak()                  [src/lib/gamification/streaks.ts]
          → evaluateBadges()                [src/lib/gamification/badges.ts]
          → updateLeaderboard()             [src/lib/gamification/leaderboard.ts]
          → checkAnomalies()                [src/lib/gamification/antiCheat.ts]

ఈవెంట్ ఎమిటర్ ఏకైక ఇంటిగ్రేషన్ పాయింట్. ప్రతిస్పందన పంపబడిన తర్వాత chatCore.ts, emitGamificationEvent()ను కాల్ చేస్తుంది; ఈవెంట్ మాడ్యూల్ దానిని XP, స్ట్రీక్, బ్యాడ్జ్, లీడర్బోర్డ్ మరియు యాంటీ-చీట్ సబ్సిస్టమ్లకు పంపిణీ చేస్తుంది.

మాడ్యూల్ డిపెండెన్సీ గ్రాఫ్

src/lib/gamification/
  events.ts          ← ఎంట్రీ పాయింట్ (chatCore.ts నుండి కాల్ చేయబడుతుంది)
    ├── xp.ts        ← XP లెక్కింపు & లెవెల్ నిర్ధారణ
    ├── streaks.ts   ← రోజువారీ సక్రియ స్ట్రీక్ ట్రాకింగ్
    ├── badges.ts    ← బ్యాడ్జ్ ప్రమాణాల మూల్యాంకనం
    ├── leaderboard.ts ← ర్యాంక్ లెక్కింపు & SSE బ్రాడ్కాస్టింగ్
    ├── antiCheat.ts ← రేట్ లిమిటింగ్ & అసాధారణత గుర్తింపు
    ├── sharing.ts   ← టోకెన్ బదిలీ లెడ్జర్
    ├── invites.ts   ← ఆహ్వానం/రీడీమ్ కోడ్ నిర్వహణ
    ├── servers.ts   ← కమ్యూనిటీ సర్వర్ ఫెడరేషన్
    └── notifications.ts ← SSE నోటిఫికేషన్ స్ట్రీమ్

src/lib/db/
  gamification.ts    ← అన్ని CRUD ఆపరేషన్లు (8 టేబుల్లు)

src/app/api/gamification/
  leaderboard/       ← GET ర్యాంకింగ్లు, POST మాన్యువల్ రిఫ్రెష్
  leaderboard/stream ← SSE రియల్-టైమ్ అప్డేట్లు
  transfer/          ← GET చరిత్ర, POST టోకెన్లను పంపడం
  invite/            ← GET/POST కోడ్లు, DELETE ఉపసంహరణ
  invite/redeem/     ← POST కోడ్ను రీడీమ్ చేయడం
  servers/           ← GET/POST/DELETE కమ్యూనిటీ సర్వర్లు
  federation/score/  ← POST సర్వర్కు స్కోర్ను పుష్ చేయడం
  federation/leaderboard/ ← GET సర్వర్ నుండి లీడర్బోర్డ్ను పుల్ చేయడం
  notifications/     ← SSE బ్యాడ్జ్/లెవెల్-అప్ నోటిఫికేషన్లు
  anomalies/         ← GET అసాధారణత నివేదికలు (అడ్మిన్)
  rotate/            ← POST ఆహ్వాన టోకెన్ సీక్రెట్లను రొటేట్ చేయడం

డేటా లేయర్

డేటాబేస్ పట్టికలు

అన్ని పట్టికలు ప్రధాన OmniRoute SQLite డేటాబేస్లో ఉంటాయి, ఇది 060_create_gamification.sql మైగ్రేషన్ ద్వారా సృష్టించబడుతుంది. WAL జర్నలింగ్ అనేది src/lib/db/core.tsలోని సింగిల్టన్ getDbInstance() నుండి సంక్రమిస్తుంది.

┌─────────────────────────┐     ┌──────────────────────────┐
│      leaderboard        │     │      user_levels          │
├─────────────────────────┤     ├──────────────────────────┤
│ id            TEXT PK   │     │ api_key_id    TEXT PK    │
│ api_key_id    TEXT      │     │ xp            INTEGER    │
│ scope         TEXT      │     │ level         INTEGER    │
│ score         INTEGER   │     │ title         TEXT       │
│ period        TEXT      │     │ updated_at    TEXT       │
│ updated_at    TEXT      │     └──────────────────────────┘
└─────────────────────────┘
                │
                │ 1:N
                ▼
┌─────────────────────────┐     ┌──────────────────────────┐
│     user_badges         │     │    badge_definitions      │
├─────────────────────────┤     ├──────────────────────────┤
│ id            TEXT PK   │     │ id            TEXT PK    │
│ api_key_id    TEXT      │     │ name          TEXT       │
│ badge_id      TEXT FK   │     │ category      TEXT       │
│ earned_at     TEXT      │     │ rarity        TEXT       │
│ notified      INTEGER   │     │ criteria_type TEXT       │
└─────────────────────────┘     │ criteria      TEXT(JSON) │
                                │ description   TEXT       │
                                │ icon          TEXT       │
                                │ hidden        INTEGER    │
                                └──────────────────────────┘

┌─────────────────────────┐     ┌──────────────────────────┐
│     xp_audit_log        │     │     token_ledger         │
├─────────────────────────┤     ├──────────────────────────┤
│ id            TEXT PK   │     │ id            TEXT PK    │
│ api_key_id    TEXT      │     │ from_key_id   TEXT       │
│ action        TEXT      │     │ to_key_id     TEXT       │
│ xp_awarded    INTEGER   │     │ amount        INTEGER    │
│ metadata      TEXT(JSON)│     │ idempotency_key TEXT UQ  │
│ created_at    TEXT      │     │ created_at    TEXT       │
└─────────────────────────┘     └──────────────────────────┘

┌─────────────────────────┐     ┌──────────────────────────┐
│    invite_tokens        │     │   community_servers      │
├─────────────────────────┤     ├──────────────────────────┤
│ id            TEXT PK   │     │ id            TEXT PK    │
│ api_key_id    TEXT      │     │ name          TEXT       │
│ code          TEXT UQ   │     │ url           TEXT       │
│ token_hash    TEXT      │     │ token_hash    TEXT       │
│ uses          INTEGER   │     │ status        TEXT       │
│ max_uses      INTEGER   │     │ last_sync     TEXT       │
│ created_at    TEXT      │     │ created_at    TEXT       │
│ expires_at    TEXT      │     └──────────────────────────┘
└─────────────────────────┘

డొమైన్ మాడ్యూల్: `src/lib/db/gamification.ts`

ప్రామాణిక OmniRoute నమూనాను అనుసరిస్తుంది — core.ts నుండి getDbInstance()ను దిగుమతి చేసుకుని, టైప్ చేయబడిన CRUD ఫంక్షన్లను ఎగుమతి చేస్తుంది. రూట్ హ్యాండ్లర్లలో ముడి SQL ఉండదు.

ముఖ్యమైన ఫంక్షన్లు:

ఫంక్షన్	వివరణ
`upsertLeaderboardEntry()`	(api_key_id, scope, period) కోసం స్కోర్ను చొప్పించడం లేదా నవీకరించడం
`getLeaderboard()`	ఇచ్చిన scope/period కోసం పేజీలుగా విభజించిన ర్యాంకింగ్లు
`getUserLevel()`	వినియోగదారు స్థాయి రికార్డ్ను పొందడం లేదా సృష్టించడం
`updateUserLevel()`	XP, level మరియు titleను అటామిక్గా సెట్ చేయడం
`getBadgeDefinitions()`	అన్ని బ్యాడ్జ్ నిర్వచనాలు (ఐచ్ఛికంగా ఫిల్టర్ చేయబడినవి)
`getUserBadges()`	వినియోగదారు సంపాదించిన బ్యాడ్జ్లు
`awardBadge()`	బ్యాడ్జ్ సంపాదనను చొప్పించడం (badge_idపై ఐడెంపొటెంట్)
`logXpAction()`	xp_audit_logకు జోడించడం
`getXpAuditLog()`	వినియోగదారు కోసం పేజీలుగా విభజించిన ఆడిట్ చరిత్ర
`insertLedgerEntry()`	డబుల్-ఎంట్రీ బదిలీ (ట్రాన్సాక్షన్లో)
`getBalance()`	వినియోగదారు కోసం అందుకున్న వాటి మొత్తం నుండి పంపిన వాటి మొత్తాన్ని తీసివేయడం
`getTransferHistory()`	పేజీలుగా విభజించిన బదిలీ లాగ్
`createInviteToken()`	ఆహ్వాన కోడ్ + హ్యాష్ చేసిన టోకెన్ను చొప్పించడం
`redeemInviteToken()`	కోడ్ ద్వారా శోధించడం, ధృవీకరించడం, usesను పెంచడం
`upsertCommunityServer()`	ఫెడరేషన్ సర్వర్ను నమోదు చేయడం లేదా నవీకరించడం
`getCommunityServers()`	వినియోగదారు కోసం సర్వర్లను జాబితా చేయడం
`deleteCommunityServer()`	సర్వర్ నమోదును తొలగించడం

XP / లెవల్ సిస్టమ్

ఫైల్: src/lib/gamification/xp.ts

లెవల్ కర్వ్

లెవల్ n చేరుకోవడానికి అవసరమైన XP ఒక పాలినోమియల్ కర్వ్ను అనుసరిస్తుంది:

xp_for_level(n) = floor(100 * n^1.5)

లెవల్	తదుపరి లెవల్కు XP	మొత్తం XP	బిరుదు
1	100	100	ప్రారంభకుడు
5	1,118	2,415	ప్రారంభకుడు
10	3,162	10,523	అన్వేషకుడు
25	12,500	86,024	అన్వేషకుడు
50	35,355	345,529	నిపుణుడు
75	64,952	948,683	మాస్టర్
100	100,000	2,050,000	దిగ్గజం

బిరుదులు

లెవల్ పరిధి	బిరుదు
1 – 9	ప్రారంభకుడు
10 – 24	అన్వేషకుడు
25 – 49	నిపుణుడు
50 – 74	మాస్టర్
75 – 100	దిగ్గజం

XP రివార్డులు

చర్య	XP	వివరణ
`request`	1	OmniRoute ద్వారా రూట్ చేయబడిన ప్రతి API అభ్యర్థనకు
`provider_switch`	5	వేరొక ప్రొవైడర్కు మారడం
`model_switch`	3	వేరొక మోడల్కు మారడం
`combo_create`	10	కొత్త కాంబోను సృష్టించడం
`combo_use`	2	అభ్యర్థన కోసం కాంబోను ఉపయోగించడం
`token_share`	1	మరొక వినియోగదారుతో పంచుకున్న ప్రతి 1 000 టోకెన్లకు
`invite_redeem`	50	ఆహ్వాన కోడ్ను రీడీమ్ చేయడం
`daily_login`	5	రోజువారీ క్రియాశీల వినియోగం (రోజుకు ఒకసారి)
`streak_bonus`	2	వరుసగా కొనసాగిన ప్రతి స్ట్రీక్ రోజుకు (స్ట్రీక్ నిడివితో గుణించబడుతుంది)
`badge_unlock`	10	బ్యాడ్జ్ను అన్లాక్ చేయడం

ప్రదాన ప్రక్రియ

export async function awardXp(
  apiKeyId: string,
  action: XpAction,
  metadata?: Record<string, unknown>
): Promise<{ xp: number; level: number; title: string; levelUp: boolean }>;

XP మొత్తాన్ని పొందడానికి XP_REWARDS[action]ను చూడండి.
checkRateLimit() ద్వారా పంపండి (మోస నిరోధం: ఒక్కో కీకి నిమిషానికి గరిష్ఠంగా 1000 XP).
ఒక ట్రాన్సాక్షన్ను తెరవండి:
- ప్రస్తుత user_levels వరుసను చదవండి.
- XPని జోడించండి; levelFromXp(totalXp) ద్వారా లెవల్ను మళ్లీ లెక్కించండి.
- లెవల్ మారితే, levelUp = trueగా సెట్ చేయండి.
- user_levels వరుసను అప్డేట్ చేయండి.
- xp_audit_logలో చేర్చండి.
ఫలితాన్ని తిరిగి ఇవ్వండి. కాలర్ నోటిఫికేషన్లను నిర్వహిస్తుంది.

సహాయక ఫంక్షన్: `levelFromXp(totalXp)`

సంచిత XP totalXpను మించే వరకు xp_for_level(n)ను కూడుతూ, 1..100 లెవల్లపై పునరావృతం చేస్తుంది. థ్రెషోల్డ్ను చేరుకున్న అత్యధిక లెవల్ను తిరిగి ఇస్తుంది. లెవల్లు 100 వద్ద పరిమితం అవుతాయి కాబట్టి ఇది O(100) — ఆమోదయోగ్యమైనది.

బ్యాడ్జ్ సిస్టమ్

ఫైల్: src/lib/gamification/badges.ts

వర్గాలు

వర్గం	వివరణ	ఉదాహరణ బ్యాడ్జ్లు
`usage`	వినియోగ పరిమాణం ఆధారిత మైలురాళ్లు	మొదటి అభ్యర్థన, 1K అభ్యర్థనలు, 100K
`sharing`	టోకెన్ భాగస్వామ్యం మరియు రెఫరల్స్	మొదటి భాగస్వామ్యం, ఉదారుడు (10 భాగస్వామ్యాలు)
`contribution`	కమ్యూనిటీ భాగస్వామ్యం	కాంబో సృష్టికర్త, ప్రొవైడర్ అన్వేషకుడు
`streak`	కాలక్రమంలో స్థిరత్వం	వారపు యోధుడు, నెలవారీ అంకితభావి
`rare`	పొందడం కష్టమైన లేదా దాచిన విజయాలు	ప్రారంభ స్వీకర్త, బగ్ రిపోర్టర్

అరుదుదనాలు

అరుదుదనం	రంగు	సంభావ్యత సూచన
`common`	బూడిద	అత్యధిక వినియోగదారులు
`uncommon`	ఆకుపచ్చ	క్రియాశీల వినియోగదారులు
`rare`	నీలం	అంకితభావం గల వినియోగదారులు
`legendary`	బంగారు	అగ్ర 1%

ప్రమాణాల రకాలు

రకం	ఫీల్డ్	వివరణ
`action_count`	`count`	చర్యను N సార్లు నిర్వహించడం (ఉదా., 1000 అభ్యర్థనలు)
`streak`	`days`	వరుసగా N రోజుల పాటు స్ట్రీక్ను కొనసాగించడం
`unique_count`	`field`, `n`	N ప్రత్యేక విలువలను ఉపయోగించడం (ఉదా., 10 వేర్వేరు మోడల్లు)
`rank`	`scope`, `n`	లీడర్బోర్డ్ స్కోప్లో N ర్యాంక్ను చేరుకోవడం
`first`	—	ఒక చర్యను నిర్వహించిన మొదటి వ్యక్తిగా ఉండడం
`hidden`	(మారుతుంది)	సంపాదించే వరకు ప్రమాణాలు చూపబడవు

బ్యాడ్జ్ నిర్వచనాలు badge_definitionsలో JSON criteriaగా నిల్వ చేయబడతాయి:

{
  "type": "action_count",
  "action": "request",
  "count": 1000
}

మూల్యాంకన ప్రక్రియ

emitGamificationEvent(event)
  → evaluateBadges(apiKeyId, event)
    → getBadgeDefinitions()           # అన్ని నిర్వచనాలు
    → getUserBadges(apiKeyId)         # ఇప్పటికే సంపాదించినవి (దాటవేయండి)
    → సంపాదించని ప్రతి బ్యాడ్జ్ కోసం:
       → matchesCriteria(badge, event, userState)
       → సరిపోలితే: awardBadge(apiKeyId, badgeId)
         → నోటిఫికేషన్ పేలోడ్ను తిరిగి ఇవ్వండి

మూల్యాంకనం ఈవెంట్ ఆధారితమైనది — ఇది ప్రతి గేమిఫికేషన్ ఈవెంట్ తర్వాత రన్ అవుతుంది, కానీ ఈవెంట్ చర్యతో criteria.type సరిపోలే బ్యాడ్జ్లను మాత్రమే తనిఖీ చేస్తుంది. ఇది చాలా ఈవెంట్లకు మూల్యాంకనాన్ని వేగంగా (< 5ms) ఉంచుతుంది.

`matchesCriteria(badge, event, userState)`

ప్రమాణం రకం	తనిఖీ
`action_count`	`getActionCount(apiKeyId, action) >= count`
`streak`	`getCurrentStreak(apiKeyId) >= days`
`unique_count`	`getUniqueCount(apiKeyId, field) >= n`
`rank`	`getRank(apiKeyId, scope) <= n`
`first`	ఈ చర్య రకానికి ముందస్తు `xp_audit_log` ఎంట్రీ లేకపోవడం
`hidden`	తగిన ఉప-తనిఖీకి అప్పగిస్తుంది

అంతర్నిర్మిత బ్యాడ్జ్లు (20+)

పూర్తి బ్యాడ్జ్ జాబితా

బ్యాడ్జ్	వర్గం	అరుదుదనం	ప్రమాణం
తొలి అడుగులు	వినియోగం	సాధారణం	1 అభ్యర్థన
అలవాటు పడుతున్నారు	వినియోగం	సాధారణం	100 అభ్యర్థనలు
పవర్ యూజర్	వినియోగం	అసాధారణం	1,000 అభ్యర్థనలు
సెంచూరియన్	వినియోగం	అరుదైనది	10,000 అభ్యర్థనలు
ఓమ్నీపవర్	వినియోగం	దిగ్గజం	100,000 అభ్యర్థనలు
ప్రొవైడర్ హాపర్	సహకారం	సాధారణం	5 వేర్వేరు ప్రొవైడర్లను ఉపయోగించండి
ప్రొవైడర్ మాస్టర్	సహకారం	అసాధారణం	20 వేర్వేరు ప్రొవైడర్లను ఉపయోగించండి
కాంబో ఆర్కిటెక్ట్	సహకారం	అసాధారణం	5 కాంబోలను సృష్టించండి
కాంబో గ్రాండ్మాస్టర్	సహకారం	అరుదైనది	25 కాంబోలను సృష్టించండి
తొలి భాగస్వామ్యం	భాగస్వామ్యం	సాధారణం	1 టోకెన్ బదిలీ
ఉదారశీలి	భాగస్వామ్యం	అసాధారణం	10 టోకెన్ బదిలీలు
పరోపకారి	భాగస్వామ్యం	అరుదైనది	మొత్తం 10,000 టోకెన్లను బదిలీ చేయండి
రెఫరర్	భాగస్వామ్యం	సాధారణం	1 విజయవంతమైన రెఫరల్
నెట్వర్క్ బిల్డర్	భాగస్వామ్యం	అసాధారణం	10 విజయవంతమైన రెఫరల్స్
వారపు యోధుడు	వరుస	అసాధారణం	7 రోజుల వరుస
నెలవారీ అంకితభావం	వరుస	అరుదైనది	30 రోజుల వరుస
అజేయం	వరుస	దిగ్గజం	365 రోజుల వరుస
తొలి స్వీకర్త	అరుదైనది	దిగ్గజం	బీటా వ్యవధిలో చేరండి
కంప్రెషన్ మార్గదర్శి	అరుదైనది	అసాధారణం	కంప్రెషన్ను 100 సార్లు ఉపయోగించండి
నైపుణ్యాల సేకరణకర్త	అరుదైనది	అరుదైనది	10 వేర్వేరు నైపుణ్యాలను ఉపయోగించండి
మోడల్ అన్వేషకుడు	సహకారం	అసాధారణం	15 వేర్వేరు మోడళ్లను ఉపయోగించండి

స్ట్రీక్ ట్రాకర్

ఫైల్: src/lib/gamification/streaks.ts

డేటా మోడల్

స్ట్రీక్లు key_value పట్టికలో (భాగస్వామ్య యుటిలిటీ పట్టిక), నేమ్స్పేస్ చేయబడిన కీల కింద నిల్వ చేయబడతాయి:

కీ	విలువ	వివరణ
`gamification:streak:{keyId}`	`{current},{longest},{lastDate}`	సక్రియ స్ట్రీక్ డేటా

లాజిక్

export async function updateStreak(
  apiKeyId: string
): Promise<{ current: number; longest: number; milestone: boolean }>;

key_value నుండి స్ట్రీక్ రికార్డును చదవండి.
{current}, {longest}, {lastDate} (ISO తేదీ స్ట్రింగ్)ను పార్స్ చేయండి.
lastDate === today అయితే — ఎలాంటి మార్పూ లేదు (ఈరోజు ఇప్పటికే లెక్కించబడింది).
lastDate === yesterday అయితే — currentను పెంచండి; అవసరమైతే longestను నవీకరించండి.
lastDate < yesterday అయితే — current = 1కు రీసెట్ చేయండి (స్ట్రీక్ తెగిపోయింది).
నవీకరించిన రికార్డును వ్రాయండి.
మైలురాళ్లను తనిఖీ చేయండి: 7, 14, 30, 60, 90, 180, 365 రోజులు. ఏదైనా దాటితే, milestone = trueగా సెట్ చేయండి (కాలర్ XPని ప్రదానం చేసి బ్యాడ్జ్లను తనిఖీ చేస్తుంది).

ప్రత్యేక సందర్భాలు

టైమ్జోన్: స్ట్రీక్లు UTC తేదీలను ఉపయోగిస్తాయి (new Date().toISOString().slice(0, 10)). ఇది ఉద్దేశపూర్వకమే — ఒకే ప్రామాణిక టైమ్జోన్, టైమ్జోన్ల మధ్య మారడం ద్వారా వ్యవస్థను దుర్వినియోగం చేయడాన్ని నివారిస్తుంది.
కొత్త వినియోగదారులు: స్ట్రీక్ రికార్డు ఉండదు; మొదటి అభ్యర్థన దానిని current=1, longest=1, lastDate=todayతో సృష్టిస్తుంది.
రోజుకు అనేక అభ్యర్థనలు: UTC రోజులోని మొదటి అభ్యర్థన మాత్రమే స్ట్రీక్ను పెంచుతుంది.

లీడర్బోర్డ్

ఫైల్: src/lib/gamification/leaderboard.ts

స్కోప్లు

స్కోప్	వ్యవధి	వివరణ
`global`	`all`	అన్ని కాలాల సంచిత XP
`weekly`	`week`	ప్రస్తుత UTC వారంలో (సోమ-ఆది) సంపాదించిన XP
`monthly`	`month`	ప్రస్తుత UTC నెలలో సంపాదించిన XP
`tokens_shared`	`all`	ఇతరులకు బదిలీ చేసిన మొత్తం టోకెన్లు
`contributions`	`all`	సృష్టించిన కాంబోలు + ఉపయోగించిన ప్రొవైడర్లు + ఉపయోగించిన నైపుణ్యాలు

ర్యాంక్ గణన

ర్యాంక్లు నిల్వ చేయబడవు, వాటిని చదివే సమయంలో గణిస్తారు. ఇది కాలం చెల్లిన ర్యాంక్ డేటాను నివారించి, కాలానుగుణ ర్యాంక్ పునఃగణన జాబ్ల అవసరాన్ని తొలగిస్తుంది.

export async function getLeaderboard(
  scope: LeaderboardScope,
  period: string,
  limit: number,
  offset: number
): Promise<{ entries: LeaderboardEntry[]; total: number }>;

క్వెరీ నమూనా:

SELECT api_key_id, score,
       RANK() OVER (ORDER BY score DESC) as rank
FROM leaderboard
WHERE scope = ? AND period = ?
ORDER BY score DESC
LIMIT ? OFFSET ?

వ్యవధి రొటేషన్

వారపు మరియు నెలవారీ లీడర్బోర్డ్లు స్వయంచాలకంగా రొటేట్ అవుతాయి:

ఆర్కైవ్: వ్యవధి సరిహద్దు వద్ద, ప్రస్తుత ఎంట్రీలను వ్యవధి లేబుల్తో leaderboard_archiveకు కాపీ చేయండి.
రీసెట్: గడువు ముగిసిన వ్యవధికి సంబంధించిన ఎంట్రీలను తొలగించండి.
ట్రిగ్గర్: ప్రతి updateLeaderboard() కాల్లో తనిఖీ చేయబడుతుంది; కొత్త వ్యవధిలోని మొదటి అభ్యర్థన రొటేషన్ను ట్రిగ్గర్ చేస్తుంది.

దీని వల్ల వారపు బోర్డులు ప్రతి సోమవారం 00:00 UTCకు, నెలవారీ బోర్డులు ప్రతి నెల 1వ తేదీన రీసెట్ అవుతాయి.

SSE రియల్-టైమ్ నవీకరణలు

ఎండ్పాయింట్: GET /api/gamification/stream

క్లయింట్ → GET /api/gamification/stream
  → SSE కనెక్షన్ ఏర్పడుతుంది
  → సర్వర్ వెంటనే టాప్-10 లీడర్బోర్డ్ స్నాప్షాట్ను పంపుతుంది
  → ప్రతి 5 సెకన్లకు: మార్పు ఉంటే నవీకరించిన టాప్-10ను పుష్ చేస్తుంది
  → ప్రతి 15 సెకన్లకు: హార్ట్బీట్ వ్యాఖ్య (": heartbeat\n\n")
  → క్లయింట్ డిస్కనెక్ట్ అవుతుంది → క్లీనప్ (లిసనర్ను తొలగించడం)

ఈవెంట్ ఫార్మాట్:

event: leaderboard
data: {"scope":"global","entries":[...]}

event: leaderboard
data: {"scope":"weekly","entries":[...]}

: heartbeat

SSE మేనేజర్ ప్రతి స్కోప్కు కనెక్ట్ అయిన క్లయింట్లను ట్రాక్ చేస్తుంది మరియు చివరి పుష్ తర్వాత లీడర్బోర్డ్ డేటా నిజంగా మారినప్పుడు మాత్రమే నవీకరణలను పంపుతుంది.

టోకెన్ భాగస్వామ్యం

ఫైల్: src/lib/gamification/sharing.ts

డబుల్-ఎంట్రీ లెడ్జర్

ప్రతి బదిలీ token_ledgerలో రెండు వరుసలను సృష్టిస్తుంది:

వరుస	`from_key_id`	`to_key_id`	`amount`
డెబిట్	పంపినవారు	స్వీకర్త	+మొత్తం
క్రెడిట్	స్వీకర్త	పంపినవారు	-మొత్తం

ఆగండి — అనుసరించే పద్ధతి ఇది:

వరుస	`from_key_id`	`to_key_id`	`amount`	అర్థం
పంపడం	పంపినవారు	స్వీకర్త	+మొత్తం	పంపినవారి నుండి బయటకు వెళ్లే మొత్తం
స్వీకరించడం	స్వీకర్త	పంపినవారు	+మొత్తం	స్వీకర్తకు లోపలికి వచ్చే మొత్తం

బ్యాలెన్స్ ఇలా లెక్కించబడుతుంది:

SELECT
  COALESCE(SUM(CASE WHEN to_key_id = ? THEN amount ELSE 0 END), 0)
  - COALESCE(SUM(CASE WHEN from_key_id = ? THEN amount ELSE 0 END), 0)
  AS balance
FROM token_ledger
WHERE from_key_id = ? OR to_key_id = ?

బదిలీ ప్రక్రియ

export async function transferTokens(
  fromKeyId: string,
  toKeyId: string,
  amount: number,
  idempotencyKey: string
): Promise<{ success: boolean; balance: number }>;

ధ్రువీకరణ: amount > 0, fromKeyId !== toKeyId.
ఐడెంపొటెన్సీ: లెడ్జర్లో idempotency_key ఇప్పటికే ఉందో లేదో తనిఖీ చేయండి. ఉంటే, క్యాష్ చేసిన ఫలితాన్ని తిరిగి ఇవ్వండి.
ట్రాన్సాక్షన్ (ఒకే SQLite ట్రాన్సాక్షన్): a. పంపినవారి బ్యాలెన్స్ను లెక్కించండి. b. balance < amount అయితే, రద్దు చేయండి (తగినంత నిధులు లేవు). c. పంపే వరుసను చొప్పించండి (from=sender,ను తిరిగి ఇవ్వండి.

రేట్ పరిమితి

ప్రతి API కీకి నిమిషానికి గరిష్ఠంగా 10 బదిలీలు.
ఒక్క బదిలీకి గరిష్ఠంగా 10,000 టోకెన్లు.
ప్రతి API కీకి రోజుకు గరిష్ఠంగా 100,000 టోకెన్ల బదిలీ.

ఆహ్వాన & రిడీమ్ టోకెన్లు

ఫైల్: src/lib/gamification/invites.ts

కోడ్ ఫార్మాట్

కోడ్: 8-అక్షరాల ఆల్ఫాన్యూమరిక్ కోడ్ (ఉదా., A3K9-X7M2), మనుషులు సులభంగా చదవగలిగేది, వినియోగదారుకు ప్రదర్శించబడుతుంది.
టోకెన్: 32-బైట్ యాదృచ్ఛిక టోకెన్, SHA-256 హ్యాష్గా నిల్వ చేయబడుతుంది. ప్రోగ్రామాటిక్ రిడెంప్షన్ కోసం ఉపయోగించబడుతుంది (ఉదా., URL లింకులు).

నిల్వ

కాలమ్	విలువ
`code`	`A3K9X7M2` (ప్రత్యేకం, ఇండెక్స్ చేయబడినది)
`token_hash`	SHA-256(raw_token)

ముడి టోకెన్ సృష్టించే సమయంలో సరిగ్గా ఒక్కసారి మాత్రమే వినియోగదారుకు తిరిగి ఇవ్వబడుతుంది. OmniRoute దాన్ని మళ్లీ ఎప్పుడూ నిల్వ చేయదు లేదా ప్రదర్శించదు — హ్యాష్ మాత్రమే కొనసాగుతుంది.

స్వీయ-రిఫరల్ నివారణ

ఒక వినియోగదారు కోడ్ను రిడీమ్ చేసినప్పుడు, సిస్టమ్ వీటిని తనిఖీ చేస్తుంది:

కోడ్ వేరే api_key_idకు చెందినది.
రిడీమ్ చేస్తున్న వినియోగదారు అదే రిఫరర్ నుండి ఇంతకు ముందు ఏ కోడ్నూ రిడీమ్ చేయలేదు (invite_tokens + రిడెంప్షన్ లాగ్పై జాయిన్ చేస్తుంది).

ఈ తనిఖీలలో ఏదైనా విఫలమైతే, స్పష్టమైన దోష సందేశంతో రిడెంప్షన్ తిరస్కరించబడుతుంది.

గడువు & పరిమితులు

డిఫాల్ట్ max_uses: 10 (సృష్టించే సమయంలో కాన్ఫిగర్ చేయవచ్చు).
డిఫాల్ట్ expires_at: సృష్టించిన తేదీ నుండి 30 రోజులు.
గడువు ముగిసిన లేదా వినియోగ పరిమితి పూర్తయిన కోడ్లు HTTP 410 Goneను తిరిగి ఇస్తాయి.

కమ్యూనిటీ సర్వర్ ఫెడరేషన్

ఫైల్: src/lib/gamification/servers.ts

కనెక్ట్ చేయడం

రిమోట్ సర్వర్ జారీ చేసిన ఆహ్వాన టోకెన్ ద్వారా కమ్యూనిటీ సర్వర్ నమోదు చేయబడుతుంది. లోకల్ ఇన్స్టాన్స్:

ఆహ్వాన టోకెన్ను స్వీకరిస్తుంది (ఉదా., డ్యాష్బోర్డ్లో పేస్ట్ చేసినది).
టోకెన్ను ధృవీకరించి, ప్రస్తుత లీడర్బోర్డ్ను పొందడానికి రిమోట్ సర్వర్లోని POST /api/gamification/federation/leaderboardను కాల్ చేస్తుంది.
సర్వర్ రికార్డును status: connectedతో నిల్వ చేస్తుంది.

సింక్ మోడల్

ఫెడరేషన్ ఓవర్రైట్ సింక్ను ఉపయోగిస్తుంది, అడిటివ్ సింక్ను కాదు:

లోకల్ ఇన్స్టాన్స్                కమ్యూనిటీ సర్వర్
     │                              │
     ├── స్కోర్ను పుష్ చేయి ─────►│  POST /federation/score
     │   { api_key_id, score }      │  (సర్వర్ టోకెన్ హాష్ను ధృవీకరిస్తుంది)
     │                              │
     ├── లీడర్బోర్డ్ను పుల్ చేయి ►│  GET /federation/leaderboard
     │◄── అగ్ర-N ఎంట్రీలు ─────────┤  (లోకల్ క్యాష్ను ఓవర్రైట్ చేస్తుంది)
     │                              │
     └── హెల్త్ చెక్ ──────────────►│  GET /federation/health
         (ప్రతి 60sకు, టైమ్అవుట్ 5s)│

ప్రమాణీకరణ

ఫెడరేషన్ అభ్యర్థనల్లో ఇవి ఉంటాయి:

Authorization: Bearer <raw_token>
X-Federation-Version: 1

రిమోట్ సర్వర్ టోకెన్ను హాష్ చేసి, సరిపోలే community_servers రోను వెతుకుతుంది. దీని వల్ల నిల్వ చేసిన హాష్ను ప్రసారం చేయాల్సిన అవసరం ఉండదు.

హెల్త్ మానిటరింగ్

ప్రతి సర్వర్ రికార్డు వీటిని ట్రాక్ చేస్తుంది:

ఫీల్డ్	వివరణ
`status`	`connected`, `degraded`, `unreachable`
`last_sync`	చివరిగా విజయవంతమైన సింక్ యొక్క ISO టైమ్స్టాంప్
`failures`	వరుసగా విఫలమైన హెల్త్ చెక్లు

వరుసగా 5 వైఫల్యాల తర్వాత, స్థితి unreachableకు మారుతుంది మరియు మాన్యువల్ హెల్త్ చెక్ విజయవంతమయ్యే వరకు సింక్ పాజ్ చేయబడుతుంది.

మోస నిరోధం

ఫైల్: src/lib/gamification/antiCheat.ts

సర్వర్-సైడ్ స్కోరింగ్

అన్ని XP లెక్కింపులు src/lib/gamification/xp.tsలో జరుగుతాయి. క్లయింట్లు ఎప్పుడూ స్కోర్ను సమర్పించరు — వారు చర్యలను సమర్పిస్తారు, సర్వర్ XPని లెక్కిస్తుంది. leaderboard.score కాలమ్ను సర్వర్-సైడ్ కోడ్ మాత్రమే రాయగలదు.

రేట్ లిమిటింగ్

పరిమితి	విలువ	పరిధి
నిమిషానికి గరిష్ఠ XP	1,000	ప్రతి API కీకి
నిమిషానికి గరిష్ఠ బదిలీలు	10	ప్రతి API కీకి
గరిష్ఠ బదిలీ మొత్తం	10,000	ప్రతి బదిలీకి
గరిష్ఠ రోజువారీ బదిలీలు	100,000	ప్రతి API కీకి

రేట్ లిమిట్లు ఇన్-మెమరీ స్లైడింగ్ విండోను ఉపయోగిస్తాయి (open-sse/services/లోని RateLimitManager మాదిరిగానే). ప్రాసెస్ రీస్టార్ట్ అయితే SQLite-ఆధారిత కౌంటర్లను ప్రత్యామ్నాయంగా ఉపయోగిస్తుంది.

Z-స్కోర్ అసాధారణత గుర్తింపు

ప్రతి API కీ కోసం, గంటకు సంపాదించిన XP యొక్క రోలింగ్ 7-రోజుల విండోను సిస్టమ్ నిర్వహిస్తుంది. ప్రతి XP ప్రదానం సమయంలో:

యూజర్ యొక్క ప్రస్తుత గంటవారీ XP రేటును లెక్కించండి.
పాప్యులేషన్ సగటు మరియు ప్రామాణిక విచలనాన్ని లెక్కించండి.
z = (user_rate - mean) / stddevను లెక్కించండి.
z > 3.0 (3 ప్రామాణిక విచలనాలు) అయితే, దాన్ని అసాధారణతగా ఫ్లాగ్ చేయండి.

అసాధారణతలు action = 'anomaly_detected'తో xp_audit_logలో లాగ్ చేయబడతాయి మరియు అడ్మిన్ డ్యాష్బోర్డ్లో చూపబడతాయి.

ఆడిట్ ట్రైల్

ప్రతి XP ప్రదానం, బదిలీ, బ్యాడ్జ్ సంపాదన మరియు అసాధారణత గుర్తింపు xp_audit_logలో ఈ వివరాలతో లాగ్ చేయబడుతుంది:

ఫీల్డ్	వివరణ
`api_key_id`	ఎవరు
`action`	ఏమి జరిగింది (xp_award, transfer, anomaly, …)
`xp_awarded`	మొత్తం (XP-యేతర ఈవెంట్లకు 0)
`metadata`	సందర్భంతో కూడిన JSON (చర్య రకం, లక్ష్యం, …)
`created_at`	ఎప్పుడు (ISO 8601)

అడ్మిన్లు GET /api/gamification/anomalies ద్వారా పూర్తి ఆడిట్ ట్రైల్ను క్వెరీ చేయవచ్చు.

API రూట్లు

అన్ని రూట్లు ప్రామాణిక OmniRoute నమూనాను అనుసరిస్తాయి:

రూట్ → CORS ప్రీఫ్లైట్ → బాడీ ధ్రువీకరణ (Zod) → ప్రమాణీకరణ (extractApiKey)
  → హ్యాండ్లర్

ఎండ్పాయింట్లు

పద్ధతి	పాత్	వివరణ	ప్రమాణీకరణ
GET	`/api/gamification/leaderboard`	లీడర్బోర్డ్ను పొందండి (పరిధి, కాలవ్యవధి, పేజినేషన్)	ఐచ్ఛికం
POST	`/api/gamification/leaderboard`	లీడర్బోర్డ్ క్యాష్ను బలవంతంగా రిఫ్రెష్ చేయండి	అవసరం
GET	`/api/gamification/stream`	SSE రియల్-టైమ్ లీడర్బోర్డ్ అప్డేట్లు	ఐచ్ఛికం
GET	`/api/gamification/transfer`	బదిలీ చరిత్రను పొందండి (పేజినేషన్)	అవసరం
POST	`/api/gamification/transfer`	మరొక వినియోగదారుకు టోకెన్లను పంపండి	అవసరం
GET	`/api/gamification/invite`	నా ఆహ్వాన కోడ్లను జాబితా చేయండి	అవసరం
POST	`/api/gamification/invite`	కొత్త ఆహ్వాన కోడ్ను రూపొందించండి	అవసరం
DELETE	`/api/gamification/invite`	ఆహ్వాన కోడ్ను ఉపసంహరించండి	అవసరం
POST	`/api/gamification/invite/redeem`	ఆహ్వాన కోడ్ను రిడీమ్ చేయండి	అవసరం
GET	`/api/gamification/servers`	కమ్యూనిటీ సర్వర్లను జాబితా చేయండి	అవసరం
POST	`/api/gamification/servers`	కమ్యూనిటీ సర్వర్కు కనెక్ట్ అవ్వండి	అవసరం
DELETE	`/api/gamification/servers`	కమ్యూనిటీ సర్వర్ నుండి డిస్కనెక్ట్ అవ్వండి	అవసరం
POST	`/api/gamification/federation/score`	స్కోర్ను రిమోట్ సర్వర్కు పంపండి	ఫెడరేషన్
GET	`/api/gamification/federation/leaderboard`	రిమోట్ సర్వర్ నుండి లీడర్బోర్డ్ను పొందండి	ఫెడరేషన్
GET	`/api/gamification/notifications`	SSE బ్యాడ్జ్/లెవల్-అప్ నోటిఫికేషన్లు	అవసరం
GET	`/api/gamification/anomalies`	అసాధారణత నివేదికలను వీక్షించండి (అడ్మిన్)	అడ్మిన్
POST	`/api/gamification/rotate`	ఆహ్వాన టోకెన్ సీక్రెట్లను రొటేట్ చేయండి	అవసరం

అభ్యర్థన/ప్రతిస్పందన ఉదాహరణలు

POST /api/gamification/transfer

// అభ్యర్థన
{
  "to": "recipient-api-key-id",
  "amount": 500,
  "idempotencyKey": "uuid-v4"
}

// ప్రతిస్పందన 200
{
  "success": true,
  "transfer": {
    "id": "txn-uuid",
    "from": "sender-api-key-id",
    "to": "recipient-api-key-id",
    "amount": 500,
    "createdAt": "2026-05-19T12:00:00.000Z"
  },
  "balance": 2500
}

// ప్రతిస్పందన 400 (తగినంత నిధులు లేవు)
{
  "error": "Insufficient balance",
  "balance": 200,
  "requested": 500
}

GET /api/gamification/leaderboard?scope=weekly&limit=10

{
  "scope": "weekly",
  "period": "2026-W20",
  "entries": [
    {
      "rank": 1,
      "apiKeyId": "key-uuid",
      "displayName": "User***1234",
      "score": 15230,
      "level": 42,
      "title": "Expert"
    }
  ],
  "total": 847,
  "updatedAt": "2026-05-19T12:00:00.000Z"
}

MCP సాధనాలు (8)

ఇప్పటికే ఉన్న సాధనాలతో పాటు open-sse/mcp-server/లో నమోదు చేయబడ్డాయి. ఇవి gamification అనుమతి పరిధికి పరిమితం చేయబడ్డాయి.

సాధనం	వివరణ	ఇన్పుట్ స్కీమా
`gamification_leaderboard`	ఒక పరిధి/కాలవ్యవధికి లీడర్బోర్డ్ను పొందండి	`{ scope, period?, limit? }`
`gamification_rank`	కాలర్ ర్యాంక్ మరియు సమీప ర్యాంకులను పొందండి	`{ scope }`
`gamification_profile`	XP, స్థాయి, బిరుదు, స్ట్రీక్ సారాంశాన్ని పొందండి	`{}`
`gamification_badges`	సాధించిన బ్యాడ్జ్లు లేదా అన్ని నిర్వచనాలను జాబితా చేయండి	`{ earned?: boolean }`
`gamification_transfer`	మరొక వినియోగదారుకు టోకెన్లను పంపండి	`{ to, amount }`
`gamification_invite`	ఆహ్వాన కోడ్లను రూపొందించండి లేదా జాబితా చేయండి	`{ action: "create"	"list" }`
`gamification_servers`	కమ్యూనిటీ సర్వర్లను జాబితా చేయండి లేదా కనెక్ట్ చేయండి	`{ action, token? }`
`gamification_anomalies`	అసాధారణత నివేదికలను వీక్షించండి (అడ్మిన్ పరిధి)	`{ limit?, since? }`

డ్యాష్బోర్డ్ పేజీలు

`/dashboard/leaderboard`

పోడియం ప్రదర్శన (అవతార్లు మరియు XPతో అగ్రస్థానంలోని 3 మంది).
పరిధి ఎంపిక: గ్లోబల్ / వారంవారీ / నెలవారీ / షేర్ చేసిన టోకెన్లు / సహకారాలు.
ర్యాంక్, పేరు, స్కోర్, స్థాయి, బిరుదుతో పేజీకి 25 అంశాలు ఉండే పేజినేట్ చేసిన పట్టిక.
SSE రియల్-టైమ్ అప్డేట్లు — ర్యాంక్ మార్పులు యానిమేషన్తో కనిపిస్తాయి.
పట్టికలో ప్రస్తుత వినియోగదారు "మీ ర్యాంక్" అనే స్థిర వరుసతో హైలైట్ చేయబడతారు.

`/dashboard/profile`

ప్రస్తుత స్థాయి మరియు తదుపరి స్థాయి థ్రెషోల్డ్తో XP పురోగతి పట్టీ.
బిరుదు బ్యాడ్జ్ ప్రముఖంగా ప్రదర్శించబడుతుంది.
బ్యాడ్జ్ గ్యాలరీ — సాధించిన తేదీతో సాధించిన బ్యాడ్జ్లు, సాధించని బ్యాడ్జ్లు బూడిద రంగులో (దాచిన బ్యాడ్జ్లు సాధించే వరకు "???"గా కనిపిస్తాయి).
మంట చిహ్నంతో స్ట్రీక్ కౌంటర్; స్ట్రీక్ క్యాలెండర్ (గత 30 రోజులు).
XP చరిత్ర చార్ట్ (గత 30 రోజుల రోజువారీ XP).

`/dashboard/tokens`

టోకెన్ బ్యాలెన్స్ (ప్రముఖంగా, పేజీ ఎగువన).
బదిలీ ఫారమ్: గ్రహీత, మొత్తం, నిర్ధారణ డైలాగ్.
ఫిల్టర్లతో బదిలీ చరిత్ర పట్టిక (పంపినవి/అందుకున్నవి/అన్నీ).
ఆహ్వాన విభాగం: క్రియాశీల కోడ్లు, కొత్తదాన్ని రూపొందించడం, లింక్ను షేర్ చేయడం.
కమ్యూనిటీ సర్వర్లు: ఆరోగ్య స్థితితో జాబితా, కనెక్ట్/డిస్కనెక్ట్.

`/dashboard/gamification/admin`

తీవ్రత, వినియోగదారు, టైమ్స్టాంప్, z-స్కోర్తో అసాధారణతల జాబితా.
ఫిల్టర్లతో ఆడిట్ లాగ్ వ్యూయర్ (చర్య రకం, వినియోగదారు, తేదీ పరిధి).
సిస్టమ్ గణాంకాలు: ప్రదానం చేసిన మొత్తం XP, క్రియాశీల వినియోగదారులు, బ్యాడ్జ్ సాధన రేట్లు.
ఫెడరేషన్ సర్వర్ ఆరోగ్య స్థితి సమగ్ర అవలోకనం.

పైప్లైన్ ఇంటిగ్రేషన్

ఇంటిగ్రేషన్ పాయింట్

గేమిఫికేషన్ open-sse/handlers/chatCore.tsలోని ఒకే పాయింట్ వద్ద అభ్యర్థన పైప్లైన్లో అనుసంధానమవుతుంది:

// ప్రతిస్పందనను క్లయింట్కు పంపిన తర్వాత:
setImmediate(() => {
  emitGamificationEvent({
    type: "request.completed",
    apiKeyId,
    metadata: {
      provider: selectedProvider,
      model: selectedModel,
      comboId: resolvedCombo?.id,
      compressionUsed: compressionStats?.applied,
      skillUsed: skillExecution?.name,
    },
  }).catch(() => {
    // అమలు చేసి వదిలేయండి: లాగ్ చేయండి, కానీ క్లయింట్కు ఎప్పుడూ పంపవద్దు
  });
});

ఈవెంట్ రకాలు

ఈవెంట్ రకం	ఎప్పుడు విడుదల చేయబడుతుంది
`request.completed`	విజయవంతమైన LLM ప్రతిస్పందన పంపబడినప్పుడు
`provider.switch`	ప్రొవైడర్ మారినప్పుడు (కాంబో ఫాల్బ్యాక్లు లెక్కించబడతాయి)
`combo.created`	కొత్త కాంబో కాన్ఫిగరేషన్ సేవ్ చేయబడినప్పుడు
`combo.used`	కాంబో లక్ష్యం విజయవంతంగా చేరుకున్నప్పుడు
`badge.earned`	బ్యాడ్జ్ మూల్యాంకనం సరిపోలికను కనుగొన్నప్పుడు
`streak.milestone`	స్ట్రీక్ థ్రెషోల్డ్ దాటినప్పుడు
`transfer.sent`	టోకెన్ బదిలీ పూర్తయినప్పుడు
`referral.redeemed`	ఆహ్వాన కోడ్ విజయవంతంగా రిడీమ్ చేయబడినప్పుడు
`compression.used`	ప్రాంప్ట్ కంప్రెషన్ వర్తింపజేసినప్పుడు
`skill.executed`	నైపుణ్య అమలు పూర్తయినప్పుడు
`model.first_use`	గత 7 రోజుల్లో మోడల్ ఉపయోగించబడనప్పుడు

నాన్-బ్లాకింగ్ హామీ

setImmediate + .catch(() => {}) నమూనా వీటిని నిర్ధారిస్తుంది:

గేమిఫికేషన్ అమలయ్యే ముందు ప్రతిస్పందన పూర్తిగా పంపబడుతుంది.
గేమిఫికేషన్ లోపాలు ఎప్పుడూ క్లయింట్కు చేరవు.
ఈవెంట్ ప్రాసెసింగ్ ఇన్లైన్లో కాకుండా తదుపరి మైక్రోటాస్క్లో నడుస్తుంది.

భద్రత

ముప్పు నమూనా

ముప్పు	నివారణ
స్కోర్ను కృత్రిమంగా పెంచడం	సర్వర్ వైపు మాత్రమే XP గణన; క్లయింట్లు స్కోర్లను కాకుండా చర్యలను సమర్పిస్తారు
రీప్లే దాడులు	బదిలీలపై ఐడెంపొటెన్సీ కీలు; ఆడిట్ లాగ్ డీడూప్లికేషన్
బదిలీ మోసం	డబుల్-ఎంట్రీ లెడ్జర్; అటామిక్ లావాదేవీలు; రేట్ పరిమితులు
స్వీయ-రిఫరల్	రిడెంప్షన్ సమయంలో `api_key_id`ను క్రాస్-చెక్ చేయడం
లీడర్బోర్డ్ తారుమారు	Z-స్కోర్ అసాధారణత గుర్తింపు; అడ్మిన్ అసాధారణత డ్యాష్బోర్డ్
ఫెడరేషన్ టోకెన్ దొంగతనం	SHA-256 హ్యాష్ చేసిన నిల్వ; ముడి టోకెన్ను ఒక్కసారి మాత్రమే చూపించడం
ఆహ్వాన కోడ్లపై బ్రూట్ ఫోర్స్	రిడెంప్షన్ ఎండ్పాయింట్పై రేట్ పరిమితి; 8-అక్షరాల ఎంట్రోపీ
ప్రదర్శన పేర్లలో XSS	ప్రదర్శన పేర్ల శుద్ధీకరణ; లీడర్బోర్డ్ ఎంట్రీల ఎస్కేపింగ్
హ్యాష్లపై టైమింగ్ దాడులు	టోకెన్ హ్యాష్ పోలిక కోసం `crypto.timingSafeEqual`

ప్రామాణీకరణ అవసరాలు

పబ్లిక్ (ప్రామాణీకరణ అవసరం లేదు): GET /leaderboard, GET /stream (చదవడానికి మాత్రమే అనుమతించే లీడర్బోర్డ్లు).
API కీ అవసరం: అన్ని రైట్ ఆపరేషన్లు, ప్రొఫైల్, బదిలీలు, ఆహ్వానాలు.
అడ్మిన్కు మాత్రమే: అసాధారణత డ్యాష్బోర్డ్, ఆడిట్ లాగ్ వ్యూయర్.
ఫెడరేషన్: Authorization హెడర్లో ముడి టోకెన్ను ఉపయోగించే ప్రత్యేక ప్రామాణీకరణ మార్గం; నిల్వ చేసిన SHA-256 హ్యాష్తో ధృవీకరించబడుతుంది.

పరీక్ష

పరీక్ష ఫైళ్లు

అన్ని పరీక్షలు Node.js స్థానిక టెస్ట్ రన్నర్ను (node --import tsx/esm --test) ఉపయోగిస్తాయి.

పరీక్ష ఫైల్	పరీక్షించే అంశాలు	పరీక్షలు
`tests/unit/gamification/xp.test.ts`	XP గణన, లెవల్ కర్వ్, బిరుదులు	8
`tests/unit/gamification/badges.test.ts`	బ్యాడ్జ్ ప్రమాణాల సరిపోలిక, ప్రదానం	10
`tests/unit/gamification/streaks.test.ts`	స్ట్రీక్ లాజిక్, మైలురాళ్లు, ఎడ్జ్ కేసులు	7
`tests/unit/gamification/leaderboard.test.ts`	ర్యాంక్ గణన, పేజినేషన్, రొటేషన్	8
`tests/unit/gamification/sharing.test.ts`	బదిలీలు, బ్యాలెన్స్, ఐడెంపొటెన్సీ	9
`tests/unit/gamification/invites.test.ts`	సృష్టి, రిడీమ్ చేయడం, గడువు ముగింపు, స్వీయ-రిఫరల్	7
`tests/unit/gamification/antiCheat.test.ts`	రేట్ పరిమితులు, z-స్కోర్, ఆడిట్ లాగింగ్	6
`tests/unit/gamification/events.test.ts`	ఈవెంట్ ఉద్గారం, ఫ్యాన్-అవుట్, లోప నిర్వహణ	5

పరీక్షలను అమలు చేయడం

# అన్ని గేమిఫికేషన్ పరీక్షలు
node --import tsx/esm --test tests/unit/gamification/*.test.ts

# ఒకే పరీక్ష ఫైల్
node --import tsx/esm --test tests/unit/gamification/xp.test.ts

కవరేజ్ అవసరాలు

CONTRIBUTING.md ప్రకారం — అన్ని కొత్త మాడ్యూల్లు కింది వాటిని కలిగి ఉండాలి:

బ్రాంచ్ కవరేజ్ >= 80%.
ప్రతి పబ్లిక్ ఫంక్షన్ను కనీసం ఒక్కసారైనా పరీక్షించాలి.
లోప మార్గాలను పరీక్షించాలి (సరిపోని బ్యాలెన్స్, గడువు ముగిసిన కోడ్లు, రేట్ పరిమితులు).

ఫైల్ నిర్మాణం

src/
  lib/
    db/
      migrations/
        060_create_gamification.sql    # మొత్తం 8 పట్టికలు + సూచికలు
      gamification.ts                  # డొమైన్ CRUD మాడ్యూల్
    gamification/
      xp.ts                           # XP గణన, స్థాయి వక్రరేఖ, బిరుదులు
      badges.ts                       # బ్యాడ్జ్ నిర్వచనాలు, ప్రమాణాలు, మూల్యాంకనం
      streaks.ts                      # రోజువారీ పరంపర ట్రాకింగ్
      leaderboard.ts                  # ర్యాంక్ గణన, SSE, రొటేషన్
      antiCheat.ts                    # రేటు పరిమితి, z-score, ఆడిట్
      sharing.ts                      # టోకెన్ బదిలీ లెడ్జర్
      invites.ts                      # ఆహ్వాన/రిడీమ్ కోడ్లు
      servers.ts                      # కమ్యూనిటీ సర్వర్ ఫెడరేషన్
      events.ts                       # ఈవెంట్ ఎమిటర్ (ఇంటిగ్రేషన్ పాయింట్)
      notifications.ts                # SSE నోటిఫికేషన్ స్ట్రీమ్
  app/
    api/
      gamification/
        leaderboard/route.ts          # GET/POST లీడర్బోర్డ్
        leaderboard/stream/route.ts   # SSE రియల్-టైమ్ అప్డేట్లు
        transfer/route.ts             # GET/POST బదిలీలు
        invite/route.ts               # GET/POST/DELETE ఆహ్వాన కోడ్లు
        invite/redeem/route.ts        # POST రిడీమ్ కోడ్
        servers/route.ts              # GET/POST/DELETE సర్వర్లు
        federation/score/route.ts     # POST స్కోర్ను పుష్ చేయడం
        federation/leaderboard/route.ts # GET లీడర్బోర్డ్ను పుల్ చేయడం
        notifications/route.ts        # SSE నోటిఫికేషన్లు
        anomalies/route.ts            # GET అసాధారణత నివేదికలు
        rotate/route.ts               # POST రహస్యాలను రొటేట్ చేయడం
    (dashboard)/
      dashboard/
        leaderboard/page.tsx           # ర్యాంకింగ్ల పేజీ
        profile/page.tsx               # XP/బ్యాడ్జ్లు/పరంపరల పేజీ
        tokens/page.tsx                # బ్యాలెన్స్/బదిలీలు/ఆహ్వానాల పేజీ
        gamification/admin/page.tsx    # అడ్మిన్ అసాధారణత పర్యవేక్షణ
  shared/
    constants/
      gamification.ts                  # XP_REWARDS, TITLES, BADGE_DEFS, LIMITS

tests/
  unit/
    gamification/
      xp.test.ts
      badges.test.ts
      streaks.test.ts
      leaderboard.test.ts
      sharing.test.ts
      invites.test.ts
      antiCheat.test.ts
      events.test.ts

docs/
  frameworks/
    GAMIFICATION.md                    # ఈ పత్రం

మైగ్రేషన్ వ్యూహం

దశ 1: బ్యాకెండ్ కోర్ (PR 1)

మైగ్రేషన్ 060_create_gamification.sql (8 పట్టికలు).
src/lib/db/gamification.ts (డొమైన్ మాడ్యూల్).
src/lib/gamification/xp.ts, streaks.ts, events.ts.
chatCore.tsలో ఇంటిగ్రేషన్ పాయింట్.
XP, పరంపరలు, ఈవెంట్ల కోసం యూనిట్ పరీక్షలు.

దశ 2: బ్యాడ్జ్లు & లీడర్బోర్డ్ (PR 2)

src/lib/gamification/badges.ts, leaderboard.ts.
స్థిరాంకాలలో బ్యాడ్జ్ నిర్వచనాలు.
లీడర్బోర్డ్ API రూట్లు + SSE స్ట్రీమ్.
బ్యాడ్జ్లు, లీడర్బోర్డ్ కోసం యూనిట్ పరీక్షలు.

దశ 3: భాగస్వామ్యం & ఆహ్వానాలు (PR 3)

src/lib/gamification/sharing.ts, invites.ts, antiCheat.ts.
బదిలీ + ఆహ్వాన API రూట్లు.
భాగస్వామ్యం, ఆహ్వానాలు, మోస నిరోధం కోసం యూనిట్ పరీక్షలు.

దశ 4: ఫెడరేషన్ & డ్యాష్బోర్డ్ (PR 4)

src/lib/gamification/servers.ts, notifications.ts.
ఫెడరేషన్ API రూట్లు.
డ్యాష్బోర్డ్ పేజీలు (లీడర్బోర్డ్, ప్రొఫైల్, టోకెన్లు, అడ్మిన్).
MCP సాధనాల నమోదు.

భవిష్యత్ పరిశీలనలు

సీజనల్ ఈవెంట్లు: పరిమిత కాల బ్యాడ్జ్ సెట్లు మరియు లీడర్బోర్డ్ సీజన్లు.
టీమ్ లీడర్బోర్డ్లు: సంస్థ లేదా కాంబో ఆధారంగా వినియోగదారులను సమూహపరచడం.
XP మల్టిప్లయర్లు: ప్రచార వ్యవధుల్లో XPని పెంచడం.
అచీవ్మెంట్ షేరింగ్: షేర్ చేయగల బ్యాడ్జ్ కార్డ్లను (OpenGraph చిత్రాలు) రూపొందించడం.
మొబైల్ పుష్: బ్యాడ్జ్/లెవల్ ఈవెంట్ల కోసం webhook-ఆధారిత నోటిఫికేషన్లు.
లీడర్బోర్డ్ API: మూడవ పక్ష ఇంటిగ్రేషన్ల కోసం పబ్లిక్ API.

85 KiB Raw Blame History Unescape Escape