Подготовка к релизу

role_based_greetings_plan.md

@@ -0,0 +1,173 @@
+# 🏗 План реализации системы разделения приветствий по ролям
+
+## Обзор
+
+Реализация системы персонализированных приветствий для разных категорий пользователей (обычные пользователи, модераторы, администраторы) в Telegram боте.
+
+## 🎯 Цели
+
+- Персонализация приветствий на основе ролей пользователей
+- Обеспечение обратной совместимости с существующими пользователями
+- Безопасность и валидация ролей
+- Масштабируемость для будущих ролей
+
+## 📋 Компоненты системы
+
+### 1. Модель данных (Database Layer)
+- **User модель**: Добавить поле `role` типа `str` с default `'user'`
+- **Миграция БД**: ALTER TABLE users ADD COLUMN role TEXT DEFAULT 'user'
+- **UserRepository**: Методы для работы с ролями пользователей
+
+### 2. Бизнес-логика (Services Layer)
+- **RoleService**: Управление ролями пользователей
+  - `assign_role(user_id: int, role: str) -> bool`
+  - `get_user_role(user_id: int) -> str`
+  - `validate_role(role: str) -> bool`
+  - `is_admin(user_id: int) -> bool`
+  - `is_moderator(user_id: int) -> bool`
+- **UserService**: Интеграция с RoleService
+
+### 3. Презентационный слой (Handlers Layer)
+- **messages.py**: Словарь `greetings_by_role` с приветствиями по ролям
+- **UserHandlers._handle_start**: Выбор приветствия на основе роли
+
+### 4. Валидация и безопасность
+- Допустимые роли: 'user', 'moderator', 'admin'
+- Fallback на 'user' для неизвестных ролей
+- Защита от изменения ролей обычными пользователями
+
+## 🔄 Поток работы
+
+```mermaid
+sequenceDiagram
+    participant U as Пользователь
+    participant H as UserHandlers
+    participant US as UserService
+    participant RS as RoleService
+    participant UR as UserRepository
+    participant DB as Database
+
+    U->>H: /start
+    H->>US: get_or_create_user(user_id)
+    US->>RS: get_user_role(user_id)
+    RS->>UR: get_user_role(user_id)
+    UR->>DB: SELECT role FROM users WHERE telegram_id = ?
+    DB-->>UR: role
+    UR-->>RS: role
+    RS-->>US: role
+    US-->>H: role
+    H->>H: Выбор приветствия по role
+    H->>U: Персонализированное приветствие
+```
+
+## 📁 Структура изменений
+
+```
+telegram_bot/
+├── database/
+│   ├── models.py              # + поле role в User
+│   └── repository.py          # + методы для ролей
+├── services/
+│   ├── user_service.py        # обновление
+│   └── role_service.py        # НОВЫЙ
+├── handlers/
+│   └── user_handlers.py       # модификация _handle_start
+├── messages.py                # + greetings_by_role
+└── database_migration.sql     # НОВЫЙ: миграция БД
+```
+
+## 📋 План реализации (пошагово)
+
+### Этап 1: Подготовка данных
+1. ✅ Анализ существующей архитектуры
+2. 🔄 Обновить модель User (добавить поле role)
+3. 🔄 Создать миграцию базы данных
+4. 🔄 Добавить приветствия по ролям в messages.py
+
+### Этап 2: Бизнес-логика
+5. 🔄 Создать RoleService
+6. 🔄 Обновить UserService для работы с ролями
+7. 🔄 Обновить UserRepository
+
+### Этап 3: Обработчики и валидация
+8. 🔄 Модифицировать обработчик /start
+9. 🔄 Добавить логику проверки ролей
+10. 🔄 Добавить валидацию ролей
+
+### Этап 4: Тестирование
+11. 🔄 Протестировать систему приветствий для разных ролей
+
+## 🔧 Технические детали
+
+### Модель User (database/models.py)
+```python
+@dataclass
+class User:
+    # ... существующие поля ...
+    role: str = "user"  # НОВОЕ ПОЛЕ
+```
+
+### Миграция БД
+```sql
+ALTER TABLE users ADD COLUMN role TEXT DEFAULT 'user';
+```
+
+### Приветствия по ролям (messages.py)
+```python
+'greetings_by_role': {
+    'user': '''Привет, {name}! 👋
+Добро пожаловать в чат. Я ваш помощник здесь.
+Используйте /help для подробной информации.''',
+
+    'moderator': '''Привет, {name}! 👋
+Как модератор, вы можете управлять чатом.
+Используйте /help для команд модерации.''',
+
+    'admin': '''Привет, {name}! 👋
+Добро пожаловать, администратор. У вас полный доступ к управлению ботом.
+Начните с /help для списка команд.'''
+}
+```
+
+### RoleService (services/role_service.py)
+```python
+class RoleService:
+    VALID_ROLES = {'user', 'moderator', 'admin'}
+
+    def get_user_role(self, user_id: int) -> str:
+        # Получение роли из БД
+
+    def assign_role(self, user_id: int, role: str) -> bool:
+        # Назначение роли с валидацией
+
+    def validate_role(self, role: str) -> bool:
+        return role in self.VALID_ROLES
+
+    def is_admin(self, user_id: int) -> bool:
+        return self.get_user_role(user_id) == 'admin'
+
+    def is_moderator(self, user_id: int) -> bool:
+        role = self.get_user_role(user_id)
+        return role in {'moderator', 'admin'}
+```
+
+## ✅ Критерии успеха
+
+- ✅ Новые пользователи получают роль 'user' и соответствующее приветствие
+- ✅ Администраторы получают расширенное приветствие
+- ✅ Модераторы получают приветствие с информацией о правах
+- ✅ Fallback работает для неизвестных ролей
+- ✅ Обратная совместимость с существующими пользователями
+- ✅ Безопасность: только админы могут менять роли
+
+## 🚀 Следующие шаги
+
+После утверждения плана:
+1. Переключиться в режим code для реализации
+2. Начать с обновления модели User
+3. Последовательно реализовать все компоненты
+4. Протестировать на всех ролях
+
+---
+*Создано: 27 октября 2025 г.*
+*Статус: Готово к реализации*