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
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
2c9753fae7
commit
798a36bd6c
@@ -0,0 +1,123 @@
|
||||
-- EnakGame vouchers, what EnakPoint is redeemed for, and what each redemption cost
|
||||
-- which budget (docs/rfc-enakgame.md §5.7, D5). Replaces the unused rewards table for
|
||||
-- EnakGame; rewards itself stays.
|
||||
|
||||
CREATE TABLE vouchers (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
organization_id UUID NOT NULL,
|
||||
name VARCHAR(255) NOT NULL,
|
||||
description TEXT,
|
||||
image_url VARCHAR(500),
|
||||
voucher_type VARCHAR(30) NOT NULL,
|
||||
-- Rupiah: what a redemption costs, the basis of realized cost.
|
||||
face_value BIGINT NOT NULL,
|
||||
-- EnakPoint asked for it; may differ from face_value (PRD §22).
|
||||
point_cost BIGINT NOT NULL,
|
||||
-- Reporting only, never counted against a budget.
|
||||
business_cost BIGINT,
|
||||
stock_mode VARCHAR(20) NOT NULL,
|
||||
-- STATIC only.
|
||||
stock BIGINT,
|
||||
-- EXTERNAL only.
|
||||
provider VARCHAR(50),
|
||||
provider_ref VARCHAR(255),
|
||||
max_per_customer INT,
|
||||
valid_from TIMESTAMP WITH TIME ZONE,
|
||||
valid_until TIMESTAMP WITH TIME ZONE,
|
||||
terms JSONB NOT NULL DEFAULT '{}',
|
||||
status VARCHAR(20) NOT NULL DEFAULT 'DRAFT',
|
||||
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
|
||||
|
||||
CONSTRAINT chk_vouchers_voucher_type
|
||||
CHECK (voucher_type IN ('FIXED_VALUE', 'PERCENTAGE', 'FREE_ITEM', 'MERCHANT_BENEFIT')),
|
||||
CONSTRAINT chk_vouchers_face_value CHECK (face_value > 0),
|
||||
CONSTRAINT chk_vouchers_point_cost CHECK (point_cost > 0),
|
||||
CONSTRAINT chk_vouchers_business_cost CHECK (business_cost IS NULL OR business_cost >= 0),
|
||||
CONSTRAINT chk_vouchers_stock_mode CHECK (stock_mode IN ('STATIC', 'CODE_POOL', 'EXTERNAL')),
|
||||
CONSTRAINT chk_vouchers_stock CHECK (stock IS NULL OR stock >= 0),
|
||||
CONSTRAINT chk_vouchers_static_stock CHECK ((stock_mode = 'STATIC') = (stock IS NOT NULL)),
|
||||
CONSTRAINT chk_vouchers_external_provider CHECK ((stock_mode = 'EXTERNAL') = (provider IS NOT NULL)),
|
||||
CONSTRAINT chk_vouchers_max_per_customer CHECK (max_per_customer IS NULL OR max_per_customer >= 1),
|
||||
CONSTRAINT chk_vouchers_validity CHECK (valid_from IS NULL OR valid_until IS NULL OR valid_until > valid_from),
|
||||
CONSTRAINT chk_vouchers_status CHECK (status IN ('DRAFT', 'ACTIVE', 'INACTIVE', 'ARCHIVED'))
|
||||
);
|
||||
|
||||
CREATE INDEX idx_vouchers_org_status ON vouchers(organization_id, status);
|
||||
|
||||
-- The codes of a CODE_POOL voucher, one per redemption.
|
||||
CREATE TABLE voucher_codes (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
voucher_id UUID NOT NULL REFERENCES vouchers(id) ON DELETE RESTRICT,
|
||||
code VARCHAR(255) NOT NULL,
|
||||
status VARCHAR(20) NOT NULL DEFAULT 'AVAILABLE',
|
||||
-- No foreign key: the code is taken before its redemption row is written.
|
||||
redemption_id UUID,
|
||||
expires_at TIMESTAMP WITH TIME ZONE,
|
||||
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
|
||||
|
||||
CONSTRAINT uq_voucher_codes_code UNIQUE (voucher_id, code),
|
||||
CONSTRAINT chk_voucher_codes_status
|
||||
CHECK (status IN ('AVAILABLE', 'RESERVED', 'REDEEMED', 'EXPIRED', 'CANCELLED')),
|
||||
CONSTRAINT chk_voucher_codes_redemption
|
||||
CHECK ((status IN ('RESERVED', 'REDEEMED')) = (redemption_id IS NOT NULL))
|
||||
);
|
||||
|
||||
CREATE INDEX idx_voucher_codes_available ON voucher_codes(voucher_id, created_at)
|
||||
WHERE status = 'AVAILABLE';
|
||||
CREATE INDEX idx_voucher_codes_expiring ON voucher_codes(expires_at)
|
||||
WHERE status = 'AVAILABLE' AND expires_at IS NOT NULL;
|
||||
|
||||
-- One redemption of a voucher by a customer, with the voucher's numbers frozen (P3).
|
||||
CREATE TABLE voucher_redemptions (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
organization_id UUID NOT NULL,
|
||||
customer_id UUID NOT NULL REFERENCES customers(id) ON DELETE RESTRICT,
|
||||
voucher_id UUID NOT NULL REFERENCES vouchers(id),
|
||||
idempotency_key VARCHAR(100) NOT NULL,
|
||||
status VARCHAR(20) NOT NULL,
|
||||
face_value BIGINT NOT NULL,
|
||||
point_cost BIGINT NOT NULL,
|
||||
voucher_code_id UUID REFERENCES voucher_codes(id),
|
||||
external_code VARCHAR(255),
|
||||
external_ref VARCHAR(255),
|
||||
debit_transaction_id UUID NOT NULL REFERENCES wallet_transactions(id),
|
||||
refund_transaction_id UUID REFERENCES wallet_transactions(id),
|
||||
failure_reason VARCHAR(255),
|
||||
attempts INT NOT NULL DEFAULT 0,
|
||||
completed_at TIMESTAMP WITH TIME ZONE,
|
||||
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
|
||||
|
||||
CONSTRAINT uq_voucher_redemptions_key UNIQUE (customer_id, idempotency_key),
|
||||
CONSTRAINT uq_voucher_redemptions_debit UNIQUE (debit_transaction_id),
|
||||
CONSTRAINT chk_voucher_redemptions_status CHECK (status IN ('PENDING', 'COMPLETED', 'FAILED')),
|
||||
CONSTRAINT chk_voucher_redemptions_refund CHECK ((status = 'FAILED') = (refund_transaction_id IS NOT NULL)),
|
||||
CONSTRAINT chk_voucher_redemptions_completed CHECK ((status = 'COMPLETED') = (completed_at IS NOT NULL))
|
||||
);
|
||||
|
||||
CREATE INDEX idx_voucher_redemptions_customer ON voucher_redemptions(customer_id, created_at DESC);
|
||||
CREATE INDEX idx_voucher_redemptions_customer_voucher ON voucher_redemptions(customer_id, voucher_id);
|
||||
CREATE INDEX idx_voucher_redemptions_pending ON voucher_redemptions(updated_at)
|
||||
WHERE status = 'PENDING';
|
||||
|
||||
-- What a redemption cost each budget, frozen when it completes (D5).
|
||||
CREATE TABLE voucher_redemption_costs (
|
||||
redemption_id UUID NOT NULL REFERENCES voucher_redemptions(id),
|
||||
-- NULL: EnakPoint that did not come from EnakGame (EARN, ADJUSTMENT, MIGRATION).
|
||||
budget_id UUID REFERENCES game_budgets(id),
|
||||
-- Ledger type of the root lot the EnakPoint came from.
|
||||
source_type VARCHAR(30) NOT NULL,
|
||||
points BIGINT NOT NULL,
|
||||
-- Rupiah, a share of face_value.
|
||||
cost BIGINT NOT NULL,
|
||||
-- = completed_at, what puts the cost in a budget period.
|
||||
recognized_at TIMESTAMP WITH TIME ZONE NOT NULL,
|
||||
|
||||
CONSTRAINT uq_voucher_redemption_costs UNIQUE (redemption_id, budget_id, source_type),
|
||||
CONSTRAINT chk_voucher_redemption_costs_points CHECK (points > 0),
|
||||
CONSTRAINT chk_voucher_redemption_costs_cost CHECK (cost >= 0)
|
||||
);
|
||||
|
||||
CREATE INDEX idx_voucher_redemption_costs_budget ON voucher_redemption_costs(budget_id, recognized_at);
|
||||
Reference in New Issue
Block a user