feat(admin): product catalog editor

The /_gm console gains a Catalog editor — the source of truth for products.
Create / edit / archive-unarchive products, their atom composition and per-rail
prices (RUB via direct / VOTE via vk / XTR via telegram / CHIP value), and
hard-delete only a never-transacted product (an order or ledger reference forces
archive-only, backed by the FK RESTRICT). The archived flag reuses the existing
product.active. Activation revalidates the sellable shape — a pack (the chips
atom ⇒ a money price per rail, chips-only) or a value (no chips ⇒ a CHIP price);
a tournament-bearing product is composable but never sellable yet.

Backed by payments AdminCatalog / CreateProduct / UpdateProduct /
SetProductActive / DeleteProduct + a pure validateProduct.

Tests: validateProduct (pack / value / tournament / duplicate / shape); the
console editor end to end (create, edit, archive, delete-if-clean, refuse a
transacted delete).

backend/internal/payments/catalog_admin.go

@@ -0,0 +1,191 @@
+package payments
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/google/uuid"
+)
+
+// AdminProduct is one catalog product for the admin editor: its full composition, every price, the
+// archived flag (Active), and whether it has ever been transacted — which forbids a hard delete
+// (orders / ledger rows reference it, and the ledger is append-only).
+type AdminProduct struct {
+	ID         uuid.UUID
+	Title      string
+	Active     bool
+	Atoms      []AtomLine
+	Prices     []PriceLine
+	Transacted bool
+}
+
+// AtomLine is one atom of a product: the atom type and its positive quantity.
+type AtomLine struct {
+	Atom     string
+	Quantity int
+}
+
+// PriceLine is one price of a product: the payment method ("" for a value's CHIP price, which is
+// stored with a NULL method), the currency, and the amount in that currency's minor units.
+type PriceLine struct {
+	Method   string
+	Currency Currency
+	Amount   int64
+}
+
+// ProductInput is the editable content of a product: its title, atom composition and prices.
+type ProductInput struct {
+	Title  string
+	Atoms  []AtomLine
+	Prices []PriceLine
+}
+
+// knownAtoms is the fixed atom set, mirroring the catalog_atom seed / CHECK.
+var knownAtoms = map[string]bool{atomChips: true, "hints": true, "noads_days": true, "tournament": true}
+
+// validCurrency reports whether c is one of the four catalog currencies.
+func validCurrency(c Currency) bool {
+	switch c {
+	case CurrencyRUB, CurrencyVote, CurrencyStar, CurrencyChip:
+		return true
+	}
+	return false
+}
+
+// validateProduct checks a product's composition and prices. When sellable is true (the product is
+// or is becoming active) it also enforces the storefront shape: a pack (the chips atom ⇒ a money
+// price per method and no CHIP price, chips-only) or a value (no chips ⇒ a single CHIP price and no
+// money price). The tournament atom is never sellable (its economy is the tournament stage), so an
+// active product may not carry it; an archived draft may (a template for later) and skips the shape
+// check.
+func validateProduct(in ProductInput, sellable bool) error {
+	if strings.TrimSpace(in.Title) == "" {
+		return errors.New("product title is required")
+	}
+	if len(in.Atoms) == 0 {
+		return errors.New("product needs at least one atom")
+	}
+	seen := map[string]bool{}
+	hasChips, hasTournament, hasBenefit := false, false, false
+	for _, a := range in.Atoms {
+		if !knownAtoms[a.Atom] {
+			return fmt.Errorf("unknown atom %q", a.Atom)
+		}
+		if seen[a.Atom] {
+			return fmt.Errorf("duplicate atom %q", a.Atom)
+		}
+		seen[a.Atom] = true
+		if a.Quantity <= 0 {
+			return fmt.Errorf("atom %q quantity must be positive", a.Atom)
+		}
+		switch a.Atom {
+		case atomChips:
+			hasChips = true
+		case "tournament":
+			hasTournament = true
+		default:
+			hasBenefit = true
+		}
+	}
+
+	priceSeen := map[string]bool{}
+	hasChipPrice, hasMoneyPrice := false, false
+	for _, p := range in.Prices {
+		if p.Method != "" && p.Method != string(SourceVK) && p.Method != string(SourceTelegram) && p.Method != string(SourceDirect) {
+			return fmt.Errorf("invalid price method %q", p.Method)
+		}
+		if !validCurrency(p.Currency) {
+			return fmt.Errorf("invalid currency %q", p.Currency)
+		}
+		if p.Amount < 0 {
+			return errors.New("price amount must be non-negative")
+		}
+		if p.Currency == CurrencyChip && p.Method != "" {
+			return errors.New("a CHIP price must have no method")
+		}
+		if p.Currency != CurrencyChip && p.Method == "" {
+			return fmt.Errorf("a %s price needs a payment method", p.Currency)
+		}
+		key := p.Method + "|" + string(p.Currency)
+		if priceSeen[key] {
+			return fmt.Errorf("duplicate price (%s, %s)", p.Method, p.Currency)
+		}
+		priceSeen[key] = true
+		if p.Currency == CurrencyChip {
+			hasChipPrice = true
+		} else {
+			hasMoneyPrice = true
+		}
+	}
+
+	if !sellable {
+		return nil // an archived draft may be incomplete
+	}
+	if hasTournament {
+		return errors.New("a product carrying the tournament atom cannot be sold yet")
+	}
+	if hasChips {
+		if hasBenefit {
+			return errors.New("a chip pack must contain only the chips atom")
+		}
+		if !hasMoneyPrice || hasChipPrice {
+			return errors.New("a chip pack needs a money price per method and no CHIP price")
+		}
+	} else {
+		if !hasChipPrice || hasMoneyPrice {
+			return errors.New("a value needs a single CHIP price and no money price")
+		}
+	}
+	return nil
+}
+
+// AdminCatalog lists every product (active and archived) with its composition, prices and whether it
+// has been transacted, for the admin editor. Read uncached, straight from the catalog tables.
+func (s *Service) AdminCatalog(ctx context.Context) ([]AdminProduct, error) {
+	return s.store.adminCatalog(ctx)
+}
+
+// CreateProduct validates and inserts a new product with its atoms and prices, returning its id. A
+// product created active must satisfy the sellable shape.
+func (s *Service) CreateProduct(ctx context.Context, in ProductInput, active bool) (uuid.UUID, error) {
+	if err := validateProduct(in, active); err != nil {
+		return uuid.Nil, err
+	}
+	return s.store.createProduct(ctx, in, active, s.clock())
+}
+
+// UpdateProduct validates and replaces a product's title, atoms and prices. An active product must
+// satisfy the sellable shape.
+func (s *Service) UpdateProduct(ctx context.Context, id uuid.UUID, in ProductInput) (err error) {
+	active, err := s.store.productActive(ctx, id)
+	if err != nil {
+		return err
+	}
+	if err := validateProduct(in, active); err != nil {
+		return err
+	}
+	return s.store.updateProduct(ctx, id, in, s.clock())
+}
+
+// SetProductActive archives (active=false) or unarchives a product. Unarchiving revalidates the
+// sellable shape, so a draft or a tournament product cannot be put on sale.
+func (s *Service) SetProductActive(ctx context.Context, id uuid.UUID, active bool) error {
+	if active {
+		in, err := s.store.productInput(ctx, id)
+		if err != nil {
+			return err
+		}
+		if err := validateProduct(in, true); err != nil {
+			return err
+		}
+	}
+	return s.store.setProductActive(ctx, id, active, s.clock())
+}
+
+// DeleteProduct hard-deletes a product only when it has never been transacted (no order or ledger
+// row references it); otherwise it returns ErrProductTransacted and the caller archives instead.
+func (s *Service) DeleteProduct(ctx context.Context, id uuid.UUID) error {
+	return s.store.deleteProduct(ctx, id)
+}

