@2byte/tgbot-framework 1.0.3 → 1.0.5

package/templates/bot/docs/INPUT_SYSTEM.md

@@ -0,0 +1,211 @@
+# Улучшенная система ввода пользователя
+
+## Обзор
+
+Система ввода была значительно улучшена для поддержки:
+- Возможности отмены ввода пользователем
+- Настраиваемых опций отмены при создании запроса
+- Сохранения состояния ожидания при неверном вводе
+- Расширенной валидации, включая файлы
+- Гибкой системы валидации для различных типов ботов
+
+## Основные возможности
+
+### 1. Настройка отмены ввода
+
+При создании запроса на ввод можно настроить возможность отмены:
+
+```typescript
+// Разрешить отмену (по умолчанию)
+.requestInput("phone", {
+  validator: "phone",
+  allowCancel: true, // по умолчанию true
+  cancelButtonText: "Отмена", // текст кнопки
+  cancelAction: "home.index[cancel_wait=1]", // действие при отмене
+})
+
+// Запретить отмену (обязательный ввод)
+.requestInputWithAwait("password", {
+  allowCancel: false, // отмена запрещена
+  errorMessage: "Пароль обязателен для ввода"
+})
+```
+
+### 2. Сохранение состояния при ошибках
+
+При неверном вводе пользователь остается в режиме ожидания:
+
+```typescript
+.requestInput("code", {
+  validator: "code",
+  errorMessage: "Неверный формат кода. Введите 5-6 цифр",
+  allowCancel: true
+})
+```
+
+Система будет:
+- Показывать сообщение об ошибке
+- Увеличивать счетчик попыток
+- Сохранять состояние ожидания
+- Позволять отмену только если `allowCancel: true`
+
+### 3. Валидация файлов
+
+Поддержка загрузки и валидации файлов:
+
+```typescript
+.requestInput("uploadedFile", {
+  validator: "file",
+  errorMessage: "Неподдерживаемый формат файла",
+  fileValidation: {
+    allowedTypes: ['image/jpeg', 'image/png', 'application/pdf'],
+    maxSize: 10 * 1024 * 1024, // 10 МБ
+    minSize: 1024, // 1 КБ
+  },
+  allowCancel: true
+})
+```
+
+### 4. Кастомная валидация
+
+Поддержка асинхронных валидаторов:
+
+```typescript
+.requestInput("customData", {
+  validator: async (value) => {
+    // Асинхронная проверка
+    const isValid = await checkInDatabase(value);
+    return isValid;
+  },
+  errorMessage: "Данные не прошли проверку"
+})
+```
+
+## Типы валидаторов
+
+### Встроенные валидаторы:
+- `"number"` - числовые значения
+- `"phone"` - российские номера телефонов (79xxxxxxxxx)
+- `"code"` - коды подтверждения (5-6 цифр)
+- `"file"` - файлы (с дополнительными опциями)
+
+### Кастомные валидаторы:
+```typescript
+// Синхронный валидатор
+validator: (value: string) => value.length > 5
+
+// Асинхронный валидатор
+validator: async (value: string) => {
+  const result = await apiCall(value);
+  return result.isValid;
+}
+```
+
+## Примеры использования
+
+### Базовый ввод с отменой
+```typescript
+async startRegistration() {
+  await this.message("Введите ваш номер телефона:")
+    .requestInput("phone", {
+      validator: "phone",
+      errorMessage: "Неверный формат. Используйте: 79000000000",
+      allowCancel: true,
+      cancelButtonText: "Отмена",
+      cancelAction: "home.index[cancel_wait=1]",
+      runSection: new RunSectionRoute().section("home").method("processPhone")
+    })
+    .send();
+}
+```
+
+### Обязательный ввод без отмены
+```typescript
+async requestPassword() {
+  return await this.message("Введите пароль:")
+    .requestInputWithAwait("password", {
+      errorMessage: "Пароль не может быть пустым",
+      allowCancel: false // отмена запрещена
+    });
+}
+```
+
+### Загрузка файлов с валидацией
+```typescript
+async uploadDocument() {
+  await this.message("Отправьте документ (PDF, до 5 МБ):")
+    .requestInput("document", {
+      validator: "file",
+      fileValidation: {
+        allowedTypes: ['application/pdf'],
+        maxSize: 5 * 1024 * 1024,
+        minSize: 1024
+      },
+      errorMessage: "Только PDF файлы до 5 МБ",
+      allowCancel: true,
+      runSection: new RunSectionRoute().section("home").method("processDocument")
+    })
+    .send();
+}
+```
+
+### Кастомная валидация с API
+```typescript
+async requestUsername() {
+  await this.message("Введите желаемое имя пользователя:")
+    .requestInput("username", {
+      validator: async (username: string) => {
+        // Проверяем доступность имени через API
+        const response = await fetch(`/api/check-username/${username}`);
+        const data = await response.json();
+        return data.available;
+      },
+      errorMessage: "Это имя уже занято. Попробуйте другое.",
+      allowCancel: true,
+      runSection: new RunSectionRoute().section("user").method("processUsername")
+    })
+    .send();
+}
+```
+
+## Обработка отмены
+
+Отмена обрабатывается автоматически через параметр `cancel_wait`:
+
+```typescript
+// В конструкторе Section автоматически вызывается:
+this.cancelUserWaitingReply();
+
+// Который проверяет параметр cancel_wait и очищает состояние ожидания
+```
+
+## Миграция с старой системы
+
+### Было:
+```typescript
+.requestInput("phone", {
+  validator: "phone",
+  errorMessage: "Неверный номер"
+})
+```
+
+### Стало:
+```typescript
+.requestInput("phone", {
+  validator: "phone", 
+  errorMessage: "Неверный номер",
+  allowCancel: true, // новый параметр
+  cancelButtonText: "Отмена", // настройка текста кнопки
+  cancelAction: "home.index[cancel_wait=1]" // действие при отмене
+})
+```
+
+Старый код будет работать с настройками по умолчанию (отмена разрешена).
+
+## Лучшие практики
+
+1. **Всегда предоставляйте возможность отмены** для необязательных действий
+2. **Используйте понятные сообщения об ошибках** с указанием формата
+3. **Ограничивайте размеры файлов** для предотвращения злоупотреблений
+4. **Используйте асинхронную валидацию** для проверок через API
+5. **Тестируйте различные сценарии** включая отмену и повторные попытки

