OmniRoute/docs/i18n/am/docs/frameworks/GAMIFICATION.md

Gamification & Leaderboard System (አማርኛ)

🌐 Languages: 🇺🇸 English · 🇸🇦 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 · 🇮🇳 te · 🇹🇭 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 ያግኙ፤ በፖሊኖሚያል ኩርባ መሠረት ደረጃ ያድጉ
ባጆች	በ5 ምድቦች እና በ4 የብርቅነት እርከኖች የተከፋፈሉ ከ20 በላይ ስኬቶች
ተከታታይ ቀናት	የአሁኑን/ረጅሙን ተከታታይነት የሚያሳይ የዕለታዊ ንቁ አጠቃቀም ክትትል
የደረጃ ሰንጠረዦች	ዓለም አቀፍ፣ ሳምንታዊ፣ ወርሃዊ፣ የቶከን ማጋራት እና የአስተዋጽኦ ወሰኖች
የቶከን ማጋራት	ባለሁለት መዝገብ ደብተር በመጠቀም በተጠቃሚዎች መካከል ክሬዲቶችን ማስተላለፍ
ግብዣ እና ማስመለስ	በSHA-256 የተሰናዳ ማከማቻ ያላቸው የሪፈራል ኮዶች
የማህበረሰብ ሰርቨሮች	ከውጫዊ OmniRoute ኢንስታንሶች ጋር ፌዴሬሽን ማድረግ
ጸረ-ማጭበርበር	የሰርቨር-ወገን ነጥብ አሰጣጥ፣ የፍጥነት ገደብ፣ የz-score ያልተለመደ ሁኔታ ማወቂያ

የንድፍ መርሆዎች

1. አካባቢያዊነትን ቅድሚያ የሚሰጥ — ሁሉም ሁኔታ በSQLite ውስጥ ይገኛል፣ ምንም ውጫዊ አገልግሎት አያስፈልግም።
2. የማያግድ — ክስተቶች ምላሽ ሳይጠብቁ ይላካሉ፤ የLLM ምላሽ መንገድ በጨዋታ ማበረታቻ አመክንዮ ፈጽሞ አይዘገይም።
3. በሰርቨር የሚተዳደር — XP የሚሰላው በሰርቨር ወገን ብቻ ነው፤ ደንበኞች ነጥቦችን በማጋነን ማሳደግ አይችሉም።
4. ግላዊነትን የሚያከብር — በደረጃ ሰንጠረዥ ውስጥ መሳተፍ በምርጫ ነው፤ ተጠቃሚዎች መገለጫቸውን መደበቅ ይችላሉ።
5. ለፌዴሬሽን ዝግጁ — የማህበረሰብ ሰርቨሮች በተፈረመ 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 የግብዣ ቶከን ምስጢሮችን ማዞር

---

የውሂብ ንብርብር

የውሂብ ጎታ ሰንጠረዦች

ሁሉም ሰንጠረዦች በማይግሬሽን 060_create_gamification.sql በተፈጠረው ዋናው OmniRoute SQLite የውሂብ ጎታ ውስጥ ይገኛሉ። የWAL ጆርናሊንግ ከsrc/lib/db/core.ts ውስጥ ካለው singleton 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 ንድፍ ይከተላል — getDbInstance()ን ከcore.ts ያስገባል፣ ዓይነት የተወሰነላቸውን CRUD ፈንክሽኖችም ወደ ውጭ ይልካል። በመስመር አስተናጋጆች ውስጥ ቀጥተኛ SQL የለም።

ቁልፍ ፈንክሽኖች፦

ፈንክሽን	መግለጫ
upsertLeaderboardEntry()	ለ(api_key_id, scope, period) ውጤት ያስገባል ወይም ያዘምናል
getLeaderboard()	ለተወሰነ scope/period በገጽ የተከፋፈሉ ደረጃዎች
getUserLevel()	የተጠቃሚ ደረጃ መዝገብን ያገኛል ወይም ይፈጥራል
updateUserLevel()	XPን፣ ደረጃን እና ርዕስን በአንድ አቶሚክ ክዋኔ ያዘጋጃል
getBadgeDefinitions()	ሁሉም የባጅ ትርጓሜዎች (በአማራጭ የተጣሩ)
getUserBadges()	በተጠቃሚ የተገኙ ባጆች
awardBadge()	የባጅ ማግኘትን ያስገባል (በbadge_id ላይ idempotent)
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 }>;

