Skip to main content

Profile

1. Summary​

Goal: Центральная точка данных пользователя — балансы, статистика, прогресс. Единый источник правды для состояния аккаунта во всех частях приложения.

User Value: Личный кабинет с полной информацией об активности, балансах, достижениях и готовности к выводу скинов.

2. Business Logic​

Types of Data​

Scrap — основная внутриигровая валюта

  • Источники: кейсы, спины, квесты, ачивменты, рефералы
  • Трата: платные кейсы, платные спины
  • Баланс scrap на User (O(1) чтение), breakdown по источникам — только в UserSeasonStats

XP (Experience) — метрика прогресса в сезоне

  • Только растёт (никогда не тратится)
  • Сбрасывается при завершении сезона
  • Влияет на позицию в рейтинге

Streak Points (SP) — валюта лояльности

  • Источники: ежедневные входы, квесты, достижения, топ-бонусы
  • Трата: билеты в розыгрышах, Streak кейсы

Profile Data Assembly​

При запросе профиля (GET /api/users/profile) происходит сборка данных:

1. Fetch User Data

  • Загрузка полей из User модели (балансы, стрики, статусы)
  • Агрегатные балансы (scrap, xp, level, streakPoints) — O(1) чтение

2. Check and Update Streak

  • StreakService.checkAndUpdateStreak() вызывается при каждом запросе
  • Автоматическое обновление dailyLoginStreak если прошёл день

3. Ensure Season Participation

  • Upsert записи UserSeasonStats для активного сезона
  • Создаёт участие автоматически при первом входе в сезон

4. Calculate Derived Fields

  • avatar — URL из static сервера
  • activeBuffs — список активных баффов через BuffService
  • streakInfo — информация о использовании щитов (если применимо)
Side Effect on Read

Запрос профиля — не чистый read! Происходит обновление стрика и создание записи сезона. Это сделано для UX: пользователь не должен явно "начинать день".

Avatar Caching System​

Аватарки пользователей кэшируются на static сервере вместо прямого использования Telegram URL.

Проблемы которые решает:

ПроблемаОписание
Временные URLTelegram Bot API возвращает URL действительные ~1 час
Утечка токенаПрямой URL содержит токен бота — нельзя отдавать на frontend
ПроизводительностьЗапрос к Telegram API на каждый показ аватара — медленно

Как работает:

Хранение:

  • Путь на диске: /static/images/avatars/{telegramId}.jpg
  • В БД (User.avatarUrl): relative path /images/avatars/{telegramId}.jpg?v={mtime}
  • URL для клиента: {STATIC_URL}/images/avatars/{telegramId}.jpg (prepend через normalizeImageUrl() при чтении)
  • TTL кэша: 24 часа (после этого перезагружается с Telegram)
Почему 24 часа?
TTLПлюсыМинусы
1 часБыстрое обновлениеМного запросов к Telegram API
24 часа ✓Баланс свежести и нагрузкиАватар обновится максимум через сутки
7 днейМинимум запросовСлишком устаревшие аватары

Люди редко меняют аватарки. Сутки — разумный компромисс.

Где используется:

  • profile.photoUrl — аватар текущего пользователя
  • leaderboard[].avatarUrl — аватары топ-10 в рейтинге
  • Feed events — аватары в ленте активности

Файлы:

  • Service: backend/src/domains/users/services/avatar-cache.service.ts
  • URL Builder: backend/src/common/constants/url.constants.ts → buildAvatarUrl()

Level System​

Прогрессивная формула: каждый уровень требует больше XP, чем предыдущий.

Детали расчёта уровня

Уровень рассчитывается на основе накопленного XP с прогрессивно растущими требованиями.

УровеньТребуется XP
10
2100
3250
......

Уровень влияет на:

  • Визуальное отображение в профиле
  • Возможные будущие разблокировки

Steam Verification Flow​

Установка Trade URL:

  1. Пользователь вводит Steam Trade URL
  2. Backend валидирует формат URL
  3. Извлекается SteamID из URL
  4. Вызывается SteamVerificationService для проверки:
    • Существование аккаунта
    • Возраст аккаунта (steamAccountCreatedAt)
    • Стоимость библиотеки (steamLibraryValueUsd)
    • Количество игр (steamGamesCount)
  5. Результат: автоматическая верификация или необходимость ручной
