added more documentation

2026-09-13 22:10:34 +02:00
parent dd4d6e4817
commit 6e3e1620d1
7 changed files with 1020 additions and 669 deletions
@@ -0,0 +1,200 @@
+# ShaiBot Profiles, Achievements & Badges
+
+ShaiBot's profile system is the permanent progression layer behind the
+economy and games.
+
+## Central Profile System
+
+`utils/profileSystem.js` owns the main profile/progression behavior.
+
+Important collections:
+
+``` text
+stats_profiles
+items_achievements
+guild_badges
+config_achievements
+```
+
+Game modules should integrate with this system instead of creating
+separate progression databases.
+
+## Profiles
+
+Profiles can track:
+
+-   Overall game totals
+-   Per-game statistics
+-   Cookie gains and losses
+-   Giving and stealing
+-   Daily activity
+-   Win/loss streaks
+-   Weekday/time-of-day activity
+-   Social relationships
+-   Run It Back progression
+-   Poker history
+-   Achievement progress
+-   Badge ownership
+
+Profiles are intended to preserve meaningful long-term history.
+
+## Profile Events
+
+Prefer extending established event metadata rather than inventing
+parallel event systems.
+
+Common concepts include:
+
+``` text
+game_start
+game_result
+cookie_gain
+cookies_given
+steal_success
+stolen_from_me
+```
+
+New wager metadata should prefer:
+
+``` text
+wager
+```
+
+Compatibility reads for older `bet`/`previousBet` fields may remain
+intentionally.
+
+## Activity
+
+Profile activity uses a configured timezone.
+
+Default:
+
+``` text
+Europe/Berlin
+```
+
+Activity supports daily streaks, weekly participation, weekday counts,
+and broad time buckets.
+
+Avoid making ordinary progression depend on excessively narrow
+late-night windows.
+
+## Social Progression
+
+Profiles can store unique relationship sets for gifting and stealing.
+
+Use set-style updates for unique users rather than appending duplicates.
+
+Current social progression is intentionally scaled for a relatively
+small community.
+
+## Achievements
+
+Achievements are personal: multiple players can earn the same
+achievement.
+
+Supported models include:
+
+### Stat-backed
+
+Best for durable lifetime milestones and reconciliation.
+
+### Composite
+
+Combines multiple durable conditions.
+
+### Event-only
+
+Used when the accomplishment depends on exact event context that cannot
+reliably be reconstructed later.
+
+### Hidden
+
+Used for secret/special challenges.
+
+Event-only achievements should not be treated as historically
+backfillable when the necessary event was never stored.
+
+## Achievement Notifications
+
+Unlock notification is centralized.
+
+Individual games should not create competing achievement announcement
+systems.
+
+## Global Badges
+
+Global badges are guild-unique distinctions.
+
+The common pattern is an atomic claim against an unowned badge:
+
+``` text
+guildId
+badgeId
+ownerId: null
+```
+
+then setting the winner.
+
+This prevents simultaneous candidates from both owning the same
+guild-first badge.
+
+Achievements and badges are intentionally different:
+
+``` text
+Achievement → personal; many owners
+Global badge → guild-unique; one owner
+```
+
+## ID Stability
+
+Once achievement or badge IDs may exist in MongoDB, treat them as
+persistent database identifiers.
+
+Prefer retiring an old definition over renaming/deleting an ID that
+players may already own.
+
+## Reconciliation & Audit
+
+Administrative tooling includes:
+
+``` text
+/profileadmin audit
+/profileadmin reconcile dry-run:true
+```
+
+Reconciliation can backfill durable/stat-backed accomplishments.
+
+Event-only achievements may be skipped because historical event context
+cannot be invented safely.
+
+When changing progression schemas:
+
+-   use idempotent migrations
+-   preserve existing values
+-   preserve historical IDs
+-   dry-run reconciliation first
+-   do not fabricate data that was never tracked
+
+## Poker History
+
+Poker stores permanent statistics in the profile system rather than
+retaining completed raw table documents.
+
+Examples include:
+
+-   hands played/won/lost
+-   Cookies won/lost
+-   largest pot
+-   All-Ins
+-   showdowns
+-   action counts
+-   streaks
+-   hand-rank counters
+-   pocket Aces wins
+-   7-2 wins
+-   fold wins
+-   full-table wins
+
+Poker profile tracking occurs after authoritative game state succeeds. A
+profile failure must never corrupt a valid pot/economy settlement.