> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedolagam.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# Регистрация пользователя

> Путь клиента от /start до главного меню

## Общая схема

При первом запуске `/start` пользователь проходит цепочку шагов. Каждый шаг можно пропустить или настроить.

```
/start → Проверка подписки на канал → Выбор языка → Правила → Политика конф. → Реферальный код → Главное меню
```

Если у пользователя есть deeplink (реферальный код, кампания, промокод) — он передаётся через параметр `/start <код>` и обрабатывается автоматически.

***

## Шаг 1. Проверка подписки на каналы

Если включена обязательная подписка (`CHANNEL_IS_REQUIRED_SUB=true`) — бот не пустит дальше, пока пользователь не подпишется на все обязательные каналы.

Пользователь видит кнопки каналов (синие для неподписанных, зелёные для подписанных) и кнопку «Я подписался». После подписки deeplink-параметр восстанавливается из Redis и регистрация продолжается.

<Note>
  Если `CHANNEL_IS_REQUIRED_SUB=false` — шаг пропускается полностью.
</Note>

<Card title="Подробнее: обязательная подписка на каналы" icon="megaphone" href="/bot/channel-subscription">
  Мультиканальная подписка, цветные кнопки, автодеактивация, управление через бот и Cabinet.
</Card>

***

## Шаг 2. Выбор языка

Если включён выбор языка — пользователь видит кнопки с доступными языками.

```env theme={null}
# Включить выбор языка при старте
LANGUAGE_SELECTION_ENABLED=true

# Язык по умолчанию (если выбор отключён)
DEFAULT_LANGUAGE=ru

# Доступные языки
AVAILABLE_LANGUAGES=ru,en,ua,zh,fa
```

**Что видит пользователь:** `🌐 Выберите язык / Choose your language:` с inline-кнопками.

Если `LANGUAGE_SELECTION_ENABLED=false` — автоматически назначается `DEFAULT_LANGUAGE` и шаг пропускается.

***

## Шаг 3. Принятие правил

Пользователь видит текст правил с кнопками «Принять» / «Отклонить».

```env theme={null}
# Пропустить принятие правил
SKIP_RULES_ACCEPT=false
```

**Если отклонил** — бот отвечает: «Для использования бота необходимо принять правила сервиса» и показывает правила снова. Без принятия регистрация невозможна.

**Если `SKIP_RULES_ACCEPT=true`** — шаг пропускается полностью.

<Note>
  Текст правил настраивается в админ-панели или через файлы локализации. Для каждого языка свой текст.
</Note>

***

## Шаг 4. Политика конфиденциальности

После принятия правил бот показывает политику конфиденциальности (если она включена в админ-панели).

**Что видит пользователь:** текст политики с кнопками «Принять» / «Отклонить».

Шаг появляется только если:

* Политика включена в админ-панели (**Настройки → Контент → Политика конфиденциальности**)
* Текст политики заполнен (или есть дефолтный текст в локализации)

Если политика не настроена — шаг пропускается автоматически.

***

## Шаг 5. Реферальный код

Пользователь видит вопрос: «У вас есть реферальный код?» с полем ввода и кнопкой «Пропустить».

```env theme={null}
# Пропустить запрос реферального кода
SKIP_REFERRAL_CODE=false
```

**Что можно ввести:**

* **Реферальный код** — код другого пользователя. При вводе применяется реферальная связь.
* **Промокод** — если реферальный код не найден, бот проверяет промокоды. Если валидный — сохраняет и активирует после создания пользователя.
* **Невалидный код** — сообщение: «Неверный реферальный код или промокод». Можно попробовать снова или нажать `/start` для продолжения без кода.

**Шаг пропускается если:**

* `SKIP_REFERRAL_CODE=true`
* Пользователь пришёл по deeplink с реферальным кодом (`/start <ref_code>`)
* Пользователь пришёл по ссылке рекламной кампании (`/start <campaign_parameter>`)

<Warning>
  Есть защита от перебора: после нескольких неудачных попыток ввода кода пользователь блокируется на несколько секунд (rate limiting).
</Warning>

***

## Шаг 6. Завершение регистрации

После прохождения всех шагов:

1. Создаётся пользователь в БД (или восстанавливается удалённый)
2. Применяется реферальная связь (если был код)
3. Активируется промокод (если был введён)
4. Применяется бонус рекламной кампании (если пришёл по deeplink кампании)
5. Выдаётся триал (если настроен)
6. Показывается главное меню

***

## Deeplinks

Бот обрабатывает параметры `/start <payload>` в следующем порядке:

1. **Рекламная кампания** — если payload совпадает с `start_parameter` активной кампании → применяется бонус кампании
2. **Реферальный код** — если кампания не найдена → payload сохраняется как реферальный код

Формат ссылки: `https://t.me/your_bot?start=<payload>`

***

## Повторный `/start` (существующий пользователь)

Если пользователь уже зарегистрирован и нажимает `/start`:

* Обновляются username, имя, фамилия (если изменились)
* Показывается главное меню
* Реферальная ссылка **не применяется** (только для новых)
* Кампания **не применяется** (только для новых)

***

## Конфигурация: быстрый старт без лишних шагов

Для максимально быстрой регистрации (сразу в главное меню):

```env theme={null}
# Пропустить все промежуточные шаги
SKIP_RULES_ACCEPT=true
SKIP_REFERRAL_CODE=true
LANGUAGE_SELECTION_ENABLED=false
CHANNEL_IS_REQUIRED_SUB=false
```

<Warning>
  При `SKIP_RULES_ACCEPT=true` пользователь не принимает правила и политику конфиденциальности. Убедитесь, что это допустимо для вашего сценария.
</Warning>

***

## Устранение проблем

### Пользователь застрял на вводе реферального кода

Если пользователь ввёл невалидный код и не может продолжить — ему нужно отправить `/start` для перезапуска регистрации.

### Deeplink не применился

Если пользователь пришёл по реферальной ссылке, но подписка на канал обязательна — deeplink сохраняется в Redis (TTL 1 час) и применяется после подписки на канал. Если прошло больше часа — deeplink теряется.

### «Вы уже зарегистрированы, реферальная ссылка не может быть применена»

Реферальная связь устанавливается только при первой регистрации. Если пользователь уже зарегистрирован — реферальный код не применяется.

### Бот не отвечает на /start

1. Проверьте что бот запущен: `docker compose ps`
2. Проверьте логи: `docker compose logs -f bot`
3. Если включена обязательная подписка на каналы — убедитесь что бот является администратором каждого обязательного канала