Валюта верификации

Несмотря на название поля steamLibraryValueUsd, фактическая проверка стоимости библиотеки выполняется в рублях (регион cc=ru). Порог верификации: MIN_LIBRARY_VALUE_RUB: 1000 (1000 руб.). Константа определена в steam-verification.types.ts.

Ручная верификация:

  • Админ просматривает заявку через тикет
  • Одобряет или отклоняет с комментарием
  • steamManuallyVerified = true при одобрении

Withdraw Readiness Checks​

6-точечная проверка готовности к выводу:

#ПроверкаОписание
1hasTradeUrlTrade URL установлен
2isSteamVerifiedSteam аккаунт верифицирован (авто или ручной)
3isInventoryPublicИнвентарь Steam публичный
4noActiveWithdrawalНет активного вывода в процессе
5userHasItemПредмет существует в инвентаре пользователя
6itemAvailableOnBotПредмет доступен на боте (tradable + marketable)

Protection​

ДействиеRate LimitAuthValidation
Get profilegeneral (100/min)TelegramUserProfileGetSchema
Get statsgeneral (100/min)TelegramUserStatsSchema
Update profilegeneral (100/min)— (нет telegramAuth)UserProfileUpdateSchema
Set trade URLgeneral (100/min)TelegramUpdateSteamTradeUrlSchema
Delete trade URLgeneral (100/min)TelegramDeleteSteamTradeUrlSchema
Get verificationgeneral (100/min)TelegramGetVerificationStatusSchema
Get withdraw readinessgeneral (100/min)TelegramGetWithdrawReadinessSchema
Get Rust statusgeneral (100/min)TelegramGetRustOnlineStatusSchema
Детали реализации

См. Security Matrix для полного обзора защит.

Edge Cases​

СитуацияПоведениеUI
Активный выводБлок изменения Trade URLСообщение "Дождитесь завершения вывода"
Удаление Trade URL с активной Rust сессиейСессии закрываются, кэш инвалидируется, прогресс квестов сохранёнЧерез ≤60 сек plugin увидит пустые квесты
Steam не верифицированWithdraw Readiness = falseКнопка вывода неактивна
Streak shield использованstreakInfo в ответеПоказ информации о защите
Первый вход в сезонAuto-create UserSeasonStatsПрозрачно для пользователя
Клик на badge звания в headerОткрывает TitlesModalКликабельный badge под username: иконка Award + текст звания + chevron
Клик на "Промокод" в List CardCollapsible секция раскрывается inlineChevron → collapse arrow, под item появляется PromoCodeInput с анимацией max-height
Нет активного званияFallback текстBadge показывает "Путник"
Сезонный ранг отсутствуетНет XP в сезонеТекст "Рейтинг появится после получения XP" вместо ранга

3. ADR (Architectural Decisions)​

Почему денормализованные поля на User?​

Проблема: Подсчёт статистики из истории (QuizResult, CaseOpening, etc.) слишком медленный для каждого запроса профиля.

Решение: Денормализованные агрегатные поля на User модели:

  • Балансы: scrap, xp, level, streakPoints
  • Счётчики: quizzesCompleted, correctAnswers, casesOpened, friendsInvited
Source-breakdown поля удалены

Ранее User содержал 17 полей-breakdown (scrapFromQuizzes, xpFromQuests, scrapSpent и др.), дублирующих данные из UserSeasonStats. Все reads для all-time статистики уже использовали SUM(USS), а поля на User создавали риск рассинхрона и лишние writes. Удалены в рамках рефакторинга (commit e48332834). Breakdown по источникам теперь хранится только в UserSeasonStats.

Альтернативы (отклонены):

  • Real-time агрегация — O(n) на каждый запрос, неприемлемо
  • Redis cache — сложность инвалидации, eventual consistency
  • Materialized views — дополнительная нагрузка на PostgreSQL

Последствия:

  • Быстрые чтения (O(1) для балансов)
  • Breakdown по источникам — через SUM(UserSeasonStats)
  • Каждая операция должна атомарно обновлять USS