1. የXP መጠኑን ለማግኘት XP_REWARDS[action]ን ይፈልጉ።
2. በcheckRateLimit() ውስጥ ያሳልፉ (ማጭበርበርን ለመከላከል፦ ለእያንዳንዱ ቁልፍ በደቂቃ ከፍተኛው 1000 XP)።
3. ግብይት ይክፈቱ፦
   • የአሁኑን user_levels ረድፍ ያንብቡ።
   • XP ይጨምሩ፤ levelFromXp(totalXp)ን በመጠቀም ደረጃውን እንደገና ያስሉ።
   • ደረጃው ከተቀየረ፣ levelUp = true ያድርጉ።
   • የuser_levels ረድፉን ያዘምኑ።
   • ወደ xp_audit_log ያስገቡ።
4. ውጤቱን ይመልሱ። ጠሪው ማሳወቂያዎችን ያስተናግዳል።

ረዳት፦ levelFromXp(totalXp)

በደረጃ 1..100 ውስጥ እየዞረ፣ ድምር XPው totalXpን እስኪያልፍ ድረስ xp_for_level(n)ን ይደምራል። መጠነ-ገደቡን ያሟላውን ከፍተኛውን ደረጃ ይመልሳል። ይህ O(100) ነው — ደረጃዎች በ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)
         → የማሳወቂያውን payload መልስ

ግምገማው በክስተት የሚነሳ ነው — ከእያንዳንዱ የጨዋታ ማበረታቻ ክስተት በኋላ ይሰራል፣ ነገር ግን 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 }>;

1. የተከታታይነት መዝገቡን ከkey_value ያንብቡ።
2. {current}ን፣ {longest}ን እና {lastDate}ን (የISO ቀን ሕብረቁምፊ) ይተንትኑ።
3. lastDate === today ከሆነ — ምንም ለውጥ የለም (ዛሬ አስቀድሞ ተቆጥሯል)።
4. lastDate === yesterday ከሆነ — currentን በአንድ ይጨምሩ፤ አስፈላጊ ከሆነ longestን ያዘምኑ።
5. lastDate < yesterday ከሆነ — current = 1 በማድረግ ዳግም ያስጀምሩ (ተከታታይነቱ ተቋርጧል)።
6. የዘመነውን መዝገብ ይጻፉ።
7. የደረጃ ምዕራፎችን ያረጋግጡ፦ 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 ?

የጊዜ ሽግግር

ሳምንታዊ እና ወርሃዊ የደረጃ ሰንጠረዦች በራስ-ሰር ይሸጋገራሉ፦

1. መዝገብ ቤት፦ በጊዜው ወሰን ላይ፣ የአሁኑን ግቤቶች ከጊዜ መለያው ጋር ወደ leaderboard_archive ይቅዱ።
2. ዳግም ማስጀመር፦ ጊዜው ላለፈበት ወቅት የሚገኙ ግቤቶችን ይሰርዙ።
3. አስጀማሪ፦ በእያንዳንዱ 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 }>;

