@2byte/tgbot-framework 1.0.6 → 1.0.8

package/templates/bot/docs/MASS_SEND_SERVICE.md

@@ -0,0 +1,327 @@
+# MassSendApiService - Массовая рассылка сообщений
+
+## Описание
+
+`MassSendApiService` - это встроенный API-сервис для массовой рассылки сообщений пользователям Telegram бота. Сервис предоставляет HTTP API для отправки сообщений всем пользователям или конкретной группе пользователей.
+
+## Возможности
+
+- ✅ Массовая рассылка всем пользователям бота
+- ✅ Целевая рассылка по списку Telegram ID
+- ✅ Поддержка дополнительных параметров Telegram (кнопки, форматирование)
+- ✅ HTTP API для интеграции с внешними системами
+- ✅ Автоматическая обработка ошибок отправки
+- ✅ Подробное логирование процесса рассылки
+
+## Установка и настройка
+
+### 1. Включение сервиса
+
+Сервис автоматически загружается при запуске бота. Убедитесь, что в файле `.env` указан порт для API:
+
+```env
+BOT_APP_API_PORT=3033
+```
+
+### 2. Настройка базы данных
+
+Сервис требует подключения к базе данных для получения списка пользователей. Убедитесь, что `UserModel` настроен корректно в вашем боте.
+
+## Использование
+
+### HTTP API Endpoint
+
+**URL:** `http://localhost:3033/`  
+**Метод:** `POST`  
+**Content-Type:** `application/json`
+
+### Структура запроса
+
+```typescript
+{
+  userIds?: number[];      // Массив Telegram ID пользователей (опционально)
+  message?: string;        // Текст сообщения
+  extra?: ExtraReplyMessage; // Дополнительные параметры Telegram
+}
+```
+
+### Примеры использования
+
+#### 1. Рассылка всем пользователям
+
+```bash
+curl -X POST http://localhost:3033/ \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "🎉 Важное объявление для всех пользователей!"
+  }'
+```
+
+```javascript
+fetch('http://localhost:3033/', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    message: '🎉 Важное объявление для всех пользователей!'
+  })
+});
+```
+
+#### 2. Рассылка конкретным пользователям
+
+```bash
+curl -X POST http://localhost:3033/ \
+  -H "Content-Type: application/json" \
+  -d '{
+    "userIds": [123456789, 987654321],
+    "message": "Персональное сообщение для вас!"
+  }'
+```
+
+```javascript
+fetch('http://localhost:3033/', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    userIds: [123456789, 987654321],
+    message: 'Персональное сообщение для вас!'
+  })
+});
+```
+
+#### 3. Рассылка с форматированием и кнопками
+
+```bash
+curl -X POST http://localhost:3033/ \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "*Жирный текст*\n_Курсив_\n`Код`",
+    "extra": {
+      "parse_mode": "Markdown",
+      "reply_markup": {
+        "inline_keyboard": [
+          [
+            { "text": "Кнопка 1", "callback_data": "action1" },
+            { "text": "Кнопка 2", "callback_data": "action2" }
+          ]
+        ]
+      }
+    }
+  }'
+```
+
+```javascript
+fetch('http://localhost:3033/', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    message: '*Жирный текст*\n_Курсив_\n`Код`',
+    extra: {
+      parse_mode: 'Markdown',
+      reply_markup: {
+        inline_keyboard: [
+          [
+            { text: 'Кнопка 1', callback_data: 'action1' },
+            { text: 'Кнопка 2', callback_data: 'action2' }
+          ]
+        ]
+      }
+    }
+  })
+});
+```
+
+#### 4. Использование из другого Node.js сервиса
+
+```typescript
+import axios from 'axios';
+
+async function sendMassMessage(message: string, userIds?: number[]) {
+  try {
+    const response = await axios.post('http://localhost:3033/', {
+      message,
+      userIds,
+      extra: {
+        parse_mode: 'HTML'
+      }
+    });
+    
+    console.log('Рассылка инициирована:', response.data);
+  } catch (error) {
+    console.error('Ошибка рассылки:', error);
+  }
+}
+
+// Рассылка всем
+await sendMassMessage('<b>Привет всем!</b>');
+
+// Рассылка конкретным пользователям
+await sendMassMessage('Персональное сообщение', [123456, 789012]);
+```
+
+## Параметры Extra (Telegram API)
+
+Параметр `extra` поддерживает все опции Telegram Bot API для отправки сообщений:
+
+```typescript
+{
+  parse_mode?: 'Markdown' | 'HTML' | 'MarkdownV2';
+  disable_web_page_preview?: boolean;
+  disable_notification?: boolean;
+  protect_content?: boolean;
+  reply_markup?: {
+    inline_keyboard?: Array<Array<{
+      text: string;
+      callback_data?: string;
+      url?: string;
+    }>>;
+    // ... другие типы клавиатур
+  };
+}
+```
+
+## Логирование
+
+Сервис подробно логирует процесс рассылки:
+
+```
+[MassSendApiService] Received data for mass message: {...}
+[MassSendApiService] Fetching all users for mass message...
+[MassSendApiService] Fetched users for mass message: [...]
+[MassSendApiService] Sending message to user ID: 123456 username: john_doe
+[MassSendApiService] Message sent to user ID: 123456 username: john_doe
+[MassSendApiService] Failed to send message to user ID: 789012 username: blocked_user
+```
+
+Для включения логов установите `DEBUG=true` в `.env` файле.
+
+## Обработка ошибок
+
+Сервис автоматически обрабатывает ошибки при отправке сообщений:
+
+- ❌ Пользователь заблокировал бота - сообщение пропускается, логируется ошибка
+- ❌ Невалидный Telegram ID - сообщение пропускается, логируется ошибка
+- ✅ Процесс рассылки продолжается даже при ошибках отдельных сообщений
+
+## Безопасность
+
+### Рекомендации:
+
+1. **Ограничьте доступ к API** - используйте firewall или reverse proxy
+2. **Добавьте аутентификацию** - расширьте сервис для проверки токенов
+3. **Rate limiting** - ограничьте частоту запросов
+4. **Используйте HTTPS** - в продакшене используйте SSL/TLS
+
+### Пример добавления аутентификации:
+
+```typescript
+// В MassSendApiService.ts
+public async run(): Promise<void> {
+    this.bunServerInstance = Bun.serve({
+        port: this.app.configApp.envConfig.BOT_APP_API_PORT || 3033,
+        routes: {
+            '/': async (req) => {
+                // Проверка токена
+                const authHeader = req.headers.get('Authorization');
+                const apiToken = this.app.configApp.envConfig.MASS_SEND_API_TOKEN;
+                
+                if (!authHeader || authHeader !== `Bearer ${apiToken}`) {
+                    return Response.json({ 
+                        status: 401, 
+                        error: 'Unauthorized' 
+                    }, { status: 401 });
+                }
+
+                // Остальная логика...
+            }
+        }
+    });
+}
+```
+
+Добавьте в `.env`:
+```env
+MASS_SEND_API_TOKEN=your_secret_token_here
+```
+
+## Интеграция с cron-задачами
+
+Используйте для регулярных рассылок:
+
+```bash
+# Ежедневная рассылка в 10:00
+0 10 * * * curl -X POST http://localhost:3033/ -H "Content-Type: application/json" -d '{"message":"Доброе утро!"}'
+```
+
+## Расширение функциональности
+
+### Добавление планировщика рассылок
+
+```typescript
+// workflow/services/ScheduledMassSendService.ts
+import MassSendApiService from './MassSendApiService';
+
+export default class ScheduledMassSendService extends MassSendApiService {
+    
+    public async run(): Promise<void> {
+        await super.run();
+        
+        // Ежедневная рассылка в 9:00
+        this.scheduleDaily('09:00', async () => {
+            await this.sendMassMessage(
+                [], 
+                '☀️ Доброе утро! Хорошего дня!',
+                { parse_mode: 'HTML' }
+            );
+        });
+    }
+    
+    private scheduleDaily(time: string, callback: () => void) {
+        // Реализация планировщика
+    }
+}
+```
+
+## Troubleshooting
+
+### Проблема: Сообщения не отправляются
+
+**Решение:**
+1. Проверьте подключение к базе данных
+2. Убедитесь, что в базе есть пользователи
+3. Проверьте, что бот имеет права отправлять сообщения
+4. Включите DEBUG режим для просмотра логов
+
+### Проблема: Порт уже занят
+
+**Решение:**
+1. Измените `BOT_APP_API_PORT` в `.env`
+2. Остановите другие процессы на порту 3033
+
+### Проблема: База данных не найдена
+
+**Решение:**
+Убедитесь, что переменная `db` доступна в контексте сервиса. Возможно, нужно импортировать и инициализировать подключение к БД.
+
+## API Response
+
+```json
+{
+  "status": 200,
+  "body": "Mass message sending initiated."
+}
+```
+
+Рассылка выполняется асинхронно, ответ приходит сразу после инициации процесса.
+
+## Производительность
+
+- Рассылка выполняется последовательно для избежания rate limits Telegram API
+- Рекомендуется не отправлять более 30 сообщений в секунду
+- Для больших объемов рассылки используйте очереди (например, BullMQ)
+
+## См. также
+
+- [Telegram Bot API Documentation](https://core.telegram.org/bots/api)
+- [API Services Guide](API_SERVICES.md)
+- [Service Examples](SERVICE_EXAMPLES.md)