Почему UserSeasonStats отдельно от User?​

Проблема: Нужна статистика, которая сбрасывается между сезонами, но all-time данные должны сохраняться.

Решение: Отдельная таблица UserSeasonStats с compound unique (userId, seasonId).

Последствия:

  • All-time статистика = SUM/MAX через все записи UserSeasonStats
  • Сезонный сброс = создание новой записи без удаления старых

Dual-Write Pattern: User + UserSeasonStats​

Критичное архитектурное решение

При изменении баланса или счётчика на User ОБЯЗАТЕЛЬНО обновлять соответствующее поле в UserSeasonStats.

Проблема: Нужны быстрые O(1) чтения балансов (scrap, streakPoints) и счётчиков, но также нужна сезонная агрегация для All-Time статистики.

Решение: Dual-write в обе таблицы:

User = Materialized View (агрегатные балансы, O(1) чтение)
UserSeasonStats = Source of Truth (breakdown по источникам + сезонная агрегация)

Почему не только UserSeasonStats?

ОперацияТолько UserSeasonStatsDual-write (текущий)
Проверка балансаaggregate() ~10-50msuser.scrap ~1-5ms
Отображение профиляaggregate на каждый запроспрямое чтение
Покупка кейсаaggregate → check → updateread → check → update

Альтернативы (отклонены):

  • Только UserSeasonStats — медленные агрегации на каждый запрос баланса
  • Redis cache — сложность инвалидации, eventual consistency
  • Computed columns — PostgreSQL не поддерживает cross-table computed

Синхронизируемые поля:

User полеUserSeasonStats полеУтилита
scrapscrap, scrapFrom{Quizzes,Tasks,...}updateSeasonScrap()
xpxp, xpFrom{Tasks,Achievements,...}updateSeasonXP()
friendsInvitedfriendsInvitedupdateSeasonStats()
achievementsUnlockedachievementsUnlockedupdateSeasonStats()
casesOpenedcasesOpenedupdateSeasonStats()
dailyCasesOpeneddailyCasesOpenedupdateSeasonStats()
dailySpinsUseddailySpinsUsedupdateSeasonStats()
itemsCrafteditemsCraftedupdateSeasonStats()
itemsSalvageditemsSalvagedupdateSeasonStats()
streakPointsTotalstreakPointsEarnedupdateSeasonStats()
streakPointsSpentstreakPointsSpentupdateSeasonStats()
bestDailyLoginStreakbestDailyLoginStreakdirect upsert (MAX)
Breakdown только в USS

Source-breakdown поля (scrapFrom{Source}, xpFrom{Source}, scrapSpent{Source}) хранятся только в UserSeasonStats. User содержит только агрегатные балансы (scrap, xp). All-Time статистика читается через SUM(USS).

Правило для разработчиков:

// НЕПРАВИЛЬНО — обновляем только User
await tx.user.update({
  where: { id: userId },
  data: { friendsInvited: { increment: 1 } }
});

// ПРАВИЛЬНО — обновляем User + UserSeasonStats
await tx.user.update({
  where: { id: userId },
  data: { friendsInvited: { increment: 1 } }
});
await updateSeasonStats(tx, userId, {
  incrementFields: { friendsInvited: 1 }
});

Последствия:

  • Быстрые O(1) чтения балансов и счётчиков
  • All-Time = SUM(UserSeasonStats) работает корректно
  • Breakdown по источникам — единственный source of truth в USS
  • Требуется дисциплина: не забывать синхронизировать
Утилита updateSeasonStats

Путь: backend/src/domains/seasons/utils/season-stats-updater.ts

await updateSeasonStats(tx, userId, {
  incrementFields: {
    friendsInvited: 1,
    casesOpened: 1
  }
});

Автоматически:

  • Находит активный сезон
  • Upsert в UserSeasonStats
  • Инкрементирует указанные поля

Почему консолидация карточек профиля (8→5)?​

Проблема: ProfileScreen содержал 8 одинаковых glass-card карточек без визуальной иерархии — всё выглядело одинаково важным. Три идентичных list-item карточки внизу (Звание, Достижения, История) были overkill, промокод занимал целую карточку ради редко используемой функции, сезонный ранг дублировался (badge на аватаре + отдельная карточка).

