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,124 @@
+package repository
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/google/uuid"
+	"gorm.io/gorm"
+
+	"apskel-pos-be/internal/entities"
+)
+
+// ErrAuditTxRequired is returned when an audit row is written outside a transaction:
+// the row must commit or roll back together with the change it records.
+var ErrAuditTxRequired = errors.New("audit: write must run inside a transaction")
+
+// AuditLogRepository stores audit_logs (docs/rfc-enakgame.md §5.9).
+type AuditLogRepository interface {
+	// Insert writes a row in the caller's transaction, or returns ErrAuditTxRequired.
+	Insert(ctx context.Context, entry *entities.AuditLog) error
+	// ListByEntity returns an entity's rows in an organization, newest first.
+	ListByEntity(ctx context.Context, organizationID uuid.UUID, entityType string, entityID uuid.UUID, limit int) ([]entities.AuditLog, error)
+}
+
+type auditLogRepository struct {
+	db *gorm.DB
+}
+
+func NewAuditLogRepository(db *gorm.DB) AuditLogRepository {
+	return &auditLogRepository{db: db}
+}
+
+func (r *auditLogRepository) Insert(ctx context.Context, entry *entities.AuditLog) error {
+	tx, ok := ctx.Value(txKey).(*gorm.DB)
+	if !ok || tx == nil {
+		return ErrAuditTxRequired
+	}
+	if entry.ID == uuid.Nil {
+		entry.ID = uuid.New()
+	}
+	var rows []struct{ CreatedAt time.Time }
+	err := tx.WithContext(ctx).Raw(`
+		INSERT INTO audit_logs (id, organization_id, actor_type, actor_id, entity_type, entity_id,
+			action, before, after, reason, source)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?::jsonb, ?::jsonb, ?, ?)
+		RETURNING created_at`,
+		entry.ID, entry.OrganizationID, entry.ActorType, entry.ActorID, entry.EntityType, entry.EntityID,
+		entry.Action, jsonOrNull(entry.Before), jsonOrNull(entry.After), entry.Reason, entry.Source).
+		Scan(&rows).Error
+	if err != nil {
+		return fmt.Errorf("failed to write audit log: %w", err)
+	}
+	if len(rows) == 1 {
+		entry.CreatedAt = rows[0].CreatedAt
+	}
+	return nil
+}
+
+func (r *auditLogRepository) ListByEntity(ctx context.Context, organizationID uuid.UUID, entityType string, entityID uuid.UUID, limit int) ([]entities.AuditLog, error) {
+	var rows []struct {
+		ID             string
+		OrganizationID string
+		ActorType      string
+		ActorID        *string
+		EntityType     string
+		EntityID       string
+		Action         string
+		Before         *string
+		After          *string
+		Reason         *string
+		Source         string
+		CreatedAt      time.Time
+	}
+	err := DBFromContext(ctx, r.db).WithContext(ctx).Raw(`
+		SELECT id::text AS id, organization_id::text AS organization_id, actor_type, actor_id::text AS actor_id,
+			entity_type, entity_id::text AS entity_id, action, before::text AS before, after::text AS after,
+			reason, source, created_at
+		FROM audit_logs
+		WHERE organization_id = ? AND entity_type = ? AND entity_id = ?
+		ORDER BY created_at DESC, id
+		LIMIT ?`, organizationID, entityType, entityID, limit).Scan(&rows).Error
+	if err != nil {
+		return nil, fmt.Errorf("failed to read audit logs: %w", err)
+	}
+	out := make([]entities.AuditLog, 0, len(rows))
+	for _, row := range rows {
+		entry := entities.AuditLog{
+			ActorType:  row.ActorType,
+			EntityType: row.EntityType,
+			Action:     row.Action,
+			Reason:     row.Reason,
+			Source:     row.Source,
+			CreatedAt:  row.CreatedAt,
+		}
+		entry.ID, _ = uuid.Parse(row.ID)
+		entry.OrganizationID, _ = uuid.Parse(row.OrganizationID)
+		entry.EntityID, _ = uuid.Parse(row.EntityID)
+		if row.ActorID != nil {
+			if id, err := uuid.Parse(*row.ActorID); err == nil {
+				entry.ActorID = &id
+			}
+		}
+		if row.Before != nil {
+			entry.Before = json.RawMessage(*row.Before)
+		}
+		if row.After != nil {
+			entry.After = json.RawMessage(*row.After)
+		}
+		out = append(out, entry)
+	}
+	return out, nil
+}
+
+// jsonOrNull passes a JSON document as text, or NULL when there is none.
+func jsonOrNull(doc json.RawMessage) *string {
+	if len(doc) == 0 {
+		return nil
+	}
+	s := string(doc)
+	return &s
+}