feat(telegram): promo deep-link seeds English Scrabble for new users

The promo bot button carries a configurable variant-seed start-param (default verudit_ru-scrabble_en). The gateway parses start_param from the validated initData and forwards it; the backend, on first contact only, seeds the new account variant_preferences from it (English Scrabble alongside the default Erudit).

No schema change (the scrabble_en CHECK is already in the baseline) and the gateway<->backend REST field is additive, so the rolling deploy is safe in either order. TELEGRAM_PROMO_START_PARAM configures the payload (empty forwards the user own /start payload). Covered by account unit tests, a gateway transcode test, and an integration test asserting new-only seeding.

backend/internal/account/profile.go

@@ -101,6 +101,66 @@ func validateVariantPreferences(prefs []string) ([]string, error) {
 	return out, nil
 }
 
+// variantSeedPrefix marks a Telegram start-param payload that seeds a brand-new
+// account's variant preferences (e.g. "verudit_ru-scrabble_en"): the prefix, then the
+// canonical variant labels joined by "-". It is deliberately distinct from the routing
+// deep links (g/i/f; see platform/telegram .../deeplink) so the client's start-param
+// router falls through to the lobby for it.
+const variantSeedPrefix = "v"
+
+// SeedVariantsFromStartParam decodes a promo deep-link start-param into the variant
+// preference set to seed onto a brand-new account: the variantSeedPrefix followed by
+// the canonical variant labels joined by "-" (e.g. "verudit_ru-scrabble_en"). It
+// returns nil for any payload that is not a variant-seed link or that fails validation
+// against the known variants, so a malformed, empty or unrelated start-param simply
+// leaves the account on its default preferences rather than failing the login.
+func SeedVariantsFromStartParam(startParam string) []string {
+	if !strings.HasPrefix(startParam, variantSeedPrefix) {
+		return nil
+	}
+	body := strings.TrimPrefix(startParam, variantSeedPrefix)
+	if body == "" {
+		return nil
+	}
+	prefs, err := validateVariantPreferences(strings.Split(body, "-"))
+	if err != nil {
+		return nil
+	}
+	return prefs
+}
+
+// SetVariantPreferences overwrites only the variant-preference set of the account,
+// cleaning it to a deduplicated, canonically ordered subset of the known variants
+// (rejecting an empty or unknown set with ErrInvalidProfile) and bumping updated_at; it
+// reports ErrNotFound when no account matches id. It is the narrow counterpart to
+// UpdateProfile used to seed a promo-onboarded account's variants at first contact
+// without disturbing its other profile fields.
+func (s *Store) SetVariantPreferences(ctx context.Context, id uuid.UUID, prefs []string) (Account, error) {
+	clean, err := validateVariantPreferences(prefs)
+	if err != nil {
+		return Account{}, err
+	}
+	stmt := table.Accounts.UPDATE(
+		table.Accounts.VariantPreferences, table.Accounts.UpdatedAt,
+	).SET(
+		// clean is validated against the closed knownVariants set; bind as a text[]
+		// parameter (lib/pq encodes the array, the cast pins the column type), mirroring
+		// UpdateProfile.
+		postgres.Raw("#variant_prefs::text[]", map[string]interface{}{"#variant_prefs": pq.StringArray(clean)}),
+		postgres.TimestampzT(time.Now().UTC()),
+	).WHERE(table.Accounts.AccountID.EQ(postgres.UUID(id))).
+		RETURNING(table.Accounts.AllColumns)
+
+	var row model.Accounts
+	if err := stmt.QueryContext(ctx, s.db, &row); err != nil {
+		if errors.Is(err, qrm.ErrNoRows) {
+			return Account{}, ErrNotFound
+		}
+		return Account{}, fmt.Errorf("account: set variant preferences %s: %w", id, err)
+	}
+	return modelToAccount(row), nil
+}
+
 // UpdateProfile validates and overwrites the editable fields of the account, then
 // returns the stored row. It reports ErrInvalidProfile for a bad language,
 // timezone or display name and ErrNotFound when no account matches id.

backend/internal/account/variant_seed_test.go

@@ -0,0 +1,37 @@
+package account
+
+import (
+	"slices"
+	"testing"
+)
+
+// TestSeedVariantsFromStartParam covers decoding a promo deep-link start-param into the
+// variant-preference set to seed: a valid "v"-prefixed, "-"-joined label list is cleaned
+// to the canonical order and deduplicated, while anything that is not a variant-seed link
+// or that names an unknown variant yields nil (leaving the account on its defaults).
+func TestSeedVariantsFromStartParam(t *testing.T) {
+	tests := []struct {
+		name  string
+		param string
+		want  []string
+	}{
+		{"english promo", "verudit_ru-scrabble_en", []string{"erudit_ru", "scrabble_en"}},
+		{"single variant", "vscrabble_en", []string{"scrabble_en"}},
+		{"canonical order regardless of payload order", "vscrabble_en-erudit_ru", []string{"erudit_ru", "scrabble_en"}},
+		{"deduplicated", "verudit_ru-erudit_ru", []string{"erudit_ru"}},
+		{"empty", "", nil},
+		{"prefix only", "v", nil},
+		{"routing game link is not a seed", "g0190abcd", nil},
+		{"friend code link is not a seed", "f123456", nil},
+		{"unknown variant rejected", "vscrabble_de", nil},
+		{"one unknown label rejects the whole set", "verudit_ru-scrabble_de", nil},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := SeedVariantsFromStartParam(tc.param)
+			if !slices.Equal(got, tc.want) {
+				t.Errorf("SeedVariantsFromStartParam(%q) = %v, want %v", tc.param, got, tc.want)
+			}
+		})
+	}
+}