Решение: Сокращение до 5 карточек с чёткой иерархией:

  1. Header Card — аватар, имя, звание (inline badge), XP, streak/invite, boost pass, buffs
  2. Steam Trade URL — без изменений
  3. Quick Actions — 4 кнопки (без изменений)
  4. Season Card — компактный (ранг + подсказка в одну строку)
  5. List Card — Достижения / История / Промокод (collapsible inline)

Альтернативы (отклонены):

  • Оставить 8 карточек с визуальной дифференциацией — не решает проблему скролла
  • Tabs / accordion для всего — усложняет навигацию

Последствия:

  • Меньше скролла, чёткая иерархия информации
  • Звание стало частью идентичности пользователя (inline в header)
  • Промокод не занимает отдельную карточку — раскрывается inline при необходимости

Почему Streak Update на Read?​

Проблема: Пользователь не должен явно "чекиниться" каждый день.

Решение: checkAndUpdateStreak() вызывается при GET /profile.

Альтернативы (отклонены):

  • Отдельный endpoint /checkin — лишний шаг для пользователя
  • Cron job — сложность с timezone, нагрузка пиком в полночь

Последствия:

  • Read endpoint имеет side effects (не REST pure)
  • Гарантированное обновление при первом входе за день
  • Streak Shield автоматически применяется при пропуске

4. Architecture​

Profile Data Flow​

Key Components​

КомпонентПутьОписание
ProfileControllerbackend/src/domains/users/controllers/user-profile.controller.tsHTTP handlers для профиля
StatisticsServicebackend/src/domains/users/services/statistics.service.tsАгрегация статистики
StreakServicebackend/src/domains/streaks/services/streak.service.tsУправление стриками
BuffServicebackend/src/domains/buffs/services/buff.service.tsАктивные баффы
SteamVerificationServicebackend/src/domains/steam-verification/services/steam-verification.service.tsВерификация Steam
WithdrawReadinessServicebackend/src/domains/steam-trade-bot/services/withdraw-readiness.service.tsПроверка готовности к выводу
Routesbackend/src/domains/users/routes/user-profile.routes.tsAPI endpoints
Schemas (profile)backend/src/domains/users/schemas/user-profile.schemas.tsRequest/Response validation для профиля
Schemas (integrations)backend/src/domains/users/schemas/user-integrations.schemas.tsSteam, verification, readiness, statistics schemas
ProfileScreenfrontend/src/components/screens/ProfileScreen.tsxUI экрана профиля

ProfileScreen Layout​

5 карточек сверху вниз:

#КарточкаСодержимое
1Header CardАватар, имя, @username, inline badge звания (кликабельный → TitlesModal), XP прогресс, streak/invite, boost pass, buffs
2Steam Trade URLВвод/отображение Trade URL
3Quick ActionsСетка 2×2 кнопок быстрых действий
4Season CardCompact: название сезона + день, ранг + подсказка в одну строку
5List CardДостижения (Trophy) / История (Clock) / Промокод (Gift, collapsible inline) — разделены border-t

5. Database Schema​

Models​

МодельОписаниеКлючевые поля
UserОсновная модельtelegramId, scrap, xp, level, балансы, стрики
UserSeasonStatsСтатистика по сезонамuserId, seasonId, XP/Scrap breakdown

User Key Fields (subset)​

КатегорияПоля
Identityid, telegramId, username, firstName
Balancesscrap, xp, level, streakPoints
CountersquizzesCompleted, correctAnswers, casesOpened, friendsInvited
StreaksdailyLoginStreak, bestDailyLoginStreak
SteamsteamTradeUrl, steamId, steamVerified, steamManuallyVerified
StatusisActive, isBanned, isPremium
Breakdown по источникам

Поля scrapFrom{Source}, xpFrom{Source}, scrapSpent{Source} хранятся только в UserSeasonStats. All-time статистика читается через SUM(USS) в GET /api/users/statistics/all-time.

Полная схема

См. SCHEMA_GUIDE для полного списка полей User (строки 14-193).

Relationships​

6. API Endpoints​

User API​

