feat(enakgame): game sessions, rewards, vouchers, budgets and events

EnakGame phases 1-8 of docs/tasks-enakgame.md (EG-101 to EG-803), built on the existing EnakPoint/EnakCoin wallet (docs/rfc-enakgame.md). Foundation (phase 1) - Migrations 000103-000106: games extended with organization, slug, status, entry cost and result rules, old games archived (not deleted); budgets, versioned reward configs, sessions and session rewards; the ledger types GAME_SPEND_REFUND, GAME_REWARD and REWARD_REDEEM_REFUND; audit_logs. - AuditLogger writes in the caller's transaction only. - enakgame.limit.user_daily and global_daily organization settings. Games and sessions (phases 2-4) - Admin /marketing/enakgame: games, reward config versions (immutable but for status, one ACTIVE per game), budgets with non-overlapping global periods and a daily job opening the next month. - Customer /customer/enakgame: start (Idempotency-Key, entry cost and config frozen on the session), complete (result validation, reward engine, max_reward cap, daily limits via game_reward_counters, one GAME_REWARD per budget), automatic refunds for system errors and deactivated games, and a session job. - Reward engine: FIXED, SCORE_BASED, OUTCOME_BASED, PROBABILITY (crypto/rand), rounded down. Vouchers and budgets (phases 5-6) - Migration 000108 and 000107: vouchers, codes, redemptions, cost attribution; Economy Guard counters. - STATIC and CODE_POOL redemption in one transaction with the REDEEM PIN action; realized cost traced through the lots to the budget that paid the reward. - Budget metrics: realized cost, forecast, exposure and status. Migrations 000109-000110 add the wallet_lots indexes they need, built CONCURRENTLY. Events (phase 7) - Migration 000111: game events, each with its own EVENT budget. Event extras stack per PRD §16 defaults, with event and per-customer limits. External vouchers (phase 8) - VoucherProvider contract, two-step PENDING redemption and a recovery job, tested with a fake provider. No provider adapter is registered yet, so EXTERNAL vouchers stay out of the catalog. Not yet decided before release: reward rounding, event stacking, budget exhaustion policy and thresholds (RFC §19.2). Migrations 000103-000111 have not been run on any shared database. Also fixes a leftover PAYMENT filter in a wallet test and a data race in a test PIN fake. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 20:53:14 +07:00
parent 2c9753fae7
commit 798a36bd6c
92 changed files with 12392 additions and 23 deletions
@@ -0,0 +1,120 @@
+-- EnakGame budgets, reward configurations and sessions (docs/rfc-enakgame.md §5.2,
+-- §5.3, §5.4, §5.6), in foreign key order.
+
+-- What an organization may spend on EnakGame rewards (§5.6). The global budget pays for
+-- base rewards, one per period; an event budget pays for what its event adds.
+CREATE TABLE game_budgets (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    organization_id UUID NOT NULL,
+    scope VARCHAR(20) NOT NULL,
+    name VARCHAR(255) NOT NULL,
+    period_start DATE NOT NULL,
+    period_end DATE NOT NULL,
+    -- Rupiah.
+    amount BIGINT NOT NULL,
+    -- {"warning": 70, "critical": 90}: percent of utilization or forecast (PRD §8, §32).
+    thresholds JSONB NOT NULL DEFAULT '{}',
+    -- PRD §34, pending a decision (RFC §19.2).
+    exhaustion_policy VARCHAR(30),
+    created_by UUID NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT chk_game_budgets_scope CHECK (scope IN ('GLOBAL', 'EVENT')),
+    CONSTRAINT chk_game_budgets_amount CHECK (amount > 0),
+    CONSTRAINT chk_game_budgets_period CHECK (period_end >= period_start)
+);
+
+-- Global budgets of an organization do not overlap: one row per period.
+CREATE UNIQUE INDEX uq_game_budgets_global_period
+    ON game_budgets(organization_id, period_start) WHERE scope = 'GLOBAL';
+CREATE INDEX idx_game_budgets_org_scope ON game_budgets(organization_id, scope, period_start DESC);
+
+-- How a game computes its base reward (§5.2, §8). Immutable apart from status (D7): a
+-- change is a new row with the next version, and a session keeps the one it started
+-- with.
+CREATE TABLE game_reward_configs (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    organization_id UUID NOT NULL,
+    game_id UUID NOT NULL REFERENCES games(id) ON DELETE RESTRICT,
+    version INT NOT NULL,
+    reward_type VARCHAR(30) NOT NULL,
+    -- Shape per reward_type in §8.
+    rules JSONB NOT NULL,
+    max_reward BIGINT NOT NULL,
+    status VARCHAR(20) NOT NULL DEFAULT 'DRAFT',
+    effective_at TIMESTAMP WITH TIME ZONE,
+    created_by UUID NOT NULL,
+    reason VARCHAR(255),
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT uq_game_reward_configs_version UNIQUE (game_id, version),
+    CONSTRAINT chk_game_reward_configs_version CHECK (version >= 1),
+    CONSTRAINT chk_game_reward_configs_reward_type
+        CHECK (reward_type IN ('FIXED', 'SCORE_BASED', 'OUTCOME_BASED', 'PROBABILITY')),
+    CONSTRAINT chk_game_reward_configs_max_reward CHECK (max_reward >= 0),
+    CONSTRAINT chk_game_reward_configs_status CHECK (status IN ('DRAFT', 'ACTIVE', 'RETIRED'))
+);
+
+-- One active configuration per game.
+CREATE UNIQUE INDEX uq_game_reward_configs_active
+    ON game_reward_configs(game_id) WHERE status = 'ACTIVE';
+
+-- One play of a game by a customer (§5.3). STARTED → COMPLETED | REFUNDED | EXPIRED,
+-- each move an UPDATE ... WHERE status = 'STARTED' (D4).
+CREATE TABLE game_sessions (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    organization_id UUID NOT NULL,
+    customer_id UUID NOT NULL REFERENCES customers(id) ON DELETE RESTRICT,
+    game_id UUID NOT NULL REFERENCES games(id) ON DELETE RESTRICT,
+    -- Snapshots taken at start (D7, P3).
+    reward_config_id UUID NOT NULL REFERENCES game_reward_configs(id),
+    entry_cost BIGINT NOT NULL,
+
+    status VARCHAR(20) NOT NULL DEFAULT 'STARTED',
+    started_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
+    ended_at TIMESTAMP WITH TIME ZONE,
+
+    -- The result the client sent: data only, never a reward amount (P1).
+    result JSONB,
+    -- Validation and calculation: base, event modifiers, guard caps, rejection reasons,
+    -- RNG roll.
+    reward_breakdown JSONB,
+    reward_total BIGINT NOT NULL DEFAULT 0,
+    flagged BOOLEAN NOT NULL DEFAULT FALSE,
+
+    spend_transaction_id UUID NOT NULL REFERENCES wallet_transactions(id),
+    refund_transaction_id UUID REFERENCES wallet_transactions(id),
+    refund_reason VARCHAR(30),
+    -- Set, in a transaction of its own, when completing failed on a system error (§7.3).
+    completion_failed_at TIMESTAMP WITH TIME ZONE,
+
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT uq_game_sessions_spend_transaction UNIQUE (spend_transaction_id),
+    CONSTRAINT chk_game_sessions_entry_cost CHECK (entry_cost >= 1),
+    CONSTRAINT chk_game_sessions_status CHECK (status IN ('STARTED', 'COMPLETED', 'REFUNDED', 'EXPIRED')),
+    CONSTRAINT chk_game_sessions_reward_total CHECK (reward_total >= 0),
+    CONSTRAINT chk_game_sessions_refund_reason CHECK (refund_reason IN ('SYSTEM_ERROR', 'GAME_DEACTIVATED')),
+    CONSTRAINT chk_game_sessions_refund CHECK (
+        (status = 'REFUNDED') = (refund_transaction_id IS NOT NULL AND refund_reason IS NOT NULL))
+);
+
+CREATE INDEX idx_game_sessions_customer ON game_sessions(customer_id, started_at DESC);
+CREATE INDEX idx_game_sessions_open ON game_sessions(expires_at) WHERE status = 'STARTED';
+CREATE INDEX idx_game_sessions_game_open ON game_sessions(game_id) WHERE status = 'STARTED';
+
+-- One row per budget paying for a session's reward (D6), each with its own ledger row.
+CREATE TABLE game_session_rewards (
+    session_id UUID NOT NULL REFERENCES game_sessions(id),
+    budget_id UUID NOT NULL REFERENCES game_budgets(id),
+    amount BIGINT NOT NULL,
+    wallet_transaction_id UUID NOT NULL REFERENCES wallet_transactions(id),
+
+    PRIMARY KEY (session_id, budget_id),
+    CONSTRAINT uq_game_session_rewards_wallet_transaction UNIQUE (wallet_transaction_id),
+    CONSTRAINT chk_game_session_rewards_amount CHECK (amount > 0)
+);
+
+CREATE INDEX idx_game_session_rewards_budget ON game_session_rewards(budget_id);