sfera/registration-authorization-rules.md

ПРАВИЛА РЕГИСТРАЦИИ И АВТОРИЗАЦИИ

🏗️ АРХИТЕКТУРА СИСТЕМЫ

Основные сущности:

• ПОЛЬЗОВАТЕЛЬ - верхний уровень, может иметь много номеров телефонов
• НОМЕР ТЕЛЕФОНА - привязан к пользователю, может иметь много организаций
• ОРГАНИЗАЦИЯ/КАБИНЕТ - бизнес-сущность, привязана к номеру телефона
• ПАРТНЕРСТВО - связь между организациями (не пользователями или номерами)

Связи:

ПОЛЬЗОВАТЕЛЬ (1) ←→ (N) НОМЕРА ТЕЛЕФОНОВ (1) ←→ (N) ОРГАНИЗАЦИИ
ОРГАНИЗАЦИЯ (N) ←→ (N) ОРГАНИЗАЦИИ (партнерство)

Пример структуры:

ПОЛЬЗОВАТЕЛЬ "Иван Петров"
├── +7111111111 (номер 1)
│   ├── СБЕРБАНК (организация 1) 
│   └── АВИТО (организация 2)
└── +7222222222 (номер 2)
    └── ЯНДЕКС (организация 3)

📋 СПОСОБЫ СОЗДАНИЯ ОРГАНИЗАЦИЙ

1. СТАНДАРТНАЯ РЕГИСТРАЦИЯ

URL: /register (без параметров)

Флоу для НОВОГО номера телефона:

1. Ввод телефона → SMS код → авторизация
2. Выбор типа кабинета
3. Ввод данных организации (ИНН или API ключи)
4. Создание организации
5. Привязка организации к номеру телефона

Флоу для АВТОРИЗОВАННОГО номера:

1. Редирект в дашборд (стандартное поведение)

2. РЕГИСТРАЦИЯ ЧЕРЕЗ САЙДБАР (ПОТОМ)

Местоположение: Блок организации в сайдбаре

Флоу:

1. Модалка создания новой организации
2. Выбор типа кабинета
3. Ввод данных организации
4. Создание организации без партнерства

3. ПАРТНЕРСКАЯ ССЫЛКА

URL: /register?partner=CODE

Флоу для НОВОГО номера телефона:

1. Ввод телефона → SMS код → авторизация
2. Выбор типа кабинета
3. Ввод данных организации
4. Создание организации С ПАРТНЕРСТВОМ
5. Автоматическое создание партнерских связей между организациями
6. Начисление +100 сфер организации-рефереру

Флоу для АВТОРИЗОВАННОГО номера телефона:

1. Пропуск авторизации (уже авторизован на этом номере)
2. Переход сразу к выбору типа кабинета
3. Ввод данных новой организации
4. Создание организации С ПАРТНЕРСТВОМ
5. Автоматическое создание партнерских связей
6. Начисление +100 сфер организации-рефереру

4. РЕФЕРАЛЬНАЯ ССЫЛКА

URL: /register?ref=CODE

Флоу для НОВОГО номера телефона:

1. Ввод телефона → SMS код → авторизация
2. Выбор типа кабинета
3. Ввод данных организации
4. Создание организации С РЕФЕРАЛЬНОЙ СВЯЗЬЮ
5. Начисление +100 сфер организации-рефереру
6. БЕЗ автоматического партнерства

Флоу для АВТОРИЗОВАННОГО номера телефона:

1. Пропуск авторизации (уже авторизован на этом номере)
2. Переход сразу к выбору типа кабинета
3. Ввод данных новой организации
4. Создание организации С РЕФЕРАЛЬНОЙ СВЯЗЬЮ
5. Начисление +100 сфер организации-рефереру
6. БЕЗ автоматического партнерства

📊 ДАШБОРД РЕФЕРАЛОВ (РЕАЛИЗОВАНО)

