Skip to content

README.ru.md

Latest commit

 

History

History
158 lines (124 loc) · 7.16 KB

README.ru.md

File metadata and controls

158 lines (124 loc) · 7.16 KB

🍽️ ChatBot Base

TypeScript Bun Prisma Redis

Универсальный фреймворк для создания ботов (Telegram и др.), веб-бэкендов или полноценных монолитов. Построен на Bun, TypeScript и модульной архитектуре, вдохновленной лучшими практиками Go.

🏗️ Архитектура проекта

Проект использует четкое разделение ответственности. Фреймворк позволяет объединять логику чат-ботов и HTTP-сервера в одном приложении.

Структура каталогов

  • cmd/ — Точки входа в приложение.
  • internal/ — Приватный код приложения.
    • core/ — Базовые классы (App, Loader, Router), интерфейсы и системные перечисления.
    • application/ — Бизнес-логика: модули, роуты, события и сцены.
    • services/ — Специализированные сервисы (AI, бизнес-логика и др.).
    • storage/ — Логика работы с хранилищами данных (Prisma, Redis).
  • pkg/ — Публичные утилиты и библиотеки.
  • config/ — Конфигурационные файлы.
  • database/ — Схемы БД (Prisma) и миграции.

🛠️ Как пользоваться архитектурой

1. Добавление модуля (Module)

Модули — это строительные блоки приложения. Они загружаются автоматически. События (ModuleType.EVENT) загружаются в последнюю очередь, чтобы гарантировать готовность всех зависимостей.

// internal/application/modules/example.module.ts
import Module, { ModuleType } from "@core/classes/module.class";

export default new Module({ type: ModuleType.MODULE }, async (deps, config) => {
    // Ваша логика здесь
});

2. Создание сцены (Scene)

Сцены используются для сложных диалогов в ботах. В параметрах передается name, а внутри доступны методы Telegraf и deps.scene.

// internal/application/scenes/order.scene.ts
export default new Scene({ name: "order_scene" }, async (deps, config) => {
    deps.scene.enter(async (ctx) => {
        await ctx.reply("Что вы хотите заказать?");
    });
    // Обработка шагов сцены
});

3. Создание роута (Route)

Для создания API или бэкенда для сайта используйте роуты.

import Route from "@core/classes/route.class";

export default new Route(
    { path: "/api/status", method: "GET" },
    async (deps, request, config) => {
        return Response.json({ status: "ok" });
    }
);

🤖 Использование Telegram Bot

По умолчанию поддержка Telegraf отключена в базовой версии для универсальности. Чтобы активировать её:

  1. Установите библиотеку:

    bun add telegraf

  2. Активируйте файлы ядра: Переименуйте файлы, убрав расширение .disabled:

    • internal/core/classes/scene.class.ts.disabled
    • internal/core/interfaces/context.interface.ts.disabled
    • internal/core/interfaces/scene.interface.ts.disabled

  3. Раскомментируйте код:

    • В internal/core/interfaces/deps.interface.ts раскомментируйте импорты Telegraf и интерфейс ISceneDeps: 
      import { Telegraf, Scenes } from "telegraf";
// ...
export interface ISceneDeps extends IBaseDeps {
    scene: Scenes.BaseScene<any>;
}
    • В internal/core/classes/loader.class.ts раскомментируйте метод loadScenes: 
      public async loadScenes(): Promise<Scenes.BaseScene<any>[]> {
    const sceneFiles = this.getFiles(this.scenesPath, this.suffix);
    const scenes: Scenes.BaseScene<any>[] = [];
    // ...
    return scenes;
}

  4. Настройте App: В internal/core/classes/app.class.ts добавьте инициализацию сессий и сцен (middleware) перед загрузкой модулей.

    Примечание: Также необходимо добавить stage: { ttl: число } в ваш конфиг. Параметр ttl (Time To Live) определяет время жизни сцены (в секундах) после вызова; по истечении этого времени сцена автоматически закрывается.

    const scenes = await this.loader.loadScenes();
const stage = new Scenes.Stage(scenes, { ttl: config.stage.ttl });

this.deps.bot.use(session());
this.deps.bot.use(stage.middleware());

🚀 Быстрый старт

Предварительные требования

  • Bun runtime
  • Redis
  • PostgreSQL/SQLite (через Prisma)

Установка

  1. Клонируйте репозиторий.
  2. Установите зависимости: bun install.
  3. Настройте .env (используя env.example).
  4. Подготовьте БД: bun run db:migrate && bun run db:generate.
  5. Запустите: bun run dev.

📈 Список скриптов

  • bun run dev — Запуск в режиме разработки с hot-reload.
  • bun run start — Запуск в production.
  • bun run db:* — Команды для работы с Prisma (migrate, generate, studio).
  • bun run format — Форматирование кода через Prettier.

🐳 Docker

Проект включает Dockerfile и docker-compose.yml для быстрого развертывания в контейнерах.

# Запуск через docker-compose
docker-compose up -d

# Логи
docker-compose logs -f bot

Переменные окружения для продакшена

NODE_ENV=production
LOG_LEVEL=warn
BOT_TOKEN=your_production_bot_token
GEMINI_API_KEY=your_production_gemini_key
REDIS_URL=redis://your-redis-server:6379

📄 Лицензия

Этот проект распространяется под лицензией MIT. Подробности в файле LICENSE.

© 2026 Pavlotech. MIT License.