🤖 КОТИКИ ТЕЛЕГРАММ БОТ

💾 СИСТЕМА КЕРУВАННЯ ПІДПИСКАМИ 💾

+ [CORE_SYSTEM:ACTIVE] | [USERS:CONNECTED] | [SUBSCRIPTION_SERVICE:ONLINE]

📡 ОГЛЯД ПРОЕКТУ

Телеграм бот для керування користувацькими підписками з системою нагадувань про закінчення терміну підписки. Рішення для керування платним контентом, закритими спільнотами та сервісами на основі передплати.

✨ КЛЮЧОВІ ФУНКЦІЇ

• 🔐 Система керування підписками з налаштуванням рівнів доступу
• ⏰ Система нагадувань (за 48 та 24 години до закінчення підписки)
• 🛠️ Адміністративний інтерфейс для керування користувачами та підписками
• 🧩 Модульна архітектура для масштабування функціональності
• 🗃️ Зберігання даних через SQLAlchemy та SQLite
• 🔄 Асинхронна обробка для високої продуктивності

---

🧠 АРХІТЕКТУРА ПРОЕКТУ

kotiki_bot/
├── 🚀 main.py                # Основний файл запуску
├── 📋 requirements.txt       # Залежності проекту
├── 🔑 .env                   # Файл з змінними середовища
├── 🔑 .env.example           # Шаблон змінних середовища
├── 📦 database/              # Модуль роботи з базою даних
│   ├── db.py                 # Схема та операції з БД
│   └── __init__.py           # Ініціалізація модуля БД
├── 👑 admin/                 # Адміністративний модуль
│   ├── admin_commands.py     # Команди адміністратора
│   ├── notification.py       # Адміністративні сповіщення
│   └── __init__.py           # Ініціалізація адмін-модуля
├── 🎮 buttons/               # Модуль клавіатур та кнопок
├── ⚙️ config/                # Модуль конфігурації
├── 🎯 handlers/              # Обробники повідомлень
│   ├── commands.py           # Базові команди
│   ├── profile.py            # Робота з профілем
│   ├── subscriptions.py      # Керування підписками
│   ├── notifications.py      # Система сповіщень
│   ├── settings.py           # Налаштування користувача
│   └── __init__.py           # Ініціалізація обробників
├── 🧪 tests/                 # Модульні тести
└── 🔧 utils/                 # Допоміжні утиліти
    └── reminders.py          # Планувальник нагадувань

---

💻 ДЛЯ РОЗРОБНИКІВ

🔧 ТЕХНІЧНИЙ СТЕК

• Python: Асинхронний бекенд (3.09-3.11)
• aiogram 2.25.1: Бібліотека для розробки Telegram-ботів
• SQLAlchemy 2.0.19: ORM для роботи з базою даних
• aiohttp 3.8.5: Асинхронний HTTP-клієнт/сервер
• python-dotenv 1.0.0: Керування конфігурацією
• pytest: Тестування компонентів

🔌 АРХІТЕКТУРНІ ОСОБЛИВОСТІ

Модуль бази даних (database/)

• db.py - Визначає схему бази даних та класи моделей:
  • User: Інформація про користувачів
  • Subscription: Дані про підписки користувачів
  • Admin: Адміністративні права
  • ActivityLog: Логування активності
• Підтримка міграцій та автоматичне створення схеми

Адміністративний модуль (admin/)

• admin_commands.py - Адміністративні команди:
  • Керування підписками користувачів
  • Перегляд статистики
  • Розсилка повідомлень
  • Налаштування параметрів бота
• notification.py - Система адміністративних сповіщень

Модуль обробників (handlers/)

• Розподіл відповідальності між обробниками:
  • commands.py - Базові команди (/start, /help)
  • profile.py - Керування профілем користувача
  • subscriptions.py - Логіка роботи з підписками
  • notifications.py - Налаштування сповіщень
  • settings.py - Користувацькі налаштування

Асинхронний планувальник нагадувань

• Реалізовано через asyncio та asyncio.create_task
• Перевірка бази даних на наявність підписок, що закінчуються
• Автоматичне надсилання сповіщень
• Оптимізовано для мінімального навантаження

⚡ ПРИКЛАДИ КОДУ

Додавання нової команди

# У файлі handlers/commands.py
from aiogram import types
from aiogram.dispatcher.filters import Command