package/templates/bot/docs/SERVICE_EXAMPLES.md

@@ -0,0 +1,384 @@
+# Примеры использования Service Generator
+
+## Тестовые сценарии
+
+### Сценарий 1: Создание простого сервиса
+
+```bash
+cd your-bot-directory
+2byte generate service Payment
+```
+
+**Ожидаемый результат:**
+- Создан файл `workflow/services/PaymentService.ts`
+- Выведено: `✅ Created service PaymentService at workflow/services/PaymentService.ts`
+
+### Сценарий 2: Создание с полным именем
+
+```bash
+2byte g service NotificationService
+```
+
+**Ожидаемый результат:**
+- Создан файл `workflow/services/NotificationService.ts`
+- Суффикс Service не дублируется
+
+### Сценарий 3: Попытка создать существующий сервис
+
+```bash
+2byte g service Payment  # Второй раз
+```
+
+**Ожидаемый результат:**
+- Ошибка: `❌ Service PaymentService already exists`
+- Файл не перезаписывается
+
+### Сценарий 4: Создание нескольких сервисов
+
+```bash
+2byte g service Cache
+2byte g service Logger  
+2byte g service EmailSender
+2byte g service DatabaseConnector
+```
+
+**Структура после создания:**
+```
+workflow/
+└── services/
+    ├── CacheService.ts
+    ├── LoggerService.ts
+    ├── EmailSenderService.ts
+    └── DatabaseConnectorService.ts
+```
+
+## Проверка работы созданного сервиса
+
+### 1. Создайте тестовый сервис
+
+```bash
+2byte g service Test
+```
+
+### 2. Измените сервис
+
+Откройте `workflow/services/TestService.ts` и добавьте логику:
+
+```typescript
+import { App } from "@2byte/tgbot-framework";
+import { ApiService } from "@2byte/tgbot-framework";
+
+export default class TestService extends ApiService {
+
+    constructor(
+        protected app: App,
+        public name: string = "TestService"
+    ) {
+        super(app, name);
+    }
+
+    public async setup(): Promise<void> {
+        this.app.debugLog(`[${this.name}] Setting up test service`);
+        return Promise.resolve();
+    }
+
+    public async unsetup(): Promise<void> {
+        this.app.debugLog(`[${this.name}] Cleaning up test service`);
+        return Promise.resolve();
+    }
+
+    public async run(): Promise<void> {
+        this.app.debugLog(`[${this.name}] Test service is running!`);
+        
+        // Тестовая задача каждые 10 секунд
+        setInterval(() => {
+            this.app.debugLog(`[${this.name}] Heartbeat - ${new Date().toISOString()}`);
+        }, 10000);
+        
+        return Promise.resolve();
+    }
+
+    // Кастомный метод для тестирования
+    public getStatus(): string {
+        return `TestService is active at ${new Date().toISOString()}`;
+    }
+}
+```
+
+### 3. Запустите бота
+
+```bash
+bun run index.ts
+```
+
+**Ожидаемые логи:**
+```
+[App] Registered API services: [ 'TestService', ... ]
+[TestService] Setting up test service
+[TestService] Service setup completed
+[TestService] Test service is running!
+[TestService] Heartbeat - 2025-10-29T...
+[TestService] Heartbeat - 2025-10-29T...
+```
+
+### 4. Используйте сервис в секции
+
+Создайте или откройте секцию:
+
+```typescript
+import { Section } from "@2byte/tgbot-framework";
+
+export default class HomeSection extends Section {
+    async index() {
+        // Получаем наш тестовый сервис
+        const testService = this.app.getService('TestService');
+        
+        if (testService) {
+            const status = testService.getStatus();
+            
+            await this.message(`🤖 Bot Status\n\n${status}`)
+                .send();
+        }
+    }
+}
+```
+
+## Интеграционные тесты
+
+### Test 1: Автозагрузка сервиса
+
+```bash
+# Создать сервис
+2byte g service AutoLoad
+
+# Запустить бота
+bun run index.ts
+
+# Проверить логи
+# Должно быть: [App] Registered API services: [ 'AutoLoadService', ... ]
+```
+
+### Test 2: Использование в секциях
+
+```typescript
+// В любой секции
+const service = this.app.getService('AutoLoadService');
+console.log('Service loaded:', service ? 'YES' : 'NO');
+```
+
+### Test 3: Жизненный цикл
+
+```bash
+# Запустить бота
+bun run index.ts
+# Лог: [ServiceName] Service setup completed
+
+# Остановить бота (Ctrl+C)
+# Лог: [ServiceName] Service cleanup completed
+```
+
+## Примеры реальных сервисов
+
+### Email Service
+
+```bash
+2byte g service Email
+```
+
+```typescript
+// workflow/services/EmailService.ts
+import { App, ApiService } from "@2byte/tgbot-framework";
+import nodemailer from 'nodemailer';
+
+export default class EmailService extends ApiService {
+    private transporter: any;
+
+    constructor(protected app: App, public name: string = "EmailService") {
+        super(app, name);
+    }
+
+    public async setup(): Promise<void> {
+        this.transporter = nodemailer.createTransport({
+            host: process.env.SMTP_HOST,
+            port: parseInt(process.env.SMTP_PORT || '587'),
+            auth: {
+                user: process.env.SMTP_USER,
+                pass: process.env.SMTP_PASS
+            }
+        });
+        
+        this.app.debugLog(`[${this.name}] Email service ready`);
+    }
+
+    public async sendEmail(to: string, subject: string, text: string) {
+        const info = await this.transporter.sendMail({
+            from: process.env.EMAIL_FROM,
+            to,
+            subject,
+            text
+        });
+        
+        this.app.debugLog(`[${this.name}] Email sent: ${info.messageId}`);
+        return info;
+    }
+}
+```
+
+### Database Service
+
+```bash
+2byte g service Database
+```
+
+```typescript
+// workflow/services/DatabaseService.ts
+import { App, ApiService } from "@2byte/tgbot-framework";
+import { Database } from 'sqlite3';
+
+export default class DatabaseService extends ApiService {
+    private db: Database | null = null;
+
+    constructor(protected app: App, public name: string = "DatabaseService") {
+        super(app, name);
+    }
+
+    public async setup(): Promise<void> {
+        return new Promise((resolve, reject) => {
+            this.db = new Database('./database.db', (err) => {
+                if (err) {
+                    this.app.debugLog(`[${this.name}] DB connection failed`, err);
+                    reject(err);
+                } else {
+                    this.app.debugLog(`[${this.name}] DB connected`);
+                    resolve();
+                }
+            });
+        });
+    }
+
+    public async unsetup(): Promise<void> {
+        return new Promise((resolve) => {
+            this.db?.close(() => {
+                this.app.debugLog(`[${this.name}] DB connection closed`);
+                resolve();
+            });
+        });
+    }
+
+    public async query(sql: string, params: any[] = []): Promise<any> {
+        return new Promise((resolve, reject) => {
+            this.db?.all(sql, params, (err, rows) => {
+                if (err) reject(err);
+                else resolve(rows);
+            });
+        });
+    }
+}
+```
+
+### Redis Cache Service
+
+```bash
+2byte g service RedisCache
+```
+
+```typescript
+// workflow/services/RedisCacheService.ts
+import { App, ApiService } from "@2byte/tgbot-framework";
+import Redis from 'ioredis';
+
+export default class RedisCacheService extends ApiService {
+    private redis: Redis | null = null;
+
+    constructor(protected app: App, public name: string = "RedisCacheService") {
+        super(app, name);
+    }
+
+    public async setup(): Promise<void> {
+        this.redis = new Redis({
+            host: process.env.REDIS_HOST || 'localhost',
+            port: parseInt(process.env.REDIS_PORT || '6379'),
+            password: process.env.REDIS_PASSWORD
+        });
+        
+        this.redis.on('connect', () => {
+            this.app.debugLog(`[${this.name}] Redis connected`);
+        });
+    }
+
+    public async unsetup(): Promise<void> {
+        await this.redis?.quit();
+        this.app.debugLog(`[${this.name}] Redis disconnected`);
+    }
+
+    public async get(key: string): Promise<string | null> {
+        return this.redis?.get(key) || null;
+    }
+
+    public async set(key: string, value: string, ttl?: number): Promise<void> {
+        if (ttl) {
+            await this.redis?.setex(key, ttl, value);
+        } else {
+            await this.redis?.set(key, value);
+        }
+    }
+
+    public async del(key: string): Promise<void> {
+        await this.redis?.del(key);
+    }
+}
+```
+
+## Troubleshooting Examples
+
+### Проблема: Сервис не создается
+
+```bash
+$ 2byte g service Test
+Error: EACCES: permission denied
+```
+
+**Решение:**
+```bash
+# Проверьте права доступа
+ls -la workflow/services/
+
+# Создайте директорию вручную если нужно
+mkdir -p workflow/services
+chmod 755 workflow/services
+```
+
+### Проблема: Сервис создан но не загружается
+
+**Проверка:**
+```bash
+# Запустите бота с debug
+DEBUG=* bun run index.ts
+
+# Проверьте структуру файла
+cat workflow/services/TestService.ts
+```
+
+**Типичные ошибки:**
+- Файл не экспортирует класс как default
+- Класс не наследуется от ApiService
+- Синтаксическая ошибка в коде
+
+## Performance Tests
+
+### Тест загрузки множества сервисов
+
+```bash
+# Создать 10 сервисов
+for i in {1..10}; do
+    2byte g service Service$i
+done
+
+# Запустить и проверить время загрузки
+time bun run index.ts
+```
+
+**Ожидаемый результат:**
+- Все 10 сервисов загружены
+- Время загрузки < 1 секунды
+- Нет ошибок в логах