backend/internal/payments/catalog_admin_test.go

@@ -0,0 +1,47 @@
+package payments
+
+import "testing"
+
+func TestValidateProduct(t *testing.T) {
+	pack := ProductInput{
+		Title:  "100 chips",
+		Atoms:  []AtomLine{{Atom: "chips", Quantity: 100}},
+		Prices: []PriceLine{{Method: "direct", Currency: CurrencyRUB, Amount: 14900}},
+	}
+	value := ProductInput{
+		Title:  "5 hints",
+		Atoms:  []AtomLine{{Atom: "hints", Quantity: 5}},
+		Prices: []PriceLine{{Method: "", Currency: CurrencyChip, Amount: 50}},
+	}
+
+	tests := []struct {
+		name     string
+		in       ProductInput
+		sellable bool
+		wantErr  bool
+	}{
+		{"valid pack", pack, true, false},
+		{"valid value", value, true, false},
+		{"pack with a benefit atom", ProductInput{Title: "x", Atoms: []AtomLine{{"chips", 100}, {"hints", 5}}, Prices: pack.Prices}, true, true},
+		{"pack without money price", ProductInput{Title: "x", Atoms: pack.Atoms, Prices: value.Prices}, true, true},
+		{"value without chip price", ProductInput{Title: "x", Atoms: value.Atoms, Prices: pack.Prices}, true, true},
+		{"tournament sellable is refused", ProductInput{Title: "cup", Atoms: []AtomLine{{"tournament", 1}}, Prices: value.Prices}, true, true},
+		{"tournament draft is allowed", ProductInput{Title: "cup", Atoms: []AtomLine{{"tournament", 1}}}, false, false},
+		{"unknown atom", ProductInput{Title: "x", Atoms: []AtomLine{{"gold", 1}}}, false, true},
+		{"duplicate atom", ProductInput{Title: "x", Atoms: []AtomLine{{"hints", 1}, {"hints", 2}}}, false, true},
+		{"non-positive quantity", ProductInput{Title: "x", Atoms: []AtomLine{{"hints", 0}}}, false, true},
+		{"chip price with a method", ProductInput{Title: "x", Atoms: value.Atoms, Prices: []PriceLine{{Method: "direct", Currency: CurrencyChip, Amount: 50}}}, true, true},
+		{"money price without a method", ProductInput{Title: "x", Atoms: pack.Atoms, Prices: []PriceLine{{Method: "", Currency: CurrencyRUB, Amount: 149}}}, true, true},
+		{"duplicate price", ProductInput{Title: "x", Atoms: pack.Atoms, Prices: []PriceLine{{Method: "direct", Currency: CurrencyRUB, Amount: 1}, {Method: "direct", Currency: CurrencyRUB, Amount: 2}}}, true, true},
+		{"empty title", ProductInput{Title: " ", Atoms: value.Atoms, Prices: value.Prices}, true, true},
+		{"no atoms", ProductInput{Title: "x", Prices: value.Prices}, true, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := validateProduct(tt.in, tt.sellable)
+			if (err != nil) != tt.wantErr {
+				t.Fatalf("validateProduct = %v, wantErr %v", err, tt.wantErr)
+			}
+		})
+	}
+}