@dp.message_handler(Command("new_command"))
async def new_command_handler(message: types.Message):
    await message.answer("Це нова команда!")

# Реєстрація у handlers/commands.py
def register_command_handlers(dp):
    dp.register_message_handler(new_command_handler, commands=["new_command"])

Створення нової моделі даних

# У файлі database/db.py
from sqlalchemy import Column, Integer, String, ForeignKey
from sqlalchemy.orm import relationship
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class NewModel(Base):
    __tablename__ = "new_models"
    
    id = Column(Integer, primary_key=True)
    name = Column(String, nullable=False)
    description = Column(String)
    user_id = Column(Integer, ForeignKey("users.id"))
    
    user = relationship("User", back_populates="new_models")

---

🛠️ ВСТАНОВЛЕННЯ ТА ЗАПУСК

📋 ВИМОГИ

• Python 3.09, 3.10 або 3.11
• Pip (менеджер пакетів Python)
• Telegram Bot Token (отримати у @BotFather)

💿 ВСТАНОВЛЕННЯ

Linux/macOS

# Клонування репозиторію
git clone https://github.com/Panda404NotFound/kotiki_bot.git
cd kotiki_bot

# Створення віртуального середовища
python3 -m venv venv
source venv/bin/activate

# Встановлення залежностей
pip install -r requirements.txt

# Налаштування конфігурації
cp .env.example .env
# Відредагуйте .env файл, додавши власні токени та налаштування

Windows

# Клонування репозиторію
git clone https://github.com/Panda404NotFound/kotiki_bot.git
cd kotiki_bot

# Створення віртуального середовища
python -m venv venv
.\venv\Scripts\activate

# Встановлення залежностей
pip install -r requirements.txt

# Налаштування конфігурації
copy .env.example .env
# Відредагуйте .env файл, додавши власні токени та налаштування

▶️ ЗАПУСК

# Активація віртуального середовища (якщо ще не активовано)
# Linux/macOS:
source venv/bin/activate
# Windows:
# .\venv\Scripts\activate

# Запуск бота
python main.py

🧪 ТЕСТУВАННЯ

# Запуск усіх тестів
pytest

# Запуск тестів з детальним виводом
pytest -v

# Запуск конкретного тесту
pytest tests/test_specific.py

---

🎮 ВИКОРИСТАННЯ БОТА

📝 ОСНОВНІ КОМАНДИ

• /start - Почати роботу з ботом та створити профіль
• /help - Отримати довідку щодо використання бота
• /faq - Відповіді на поширені запитання

👑 АДМІНІСТРАТИВНІ КОМАНДИ

• /admin - Показати адмін-панель (доступно лише адміністраторам)
• /add_subscription <user_id> <days> - Додати підписку користувачу
• /user_info <user_id> - Отримати детальну інформацію про користувача
• /stats - Перегляд статистики використання бота
• /broadcast - Створити розсилку всім користувачам

📊 МЕНЮ НАВІГАЦІЇ

Бот використовує зручну систему кнопок для швидкої навігації:

• Мій профіль - Інформація про ваш профіль та поточні підписки
• Сповіщення - Налаштування параметрів сповіщень
• Підписки - Керування вашими підписками
• Налаштування - Персоналізація параметрів бота

⏰ СИСТЕМА НАГАДУВАНЬ

Бот автоматично надсилає нагадування користувачам про закінчення підписки:

• 🟠 За 48 годин до закінчення
• 🔴 За 24 години до закінчення

---

🔍 ВИРІШЕННЯ ПРОБЛЕМ

Бот не відповідає на команди

1. Перевірте, чи активний бот (чи запущений скрипт main.py)
2. Перевірте, чи правильно вказаний токен бота у файлі .env
3. Перевірте логи на наявність помилок підключення
4. Переконайтеся, що у бота є права на надсилання повідомлень

Помилки при запуску

1. Переконайтеся, що встановлені всі залежності з requirements.txt
2. Перевірте версію Python (потрібна 3.09-3.11)
3. Перевірте, чи правильно створений файл .env
4. Перевірте права доступу до каталогу для створення бази даних

Проблеми з базою даних

1. Перевірте налаштування DB_URL та DB_FILE у файлі .env
2. Переконайтеся, що користувач має права на запис у каталог з базою даних
3. Для повного скидання: видаліть файл бази даних та перезапустіть бота

---

📞 КОНТАКТИ

---

Розроблено з ❤️ та натхненням