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>
This commit is contained in:
efrilm
2026-10-07 20:53:14 +07:00
co-authored by Claude Opus 5.5
parent 2c9753fae7
commit 798a36bd6c
92 changed files with 12392 additions and 23 deletions
@@ -0,0 +1,47 @@
-- EnakGame events, also called campaigns (docs/rfc-enakgame.md §5.5, D6): a period in
-- which some games pay more, the extra paid by the event's own budget.
CREATE TABLE game_events (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
organization_id UUID NOT NULL,
name VARCHAR(255) NOT NULL,
slug VARCHAR(100) NOT NULL,
description TEXT,
banner_url VARCHAR(500),
start_at TIMESTAMP WITH TIME ZONE NOT NULL,
end_at TIMESTAMP WITH TIME ZONE NOT NULL,
-- Shown with the dates; start_at and end_at are instants already.
timezone VARCHAR(50) NOT NULL DEFAULT 'Asia/Jakarta',
status VARCHAR(20) NOT NULL DEFAULT 'DRAFT',
-- Higher goes first; when the reward cap cuts, the lowest goes first.
priority INT NOT NULL DEFAULT 0,
-- Applied to the base reward: 2.00 adds the base once more.
multiplier NUMERIC(5,2),
-- Added on top, per completed session.
bonus BIGINT,
-- Pays what this event adds. A budget of scope EVENT, checked by the processor.
budget_id UUID NOT NULL REFERENCES game_budgets(id),
-- EnakCoin this event may add over its whole run (PRD §35 Event Limit).
reward_limit BIGINT,
-- EnakCoin this event may add for one customer per day.
user_daily_limit BIGINT,
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
CONSTRAINT uq_game_events_slug UNIQUE (organization_id, slug),
CONSTRAINT chk_game_events_period CHECK (end_at > start_at),
CONSTRAINT chk_game_events_status CHECK (status IN ('DRAFT', 'ACTIVE', 'ENDED', 'CANCELLED')),
CONSTRAINT chk_game_events_multiplier CHECK (multiplier IS NULL OR multiplier > 0),
CONSTRAINT chk_game_events_bonus CHECK (bonus IS NULL OR bonus > 0),
CONSTRAINT chk_game_events_reward_limit CHECK (reward_limit IS NULL OR reward_limit > 0),
CONSTRAINT chk_game_events_user_daily_limit CHECK (user_daily_limit IS NULL OR user_daily_limit > 0)
);
CREATE INDEX idx_game_events_org_active ON game_events(organization_id, start_at, end_at) WHERE status = 'ACTIVE';
CREATE TABLE game_event_games (
event_id UUID NOT NULL REFERENCES game_events(id) ON DELETE CASCADE,
game_id UUID NOT NULL REFERENCES games(id) ON DELETE RESTRICT,
PRIMARY KEY (event_id, game_id)
);
CREATE INDEX idx_game_event_games_game ON game_event_games(game_id);