feat(ads): server-driven ad-banner backend, wire & admin console (PR1)

Turn the gated-off mock banner into a real advertising subsystem (backend + admin half; the UI rotation lands in PR2). - internal/ads: campaigns (percent weight + validity window; a perpetual, undeletable default that fills the remainder up to 100%), 1..N bilingual messages (en+ru), global display timings; ActiveSet computes the window-filtered, default-remainder, GCD-reduced, language-resolved rotation feed. Smooth-weighted-round-robin math is unit-tested. - migration 00006 (+ jetgen): ad_campaigns / ad_messages / ad_settings, seeded default campaign + house message + default timings. - eligibility = !paid_account && hint_balance==0 && !no_banner role (new role; guests qualify). The resolved feed rides the profile.get response (no new RPC, works for guests, nothing distinct to filter); language by service_language. - live update: a notify `banner` sub-kind (re-poll signal) published when an operator grants hints or grants/revokes no_banner, so the client shows/hides in place. - admin console /_gm/banners (+ /_gm/banner-settings): campaign + message CRUD with reorder, default protection, clamped timings. - wire: fbs BannerInfo/BannerCampaign on Profile; gateway transcode forwards it. - docs: ARCHITECTURE §10, FUNCTIONAL (+ _ru), backend README, PRERELEASE tracker (incl. the deferred app.load aggregator note).
2026-06-15 23:00:19 +02:00
parent f59c8dcd43
commit 0946a3f66c
45 changed files with 2993 additions and 28 deletions
@@ -0,0 +1,25 @@
+//
+// Code generated by go-jet DO NOT EDIT.
+//
+// WARNING: Changes to this file may cause incorrect behavior
+// and will be lost if the code is regenerated
+//
+
+package model
+
+import (
+	"github.com/google/uuid"
+	"time"
+)
+
+type AdCampaigns struct {
+	CampaignID uuid.UUID `sql:"primary_key"`
+	Name       string
+	Weight     int32
+	IsDefault  bool
+	Enabled    bool
+	StartsAt   *time.Time
+	EndsAt     *time.Time
+	CreatedAt  time.Time
+	UpdatedAt  time.Time
+}
@@ -0,0 +1,23 @@
+//
+// Code generated by go-jet DO NOT EDIT.
+//
+// WARNING: Changes to this file may cause incorrect behavior
+// and will be lost if the code is regenerated
+//
+
+package model
+
+import (
+	"github.com/google/uuid"
+	"time"
+)
+
+type AdMessages struct {
+	MessageID  uuid.UUID `sql:"primary_key"`
+	CampaignID uuid.UUID
+	Position   int32
+	BodyEn     string
+	BodyRu     string
+	CreatedAt  time.Time
+	UpdatedAt  time.Time
+}
@@ -0,0 +1,23 @@
+//
+// Code generated by go-jet DO NOT EDIT.
+//
+// WARNING: Changes to this file may cause incorrect behavior
+// and will be lost if the code is regenerated
+//
+
+package model
+
+import (
+	"time"
+)
+
+type AdSettings struct {
+	ID             bool `sql:"primary_key"`
+	HoldMs         int32
+	EdgePauseMs    int32
+	ScrollPxPerSec int32
+	FadeOutMs      int32
+	GapMs          int32
+	FadeInMs       int32
+	UpdatedAt      time.Time
+}
@@ -0,0 +1,102 @@
+//
+// Code generated by go-jet DO NOT EDIT.
+//
+// WARNING: Changes to this file may cause incorrect behavior
+// and will be lost if the code is regenerated
+//
+
+package table
+
+import (
+	"github.com/go-jet/jet/v2/postgres"
+)
+
+var AdCampaigns = newAdCampaignsTable("backend", "ad_campaigns", "")
+
+type adCampaignsTable struct {
+	postgres.Table
+
+	// Columns
+	CampaignID postgres.ColumnString
+	Name       postgres.ColumnString
+	Weight     postgres.ColumnInteger
+	IsDefault  postgres.ColumnBool
+	Enabled    postgres.ColumnBool
+	StartsAt   postgres.ColumnTimestampz
+	EndsAt     postgres.ColumnTimestampz
+	CreatedAt  postgres.ColumnTimestampz
+	UpdatedAt  postgres.ColumnTimestampz
+
+	AllColumns     postgres.ColumnList
+	MutableColumns postgres.ColumnList
+	DefaultColumns postgres.ColumnList
+}
+
+type AdCampaignsTable struct {
+	adCampaignsTable
+
+	EXCLUDED adCampaignsTable
+}
+
+// AS creates new AdCampaignsTable with assigned alias
+func (a AdCampaignsTable) AS(alias string) *AdCampaignsTable {
+	return newAdCampaignsTable(a.SchemaName(), a.TableName(), alias)
+}
+
+// Schema creates new AdCampaignsTable with assigned schema name
+func (a AdCampaignsTable) FromSchema(schemaName string) *AdCampaignsTable {
+	return newAdCampaignsTable(schemaName, a.TableName(), a.Alias())
+}
+
+// WithPrefix creates new AdCampaignsTable with assigned table prefix
+func (a AdCampaignsTable) WithPrefix(prefix string) *AdCampaignsTable {
+	return newAdCampaignsTable(a.SchemaName(), prefix+a.TableName(), a.TableName())
+}
+
+// WithSuffix creates new AdCampaignsTable with assigned table suffix
+func (a AdCampaignsTable) WithSuffix(suffix string) *AdCampaignsTable {
+	return newAdCampaignsTable(a.SchemaName(), a.TableName()+suffix, a.TableName())
+}
+
+func newAdCampaignsTable(schemaName, tableName, alias string) *AdCampaignsTable {
+	return &AdCampaignsTable{
+		adCampaignsTable: newAdCampaignsTableImpl(schemaName, tableName, alias),
+		EXCLUDED:         newAdCampaignsTableImpl("", "excluded", ""),
+	}
+}
+
+func newAdCampaignsTableImpl(schemaName, tableName, alias string) adCampaignsTable {
+	var (
+		CampaignIDColumn = postgres.StringColumn("campaign_id")
+		NameColumn       = postgres.StringColumn("name")
+		WeightColumn     = postgres.IntegerColumn("weight")
+		IsDefaultColumn  = postgres.BoolColumn("is_default")
+		EnabledColumn    = postgres.BoolColumn("enabled")
+		StartsAtColumn   = postgres.TimestampzColumn("starts_at")
+		EndsAtColumn     = postgres.TimestampzColumn("ends_at")
+		CreatedAtColumn  = postgres.TimestampzColumn("created_at")
+		UpdatedAtColumn  = postgres.TimestampzColumn("updated_at")
+		allColumns       = postgres.ColumnList{CampaignIDColumn, NameColumn, WeightColumn, IsDefaultColumn, EnabledColumn, StartsAtColumn, EndsAtColumn, CreatedAtColumn, UpdatedAtColumn}
+		mutableColumns   = postgres.ColumnList{NameColumn, WeightColumn, IsDefaultColumn, EnabledColumn, StartsAtColumn, EndsAtColumn, CreatedAtColumn, UpdatedAtColumn}
+		defaultColumns   = postgres.ColumnList{IsDefaultColumn, EnabledColumn, CreatedAtColumn, UpdatedAtColumn}
+	)
+
+	return adCampaignsTable{
+		Table: postgres.NewTable(schemaName, tableName, alias, allColumns...),
+
+		//Columns
+		CampaignID: CampaignIDColumn,
+		Name:       NameColumn,
+		Weight:     WeightColumn,
+		IsDefault:  IsDefaultColumn,
+		Enabled:    EnabledColumn,
+		StartsAt:   StartsAtColumn,
+		EndsAt:     EndsAtColumn,
+		CreatedAt:  CreatedAtColumn,
+		UpdatedAt:  UpdatedAtColumn,
+
+		AllColumns:     allColumns,
+		MutableColumns: mutableColumns,
+		DefaultColumns: defaultColumns,
+	}
+}
@@ -0,0 +1,96 @@
+//
+// Code generated by go-jet DO NOT EDIT.
+//
+// WARNING: Changes to this file may cause incorrect behavior
+// and will be lost if the code is regenerated
+//
+
+package table
+
+import (
+	"github.com/go-jet/jet/v2/postgres"
+)
+
+var AdMessages = newAdMessagesTable("backend", "ad_messages", "")
+
+type adMessagesTable struct {
+	postgres.Table
+
+	// Columns
+	MessageID  postgres.ColumnString
+	CampaignID postgres.ColumnString
+	Position   postgres.ColumnInteger
+	BodyEn     postgres.ColumnString
+	BodyRu     postgres.ColumnString
+	CreatedAt  postgres.ColumnTimestampz
+	UpdatedAt  postgres.ColumnTimestampz
+
+	AllColumns     postgres.ColumnList
+	MutableColumns postgres.ColumnList
+	DefaultColumns postgres.ColumnList
+}
+
+type AdMessagesTable struct {
+	adMessagesTable
+
+	EXCLUDED adMessagesTable
+}
+
+// AS creates new AdMessagesTable with assigned alias
+func (a AdMessagesTable) AS(alias string) *AdMessagesTable {
+	return newAdMessagesTable(a.SchemaName(), a.TableName(), alias)
+}
+
+// Schema creates new AdMessagesTable with assigned schema name
+func (a AdMessagesTable) FromSchema(schemaName string) *AdMessagesTable {
+	return newAdMessagesTable(schemaName, a.TableName(), a.Alias())
+}
+
+// WithPrefix creates new AdMessagesTable with assigned table prefix
+func (a AdMessagesTable) WithPrefix(prefix string) *AdMessagesTable {
+	return newAdMessagesTable(a.SchemaName(), prefix+a.TableName(), a.TableName())
+}
+
+// WithSuffix creates new AdMessagesTable with assigned table suffix
+func (a AdMessagesTable) WithSuffix(suffix string) *AdMessagesTable {
+	return newAdMessagesTable(a.SchemaName(), a.TableName()+suffix, a.TableName())
+}
+
+func newAdMessagesTable(schemaName, tableName, alias string) *AdMessagesTable {
+	return &AdMessagesTable{
+		adMessagesTable: newAdMessagesTableImpl(schemaName, tableName, alias),
+		EXCLUDED:        newAdMessagesTableImpl("", "excluded", ""),
+	}
+}
+
+func newAdMessagesTableImpl(schemaName, tableName, alias string) adMessagesTable {
+	var (
+		MessageIDColumn  = postgres.StringColumn("message_id")
+		CampaignIDColumn = postgres.StringColumn("campaign_id")
+		PositionColumn   = postgres.IntegerColumn("position")
+		BodyEnColumn     = postgres.StringColumn("body_en")
+		BodyRuColumn     = postgres.StringColumn("body_ru")
+		CreatedAtColumn  = postgres.TimestampzColumn("created_at")
+		UpdatedAtColumn  = postgres.TimestampzColumn("updated_at")
+		allColumns       = postgres.ColumnList{MessageIDColumn, CampaignIDColumn, PositionColumn, BodyEnColumn, BodyRuColumn, CreatedAtColumn, UpdatedAtColumn}
+		mutableColumns   = postgres.ColumnList{CampaignIDColumn, PositionColumn, BodyEnColumn, BodyRuColumn, CreatedAtColumn, UpdatedAtColumn}
+		defaultColumns   = postgres.ColumnList{PositionColumn, CreatedAtColumn, UpdatedAtColumn}
+	)
+
+	return adMessagesTable{
+		Table: postgres.NewTable(schemaName, tableName, alias, allColumns...),
+
+		//Columns
+		MessageID:  MessageIDColumn,
+		CampaignID: CampaignIDColumn,
+		Position:   PositionColumn,
+		BodyEn:     BodyEnColumn,
+		BodyRu:     BodyRuColumn,
+		CreatedAt:  CreatedAtColumn,
+		UpdatedAt:  UpdatedAtColumn,
+
+		AllColumns:     allColumns,
+		MutableColumns: mutableColumns,
+		DefaultColumns: defaultColumns,
+	}
+}
@@ -0,0 +1,99 @@
+//
+// Code generated by go-jet DO NOT EDIT.
+//
+// WARNING: Changes to this file may cause incorrect behavior
+// and will be lost if the code is regenerated
+//
+
+package table
+
+import (
+	"github.com/go-jet/jet/v2/postgres"
+)
+
+var AdSettings = newAdSettingsTable("backend", "ad_settings", "")
+
+type adSettingsTable struct {
+	postgres.Table
+
+	// Columns
+	ID             postgres.ColumnBool
+	HoldMs         postgres.ColumnInteger
+	EdgePauseMs    postgres.ColumnInteger
+	ScrollPxPerSec postgres.ColumnInteger
+	FadeOutMs      postgres.ColumnInteger
+	GapMs          postgres.ColumnInteger
+	FadeInMs       postgres.ColumnInteger
+	UpdatedAt      postgres.ColumnTimestampz
+
+	AllColumns     postgres.ColumnList
+	MutableColumns postgres.ColumnList
+	DefaultColumns postgres.ColumnList
+}
+
+type AdSettingsTable struct {
+	adSettingsTable
+
+	EXCLUDED adSettingsTable
+}
+
+// AS creates new AdSettingsTable with assigned alias
+func (a AdSettingsTable) AS(alias string) *AdSettingsTable {
+	return newAdSettingsTable(a.SchemaName(), a.TableName(), alias)
+}
+
+// Schema creates new AdSettingsTable with assigned schema name
+func (a AdSettingsTable) FromSchema(schemaName string) *AdSettingsTable {
+	return newAdSettingsTable(schemaName, a.TableName(), a.Alias())
+}
+
+// WithPrefix creates new AdSettingsTable with assigned table prefix
+func (a AdSettingsTable) WithPrefix(prefix string) *AdSettingsTable {
+	return newAdSettingsTable(a.SchemaName(), prefix+a.TableName(), a.TableName())
+}
+
+// WithSuffix creates new AdSettingsTable with assigned table suffix
+func (a AdSettingsTable) WithSuffix(suffix string) *AdSettingsTable {
+	return newAdSettingsTable(a.SchemaName(), a.TableName()+suffix, a.TableName())
+}
+
+func newAdSettingsTable(schemaName, tableName, alias string) *AdSettingsTable {
+	return &AdSettingsTable{
+		adSettingsTable: newAdSettingsTableImpl(schemaName, tableName, alias),
+		EXCLUDED:        newAdSettingsTableImpl("", "excluded", ""),
+	}
+}
+
+func newAdSettingsTableImpl(schemaName, tableName, alias string) adSettingsTable {
+	var (
+		IDColumn             = postgres.BoolColumn("id")
+		HoldMsColumn         = postgres.IntegerColumn("hold_ms")
+		EdgePauseMsColumn    = postgres.IntegerColumn("edge_pause_ms")
+		ScrollPxPerSecColumn = postgres.IntegerColumn("scroll_px_per_sec")
+		FadeOutMsColumn      = postgres.IntegerColumn("fade_out_ms")
+		GapMsColumn          = postgres.IntegerColumn("gap_ms")
+		FadeInMsColumn       = postgres.IntegerColumn("fade_in_ms")
+		UpdatedAtColumn      = postgres.TimestampzColumn("updated_at")
+		allColumns           = postgres.ColumnList{IDColumn, HoldMsColumn, EdgePauseMsColumn, ScrollPxPerSecColumn, FadeOutMsColumn, GapMsColumn, FadeInMsColumn, UpdatedAtColumn}
+		mutableColumns       = postgres.ColumnList{HoldMsColumn, EdgePauseMsColumn, ScrollPxPerSecColumn, FadeOutMsColumn, GapMsColumn, FadeInMsColumn, UpdatedAtColumn}
+		defaultColumns       = postgres.ColumnList{IDColumn, UpdatedAtColumn}
+	)
+
+	return adSettingsTable{
+		Table: postgres.NewTable(schemaName, tableName, alias, allColumns...),
+
+		//Columns
+		ID:             IDColumn,
+		HoldMs:         HoldMsColumn,
+		EdgePauseMs:    EdgePauseMsColumn,
+		ScrollPxPerSec: ScrollPxPerSecColumn,
+		FadeOutMs:      FadeOutMsColumn,
+		GapMs:          GapMsColumn,
+		FadeInMs:       FadeInMsColumn,
+		UpdatedAt:      UpdatedAtColumn,
+
+		AllColumns:     allColumns,
+		MutableColumns: mutableColumns,
+		DefaultColumns: defaultColumns,
+	}
+}
@@ -14,6 +14,9 @@ func UseSchema(schema string) {
 	AccountStats = AccountStats.FromSchema(schema)
 	AccountSuspensions = AccountSuspensions.FromSchema(schema)
 	Accounts = Accounts.FromSchema(schema)
+	AdCampaigns = AdCampaigns.FromSchema(schema)
+	AdMessages = AdMessages.FromSchema(schema)
+	AdSettings = AdSettings.FromSchema(schema)
 	Blocks = Blocks.FromSchema(schema)
 	ChatMessages = ChatMessages.FromSchema(schema)
 	Complaints = Complaints.FromSchema(schema)
@@ -0,0 +1,86 @@
+-- +goose Up
+-- Server-driven advertising banner ("advertising network"): operator-managed campaigns rotated in
+-- the client's one-line announcement strip. A campaign is one placement order with a show weight
+-- (percent); simultaneously active campaigns compete for shows in proportion to their weights. The
+-- single perpetual default campaign fills the unsold remainder up to 100%. Each campaign carries
+-- one or more bilingual messages (en + ru, both mandatory), shown by the viewer's bot (service)
+-- language. Display timings are global (one settings row). Eligibility (who sees a banner at all)
+-- reuses account fields + the no_banner role, so it needs no schema here. See docs/ARCHITECTURE.md
+-- and internal/ads.
+SET search_path = backend, pg_catalog;
+
+-- One advertising campaign = one placement order. weight is the show percentage (1..100). is_default
+-- marks the single perpetual house campaign that fills the remainder up to 100% and is never deleted;
+-- it has no validity window (its stored weight is nominal — the rotation derives its effective weight
+-- as max(0, 100 - sum of active timed weights)). A time-limited campaign is active while now() lies in
+-- [starts_at, ends_at] (a null bound is open-ended on that side). enabled toggles a campaign without
+-- deleting it.
+CREATE TABLE ad_campaigns (
+    campaign_id uuid        PRIMARY KEY,
+    name        text        NOT NULL,
+    weight      integer     NOT NULL,
+    is_default  boolean     NOT NULL DEFAULT false,
+    enabled     boolean     NOT NULL DEFAULT true,
+    starts_at   timestamptz,
+    ends_at     timestamptz,
+    created_at  timestamptz NOT NULL DEFAULT now(),
+    updated_at  timestamptz NOT NULL DEFAULT now(),
+    CONSTRAINT ad_campaigns_weight_chk CHECK (weight BETWEEN 1 AND 100),
+    -- The default campaign is perpetual (no window).
+    CONSTRAINT ad_campaigns_default_window_chk CHECK (NOT is_default OR (starts_at IS NULL AND ends_at IS NULL)),
+    -- A closed window must not be inverted.
+    CONSTRAINT ad_campaigns_window_chk CHECK (starts_at IS NULL OR ends_at IS NULL OR starts_at <= ends_at)
+);
+-- At most one default campaign.
+CREATE UNIQUE INDEX ad_campaigns_default_idx ON ad_campaigns (is_default) WHERE is_default;
+
+-- One bilingual message of a campaign. Both languages are mandatory: the client shows the variant for
+-- the viewer's bot (service) language. position orders the messages within a campaign (the round-robin
+-- order when the campaign wins a display slot). body_* is minimal markdown (text + links).
+CREATE TABLE ad_messages (
+    message_id  uuid        PRIMARY KEY,
+    campaign_id uuid        NOT NULL REFERENCES ad_campaigns (campaign_id) ON DELETE CASCADE,
+    position    integer     NOT NULL DEFAULT 0,
+    body_en     text        NOT NULL,
+    body_ru     text        NOT NULL,
+    created_at  timestamptz NOT NULL DEFAULT now(),
+    updated_at  timestamptz NOT NULL DEFAULT now()
+);
+-- Messages of a campaign are read in display order.
+CREATE INDEX ad_messages_campaign_idx ON ad_messages (campaign_id, position);
+
+-- Global banner display timings, a single row (id is always TRUE). The client rotator reads these:
+-- hold_ms is how long one message shows; edge_pause_ms and scroll_px_per_sec drive the scroll of a
+-- message wider than the strip; the transition between messages is fade_out_ms -> gap_ms -> fade_in_ms.
+-- All are clamped in Go on update.
+CREATE TABLE ad_settings (
+    id                boolean     PRIMARY KEY DEFAULT true,
+    hold_ms           integer     NOT NULL,
+    edge_pause_ms     integer     NOT NULL,
+    scroll_px_per_sec integer     NOT NULL,
+    fade_out_ms       integer     NOT NULL,
+    gap_ms            integer     NOT NULL,
+    fade_in_ms        integer     NOT NULL,
+    updated_at        timestamptz NOT NULL DEFAULT now(),
+    CONSTRAINT ad_settings_singleton_chk CHECK (id)
+);
+
+-- Seed the perpetual default campaign with one bilingual house message, and the default timings
+-- (the previous hardcoded UI defaults plus the new fade sequence). Fixed UUIDs keep the seed
+-- deterministic across environments.
+INSERT INTO ad_campaigns (campaign_id, name, weight, is_default, enabled)
+VALUES ('00000000-0000-0000-0000-0000000000ad', 'Default (house)', 100, true, true);
+INSERT INTO ad_messages (message_id, campaign_id, position, body_en, body_ru)
+VALUES (
+    '00000000-0000-0000-0000-0000000000a1', '00000000-0000-0000-0000-0000000000ad', 0,
+    'Tip: a play using all 7 tiles earns a +50 bonus.',
+    'Совет: ход всеми 7 фишками приносит бонус +50 очков.'
+);
+INSERT INTO ad_settings (id, hold_ms, edge_pause_ms, scroll_px_per_sec, fade_out_ms, gap_ms, fade_in_ms)
+VALUES (true, 60000, 5000, 40, 1000, 250, 1000);
+
+-- +goose Down
+SET search_path = backend, pg_catalog;
+DROP TABLE IF EXISTS ad_settings;
+DROP TABLE IF EXISTS ad_messages;
+DROP TABLE IF EXISTS ad_campaigns;