7398918bc0
All checks were successful
Build and Push Docker Image / build-and-push (push) Successful in 57s
- Add telegram_integrations table to store bot token and chat_id - Add Integrations tab with Todoist and Telegram integration screens - Remove TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID from env variables - All Telegram configuration now done through UI - Telegram webhook registration happens when user saves bot token - Rename TELEGRAM_WEBHOOK_BASE_URL to WEBHOOK_BASE_URL
299 lines
14 KiB
Markdown
299 lines
14 KiB
Markdown
# Настройка единого .env файла
|
||
|
||
Все приложения проекта используют единый файл `.env` в корне проекта.
|
||
|
||
## Быстрый старт
|
||
|
||
1. Скопируйте файл `.env.example` в `.env`:
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
2. Отредактируйте `.env` и укажите свои значения:
|
||
```bash
|
||
nano .env
|
||
# или
|
||
vim .env
|
||
```
|
||
|
||
3. **ВАЖНО**: Файл `.env` уже добавлен в `.gitignore` и не будет попадать в git.
|
||
|
||
## Структура переменных окружения
|
||
|
||
### Database Configuration
|
||
- `DB_HOST` - хост базы данных (по умолчанию: localhost)
|
||
- `DB_PORT` - порт базы данных (по умолчанию: 5432)
|
||
- `DB_USER` - пользователь БД (по умолчанию: playeng)
|
||
- `DB_PASSWORD` - пароль БД (по умолчанию: playeng)
|
||
- `DB_NAME` - имя БД (по умолчанию: playeng)
|
||
|
||
### Backend Server Configuration
|
||
- `PORT` - порт бэкенд сервера (по умолчанию: 8080)
|
||
- В production всегда используется порт 8080 внутри контейнера
|
||
- Nginx автоматически проксирует запросы к `http://backend:8080`
|
||
|
||
### Frontend Configuration (play-life-web)
|
||
- `VITE_PORT` - порт для dev-сервера Vite (по умолчанию: 3000)
|
||
- `WEB_PORT` - порт для production контейнера (по умолчанию: 3001)
|
||
|
||
**Примечание:** API запросы автоматически проксируются к бэкенду. В development режиме Vite проксирует запросы к `http://localhost:8080`. В production nginx проксирует запросы к бэкенд контейнеру. Не требуется настройка `VITE_API_BASE_URL`.
|
||
|
||
### Telegram Bot Configuration
|
||
- `WEBHOOK_BASE_URL` - базовый URL для автоматической настройки webhook. Webhook будет настроен автоматически при сохранении bot token через UI на `<WEBHOOK_BASE_URL>/webhook/telegram`.
|
||
- Bot Token и Chat ID настраиваются через UI приложения в разделе "Интеграции" -> "Telegram"
|
||
|
||
**Примеры значений:**
|
||
- Production с HTTPS: `https://your-domain.com` (порт не нужен для стандартных 80/443)
|
||
- Локальная разработка с ngrok: `https://abc123.ngrok.io` (порт не нужен)
|
||
- Прямой доступ на нестандартном порту: `http://your-server:8080` (порт обязателен)
|
||
|
||
### Todoist Webhook Configuration (опционально)
|
||
- `TODOIST_WEBHOOK_SECRET` - секрет для проверки подлинности webhook от Todoist (если задан, все запросы должны содержать заголовок `X-Todoist-Webhook-Secret` с этим значением)
|
||
|
||
## Настройка интеграции с Todoist
|
||
|
||
Интеграция с Todoist позволяет автоматически обрабатывать закрытые задачи и добавлять их в базу данных play-life.
|
||
|
||
### Как это работает
|
||
|
||
1. При закрытии задачи в Todoist отправляется webhook на ваш сервер
|
||
2. Сервер извлекает `title` (content) и `description` из закрытой задачи
|
||
3. Склеивает их в один текст: `title + "\n" + description`
|
||
4. Обрабатывает текст через существующую логику `processMessage`, которая:
|
||
- Парсит ноды в формате `**[Project][+/-][Score]**`
|
||
- Сохраняет данные в базу данных
|
||
- Отправляет уведомление в Telegram (если настроено)
|
||
|
||
### Настройка webhook в Todoist
|
||
|
||
1. Откройте настройки Todoist: https://todoist.com/app/settings/integrations
|
||
2. Перейдите в раздел "Webhooks" или "Integrations"
|
||
3. Создайте новый webhook:
|
||
- **URL**: `http://your-server:8080/webhook/todoist`
|
||
- Для локальной разработки: `http://localhost:8080/webhook/todoist`
|
||
- Для production: укажите публичный URL вашего сервера
|
||
- **Event**: выберите `item:completed` (закрытие задачи)
|
||
4. Сохраните webhook
|
||
|
||
### Безопасность (опционально)
|
||
|
||
Для защиты webhook от несанкционированного доступа:
|
||
|
||
1. Установите секрет в `.env`:
|
||
```bash
|
||
TODOIST_WEBHOOK_SECRET=your_secret_key_here
|
||
```
|
||
|
||
2. Настройте Todoist для отправки секрета в заголовке:
|
||
- В настройках webhook добавьте заголовок: `X-Todoist-Webhook-Secret: your_secret_key_here`
|
||
- Или используйте встроенные механизмы безопасности Todoist, если они доступны
|
||
|
||
**Примечание**: Если `TODOIST_WEBHOOK_SECRET` не задан, проверка секрета не выполняется.
|
||
|
||
### Формат задач в Todoist
|
||
|
||
Для корректной обработки задачи должны содержать ноды в формате:
|
||
```
|
||
**[ProjectName][+/-][Score]**
|
||
```
|
||
|
||
Примеры:
|
||
- `**[Work]+5.5**` - добавить 5.5 баллов к проекту "Work"
|
||
- `**[Health]-2.0**` - вычесть 2.0 баллов из проекта "Health"
|
||
|
||
Ноды можно размещать как в `title` (content), так и в `description` задачи. Они будут обработаны при закрытии задачи.
|
||
|
||
### Тестирование
|
||
|
||
Для тестирования интеграции:
|
||
|
||
1. Создайте задачу в Todoist с нодами, например:
|
||
- Title: `Test task`
|
||
- Description: `**[TestProject]+10.0**`
|
||
|
||
2. Закройте задачу в Todoist
|
||
|
||
3. Проверьте логи сервера - должно появиться сообщение:
|
||
```
|
||
Processing Todoist task: title='Test task', description='**[TestProject]+10.0**'
|
||
Successfully processed Todoist task, found 1 nodes
|
||
```
|
||
|
||
4. Проверьте базу данных или веб-интерфейс - данные должны быть добавлены
|
||
|
||
|
||
## Использование
|
||
|
||
### Локальная разработка
|
||
|
||
Все приложения автоматически читают переменные из корневого `.env` файла:
|
||
|
||
- **play-life-backend**: читает из `../.env` и `.env` (локальный имеет приоритет)
|
||
- **play-life-web**: читает из `../.env` и `.env` (локальный имеет приоритет)
|
||
|
||
### Docker Compose
|
||
|
||
Для запуска всех приложений в одном образе используйте корневой `docker-compose.yml`:
|
||
|
||
```bash
|
||
docker-compose up --build
|
||
```
|
||
|
||
Все сервисы автоматически загружают переменные из корневого `.env` файла.
|
||
|
||
### Отдельные приложения
|
||
|
||
Если нужно запустить отдельные приложения, они также будут использовать корневой `.env`:
|
||
|
||
```bash
|
||
# Backend
|
||
cd play-life-backend
|
||
docker-compose up
|
||
|
||
# Frontend
|
||
cd play-life-web
|
||
docker-compose up
|
||
```
|
||
|
||
## Приоритет переменных окружения
|
||
|
||
1. Переменные окружения системы (высший приоритет)
|
||
2. Локальный `.env` в директории приложения
|
||
3. Корневой `.env` файл
|
||
4. Значения по умолчанию в коде
|
||
|
||
## Примеры использования
|
||
|
||
### Изменение порта базы данных
|
||
|
||
```bash
|
||
# В .env
|
||
DB_PORT=5433
|
||
```
|
||
|
||
### Изменение порта бэкенда
|
||
|
||
```bash
|
||
# В .env
|
||
PORT=9090
|
||
```
|
||
|
||
### Изменение порта фронтенда
|
||
|
||
```bash
|
||
# В .env
|
||
VITE_PORT=4000 # для development
|
||
WEB_PORT=4001 # для production Docker контейнера
|
||
```
|
||
|
||
После изменения `.env` файла перезапустите соответствующие сервисы.
|
||
|
||
## Настройка интеграции с Telegram (webhook для сообщений пользователя)
|
||
|
||
Интеграция с Telegram позволяет автоматически обрабатывать сообщения, отправленные пользователем в чат бота, и добавлять их в базу данных play-life.
|
||
|
||
### Как это работает
|
||
|
||
1. Пользователь отправляет сообщение в чат с ботом в Telegram
|
||
2. Telegram отправляет webhook на ваш сервер с информацией о сообщении и entities (форматирование)
|
||
3. Сервер извлекает жирный текст из entities (type === 'bold')
|
||
4. Парсит жирный текст по формату `project+/-score` (без `**`)
|
||
5. Обрабатывает текст и сохраняет данные в базу данных
|
||
6. **НЕ отправляет сообщение обратно в Telegram** (в отличие от других интеграций)
|
||
|
||
### Отличия от других интеграций
|
||
|
||
- **Формат нод**: `project+/-score` (без `**`), например: `Work+5.5` или `Health-2.0`
|
||
- **Определение жирного текста**: через entities от Telegram, а не через markdown `**`
|
||
- **Без обратной отправки**: сообщение не отправляется обратно в Telegram
|
||
|
||
### Настройка webhook в Telegram
|
||
|
||
#### Автоматическая настройка (рекомендуется)
|
||
|
||
1. Создайте бота через [@BotFather](https://t.me/botfather) в Telegram
|
||
2. Получите токен бота
|
||
3. Добавьте `WEBHOOK_BASE_URL` в `.env`:
|
||
```bash
|
||
WEBHOOK_BASE_URL=https://your-domain.com
|
||
```
|
||
4. Откройте приложение и перейдите в раздел "Интеграции" -> "Telegram"
|
||
5. Введите Bot Token в поле и нажмите "Сохранить"
|
||
6. Отправьте первое сообщение боту в Telegram - Chat ID будет сохранён автоматически
|
||
|
||
**Важно о портах:**
|
||
- Если сервер доступен на стандартных портах (HTTP 80 или HTTPS 443), порт можно не указывать
|
||
- Если сервер работает на нестандартном порту и доступен напрямую, укажите порт: `http://your-server:8080`
|
||
- Если используется reverse proxy (nginx, etc.), указывайте внешний URL без порта: `https://your-domain.com`
|
||
|
||
3. Запустите сервер - webhook будет настроен автоматически при старте!
|
||
|
||
Для локальной разработки можно использовать ngrok или аналогичный сервис:
|
||
```bash
|
||
# Установите ngrok: https://ngrok.com/
|
||
ngrok http 8080
|
||
# Используйте полученный URL в WEBHOOK_BASE_URL (без порта)
|
||
# Например: WEBHOOK_BASE_URL=https://abc123.ngrok.io
|
||
```
|
||
|
||
4. Проверьте логи сервера - должно появиться сообщение:
|
||
```
|
||
Telegram webhook configured successfully: https://abc123.ngrok.io/webhook/telegram
|
||
```
|
||
|
||
#### Ручная настройка (если не указан WEBHOOK_BASE_URL)
|
||
|
||
Если вы не указали `WEBHOOK_BASE_URL`, webhook нужно настроить вручную:
|
||
|
||
```bash
|
||
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"url": "http://your-server:8080/webhook/telegram"
|
||
}'
|
||
```
|
||
|
||
Проверьте, что webhook установлен:
|
||
```bash
|
||
curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"
|
||
```
|
||
|
||
### Формат сообщений в Telegram
|
||
|
||
Для корректной обработки сообщения должны содержать жирный текст в формате:
|
||
```
|
||
project+/-score
|
||
```
|
||
|
||
Примеры:
|
||
- `Work+5.5` (жирным) - добавить 5.5 баллов к проекту "Work"
|
||
- `Health-2.0` (жирным) - вычесть 2.0 баллов из проекта "Health"
|
||
|
||
**Важно**: Текст должен быть выделен жирным шрифтом в Telegram (через форматирование сообщения, не через `**`).
|
||
|
||
### Тестирование
|
||
|
||
Для тестирования интеграции:
|
||
|
||
1. Откройте чат с вашим ботом в Telegram
|
||
2. Отправьте сообщение с жирным текстом в формате `project+/-score`, например:
|
||
- Напишите: `Test message`
|
||
- Выделите `Work+10.0` жирным шрифтом (через форматирование)
|
||
- Отправьте сообщение
|
||
|
||
3. Проверьте логи сервера - должно появиться сообщение:
|
||
```
|
||
Processing Telegram message: text='Test message', entities count=1
|
||
Successfully processed Telegram message, found 1 nodes
|
||
```
|
||
|
||
4. Проверьте базу данных или веб-интерфейс - данные должны быть добавлены
|
||
|
||
### Примечания
|
||
|
||
- Webhook должен быть доступен из интернета (для production используйте публичный URL)
|
||
- Для локальной разработки используйте ngrok или аналогичный сервис для туннелирования
|
||
- Сообщения обрабатываются только если содержат жирный текст в правильном формате
|
||
- Сообщения **не отправляются обратно** в Telegram (в отличие от других интеграций)
|
||
|