play-life/ENV_SETUP.md

Настройка единого .env файла

Все приложения проекта используют единый файл .env в корне проекта.

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

1. Скопируйте файл .env.example в .env:

   cp .env.example .env
   

2. Отредактируйте .env и укажите свои значения:

   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:

   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:

docker-compose up --build

Все сервисы автоматически загружают переменные из корневого .env файла.

Отдельные приложения

Если нужно запустить отдельные приложения, они также будут использовать корневой .env:

# Backend
cd play-life-backend
docker-compose up

# Frontend
cd play-life-web
docker-compose up

Приоритет переменных окружения

1. Переменные окружения системы (высший приоритет)
2. Локальный .env в директории приложения
3. Корневой .env файл
4. Значения по умолчанию в коде

Примеры использования

Изменение порта базы данных

# В .env
DB_PORT=5433

Изменение порта бэкенда

# В .env
PORT=9090

Изменение порта фронтенда

# В .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 в Telegram

2. Получите токен бота

3. Добавьте WEBHOOK_BASE_URL в .env:

   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

7. Запустите сервер - webhook будет настроен автоматически при старте!

   Для локальной разработки можно использовать ngrok или аналогичный сервис:

   # Установите ngrok: https://ngrok.com/
   ngrok http 8080
   # Используйте полученный URL в WEBHOOK_BASE_URL (без порта)
   # Например: WEBHOOK_BASE_URL=https://abc123.ngrok.io
   

8. Проверьте логи сервера - должно появиться сообщение:

   Telegram webhook configured successfully: https://abc123.ngrok.io/webhook/telegram
   

Ручная настройка (если не указан WEBHOOK_BASE_URL)

Если вы не указали WEBHOOK_BASE_URL, webhook нужно настроить вручную:

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 установлен:

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 (в отличие от других интеграций)