play-life/ENV_SETUP.md

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