feat(telegram): bot support relay — per-user forum topics

Users who DM the bot anything but /start are relayed into a private forum supergroup, one topic per user. Operators (the chat's admins) reply in the topic and the bot copies it back to the user; an info card opening each topic carries a Block/Unblock toggle and a Clear button. State is a small JSON file on a new /data volume — the bot host has no database. Off by default (TELEGRAM_SUPPORT_CHAT_ID=0): the prod bot is unchanged until the operator sets the chat id and adds the bot as a forum admin. - internal/support: concurrency-safe JSON store (topic map, block list, relayed message ids) with field-targeted mutators and atomic save - bot/support.go: relay both ways via copyMessage, short-TTL admin cache, callback buttons, per-user topic-create lock, loop guard (skip the bot's own posts), reopen a deleted topic on the next message - config + compose + CI/prod-deploy: TELEGRAM_SUPPORT_CHAT_ID per contour + TELEGRAM_SUPPORT_STATE_DIR; bot-state named volume; /data pre-owned by UID 65532 so a fresh volume is writable under distroless - docs: ARCHITECTURE §15 + decision record, FUNCTIONAL (+ru), README
2026-06-23 17:47:00 +02:00
parent e6277dcd43
commit 6a602aefae
18 changed files with 1465 additions and 7 deletions
@@ -15,6 +15,8 @@ import (
 	"github.com/go-telegram/bot/models"
 	"go.uber.org/zap"
 	"golang.org/x/time/rate"
+
+	"scrabble/platform/telegram/internal/support"
 )

 // Config configures the bot wrapper.
@@ -39,6 +41,14 @@ type Config struct {
 	// GameChannelID is the game channel whose public @username the /start welcome links
 	// to (resolved from this id via getChat at startup); 0 omits that follow link.
 	GameChannelID int64
+	// SupportChatID is the private forum supergroup the bot relays direct user messages
+	// into (one topic per user) and reads operator replies from; 0 disables the support
+	// relay. The bot must be an administrator there with the manage-topics and
+	// delete-messages rights.
+	SupportChatID int64
+	// SupportStore persists the support relay's state (topic mapping, block list,
+	// relayed message ids); required when SupportChatID is set, ignored otherwise.
+	SupportStore *support.Store
 }

 // EligibilityResolver answers whether the Telegram user identified by externalID
@@ -66,11 +76,21 @@ type Bot struct {
 	channelUsername string
 	chatUsername    string
 	// botID is the bot's own Telegram user id (resolved at startup); it skips the
-	// chat_member updates the bot's own restrict actions generate — the grant loop guard.
+	// chat_member updates the bot's own restrict actions generate — the grant loop guard —
+	// and the bot's own relayed copies in the support chat.
 	botID int64
 	// eligibility resolves a joining user's chat write eligibility; nil leaves a
 	// joiner muted (fail-closed) until it is wired.
 	eligibility EligibilityResolver
+	// supportChatID is the support relay's forum supergroup (0 disables the relay).
+	supportChatID int64
+	// support persists the support relay's per-user state; nil when the relay is off.
+	support *support.Store
+	// supportLocks serialises per-user topic creation so a burst of a new user's
+	// messages opens exactly one topic.
+	supportLocks *keyedMutex
+	// admins caches the support chat's administrator ids (who may reply and act).
+	admins *adminCache
 }

 // New builds the bot wrapper, registering the /start handler and a default handler
