bottohelp/role_based_greetings_plan.md

🏗 План реализации системы разделения приветствий по ролям

Обзор

Реализация системы персонализированных приветствий для разных категорий пользователей (обычные пользователи, модераторы, администраторы) в 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' для неизвестных ролей
• Защита от изменения ролей обычными пользователями

🔄 Поток работы

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)

@dataclass
class User:
    # ... существующие поля ...
    role: str = "user"  # НОВОЕ ПОЛЕ

Миграция БД

ALTER TABLE users ADD COLUMN role TEXT DEFAULT 'user';

Приветствия по ролям (messages.py)

'greetings_by_role': {
    'user': '''Привет, {name}! 👋
Добро пожаловать в чат. Я ваш помощник здесь.
Используйте /help для подробной информации.''',

    'moderator': '''Привет, {name}! 👋
Как модератор, вы можете управлять чатом.
Используйте /help для команд модерации.''',

    'admin': '''Привет, {name}! 👋
Добро пожаловать, администратор. У вас полный доступ к управлению ботом.
Начните с /help для списка команд.'''
}

RoleService (services/role_service.py)

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 г. Статус: Готово к реализации