1. አረጋግጥ፦ amount > 0፣ fromKeyId !== toKeyId።
2. Idempotency፦ idempotency_key አስቀድሞ በሂሳብ መዝገቡ ውስጥ መኖሩን ያረጋግጡ። ካለ፣ በመሸጎጫ የተቀመጠውን ውጤት ይመልሱ።
3. ግብይት (አንድ የ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 ከዚያ በኋላ ፈጽሞ አያከማቸውም ወይም አያሳየውም — የሚቆየው ሃሹ ብቻ ነው።

ራስን ሪፈር ማድረግን መከላከል

አንድ ተጠቃሚ ኮድን ሲቤዥ፣ ሥርዓቱ የሚከተሉትን ያረጋግጣል፦

1. ኮዱ የተለየ api_key_id ንብረት ነው።
2. ቶከኑን የሚቤዠው ተጠቃሚ ከዚያው ሪፈር አድራጊ የመጣ ማንኛውንም ኮድ ከዚህ በፊት አልተጠቀመም (invite_tokens + የመቤዠት መዝገብ ላይ በማገናኘት)።

ከሁለቱ ማረጋገጫዎች አንዱ ካልተሳካ፣ መቤዠቱ ግልጽ የስህተት መልዕክት በመስጠት ውድቅ ይደረጋል።

የማለቂያ ጊዜ እና ገደቦች

• ነባሪ max_uses፦ 10 (በሚፈጠርበት ጊዜ ሊዋቀር ይችላል)።
• ነባሪ expires_at፦ ከተፈጠረበት ጊዜ ጀምሮ 30 ቀናት።
• ጊዜያቸው ያለፈ ወይም የአጠቃቀም ገደባቸው ያለቀ ኮዶች HTTP 410 Gone ይመልሳሉ።

---

የማህበረሰብ አገልጋይ ፌዴሬሽን

ፋይል፦ src/lib/gamification/servers.ts

ማገናኘት

የማህበረሰብ አገልጋይ በርቀት አገልጋዩ በሚሰጥ የግብዣ ቶከን አማካኝነት ይመዘገባል። የአካባቢው ኢንስታንስ፦

1. የግብዣ ቶከኑን ይቀበላል (ለምሳሌ፣ በዳሽቦርዱ ውስጥ የተለጠፈ)።
2. ቶከኑን ለማረጋገጥና የአሁኑን የደረጃ ሰንጠረዥ ለማምጣት በርቀት አገልጋዩ ላይ POST /api/gamification/federation/leaderboardን ይጠራል።
3. የአገልጋዩን መዝገብ ከstatus: connected ጋር ያከማቻል።

የማመሳሰል ሞዴል

ፌዴሬሽኑ መደመርን ሳይሆን በላዩ ላይ የመጻፍ ማመሳሰልን ይጠቀማል፦

የአካባቢ ኢንስታንስ                    የማህበረሰብ አገልጋይ
     │                              │
     ├── ውጤት ግፋ ─────────────────►│  POST /federation/score
     │   { api_key_id, score }      │  (አገልጋዩ የቶከኑን ሃሽ ያረጋግጣል)
     │                              │
     ├── የደረጃ ሰንጠረዥ ሳብ ─────────►│  GET /federation/leaderboard
     │◄── ከፍተኛ-N ግቤቶች ────────────┤  (በአካባቢው መሸጎጫ ላይ ደርቦ ይጽፋል)
     │                              │
     └── የጤና ፍተሻ ────────────────►│  GET /federation/health
         (በየ60 ሰከንዱ፣ የጊዜ ገደብ 5 ሰከንድ) │

ማረጋገጫ

የፌዴሬሽን ጥያቄዎች የሚከተሉትን ያካትታሉ፦

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 ሽልማት፦

1. የተጠቃሚውን የአሁኑ የሰዓት XP መጠን አስላ።
2. የሕዝቡን አማካይ እና መደበኛ ልዩነት አስላ።
3. z = (user_rate - mean) / stddevን አስላ።
4. z > 3.0 ከሆነ (3 መደበኛ ልዩነቶች)፣ እንደ እንግዳ ሁኔታ ምልክት አድርግበት።

እንግዳ ሁኔታዎች በxp_audit_log ውስጥ ከaction = 'anomaly_detected' ጋር ይመዘገባሉ፣ እናም በአስተዳዳሪው ዳሽቦርድ ላይ ይታያሉ።

የኦዲት መከታተያ

እያንዳንዱ የ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

• የመድረክ ማሳያ (ከፍተኛዎቹ 3 ከአምሳያዎች እና XP ጋር)።
• የወሰን መራጭ፦ ዓለም አቀፍ / ሳምንታዊ / ወርሃዊ / የተጋሩ ቶከኖች / አስተዋጽኦዎች።
• ደረጃ፣ ስም፣ ውጤት፣ እርከን እና ማዕረግ ያለው በገጽ የተከፋፈለ ሰንጠረዥ (በእያንዳንዱ ገጽ 25)።
• የSSE ቅጽበታዊ ዝማኔዎች — የደረጃ ለውጦች በእነማ ይታያሉ።
• የአሁኑ ተጠቃሚ በሰንጠረዡ ውስጥ ከተለጣፊ "የእርስዎ ደረጃ" ረድፍ ጋር ጎላ ተደርጎ ይታያል።

/dashboard/profile

• የአሁኑን ደረጃ እና የቀጣዩን ደረጃ ገደብ የሚያሳይ የXP ሂደት አሞሌ።
• የማዕረግ ባጅ ጎልቶ ይታያል።
• የባጅ ማዕከለ-ስዕላት — የተገኙ ባጆች ከተገኙበት ቀን ጋር፤ ያልተገኙ ባጆች ግራጫ ሆነው ይታያሉ (የተደበቁ ባጆች እስኪገኙ ድረስ "???" ያሳያሉ)።
• የተከታታይነት ቆጣሪ ከእሳት አዶ ጋር፤ የተከታታይነት ቀን መቁጠሪያ (ያለፉት 30 ቀናት)።
• የXP ታሪክ ገበታ (ባለፉት 30 ቀናት የዕለት XP)።

/dashboard/tokens

• የቶከን ቀሪ ሂሳብ (ጎልቶ፣ በገጹ አናት ላይ)።
• የዝውውር ቅጽ፦ ተቀባይ፣ መጠን፣ የማረጋገጫ መገናኛ ሳጥን።
• የዝውውር ታሪክ ሰንጠረዥ ከማጣሪያዎች ጋር (የተላኩ/የተቀበሉ/ሁሉም)።
• የግብዣ ክፍል፦ ንቁ ኮዶች፣ አዲስ ማመንጨት፣ አገናኝ ማጋራት።
• የማህበረሰብ ሰርቨሮች፦ ከጤና ሁኔታ ጋር ዝርዝር፣ ማገናኘት/ማቋረጥ።

/dashboard/gamification/admin

• ያልተለመዱ ሁኔታዎች ዝርዝር ከክብደት፣ ተጠቃሚ፣ የጊዜ ማህተም እና z-score ጋር።
• የኦዲት ምዝግብ ማሳያ ከማጣሪያዎች ጋር (የድርጊት ዓይነት፣ ተጠቃሚ፣ የቀን ክልል)።
• የስርዓት ስታቲስቲክስ፦ ጠቅላላ የተሰጠ 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 አማራጭ መመለስ ይቆጠራል)
combo.created	አዲስ የcombo ውቅር ሲቀመጥ
combo.used	የcombo ዒላማ በተሳካ ሁኔታ ሲደረስበት
badge.earned	የባጅ ግምገማ ተዛማጅ ሲያገኝ
streak.milestone	የተከታታይነት ገደብ ሲታለፍ
transfer.sent	የቶከን ዝውውር ሲጠናቀቅ
referral.redeemed	የግብዣ ኮድ በተሳካ ሁኔታ ሲወሰድ
compression.used	የጥያቄ መጭመቅ ሲተገበር
skill.executed	የክህሎት አፈጻጸም ሲጠናቀቅ
model.first_use	ሞዴሉ ባለፉት 7 ቀናት ጥቅም ላይ ያልዋለ ሲሆን