Местоположение: /partners → вкладка "Рефералы"

Функции:

1. Мои ссылки:

   • Реферальная ссылка: register?ref=CODE
   • Партнерская ссылка: register?partner=CODE
   • Кнопка копирования

2. Статистика:

   • Всего партнеров и начисленных сфер
   • Статистика за текущий месяц

3. Список рефералов:

   • Привлеченные организации
   • Фильтрация и поиск
   • Источник регистрации

🔧 ТЕХНИЧЕСКИЕ ПРАВИЛА

Валидация URL параметров:

• Нельзя использовать partner и ref одновременно
• Коды должны быть длиной 10 символов
• Коды должны существовать в системе
• Коды должны соответствовать формату [ABCDEFGHJKLMNPQRSTUVWXYZ23456789]{10}

Поведение AuthGuard:

• Без кодов: если авторизован → дашборд, иначе → форма авторизации
• С кодами: всегда показывать AuthFlow (даже для авторизованных)

Поведение AuthFlow:

• Новый номер телефона: полный флоу (телефон → SMS → создание организации)
• Авторизованный номер: пропустить телефон/SMS, сразу к созданию организации

Создание партнерства:

• Создаются записи в таблице Counterparty в ОБЕ стороны
• Создается ReferralTransaction с начислением сфер
• Устанавливается referredById у новой организации

Создание реферальной связи:

• Создается ReferralTransaction с начислением сфер
• Устанавливается referredById у новой организации
• БЕЗ создания Counterparty записей

⚠️ ВАЖНЫЕ ОГРАНИЧЕНИЯ

Архитектурные ограничения:

• ОДИН ПОЛЬЗОВАТЕЛЬ может иметь МНОГО номеров телефонов
• ОДИН НОМЕР ТЕЛЕФОНА привязан к ОДНОМУ ПОЛЬЗОВАТЕЛЮ
• ОДИН НОМЕР ТЕЛЕФОНА может иметь МНОГО ОРГАНИЗАЦИЙ
• Нельзя зарегистрировать один номер телефона дважды

Уникальность организаций:

• Одна организация (по ИНН) может быть зарегистрирована только один раз
• API ключи селлеров должны быть уникальными

Сохранение кодов:

• Партнерские/реферальные коды должны передаваться через все компоненты
• Коды не должны теряться при авторизации номера телефона
• Коды применяются при создании ОРГАНИЗАЦИИ, не пользователя или номера

🧪 ТЕСТОВЫЕ СЦЕНАРИИ

Сценарий 1: Новый номер + партнерская ссылка

1. Переход по register?partner=A2LA72BZZX
2. Ввод нового телефона → SMS → авторизация
3. Создание новой организации
4. Проверка: создались партнерские связи, начислились сферы

Сценарий 2: Авторизованный номер + партнерская ссылка

1. Уже авторизован на номере в системе
2. Переход по register?partner=A2LA72BZZX
3. Пропуск авторизации → сразу создание организации
4. Проверка: создались партнерские связи, начислились сферы

Сценарий 3: Реферальная ссылка

1. Переход по register?ref=A2LA72BZZX
2. Авторизация (если нужно)
3. Создание организации
4. Проверка: начислились сферы, НЕТ партнерских связей

❓ ВОПРОСЫ ДЛЯ СОГЛАСОВАНИЯ

1. Архитектура БД: Нужна ли новая таблица для "мастер-пользователей" или изменить текущую схему?
2. Связь пользователь-телефон: Как будет происходить связывание номеров телефонов с одним пользователем?
3. UI для авторизованных: Показывать ли информацию "Вы создаете организацию для номера +7XXX"?
4. Переключение организаций: Как пользователь выбирает активную организацию из разных номеров?
5. Лимиты: Есть ли ограничения на количество номеров у пользователя или организаций у номера?
6. Идентификация: Как система определяет, что два номера принадлежат одному пользователю?