backend/internal/payments/store_catalog_admin.go

@@ -0,0 +1,218 @@
+package payments
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/go-jet/jet/v2/postgres"
+	"github.com/go-jet/jet/v2/qrm"
+	"github.com/google/uuid"
+
+	"scrabble/backend/internal/postgres/jet/payments/model"
+	"scrabble/backend/internal/postgres/jet/payments/table"
+)
+
+// ErrProductTransacted is returned when a hard delete is attempted on a product an order or ledger
+// row references — it must be archived instead, to keep the append-only ledger resolvable.
+var ErrProductTransacted = errors.New("payments: product has transactions; archive instead of delete")
+
+// adminCatalog lists every product (active and archived) with its atoms, prices and transacted flag.
+func (s *Store) adminCatalog(ctx context.Context) ([]AdminProduct, error) {
+	var prods []model.Product
+	if err := postgres.SELECT(table.Product.AllColumns).
+		FROM(table.Product).
+		ORDER_BY(table.Product.CreatedAt.ASC()).
+		QueryContext(ctx, s.db, &prods); err != nil {
+		return nil, fmt.Errorf("payments: admin list products: %w", err)
+	}
+	out := make([]AdminProduct, 0, len(prods))
+	for _, p := range prods {
+		atoms, prices, err := s.productComposition(ctx, p.ProductID)
+		if err != nil {
+			return nil, err
+		}
+		transacted, err := s.productTransacted(ctx, p.ProductID)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, AdminProduct{
+			ID: p.ProductID, Title: p.Title, Active: p.Active,
+			Atoms: atoms, Prices: prices, Transacted: transacted,
+		})
+	}
+	return out, nil
+}
+
+// productComposition reads one product's atom lines and price rows.
+func (s *Store) productComposition(ctx context.Context, id uuid.UUID) ([]AtomLine, []PriceLine, error) {
+	var items []model.ProductItem
+	if err := postgres.SELECT(table.ProductItem.AllColumns).
+		FROM(table.ProductItem).
+		WHERE(table.ProductItem.ProductID.EQ(postgres.UUID(id))).
+		ORDER_BY(table.ProductItem.AtomType.ASC()).
+		QueryContext(ctx, s.db, &items); err != nil {
+		return nil, nil, fmt.Errorf("payments: load items %s: %w", id, err)
+	}
+	atoms := make([]AtomLine, len(items))
+	for i, it := range items {
+		atoms[i] = AtomLine{Atom: it.AtomType, Quantity: int(it.Quantity)}
+	}
+	var prs []model.ProductPrice
+	if err := postgres.SELECT(table.ProductPrice.AllColumns).
+		FROM(table.ProductPrice).
+		WHERE(table.ProductPrice.ProductID.EQ(postgres.UUID(id))).
+		QueryContext(ctx, s.db, &prs); err != nil {
+		return nil, nil, fmt.Errorf("payments: load prices %s: %w", id, err)
+	}
+	prices := make([]PriceLine, len(prs))
+	for i, pr := range prs {
+		method := ""
+		if pr.Method != nil {
+			method = *pr.Method
+		}
+		prices[i] = PriceLine{Method: method, Currency: Currency(pr.Currency), Amount: pr.Amount}
+	}
+	return atoms, prices, nil
+}
+
+// productTransacted reports whether any order or ledger row references the product.
+func (s *Store) productTransacted(ctx context.Context, id uuid.UUID) (bool, error) {
+	var yes bool
+	if err := s.db.QueryRowContext(ctx,
+		`SELECT EXISTS(SELECT 1 FROM payments.orders WHERE product_id=$1)
+		     OR EXISTS(SELECT 1 FROM payments.ledger WHERE product_id=$1)`, id).Scan(&yes); err != nil {
+		return false, fmt.Errorf("payments: product transacted %s: %w", id, err)
+	}
+	return yes, nil
+}
+
+// productActive reads a product's archived flag, ErrProductNotFound when it is missing.
+func (s *Store) productActive(ctx context.Context, id uuid.UUID) (bool, error) {
+	var p model.Product
+	err := postgres.SELECT(table.Product.Active).FROM(table.Product).
+		WHERE(table.Product.ProductID.EQ(postgres.UUID(id))).LIMIT(1).
+		QueryContext(ctx, s.db, &p)
+	if errors.Is(err, qrm.ErrNoRows) {
+		return false, ErrProductNotFound
+	}
+	if err != nil {
+		return false, fmt.Errorf("payments: product active %s: %w", id, err)
+	}
+	return p.Active, nil
+}
+
+// productInput reads a product's current editable content (title, atoms, prices).
+func (s *Store) productInput(ctx context.Context, id uuid.UUID) (ProductInput, error) {
+	var p model.Product
+	err := postgres.SELECT(table.Product.AllColumns).FROM(table.Product).
+		WHERE(table.Product.ProductID.EQ(postgres.UUID(id))).LIMIT(1).
+		QueryContext(ctx, s.db, &p)
+	if errors.Is(err, qrm.ErrNoRows) {
+		return ProductInput{}, ErrProductNotFound
+	}
+	if err != nil {
+		return ProductInput{}, fmt.Errorf("payments: product input %s: %w", id, err)
+	}
+	atoms, prices, err := s.productComposition(ctx, id)
+	if err != nil {
+		return ProductInput{}, err
+	}
+	return ProductInput{Title: p.Title, Atoms: atoms, Prices: prices}, nil
+}
+
+// createProduct inserts a product with its atoms and prices in one transaction, returning its id.
+func (s *Store) createProduct(ctx context.Context, in ProductInput, active bool, now time.Time) (uuid.UUID, error) {
+	id := uuid.New()
+	if err := withTx(ctx, s.db, func(tx *sql.Tx) error {
+		if _, err := tx.ExecContext(ctx,
+			`INSERT INTO payments.product (product_id, title, active, created_at, updated_at) VALUES ($1,$2,$3,$4,$4)`,
+			id, in.Title, active, now); err != nil {
+			return fmt.Errorf("insert product: %w", err)
+		}
+		return insertComposition(ctx, tx, id, in)
+	}); err != nil {
+		return uuid.Nil, fmt.Errorf("payments: create product: %w", err)
+	}
+	return id, nil
+}
+
+// updateProduct replaces a product's title, atoms and prices in one transaction (active unchanged).
+func (s *Store) updateProduct(ctx context.Context, id uuid.UUID, in ProductInput, now time.Time) error {
+	return withTx(ctx, s.db, func(tx *sql.Tx) error {
+		res, err := tx.ExecContext(ctx,
+			`UPDATE payments.product SET title=$2, updated_at=$3 WHERE product_id=$1`, id, in.Title, now)
+		if err != nil {
+			return fmt.Errorf("payments: update product %s: %w", id, err)
+		}
+		if n, _ := res.RowsAffected(); n == 0 {
+			return ErrProductNotFound
+		}
+		if _, err := tx.ExecContext(ctx, `DELETE FROM payments.product_item WHERE product_id=$1`, id); err != nil {
+			return fmt.Errorf("payments: clear items %s: %w", id, err)
+		}
+		if _, err := tx.ExecContext(ctx, `DELETE FROM payments.product_price WHERE product_id=$1`, id); err != nil {
+			return fmt.Errorf("payments: clear prices %s: %w", id, err)
+		}
+		return insertComposition(ctx, tx, id, in)
+	})
+}
+
+// insertComposition inserts a product's atom items and price rows inside tx (a value's CHIP price
+// carries a NULL method).
+func insertComposition(ctx context.Context, tx *sql.Tx, id uuid.UUID, in ProductInput) error {
+	for _, a := range in.Atoms {
+		if _, err := tx.ExecContext(ctx,
+			`INSERT INTO payments.product_item (product_id, atom_type, quantity) VALUES ($1,$2,$3)`,
+			id, a.Atom, a.Quantity); err != nil {
+			return fmt.Errorf("insert item %s: %w", a.Atom, err)
+		}
+	}
+	for _, p := range in.Prices {
+		var method any
+		if p.Method != "" {
+			method = p.Method
+		}
+		if _, err := tx.ExecContext(ctx,
+			`INSERT INTO payments.product_price (product_id, method, currency, amount) VALUES ($1,$2,$3,$4)`,
+			id, method, string(p.Currency), p.Amount); err != nil {
+			return fmt.Errorf("insert price %s: %w", p.Currency, err)
+		}
+	}
+	return nil
+}
+
+// setProductActive flips the archived flag.
+func (s *Store) setProductActive(ctx context.Context, id uuid.UUID, active bool, now time.Time) error {
+	res, err := s.db.ExecContext(ctx,
+		`UPDATE payments.product SET active=$2, updated_at=$3 WHERE product_id=$1`, id, active, now)
+	if err != nil {
+		return fmt.Errorf("payments: set product active %s: %w", id, err)
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		return ErrProductNotFound
+	}
+	return nil
+}
+
+// deleteProduct hard-deletes a never-transacted product (its items/prices cascade); a transacted
+// product is refused with ErrProductTransacted.
+func (s *Store) deleteProduct(ctx context.Context, id uuid.UUID) error {
+	transacted, err := s.productTransacted(ctx, id)
+	if err != nil {
+		return err
+	}
+	if transacted {
+		return ErrProductTransacted
+	}
+	res, err := s.db.ExecContext(ctx, `DELETE FROM payments.product WHERE product_id=$1`, id)
+	if err != nil {
+		return fmt.Errorf("payments: delete product %s: %w", id, err)
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		return ErrProductNotFound
+	}
+	return nil
+}