МетодЭндпоинтОписаниеDocs
GET/api/users/profileПолный профиль с балансами→
GET/api/users/statsБазовая информация профиля (имя, дата регистрации, биндов, избранного)→
GET/api/users/statistics/categoriesСтатистика квизов по категориям→
GET/api/users/statistics/all-timeAll-time статистика→
GET/api/users/statistics/streak-pointsStreak Points breakdown→
PUT/api/users/profileОбновление профиля пользователя→
PUT/api/users/steam/trade-urlУстановка Steam Trade URL→
DELETE/api/users/steam/trade-urlУдаление Steam Trade URL→
GET/api/users/verification-statusСтатус Steam верификации→
GET/api/users/withdraw-readinessГотовность к выводу→
GET/api/users/rust-online-statusОнлайн статус в Rust→
Response Examples

GET /api/users/profile

{
  "success": true,
  "data": {
    "id": "user-id",
    "telegramId": 123456789,
    "firstName": "Alex",
    "scrap": 1500,
    "xp": 2300,
    "level": 5,
    "streakPoints": 450,
    "dailyLoginStreak": 7,
    "avatar": "https://static.example.com/images/avatars/123456789.jpg",
    "activeBuffs": [
      { "type": "XP_BUFF", "multiplier": 1.5, "expiresAt": "..." }
    ],
    "streakInfo": null
  }
}

GET /api/users/statistics/categories

{
  "success": true,
  "data": [
    { "category": "weapons", "displayName": "Оружие", "total": 50, "correct": 42, "accuracy": 84.0 },
    { "category": "maps", "displayName": "Карты", "total": 30, "correct": 21, "accuracy": 70.0 }
  ]
}

7. Account Reset (Internal)​

Только для владельца/админов

Эта секция описывает внутренние механизмы сброса аккаунта.

Partial Reset (UserDataResetService)​

Частичный сброс данных пользователя с фокусом на referral систему:

  1. Деактивация исходящих referral sessions → state=USER_RESET
  2. Деактивация входящих referral sessions → state=USER_RESET
  3. Пересчёт лимитов для затронутых рефереров
  4. Установка isBanned=true

Сохраняется: Балансы, инвентарь, история (для аналитики).

Full Reset (UserFullResetService)​

Полная очистка по команде /stop в Telegram боте:

ШагОперация
1Отмена активных выводов (PENDING, PROCESSING, SENT) → status=FAILED
2Удаление инвентаря
3Удаление истории кейсов + статистики кейсов (userCaseStats)
4Удаление результатов квизов
5Удаление результатов спинов
6Удаление истории крафтов
7Удаление достижений
8Удаление сезонной статистики
9Удаление feed events
10Удаление bot interactions
11Маркировка referral sessions как USER_RESET (исходящие + входящие)
12Обнуление полей на User (см. детали ниже)
Детали шага 12: какие поля обнуляются

Обнуляется подмножество полей User, а не все поля:

ГруппаПоля
Балансыscrap, xp, level (→ 1)
Quiz StatsquizzesCompleted, correctAnswers, incorrectAnswers
StreaksdailyLoginStreak, bestDailyLoginStreak
Daily RewardslastDailyCase (→ null), lastDailySpin (→ null)
StatusbotStatus → BLOCKED

НЕ обнуляются (остаются как есть): questsCompleted, achievementsUnlocked, friendsInvited, casesOpened, dailyCasesOpened, dailySpinsUsed, itemsSalvaged, itemsCrafted, streakPoints, streakPointsTotal, streakPointsSpent, passiveIncomeBalance

Сохраняется:

  • referral_codes — пользователь может снова пригласить друзей после /start
  • user_feedback — ценно для бизнеса
  • Analytics данные (banner/push interactions)

Технические детали:

  • Выполняется в транзакции с 30s timeout
  • botStatus=BLOCKED после сброса
  • Extensive logging для audit trail
  • Profile State Management — фронтенд архитектура: React Query как sole source of truth
  • Settings — настройки пользователя
  • Onboarding — регистрация и активация
  • Streaks — система лояльности
  • Buffs — временные бонусы
  • Seasons — сезонный рейтинг
  • Feedback — система обратной связи
  • Steam Trade — вывод скинов
  • Security Matrix — обзор защит