የማያግድ ዋስትና

የsetImmediate + .catch(() => {}) ንድፍ የሚከተሉትን ያረጋግጣል፦

1. የጨዋታ ማበረታቻው ከመሥራቱ በፊት ምላሹ ሙሉ በሙሉ ይላካል።
2. የጨዋታ ማበረታቻ ስህተቶች ፈጽሞ ለደንበኛው አይታዩም።
3. የክስተት ሂደቱ በቀጣዩ microtask ውስጥ እንጂ inline አይሠራም።

---

ደህንነት

የስጋት ሞዴል

ስጋት	መከላከያ
የውጤት መጨመር	የXP ስሌት በሰርቨር በኩል ብቻ ይከናወናል፤ ደንበኞች የሚያስገቡት ድርጊቶችን እንጂ ውጤቶችን አይደለም
የድጋሚ ማጫወት ጥቃቶች	በዝውውሮች ላይ የኢዴምፖተንሲ ቁልፎች፤ የኦዲት ምዝግብ ድግግሞሽ ማስወገድ
የዝውውር ማጭበርበር	ድርብ-ምዝገባ ሌጀር፤ አቶሚክ ግብይቶች፤ የፍጥነት ገደቦች
ራስን መጋበዝ	በመቀየሪያ ጊዜ api_key_idን ተሻጋሪ ማረጋገጥ
የደረጃ ሰሌዳ ማጭበርበር	በZ-score የልዩነት ማወቂያ፤ የአስተዳዳሪ ልዩነት ዳሽቦርድ
የፌዴሬሽን ቶከን ስርቆት	በ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-score፣ የኦዲት ምዝግብ	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።