@@ -80,7 +100,14 @@ func New(cfg Config, log *zap.Logger) (*Bot, error) {
 	if log == nil {
 		log = zap.NewNop()
 	}
-	t := &Bot{miniAppURL: cfg.MiniAppURL, log: log, chatID: cfg.ChatID, channelID: cfg.GameChannelID}
+	t := &Bot{
+		miniAppURL:    cfg.MiniAppURL,
+		log:           log,
+		chatID:        cfg.ChatID,
+		channelID:     cfg.GameChannelID,
+		supportChatID: cfg.SupportChatID,
+		support:       cfg.SupportStore,
+	}
 	if cfg.SendRatePerSecond > 0 {
 		t.limiter = rate.NewLimiter(rate.Limit(cfg.SendRatePerSecond), cfg.SendRatePerSecond)
 	}
@@ -89,15 +116,26 @@ func New(cfg Config, log *zap.Logger) (*Bot, error) {
 		tgbot.WithDefaultHandler(t.handleUpdate),
 		tgbot.WithMessageTextHandler("/start", tgbot.MatchTypePrefix, t.handleStart),
 	}
+	if t.supportEnabled() {
+		t.supportLocks = newKeyedMutex()
+		t.admins = &adminCache{}
+		// The info-card buttons are callback_query updates; route them to the support
+		// callback handler by their "sup:" data prefix.
+		opts = append(opts, tgbot.WithCallbackQueryDataHandler(supportCallbackPrefix, tgbot.MatchTypePrefix, t.handleSupportCallback))
+	}
+	// Allowed updates default to "all except chat_member". Specify an explicit set only
+	// when we need chat_member (moderated chat) — and then re-add callback_query (which
+	// the explicit set would otherwise drop) when the support relay needs it.
 	if cfg.ChatID != 0 {
-		// chat_member updates are off by default; subscribe explicitly (alongside
-		// messages) so the bot sees joins in the moderated chat. The bot must also be an
-		// administrator there for Telegram to deliver them.
-		opts = append(opts, tgbot.WithAllowedUpdates(tgbot.AllowedUpdates{
+		allowed := tgbot.AllowedUpdates{
 			models.AllowedUpdateMessage,
 			models.AllowedUpdateMyChatMember,
 			models.AllowedUpdateChatMember,
-		}))
+		}
+		if t.supportEnabled() {
+			allowed = append(allowed, models.AllowedUpdateCallbackQuery)
+		}
+		opts = append(opts, tgbot.WithAllowedUpdates(allowed))
 	}
 	if cfg.TestEnv {
 		// Route to the Bot API test environment (.../bot<token>/test/METHOD).
@@ -134,6 +172,9 @@ func (t *Bot) Run(ctx context.Context) {
 	if t.chatID != 0 {
 		t.logChatAdminStatus(ctx)
 	}
+	if t.supportEnabled() {
+		t.initSupport(ctx)
+	}
 	t.resolveWelcomeHandles(ctx)
 	t.api.Start(ctx)
 }
@@ -305,6 +346,19 @@ func (t *Bot) handleUpdate(ctx context.Context, api *tgbot.Bot, update *models.U
 		t.handleChatMember(ctx, update.ChatMember)
 		return
 	}
+	// Support relay (when enabled): a non-/start message — /start has its own handler —
+	// is either an operator's reply in the support chat or a user's direct message to
+	// relay. Everything else falls through to the Mini App launch reply.
+	if t.supportEnabled() && update.Message != nil {
+		switch {
+		case update.Message.Chat.ID == t.supportChatID:
+			t.handleSupportGroupMessage(ctx, update.Message)
+			return
+		case update.Message.Chat.Type == models.ChatTypePrivate:
+			t.handleSupportUserMessage(ctx, update.Message)
+			return
+		}
+	}
 	t.handleStart(ctx, api, update)
 }

@@ -0,0 +1,438 @@
+package bot
+
+import (
+	"context"
+	"fmt"
+	"html"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	tgbot "github.com/go-telegram/bot"
+	"github.com/go-telegram/bot/models"
+	"go.uber.org/zap"
+)
+
+// Support relay: the bot forwards a user's direct messages into a per-user forum
+// topic in the operators' private support chat, and relays operator replies in that
+// topic back to the user. The info card opening each topic carries a Block/Unblock
+// toggle and a Clear button. State (topic mapping, block list, relayed message ids)
+// lives in a small JSON file via internal/support.
+const (
+	// supportCallbackPrefix namespaces the info-card button callbacks
+	// ("sup:<action>:<userID>").
+	supportCallbackPrefix = "sup:"
+	supportActionBlock    = "block"
+	supportActionUnblock  = "unblock"
+	supportActionClear    = "clear"
+	// supportAdminTTL is how long the support chat's administrator set is cached.
+	supportAdminTTL = time.Minute
+	// supportTopicNameMax bounds the forum topic name (the Telegram limit is 128).
+	supportTopicNameMax = 128
+	// supportDeleteBatch is the maximum message ids per deleteMessages call (the
+	// Telegram limit is 100).
+	supportDeleteBatch = 100
+)
+
+// supportEnabled reports whether the support relay is configured.
+func (t *Bot) supportEnabled() bool {
+	return t.supportChatID != 0 && t.support != nil
+}
+
+// initSupport prepares the support relay at startup: it resolves the bot's own user
+// id (getMe) for the loop guard, unless the chat-gating self-check already did, and
+// logs readiness. The loop guard also tests From.IsBot, so an unresolved id is not
+// fatal.
+func (t *Bot) initSupport(ctx context.Context) {
+	if t.botID == 0 {
+		if me, err := t.api.GetMe(ctx); err != nil {
+			t.log.Warn("support: getMe failed; relying on is_bot for the loop guard", zap.Error(err))
+		} else {
+			t.botID = me.ID
+		}
+	}
+	t.log.Info("support relay ready", zap.Int64("support_chat_id", t.supportChatID))
+}
+
+// keyedMutex serialises work per int64 key (here, per user id) so two concurrent
+// updates from the same user — the go-telegram/bot library runs handlers in
+// goroutines — cannot both open a forum topic.
+type keyedMutex struct {
+	mu sync.Mutex
+	m  map[int64]*sync.Mutex
+}
+
+func newKeyedMutex() *keyedMutex { return &keyedMutex{m: map[int64]*sync.Mutex{}} }
+
+// lock acquires the per-key mutex and returns its unlock function.
+func (k *keyedMutex) lock(key int64) func() {
+	k.mu.Lock()
+	mu, ok := k.m[key]
+	if !ok {
+		mu = &sync.Mutex{}
+		k.m[key] = mu
+	}
+	k.mu.Unlock()
+	mu.Lock()
+	return mu.Unlock
+}
+
+// adminCache caches the support chat's administrator ids for a short TTL, so the bot
+// does not call getChatAdministrators on every operator action.
+type adminCache struct {
+	mu        sync.Mutex
+	ids       map[int64]bool
+	fetchedAt time.Time
+}
+
+// isSupportAdmin reports whether userID administers the support chat, refreshing the
+// cache when stale. On a refresh failure it falls back to the last known set
+// (fail-closed when nothing is cached yet).
+func (t *Bot) isSupportAdmin(ctx context.Context, userID int64) bool {
+	t.admins.mu.Lock()
+	if t.admins.ids != nil && time.Since(t.admins.fetchedAt) < supportAdminTTL {
+		ok := t.admins.ids[userID]
+		t.admins.mu.Unlock()
+		return ok
+	}
+	t.admins.mu.Unlock()
+
+	members, err := t.api.GetChatAdministrators(ctx, &tgbot.GetChatAdministratorsParams{ChatID: t.supportChatID})
+	if err != nil {
+		t.log.Warn("support: getChatAdministrators failed; using cached admin set", zap.Error(err))
+		t.admins.mu.Lock()
+		defer t.admins.mu.Unlock()
+		return t.admins.ids[userID] // a nil map yields false (fail-closed)
+	}
+	ids := make(map[int64]bool, len(members))
+	for _, m := range members {
+		if u := chatMemberUser(m); u != nil {
+			ids[u.ID] = true
+		}
+	}
+	t.admins.mu.Lock()
+	t.admins.ids = ids
+	t.admins.fetchedAt = time.Now()
+	t.admins.mu.Unlock()
+	return ids[userID]
+}
+
+// handleSupportUserMessage relays a user's direct message into their forum topic in
+// the support chat, opening the topic (and its info card) on first contact. A blocked
+// user's message is dropped silently, and the user receives no reply — operators
+// answer from the topic.
+func (t *Bot) handleSupportUserMessage(ctx context.Context, m *models.Message) {
+	if m.From == nil || m.From.IsBot {
+		return
+	}
+	uid := m.From.ID
+	unlock := t.supportLocks.lock(uid)
+	defer unlock()
+
+	rec, ok := t.support.Get(uid)
+	if ok && rec.Blocked {
+		return
+	}
+	topicID := 0
+	if ok {
+		topicID = rec.TopicID
+	}
+	if topicID == 0 {
+		var err error
+		if topicID, err = t.openSupportTopic(ctx, m.From); err != nil {
+			t.log.Warn("support: open topic failed", zap.Int64("user_id", uid), zap.Error(err))
+			return
+		}
+	}
+
+	newID, err := t.copyToTopic(ctx, m.Chat.ID, m.ID, topicID)
+	if err != nil && isTopicMissingErr(err) {
+		// The operators deleted the whole topic; reopen it and retry once.
+		t.log.Info("support: topic gone, reopening", zap.Int64("user_id", uid), zap.Int("topic_id", topicID))
+		if topicID, err = t.openSupportTopic(ctx, m.From); err == nil {
+			newID, err = t.copyToTopic(ctx, m.Chat.ID, m.ID, topicID)
+		}
+	}
+	if err != nil {
+		t.log.Warn("support: relay to topic failed", zap.Int64("user_id", uid), zap.Error(err))
+		return
+	}
+	if err := t.support.AppendMsg(uid, newID); err != nil {
+		t.log.Warn("support: persist relayed id failed", zap.Int64("user_id", uid), zap.Error(err))
+	}
+}
+
+// handleSupportGroupMessage relays an operator's reply in a user's topic back to that
+// user. It ignores the bot's own posts (the loop guard), messages outside a topic,
+// unknown topics, and non-administrators. The operator's message is tracked too, so a
+// later clear removes it.
+func (t *Bot) handleSupportGroupMessage(ctx context.Context, m *models.Message) {
+	if m.From == nil || m.From.IsBot {
+		return // the bot's own relayed copies (and other bots) — never loop them back
+	}
+	if t.botID != 0 && m.From.ID == t.botID {
+		return
+	}
+	if m.MessageThreadID == 0 {
+		return // the chat's general area, not a user's topic
+	}
+	uid, ok := t.support.ByTopic(m.MessageThreadID)
+	if !ok {
+		return
+	}
+	if !t.isSupportAdmin(ctx, m.From.ID) {
+		return // only operators reach the user
+	}
+	if err := t.support.AppendMsg(uid, m.ID); err != nil {
+		t.log.Warn("support: persist operator msg id failed", zap.Int64("user_id", uid), zap.Error(err))
+	}
+	if _, err := t.copyToUser(ctx, m.ID, uid); err != nil {
+		t.log.Warn("support: relay reply to user failed", zap.Int64("user_id", uid), zap.Error(err))
+	}
+}
+
+// handleSupportCallback handles the info-card buttons (block/unblock/clear). Only
+// support-chat administrators may act; others get a denial. It always answers the
+// callback query so the client's spinner clears.
+func (t *Bot) handleSupportCallback(ctx context.Context, _ *tgbot.Bot, update *models.Update) {
+	cq := update.CallbackQuery
+	if cq == nil {
+		return
+	}
+	action, uid, ok := parseSupportCallback(cq.Data)
+	if !ok {
+		t.answerSupportCallback(ctx, cq.ID, "")
+		return
+	}
+	if !t.isSupportAdmin(ctx, cq.From.ID) {
+		t.answerSupportCallback(ctx, cq.ID, "Недостаточно прав")
+		return
+	}
+	switch action {
+	case supportActionBlock:
+		t.setSupportBlocked(ctx, cq, uid, true)
+	case supportActionUnblock:
+		t.setSupportBlocked(ctx, cq, uid, false)
+	case supportActionClear:
+		t.clearSupportTopic(ctx, cq, uid)
+	default:
+		t.answerSupportCallback(ctx, cq.ID, "")
+	}
+}
+
+// setSupportBlocked sets the user's block state, flips the info-card toggle to match,
+// and answers the callback. Blocking does not delete the topic — it stays.
+func (t *Bot) setSupportBlocked(ctx context.Context, cq *models.CallbackQuery, uid int64, blocked bool) {
+	if err := t.support.SetBlocked(uid, blocked); err != nil {
+		t.log.Warn("support: set blocked failed", zap.Int64("user_id", uid), zap.Error(err))
+		t.answerSupportCallback(ctx, cq.ID, "Ошибка")
+		return
+	}
+	if rec, ok := t.support.Get(uid); ok && rec.HeaderMsgID != 0 {
+		if _, err := t.api.EditMessageReplyMarkup(ctx, &tgbot.EditMessageReplyMarkupParams{
+			ChatID:      t.supportChatID,
+			MessageID:   rec.HeaderMsgID,
+			ReplyMarkup: supportCardMarkup(uid, blocked),
+		}); err != nil {
+			t.log.Debug("support: update card markup failed", zap.Error(err))
+		}
+	}
+	msg := "Разблокирован"
+	if blocked {
+		msg = "Заблокирован"
+	}
+	t.answerSupportCallback(ctx, cq.ID, msg)
+}
+
+// clearSupportTopic deletes the messages relayed into the user's topic (keeping the
+// info card) and answers the callback.
+func (t *Bot) clearSupportTopic(ctx context.Context, cq *models.CallbackQuery, uid int64) {
+	ids, err := t.support.ClearMsgs(uid)
+	if err != nil {
+		t.log.Warn("support: clear failed", zap.Int64("user_id", uid), zap.Error(err))
+		t.answerSupportCallback(ctx, cq.ID, "Ошибка")
+		return
+	}
+	t.deleteSupportMessages(ctx, ids)
+	t.answerSupportCallback(ctx, cq.ID, "Очищено")
+}
+
+// openSupportTopic creates a forum topic for the user and posts its info card with
+// the block/clear buttons, persisting both. It returns the new topic id. A failure to
+// persist is logged but not fatal: the in-memory mapping still lets the relay proceed.
+func (t *Bot) openSupportTopic(ctx context.Context, u *models.User) (int, error) {
+	topic, err := t.api.CreateForumTopic(ctx, &tgbot.CreateForumTopicParams{
+		ChatID: t.supportChatID,
+		Name:   supportTopicName(u),
+	})
+	if err != nil {
+		return 0, fmt.Errorf("create forum topic: %w", err)
+	}
+	headerID := 0
+	header, err := t.api.SendMessage(ctx, &tgbot.SendMessageParams{
+		ChatID:          t.supportChatID,
+		MessageThreadID: topic.MessageThreadID,
+		Text:            supportCardText(u),
+		ParseMode:       models.ParseModeHTML,
+		ReplyMarkup:     supportCardMarkup(u.ID, false),
+	})
+	if err != nil {
+		t.log.Warn("support: post info card failed (topic opened without it)", zap.Error(err))
+	} else {
+		headerID = header.ID
+	}
+	if err := t.support.SetTopic(u.ID, topic.MessageThreadID, headerID, u.FirstName, u.LastName, u.Username); err != nil {
+		t.log.Warn("support: persist topic state failed (kept in memory)", zap.Int64("user_id", u.ID), zap.Error(err))
+	}
+	return topic.MessageThreadID, nil
+}
+
+// copyToTopic copies a message into the user's forum topic and returns the new
+// message id.
+func (t *Bot) copyToTopic(ctx context.Context, fromChatID int64, messageID, topicID int) (int, error) {
+	if err := t.throttle(ctx); err != nil {
+		return 0, err
+	}
+	res, err := t.api.CopyMessage(ctx, &tgbot.CopyMessageParams{
+		ChatID:          t.supportChatID,
+		MessageThreadID: topicID,
+		FromChatID:      fromChatID,
+		MessageID:       messageID,
+	})
+	if err != nil {
+		return 0, err
+	}
+	return res.ID, nil
+}
+
+// copyToUser copies a support-chat message to the user's private chat and returns the
+// new message id.
+func (t *Bot) copyToUser(ctx context.Context, messageID int, userID int64) (int, error) {
+	if err := t.throttle(ctx); err != nil {
+		return 0, err
+	}
+	res, err := t.api.CopyMessage(ctx, &tgbot.CopyMessageParams{
+		ChatID:     userID,
+		FromChatID: t.supportChatID,
+		MessageID:  messageID,
+	})
+	if err != nil {
+		return 0, err
+	}
+	return res.ID, nil
+}
+
+// deleteSupportMessages best-effort deletes the given support-chat messages in
+// batches; individual failures (for example a message already removed) are ignored.
+func (t *Bot) deleteSupportMessages(ctx context.Context, ids []int) {
+	for start := 0; start < len(ids); start += supportDeleteBatch {
+		end := min(start+supportDeleteBatch, len(ids))
+		if _, err := t.api.DeleteMessages(ctx, &tgbot.DeleteMessagesParams{
+			ChatID:     t.supportChatID,
+			MessageIDs: ids[start:end],
+		}); err != nil {
+			t.log.Debug("support: delete batch failed", zap.Error(err))
+		}
+	}
+}
+
+// answerSupportCallback answers a callback query, logging a failure at debug (the
+// only effect of a miss is a lingering client spinner).
+func (t *Bot) answerSupportCallback(ctx context.Context, id, text string) {
+	if _, err := t.api.AnswerCallbackQuery(ctx, &tgbot.AnswerCallbackQueryParams{
+		CallbackQueryID: id,
+		Text:            text,
+	}); err != nil {
+		t.log.Debug("support: answer callback failed", zap.Error(err))
+	}
+}
+
+// parseSupportCallback parses "sup:<action>:<userID>" callback data.
+func parseSupportCallback(data string) (action string, userID int64, ok bool) {
+	rest, found := strings.CutPrefix(data, supportCallbackPrefix)
+	if !found {
+		return "", 0, false
+	}
+	action, idStr, found := strings.Cut(rest, ":")
+	if !found {
+		return "", 0, false
+	}
+	userID, err := strconv.ParseInt(idStr, 10, 64)
+	if err != nil {
+		return "", 0, false
+	}
+	return action, userID, true
+}
+
+// supportCardMarkup builds the info-card buttons: a Block/Unblock toggle reflecting
+// the current state, and a Clear button.
+func supportCardMarkup(userID int64, blocked bool) *models.InlineKeyboardMarkup {
+	toggleText, toggleAction := "Заблокировать", supportActionBlock
+	if blocked {
+		toggleText, toggleAction = "Разблокировать", supportActionUnblock
+	}
+	return &models.InlineKeyboardMarkup{
+		InlineKeyboard: [][]models.InlineKeyboardButton{{
+			{Text: toggleText, CallbackData: fmt.Sprintf("%s%s:%d", supportCallbackPrefix, toggleAction, userID)},
+			{Text: "Очистить", CallbackData: fmt.Sprintf("%s%s:%d", supportCallbackPrefix, supportActionClear, userID)},
+		}},
+	}
+}
+
+// supportTopicName builds the forum topic title for a user: full name and @username,
+// trimmed to the Telegram length limit.
+func supportTopicName(u *models.User) string {
+	name := strings.TrimSpace(u.FirstName + " " + u.LastName)
+	if name == "" {
+		name = "user " + strconv.FormatInt(u.ID, 10)
+	}
+	if u.Username != "" {
+		name += " @" + u.Username
+	}
+	if r := []rune(name); len(r) > supportTopicNameMax {
+		return string(r[:supportTopicNameMax])
+	}
+	return name
+}
+
+// supportCardText renders the info card describing the user. User-controlled fields
+// are HTML-escaped because the card uses HTML parse mode for the profile link.
+func supportCardText(u *models.User) string {
+	name := html.EscapeString(strings.TrimSpace(u.FirstName + " " + u.LastName))
+	if name == "" {
+		name = "—"
+	}
+	username := "—"
+	if u.Username != "" {
+		username = "@" + html.EscapeString(u.Username)
+	}
+	lang := u.LanguageCode
+	if lang == "" {
+		lang = "—"
+	}
+	premium := "нет"
+	if u.IsPremium {
+		premium = "да"
+	}
+	var b strings.Builder
+	fmt.Fprintf(&b, "<b>%s</b>\n", name)
+	fmt.Fprintf(&b, "Username: %s\n", username)
+	fmt.Fprintf(&b, "ID: <code>%d</code>\n", u.ID)
+	fmt.Fprintf(&b, "Язык: %s · Premium: %s\n", html.EscapeString(lang), premium)
+	fmt.Fprintf(&b, `<a href="tg://user?id=%d">Открыть профиль</a>`, u.ID)
+	return b.String()
+}
+
+// isTopicMissingErr reports whether err is Telegram's deleted/absent forum-topic
+// error, signalling the topic must be reopened.
+func isTopicMissingErr(err error) bool {
+	if err == nil {
+		return false
+	}
+	s := strings.ToLower(err.Error())
+	return strings.Contains(s, "thread not found") ||
+		strings.Contains(s, "thread_not_found") ||
+		strings.Contains(s, "topic deleted") ||
+		strings.Contains(s, "topic_deleted")
+}
@@ -0,0 +1,404 @@
+package bot
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/go-telegram/bot/models"
+	"go.uber.org/zap"
+
+	"scrabble/platform/telegram/internal/support"
+)
+
+const supportChatID = -1001000000000
+
+// copyRec records one copyMessage call.
+type copyRec struct {
+	chatID, fromChatID, threadID, messageID string
+}
+
+// supportAPI is a fake Bot API for the support-relay handlers: it answers the
+// methods they call with incrementing ids and records the requests for assertions.
+type supportAPI struct {
+	mu           sync.Mutex
+	adminIDs     []int64
+	nextThread   int
+	nextMsg      int
+	topicsOpened int
+	copies       []copyRec
+	headerThread string // message_thread_id of the last header sendMessage
+	deleted      [][]int
+	editedMsgIDs []string
+	answers      []string
+}
+
+func newSupportAPI(adminIDs ...int64) *supportAPI {
+	return &supportAPI{adminIDs: adminIDs, nextThread: 1000, nextMsg: 5000}
+}
+
+func (s *supportAPI) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	path := r.URL.Path
+	switch {
+	case strings.HasSuffix(path, "/getMe"):
+		io.WriteString(w, `{"ok":true,"result":{"id":1,"is_bot":true,"first_name":"bot","username":"b"}}`)
+	case strings.HasSuffix(path, "/createForumTopic"):
+		s.topicsOpened++
+		tid := s.nextThread
+		s.nextThread++
+		fmt.Fprintf(w, `{"ok":true,"result":{"message_thread_id":%d,"name":%q}}`, tid, r.FormValue("name"))
+	case strings.HasSuffix(path, "/sendMessage"):
+		s.headerThread = r.FormValue("message_thread_id")
+		mid := s.nextMsg
+		s.nextMsg++
+		fmt.Fprintf(w, `{"ok":true,"result":{"message_id":%d}}`, mid)
+	case strings.HasSuffix(path, "/copyMessage"):
+		s.copies = append(s.copies, copyRec{
+			chatID:     r.FormValue("chat_id"),
+			fromChatID: r.FormValue("from_chat_id"),
+			threadID:   r.FormValue("message_thread_id"),
+			messageID:  r.FormValue("message_id"),
+		})
+		mid := s.nextMsg
+		s.nextMsg++
+		fmt.Fprintf(w, `{"ok":true,"result":{"message_id":%d}}`, mid)
+	case strings.HasSuffix(path, "/deleteMessages"):
+		var ids []int
+		_ = json.Unmarshal([]byte(r.FormValue("message_ids")), &ids)
+		s.deleted = append(s.deleted, ids)
+		io.WriteString(w, `{"ok":true,"result":true}`)
+	case strings.HasSuffix(path, "/editMessageReplyMarkup"):
+		s.editedMsgIDs = append(s.editedMsgIDs, r.FormValue("message_id"))
+		io.WriteString(w, `{"ok":true,"result":{"message_id":1}}`)
+	case strings.HasSuffix(path, "/answerCallbackQuery"):
+		s.answers = append(s.answers, r.FormValue("text"))
+		io.WriteString(w, `{"ok":true,"result":true}`)
+	case strings.HasSuffix(path, "/getChatAdministrators"):
+		var b strings.Builder
+		b.WriteString(`{"ok":true,"result":[`)
+		for i, id := range s.adminIDs {
+			if i > 0 {
+				b.WriteString(",")
+			}
+			fmt.Fprintf(&b, `{"status":"administrator","user":{"id":%d,"is_bot":false}}`, id)
+		}
+		b.WriteString(`]}`)
+		io.WriteString(w, b.String())
+	default:
+		io.WriteString(w, `{"ok":true,"result":true}`)
+	}
+}
+
+func (s *supportAPI) copyCount() int {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return len(s.copies)
+}
+
+// newSupportBot builds a support-enabled bot against the fake API and returns it with
+// its backing store.
+func newSupportBot(t *testing.T, api http.Handler) (*Bot, *support.Store) {
+	t.Helper()
+	srv := httptest.NewServer(api)
+	t.Cleanup(srv.Close)
+	st := support.New(filepath.Join(t.TempDir(), "support.json"))
+	b, err := New(Config{
+		Token:         "123:ABC",
+		APIBaseURL:    srv.URL,
+		MiniAppURL:    "https://example.com/telegram/",
+		SupportChatID: supportChatID,
+		SupportStore:  st,
+	}, zap.NewNop())
+	if err != nil {
+		t.Fatalf("new support bot: %v", err)
+	}
+	return b, st
+}
+
+// userMsg builds a private direct message from the given user.
+func userMsg(userID int64, text string) *models.Message {
+	return &models.Message{
+		ID:   int(userID)*10 + 1,
+		Chat: models.Chat{ID: userID, Type: models.ChatTypePrivate},
+		From: &models.User{ID: userID, FirstName: "Ann", Username: "annlee", LanguageCode: "ru"},
+		Text: text,
+	}
+}
+
+func TestSupportFirstContactOpensTopicAndRelays(t *testing.T) {
+	api := newSupportAPI()
+	b, st := newSupportBot(t, api)
+
+	b.handleSupportUserMessage(context.Background(), userMsg(7, "hello"))
+
+	if api.topicsOpened != 1 {
+		t.Fatalf("topics opened = %d, want 1", api.topicsOpened)
+	}
+	rec, ok := st.Get(7)
+	if !ok || rec.TopicID != 1000 || rec.HeaderMsgID != 5000 {
+		t.Fatalf("store = %+v ok=%v, want topic 1000 / header 5000", rec, ok)
+	}
+	if api.headerThread != "1000" {
+		t.Errorf("header posted to thread %q, want 1000", api.headerThread)
+	}
+	if len(api.copies) != 1 {
+		t.Fatalf("copies = %d, want 1", len(api.copies))
+	}
+	c := api.copies[0]
+	if c.threadID != "1000" || c.fromChatID != "7" || c.chatID != fmt.Sprint(supportChatID) {
+		t.Errorf("copy = %+v, want thread 1000 from 7 into the support chat", c)
+	}
+	if len(rec.RelayedMsgIDs) != 1 {
+		t.Errorf("relayed ids = %v, want 1 tracked", rec.RelayedMsgIDs)
+	}
+}
+
+func TestSupportSubsequentReusesTopic(t *testing.T) {
+	api := newSupportAPI()
+	b, st := newSupportBot(t, api)
+
+	b.handleSupportUserMessage(context.Background(), userMsg(7, "first"))
+	b.handleSupportUserMessage(context.Background(), userMsg(7, "second"))
+
+	if api.topicsOpened != 1 {
+		t.Errorf("topics opened = %d, want 1 (topic reused)", api.topicsOpened)
+	}
+	if len(api.copies) != 2 {
+		t.Errorf("copies = %d, want 2", len(api.copies))
+	}
+	rec, _ := st.Get(7)
+	if len(rec.RelayedMsgIDs) != 2 {
+		t.Errorf("relayed ids = %v, want 2", rec.RelayedMsgIDs)
+	}
+}
+
+func TestSupportBlockedUserDropped(t *testing.T) {
+	api := newSupportAPI()
+	b, st := newSupportBot(t, api)
+	if err := st.SetTopic(7, 1000, 5000, "Ann", "", "annlee"); err != nil {
+		t.Fatalf("seed topic: %v", err)
+	}
+	if err := st.SetBlocked(7, true); err != nil {
+		t.Fatalf("block: %v", err)
+	}
+
+	b.handleSupportUserMessage(context.Background(), userMsg(7, "hello?"))
+
+	if api.copyCount() != 0 {
+		t.Errorf("a blocked user's message was relayed (%d copies)", api.copyCount())
+	}
+	if api.topicsOpened != 0 {
+		t.Errorf("a blocked user opened a topic (%d)", api.topicsOpened)
+	}
+}
+
+// supportGroupMsg builds an operator message inside a topic of the support chat.
+func supportGroupMsg(fromID int64, threadID int, isBot bool) *models.Message {
+	return &models.Message{
+		ID:              700 + threadID,
+		Chat:            models.Chat{ID: supportChatID, Type: models.ChatTypeSupergroup},
+		From:            &models.User{ID: fromID, IsBot: isBot},
+		MessageThreadID: threadID,
+		Text:            "operator reply",
+	}
+}
+
+func TestSupportOperatorReplyRelayed(t *testing.T) {
+	api := newSupportAPI(50) // user 50 is an admin
+	b, st := newSupportBot(t, api)
+	if err := st.SetTopic(7, 1000, 5000, "Ann", "", "annlee"); err != nil {
+		t.Fatalf("seed topic: %v", err)
+	}
+
+	b.handleSupportGroupMessage(context.Background(), supportGroupMsg(50, 1000, false))
+
+	if len(api.copies) != 1 {
+		t.Fatalf("copies = %d, want 1 (reply relayed to user)", len(api.copies))
+	}
+	if api.copies[0].chatID != "7" || api.copies[0].fromChatID != fmt.Sprint(supportChatID) {
+		t.Errorf("copy = %+v, want from the support chat to user 7", api.copies[0])
+	}
+	rec, _ := st.Get(7)
+	if len(rec.RelayedMsgIDs) != 1 {
+		t.Errorf("operator message not tracked for clear: %v", rec.RelayedMsgIDs)
+	}
+}
+
+func TestSupportGroupMessageIgnored(t *testing.T) {
+	cases := []struct {
+		name   string
+		msg    *models.Message
+		admins []int64
+	}{
+		{"bot's own copy (loop guard)", supportGroupMsg(1, 1000, true), []int64{50}},
+		{"non-admin sender", supportGroupMsg(999, 1000, false), []int64{50}},
+		{"outside any topic", supportGroupMsg(50, 0, false), []int64{50}},
+		{"unknown topic", supportGroupMsg(50, 4242, false), []int64{50}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			api := newSupportAPI(tc.admins...)
+			b, st := newSupportBot(t, api)
+			if err := st.SetTopic(7, 1000, 5000, "Ann", "", "annlee"); err != nil {
+				t.Fatalf("seed topic: %v", err)
+			}
+			b.handleSupportGroupMessage(context.Background(), tc.msg)
+			if api.copyCount() != 0 {
+				t.Errorf("message relayed (%d copies); it should be ignored", api.copyCount())
+			}
+		})
+	}
+}
+
+// supportCallback builds a callback-query update for the given data and presser.
+func supportCallback(data string, fromID int64) *models.Update {
+	return &models.Update{CallbackQuery: &models.CallbackQuery{
+		ID:   "cb1",
+		From: models.User{ID: fromID},
+		Data: data,
+	}}
+}
+
+func TestSupportCallbackBlockToggle(t *testing.T) {
+	api := newSupportAPI(50)
+	b, st := newSupportBot(t, api)
+	if err := st.SetTopic(7, 1000, 5000, "Ann", "", "annlee"); err != nil {
+		t.Fatalf("seed topic: %v", err)
+	}
+
+	b.handleSupportCallback(context.Background(), b.api, supportCallback("sup:block:7", 50))
+	if !st.Blocked(7) {
+		t.Error("user not blocked after sup:block")
+	}
+	if len(api.editedMsgIDs) != 1 || api.editedMsgIDs[0] != "5000" {
+		t.Errorf("edited markup msg ids = %v, want [5000]", api.editedMsgIDs)
+	}
+
+	b.handleSupportCallback(context.Background(), b.api, supportCallback("sup:unblock:7", 50))
+	if st.Blocked(7) {
+		t.Error("user still blocked after sup:unblock")
+	}
+	if len(api.answers) != 2 || api.answers[0] != "Заблокирован" || api.answers[1] != "Разблокирован" {
+		t.Errorf("answers = %v, want [Заблокирован Разблокирован]", api.answers)
+	}
+}
+
+func TestSupportCallbackNonAdminDenied(t *testing.T) {
+	api := newSupportAPI(50)
+	b, st := newSupportBot(t, api)
+	if err := st.SetTopic(7, 1000, 5000, "Ann", "", "annlee"); err != nil {
+		t.Fatalf("seed topic: %v", err)
+	}
+
+	b.handleSupportCallback(context.Background(), b.api, supportCallback("sup:block:7", 999))
+
+	if st.Blocked(7) {
+		t.Error("a non-admin managed to block the user")
+	}
+	if len(api.answers) != 1 || api.answers[0] != "Недостаточно прав" {
+		t.Errorf("answers = %v, want a permission denial", api.answers)
+	}
+}
+
+func TestSupportCallbackClearDeletesTracked(t *testing.T) {
+	api := newSupportAPI(50)
+	b, st := newSupportBot(t, api)
+	if err := st.SetTopic(7, 1000, 5000, "Ann", "", "annlee"); err != nil {
+		t.Fatalf("seed topic: %v", err)
+	}
+	for _, id := range []int{501, 502, 503} {
+		if err := st.AppendMsg(7, id); err != nil {
+			t.Fatalf("append: %v", err)
+		}
+	}
+
+	b.handleSupportCallback(context.Background(), b.api, supportCallback("sup:clear:7", 50))
+
+	if len(api.deleted) != 1 || len(api.deleted[0]) != 3 {
+		t.Fatalf("deleted batches = %v, want one batch of 3", api.deleted)
+	}
+	rec, _ := st.Get(7)
+	if len(rec.RelayedMsgIDs) != 0 {
+		t.Errorf("relayed ids after clear = %v, want empty", rec.RelayedMsgIDs)
+	}
+	if rec.HeaderMsgID != 5000 {
+		t.Errorf("clear disturbed the header (%d)", rec.HeaderMsgID)
+	}
+}
+
+func TestParseSupportCallback(t *testing.T) {
+	cases := []struct {
+		data       string
+		wantAction string
+		wantUID    int64
+		wantOK     bool
+	}{
+		{"sup:block:7", "block", 7, true},
+		{"sup:clear:-100", "clear", -100, true},
+		{"sup:unblock:42", "unblock", 42, true},
+		{"block:7", "", 0, false},
+		{"sup:block", "", 0, false},
+		{"sup:block:notanumber", "", 0, false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.data, func(t *testing.T) {
+			action, uid, ok := parseSupportCallback(tc.data)
+			if action != tc.wantAction || uid != tc.wantUID || ok != tc.wantOK {
+				t.Errorf("parseSupportCallback(%q) = %q,%d,%v; want %q,%d,%v",
+					tc.data, action, uid, ok, tc.wantAction, tc.wantUID, tc.wantOK)
+			}
+		})
+	}
+}
+
+func TestSupportCardTextEscapes(t *testing.T) {
+	u := &models.User{ID: 7, FirstName: "<b>Ann</b>", Username: "ann", LanguageCode: "ru", IsPremium: true}
+	card := supportCardText(u)
+	if strings.Contains(card, "<b>Ann</b>") {
+		t.Error("user-supplied first name was not HTML-escaped in the card")
+	}
+	if !strings.Contains(card, "&lt;b&gt;Ann&lt;/b&gt;") {
+		t.Errorf("card = %q, want the escaped name", card)
+	}
+	if !strings.Contains(card, "tg://user?id=7") {
+		t.Error("card missing the profile deep link")
+	}
+	if !strings.Contains(card, "Premium: да") {
+		t.Error("card missing the premium flag")
+	}
+}
+
+func TestSupportTopicName(t *testing.T) {
+	if got := supportTopicName(&models.User{ID: 7, FirstName: "Ann", LastName: "Lee", Username: "annlee"}); got != "Ann Lee @annlee" {
+		t.Errorf("topic name = %q, want %q", got, "Ann Lee @annlee")
+	}
+	if got := supportTopicName(&models.User{ID: 7}); got != "user 7" {
+		t.Errorf("nameless topic = %q, want %q", got, "user 7")
+	}
+	long := strings.Repeat("x", 200)
+	if got := supportTopicName(&models.User{ID: 7, FirstName: long}); len([]rune(got)) != supportTopicNameMax {
+		t.Errorf("topic name length = %d, want %d (trimmed)", len([]rune(got)), supportTopicNameMax)
+	}
+}
+
+func TestSupportDisabledFallsThrough(t *testing.T) {
+	// With no SupportChatID the relay is off and supportEnabled is false.
+	srv := httptest.NewServer(&supportAPI{nextThread: 1000, nextMsg: 5000})
+	t.Cleanup(srv.Close)
+	b, err := New(Config{Token: "123:ABC", APIBaseURL: srv.URL, MiniAppURL: "https://example.com/"}, zap.NewNop())
+	if err != nil {
+		t.Fatalf("new bot: %v", err)
+	}
+	if b.supportEnabled() {
+		t.Error("supportEnabled() = true without a SupportChatID")
+	}
+}