smart-bot-factory 0.1.9__tar.gz → 0.2.0__tar.gz

{smart_bot_factory-0.1.9 → smart_bot_factory-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smart-bot-factory
-Version: 0.1.9
+Version: 0.2.0
 Summary: Библиотека для создания умных чат-ботов
 Author-email: Kopatych <kopatych@example.com>
 License: MIT
@@ -163,18 +163,24 @@ sbf run my-bot
 
 ### Router System
 
-Smart Bot Factory использует систему роутеров для организации обработчиков:
+Smart Bot Factory использует **два типа роутеров** для организации обработчиков:
+
+1. **EventRouter** - для бизнес-логики (события, задачи, глобальные обработчики)
+2. **TelegramRouter** - для Telegram команд, сообщений и callback'ов
 
 ```python
-from smart_bot_factory.router import Router
+from smart_bot_factory.router import EventRouter, TelegramRouter
 from smart_bot_factory.message import send_message_by_human
 from smart_bot_factory.creation import BotBuilder
+from aiogram import F
+from aiogram.filters import Command
+from aiogram.types import Message
+from aiogram.fsm.context import FSMContext
 
-# Создаем роутер
-router = Router("my_bot_handlers")
+# EventRouter - для бизнес-логики
+event_router = EventRouter("my_bot_events")
 
-# Регистрируем обработчики
-@router.event_handler("appointment_booking", notify=True)
+@event_router.event_handler("appointment_booking", notify=True)
 async def handle_booking(user_id: int, event_data: str):
     """Обработчик записи на прием"""
     await send_message_by_human(
@@ -183,15 +189,114 @@ async def handle_booking(user_id: int, event_data: str):
     )
     return {"status": "success"}
 
+# TelegramRouter - для Telegram команд и сообщений
+telegram_router = TelegramRouter("my_bot_telegram")
+
+@telegram_router.router.message(Command("price", "цена"))
+async def handle_price(message: Message, state: FSMContext):
+    """Обработчик команды /price"""
+    await message.answer("💰 Наши цены...")
+
+@telegram_router.router.message(F.text.contains("помощь"))
+async def handle_help(message: Message, state: FSMContext):
+    """Обработчик запросов помощи"""
+    await message.answer("📖 Чем могу помочь?")
+
 # Запуск бота
 async def main():
     bot = BotBuilder("my-bot")
-    bot.register_router(router)
+    
+    # Регистрируем роутеры (можно по одному или несколько сразу)
+    bot.register_routers(event_router)  # EventRouter
+    bot.register_telegram_routers(telegram_router)  # TelegramRouter
+    
     await bot.build()
     await bot.start()
 ```
 
-### Типы обработчиков
+### TelegramRouter - Обработчики Telegram
+
+**TelegramRouter** позволяет добавлять пользовательские команды и обработчики сообщений в Telegram бота, используя стандартный aiogram API:
+
+#### Команды
+
+```python
+from smart_bot_factory.router import TelegramRouter
+from aiogram.filters import Command
+from aiogram.types import Message
+from aiogram.fsm.context import FSMContext
+
+telegram_router = TelegramRouter("my_commands")
+
+@telegram_router.router.message(Command("start", "старт"))
+async def cmd_start(message: Message, state: FSMContext):
+    """Обработчик команды /start"""
+    await message.answer("👋 Привет!")
+
+@telegram_router.router.message(Command("price"))
+async def cmd_price(message: Message, state: FSMContext):
+    """Обработчик команды /price"""
+    await message.answer("💰 Цены:\n1. Базовый - 1000₽\n2. Премиум - 5000₽")
+```
+
+#### Фильтры по тексту
+
+```python
+from aiogram import F
+
+@telegram_router.router.message(F.text.lower().contains("цена"))
+async def handle_price_question(message: Message, state: FSMContext):
+    """Когда пользователь спрашивает о цене"""
+    await message.answer("💡 Используйте /price для просмотра цен")
+
+@telegram_router.router.message(F.text.startswith("!"))
+async def handle_commands(message: Message, state: FSMContext):
+    """Обработка кастомных команд с !"""
+    command = message.text[1:]
+    await message.answer(f"Выполняю команду: {command}")
+```
+
+#### Callback Query
+
+```python
+from aiogram.types import CallbackQuery, InlineKeyboardMarkup, InlineKeyboardButton
+
+@telegram_router.router.callback_query(F.data.startswith("buy_"))
+async def handle_buy(callback: CallbackQuery, state: FSMContext):
+    """Обработка покупки"""
+    product_id = callback.data.split("_")[1]
+    await callback.answer("Оформляем...")
+    await callback.message.answer(f"✅ Товар {product_id} добавлен в корзину")
+
+@telegram_router.router.message(Command("catalog"))
+async def show_catalog(message: Message, state: FSMContext):
+    """Показывает каталог с кнопками"""
+    keyboard = InlineKeyboardMarkup(inline_keyboard=[
+        [InlineKeyboardButton(text="Купить товар 1", callback_data="buy_1")],
+        [InlineKeyboardButton(text="Купить товар 2", callback_data="buy_2")]
+    ])
+    await message.answer("🛍️ Каталог товаров:", reply_markup=keyboard)
+```
+
+#### Регистрация нескольких роутеров
+
+```python
+# Создаем несколько TelegramRouter для разных модулей
+commands_router = TelegramRouter("commands")
+admin_router = TelegramRouter("admin_commands")
+callbacks_router = TelegramRouter("callbacks")
+
+# Регистрируем все сразу
+bot_builder.register_telegram_routers(
+    commands_router,
+    admin_router,
+    callbacks_router
+)
+```
+
+**Важно:** TelegramRouter - это обертка над aiogram Router, предоставляющая доступ к полному функционалу aiogram через свойство `.router`.
+
+### EventRouter - Типы обработчиков событий
 
 #### 1. Event Handlers - Обработчики событий
 
@@ -423,24 +528,81 @@ ADMIN_SESSION_TIMEOUT_MINUTES=30
 
 ### Множественные роутеры
 
+#### Регистрация нескольких EventRouter
+
 ```python
 # handlers/main.py
-main_router = Router("main")
+main_router = EventRouter("main")
 
 # handlers/admin.py
-admin_router = Router("admin")
+admin_router = EventRouter("admin")
+
+# handlers/payments.py
+payments_router = EventRouter("payments")
 
 # app.py
 bot = BotBuilder("my-bot")
+
+# Можно по одному
 bot.register_router(main_router)
 bot.register_router(admin_router)
+
+# Или все сразу
+bot.register_routers(main_router, admin_router, payments_router)
 ```
 
-### Вложенные роутеры
+#### Регистрация нескольких TelegramRouter
 
 ```python
-main_router = Router("main")
-payments_router = Router("payments")
+# telegram/commands.py
+commands_router = TelegramRouter("commands")
+
+@commands_router.router.message(Command("start"))
+async def start(message: Message, state: FSMContext):
+    await message.answer("Привет!")
+
+# telegram/callbacks.py
+callbacks_router = TelegramRouter("callbacks")
+
+@callbacks_router.router.callback_query(F.data.startswith("action_"))
+async def handle_action(callback: CallbackQuery, state: FSMContext):
+    await callback.answer("Выполнено!")
+
+# app.py
+bot = BotBuilder("my-bot")
+
+# Регистрируем несколько Telegram роутеров сразу
+bot.register_telegram_routers(commands_router, callbacks_router)
+```
+
+#### Комбинирование EventRouter и TelegramRouter
+
+```python
+# Создаем роутеры для разных целей
+event_router = EventRouter("events")
+telegram_router = TelegramRouter("telegram_handlers")
+
+# EventRouter - бизнес-логика
+@event_router.event_handler("payment_success")
+async def handle_payment(user_id: int, event_data: str):
+    await send_message_by_human(user_id, "✅ Оплата получена!")
+    return {"status": "success"}
+
+# TelegramRouter - пользовательские команды
+@telegram_router.router.message(Command("balance"))
+async def check_balance(message: Message, state: FSMContext):
+    await message.answer("💰 Ваш баланс: 1000₽")
+
+# Регистрируем оба типа роутеров
+bot_builder.register_routers(event_router)
+bot_builder.register_telegram_routers(telegram_router)
+```
+
+### Вложенные роутеры (EventRouter)
+
+```python
+main_router = EventRouter("main")
+payments_router = EventRouter("payments")
 
 # Включаем роутер платежей в основной
 main_router.include_router(payments_router)
@@ -486,17 +648,38 @@ my-project/
 ```python
 import asyncio
 
-from smart_bot_factory.router import Router
+from smart_bot_factory.router import EventRouter, TelegramRouter
 from smart_bot_factory.message import send_message_by_human, send_message_to_users_by_stage
 from smart_bot_factory.supabase import SupabaseClient
 from smart_bot_factory.creation import BotBuilder
+from aiogram import F
+from aiogram.filters import Command
+from aiogram.types import Message
+from aiogram.fsm.context import FSMContext
 
 # Инициализация
-router = Router("medical_bot")
+event_router = EventRouter("medical_bot_events")
+telegram_router = TelegramRouter("medical_bot_telegram")
 supabase_client = SupabaseClient("medical-bot")
 
-# Обработчик записи на прием
-@router.event_handler("appointment_booking", notify=True)
+# Пользовательские команды (TelegramRouter)
+@telegram_router.router.message(Command("appointment", "запись"))
+async def cmd_appointment(message: Message, state: FSMContext):
+    """Команда для записи на прием"""
+    await message.answer(
+        "📅 Для записи на прием укажите:\n"
+        "- Ваше имя\n"
+        "- Телефон\n"
+        "- Желаемая дата и время"
+    )
+
+@telegram_router.router.message(F.text.lower().contains("цена"))
+async def handle_price_question(message: Message, state: FSMContext):
+    """Вопросы о ценах"""
+    await message.answer("💰 Используйте /appointment для записи и уточнения стоимости")
+
+# Обработчик записи на прием (EventRouter)
+@event_router.event_handler("appointment_booking", notify=True)
 async def handle_appointment(user_id: int, event_data: str):
     """Обрабатывает запись на прием к врачу"""
     # event_data: "имя: Иван, телефон: +79991234567, дата: 2025-10-15, время: 14:00"
@@ -508,8 +691,8 @@ async def handle_appointment(user_id: int, event_data: str):
     
     return {"status": "success", "data": event_data}
 
-# Напоминание за 2 часа до приема
-@router.schedule_task(
+# Напоминание за 2 часа до приема (EventRouter)
+@event_router.schedule_task(
     "appointment_reminder",
     delay="2h",
     event_type="appointment_booking"
@@ -522,8 +705,8 @@ async def remind_before_appointment(user_id: int, reminder_text: str):
     )
     return {"status": "sent"}
 
-# Ночной дайджест для всех
-@router.global_handler("daily_digest", delay="24h")
+# Ночной дайджест для всех (EventRouter)
+@event_router.global_handler("daily_digest", delay="24h")
 async def send_daily_digest(digest_text: str):
     """Отправляет ежедневный дайджест всем активным пользователям"""
     await send_message_to_users_by_stage(
@@ -535,7 +718,11 @@ async def send_daily_digest(digest_text: str):
 # Запуск
 async def main():
     bot = BotBuilder("medical-bot")
-    bot.register_router(router)
+    
+    # Регистрируем роутеры
+    bot.register_routers(event_router)  # EventRouter
+    bot.register_telegram_routers(telegram_router)  # TelegramRouter
+    
     await bot.build()
     await bot.start()
 

{smart_bot_factory-0.1.9 → smart_bot_factory-0.2.0}/README.md

@@ -130,18 +130,24 @@ sbf run my-bot
 
 ### Router System
 
-Smart Bot Factory использует систему роутеров для организации обработчиков:
+Smart Bot Factory использует **два типа роутеров** для организации обработчиков:
+
+1. **EventRouter** - для бизнес-логики (события, задачи, глобальные обработчики)
+2. **TelegramRouter** - для Telegram команд, сообщений и callback'ов
 
 ```python
-from smart_bot_factory.router import Router
+from smart_bot_factory.router import EventRouter, TelegramRouter
 from smart_bot_factory.message import send_message_by_human
 from smart_bot_factory.creation import BotBuilder
+from aiogram import F
+from aiogram.filters import Command
+from aiogram.types import Message
+from aiogram.fsm.context import FSMContext
 
-# Создаем роутер
-router = Router("my_bot_handlers")
+# EventRouter - для бизнес-логики
+event_router = EventRouter("my_bot_events")
 
-# Регистрируем обработчики
-@router.event_handler("appointment_booking", notify=True)
+@event_router.event_handler("appointment_booking", notify=True)
 async def handle_booking(user_id: int, event_data: str):
     """Обработчик записи на прием"""
     await send_message_by_human(
@@ -150,15 +156,114 @@ async def handle_booking(user_id: int, event_data: str):
     )
     return {"status": "success"}
 
+# TelegramRouter - для Telegram команд и сообщений
+telegram_router = TelegramRouter("my_bot_telegram")
+
+@telegram_router.router.message(Command("price", "цена"))
+async def handle_price(message: Message, state: FSMContext):
+    """Обработчик команды /price"""
+    await message.answer("💰 Наши цены...")
+
+@telegram_router.router.message(F.text.contains("помощь"))
+async def handle_help(message: Message, state: FSMContext):
+    """Обработчик запросов помощи"""
+    await message.answer("📖 Чем могу помочь?")
+
 # Запуск бота
 async def main():
     bot = BotBuilder("my-bot")
-    bot.register_router(router)
+    
+    # Регистрируем роутеры (можно по одному или несколько сразу)
+    bot.register_routers(event_router)  # EventRouter
+    bot.register_telegram_routers(telegram_router)  # TelegramRouter
+    
     await bot.build()
     await bot.start()
 ```
 
-### Типы обработчиков
+### TelegramRouter - Обработчики Telegram
+
+**TelegramRouter** позволяет добавлять пользовательские команды и обработчики сообщений в Telegram бота, используя стандартный aiogram API:
+
+#### Команды
+
+```python
+from smart_bot_factory.router import TelegramRouter
+from aiogram.filters import Command
+from aiogram.types import Message
+from aiogram.fsm.context import FSMContext
+
+telegram_router = TelegramRouter("my_commands")
+
+@telegram_router.router.message(Command("start", "старт"))
+async def cmd_start(message: Message, state: FSMContext):
+    """Обработчик команды /start"""
+    await message.answer("👋 Привет!")
+
+@telegram_router.router.message(Command("price"))
+async def cmd_price(message: Message, state: FSMContext):
+    """Обработчик команды /price"""
+    await message.answer("💰 Цены:\n1. Базовый - 1000₽\n2. Премиум - 5000₽")
+```
+
+#### Фильтры по тексту
+
+```python
+from aiogram import F
+
+@telegram_router.router.message(F.text.lower().contains("цена"))
+async def handle_price_question(message: Message, state: FSMContext):
+    """Когда пользователь спрашивает о цене"""
+    await message.answer("💡 Используйте /price для просмотра цен")
+
+@telegram_router.router.message(F.text.startswith("!"))
+async def handle_commands(message: Message, state: FSMContext):
+    """Обработка кастомных команд с !"""
+    command = message.text[1:]
+    await message.answer(f"Выполняю команду: {command}")
+```
+
+#### Callback Query
+
+```python
+from aiogram.types import CallbackQuery, InlineKeyboardMarkup, InlineKeyboardButton
+
+@telegram_router.router.callback_query(F.data.startswith("buy_"))
+async def handle_buy(callback: CallbackQuery, state: FSMContext):
+    """Обработка покупки"""
+    product_id = callback.data.split("_")[1]
+    await callback.answer("Оформляем...")
+    await callback.message.answer(f"✅ Товар {product_id} добавлен в корзину")
+
+@telegram_router.router.message(Command("catalog"))
+async def show_catalog(message: Message, state: FSMContext):
+    """Показывает каталог с кнопками"""
+    keyboard = InlineKeyboardMarkup(inline_keyboard=[
+        [InlineKeyboardButton(text="Купить товар 1", callback_data="buy_1")],
+        [InlineKeyboardButton(text="Купить товар 2", callback_data="buy_2")]
+    ])
+    await message.answer("🛍️ Каталог товаров:", reply_markup=keyboard)
+```
+
+#### Регистрация нескольких роутеров
+
+```python
+# Создаем несколько TelegramRouter для разных модулей
+commands_router = TelegramRouter("commands")
+admin_router = TelegramRouter("admin_commands")
+callbacks_router = TelegramRouter("callbacks")
+
+# Регистрируем все сразу
+bot_builder.register_telegram_routers(
+    commands_router,
+    admin_router,
+    callbacks_router
+)
+```
+
+**Важно:** TelegramRouter - это обертка над aiogram Router, предоставляющая доступ к полному функционалу aiogram через свойство `.router`.
+
+### EventRouter - Типы обработчиков событий
 
 #### 1. Event Handlers - Обработчики событий
 
@@ -390,24 +495,81 @@ ADMIN_SESSION_TIMEOUT_MINUTES=30
 
 ### Множественные роутеры
 
+#### Регистрация нескольких EventRouter
+
 ```python
 # handlers/main.py
-main_router = Router("main")
+main_router = EventRouter("main")
 
 # handlers/admin.py
-admin_router = Router("admin")
+admin_router = EventRouter("admin")
+
+# handlers/payments.py
+payments_router = EventRouter("payments")
 
 # app.py
 bot = BotBuilder("my-bot")
+
+# Можно по одному
 bot.register_router(main_router)
 bot.register_router(admin_router)
+
+# Или все сразу
+bot.register_routers(main_router, admin_router, payments_router)
 ```
 
-### Вложенные роутеры
+#### Регистрация нескольких TelegramRouter
 
 ```python
-main_router = Router("main")
-payments_router = Router("payments")
+# telegram/commands.py
+commands_router = TelegramRouter("commands")
+
+@commands_router.router.message(Command("start"))
+async def start(message: Message, state: FSMContext):
+    await message.answer("Привет!")
+
+# telegram/callbacks.py
+callbacks_router = TelegramRouter("callbacks")
+
+@callbacks_router.router.callback_query(F.data.startswith("action_"))
+async def handle_action(callback: CallbackQuery, state: FSMContext):
+    await callback.answer("Выполнено!")
+
+# app.py
+bot = BotBuilder("my-bot")
+
+# Регистрируем несколько Telegram роутеров сразу
+bot.register_telegram_routers(commands_router, callbacks_router)
+```
+
+#### Комбинирование EventRouter и TelegramRouter
+
+```python
+# Создаем роутеры для разных целей
+event_router = EventRouter("events")
+telegram_router = TelegramRouter("telegram_handlers")
+
+# EventRouter - бизнес-логика
+@event_router.event_handler("payment_success")
+async def handle_payment(user_id: int, event_data: str):
+    await send_message_by_human(user_id, "✅ Оплата получена!")
+    return {"status": "success"}
+
+# TelegramRouter - пользовательские команды
+@telegram_router.router.message(Command("balance"))
+async def check_balance(message: Message, state: FSMContext):
+    await message.answer("💰 Ваш баланс: 1000₽")
+
+# Регистрируем оба типа роутеров
+bot_builder.register_routers(event_router)
+bot_builder.register_telegram_routers(telegram_router)
+```
+
+### Вложенные роутеры (EventRouter)
+
+```python
+main_router = EventRouter("main")
+payments_router = EventRouter("payments")
 
 # Включаем роутер платежей в основной
 main_router.include_router(payments_router)
@@ -453,17 +615,38 @@ my-project/
 ```python
 import asyncio
 
-from smart_bot_factory.router import Router
+from smart_bot_factory.router import EventRouter, TelegramRouter
 from smart_bot_factory.message import send_message_by_human, send_message_to_users_by_stage
 from smart_bot_factory.supabase import SupabaseClient
 from smart_bot_factory.creation import BotBuilder
+from aiogram import F
+from aiogram.filters import Command
+from aiogram.types import Message
+from aiogram.fsm.context import FSMContext
 
 # Инициализация
-router = Router("medical_bot")
+event_router = EventRouter("medical_bot_events")
+telegram_router = TelegramRouter("medical_bot_telegram")
 supabase_client = SupabaseClient("medical-bot")
 
-# Обработчик записи на прием
-@router.event_handler("appointment_booking", notify=True)
+# Пользовательские команды (TelegramRouter)
+@telegram_router.router.message(Command("appointment", "запись"))
+async def cmd_appointment(message: Message, state: FSMContext):
+    """Команда для записи на прием"""
+    await message.answer(
+        "📅 Для записи на прием укажите:\n"
+        "- Ваше имя\n"
+        "- Телефон\n"
+        "- Желаемая дата и время"
+    )
+
+@telegram_router.router.message(F.text.lower().contains("цена"))
+async def handle_price_question(message: Message, state: FSMContext):
+    """Вопросы о ценах"""
+    await message.answer("💰 Используйте /appointment для записи и уточнения стоимости")
+
+# Обработчик записи на прием (EventRouter)
+@event_router.event_handler("appointment_booking", notify=True)
 async def handle_appointment(user_id: int, event_data: str):
     """Обрабатывает запись на прием к врачу"""
     # event_data: "имя: Иван, телефон: +79991234567, дата: 2025-10-15, время: 14:00"
@@ -475,8 +658,8 @@ async def handle_appointment(user_id: int, event_data: str):
     
     return {"status": "success", "data": event_data}
 
-# Напоминание за 2 часа до приема
-@router.schedule_task(
+# Напоминание за 2 часа до приема (EventRouter)
+@event_router.schedule_task(
     "appointment_reminder",
     delay="2h",
     event_type="appointment_booking"
@@ -489,8 +672,8 @@ async def remind_before_appointment(user_id: int, reminder_text: str):
     )
     return {"status": "sent"}
 
-# Ночной дайджест для всех
-@router.global_handler("daily_digest", delay="24h")
+# Ночной дайджест для всех (EventRouter)
+@event_router.global_handler("daily_digest", delay="24h")
 async def send_daily_digest(digest_text: str):
     """Отправляет ежедневный дайджест всем активным пользователям"""
     await send_message_to_users_by_stage(
@@ -502,7 +685,11 @@ async def send_daily_digest(digest_text: str):
 # Запуск
 async def main():
     bot = BotBuilder("medical-bot")
-    bot.register_router(router)
+    
+    # Регистрируем роутеры
+    bot.register_routers(event_router)  # EventRouter
+    bot.register_telegram_routers(telegram_router)  # TelegramRouter
+    
     await bot.build()
     await bot.start()