# Локальная разработка

## Требования

- Docker + Docker Compose
- Файл `.env` (из `.env.example`)
- Для Telegram: `data/telegram.session` + `TELEGRAM_API_ID` / `TELEGRAM_API_HASH`
- Опционально: `DEEPSEEK_API_KEY` для `extract_mode: llm` (воркеры) и Generate профиля на `ca-api`

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

```bash
cp .env.example .env
# заполнить TELEGRAM_* (и при необходимости DEEPSEEK_*)

mkdir -p data
# положить telegram.session в data/

docker compose up --build
```

UI: http://localhost:8080  
Health: `curl http://localhost:8080/api/health`

## Сервисы

| Сервис | Порт снаружи | Когда нужен |
|--------|--------------|-------------|
| `ca-frontend` | 8080 | всегда (UI) |
| `ca-api` | внутренний 8000 | всегда |
| `ca-db` / `redis` | — | всегда |
| `cp-workers` | — | Telegram |
| `cp-workers-web` | — | Crawl4AI |
| `cp-workers-nlp` | — | VIINA |
| `cp-vpn` | внутренний 1080 | SOCKS из subscription (вкладка VPN) |

Пересборка одного воркера:

```bash
docker compose up --build cp-workers-web
```

Проверка compose-файла:

```bash
docker compose config
```

## Telegram-сессия

- Путь в контейнере: `/data/telegram.session` (`TELEGRAM_SESSION_PATH`)
- Локально: `./data` монтируется в `cp-workers`
- Файл **не** коммитить (`.gitignore`)
- API id/hash в `.env` должны совпадать с теми, под которыми создавалась сессия

## VPN / прокси (вкладка VPN)

Основной путь: UI → **VPN** (`/vpn`).

1. Включите «Прокси включён».
2. Способ **Subscription URL** — вставьте ссылку подписки (не коммитьте её в git).
3. Отметьте источники (`telegram`, при необходимости `crawl4ai` / `viina`).
4. Сохраните. Сервис `cp-vpn` (mihomo) подтянет подписку и отдаст SOCKS на `cp-vpn:1080`; воркеры читают `/internal/vpn`.

Режимы **SOCKS5** / **HTTP** задают host:port напрямую (без `cp-vpn` для Telegram).

### Fallback: локальный Happ/xray (без вкладки VPN)

Если VPN в UI выключен, воркеры используют `TELEGRAM_PROXY_*` из `.env`:

1. Остановите Telegram-воркер, чтобы не делить session-файл:
   `docker compose stop cp-workers`
2. В `.env`: `TELEGRAM_PROXY_TYPE=socks5`, `TELEGRAM_PROXY_HOST=127.0.0.1`, `TELEGRAM_PROXY_PORT=10808` (Happ/xray).
3. Проброс SOCKS в Docker (xray слушает только `127.0.0.1:10808`):
   ```bash
   socat TCP-LISTEN:11080,bind=0.0.0.0,fork,reuseaddr TCP:127.0.0.1:10808 &
   ```
   Для auth из контейнера с host-сетью: `TELEGRAM_PROXY_HOST=127.0.0.1`.
4. Авторизация (интерактивно, код из Telegram):
   ```bash
   docker run --rm -it --network host \
     --env-file .env \
     -e TELEGRAM_SESSION_PATH=/data/telegram.session \
     -e TELEGRAM_PROXY_HOST=127.0.0.1 \
     -v "$PWD/data:/data" \
     -v "$PWD/scripts:/scripts:ro" \
     mapmil-cp-workers \
     python /scripts/telegram_auth.py
   ```
5. `docker compose up -d cp-workers`

Без сессии batch/listener Telegram не авторизуются; остальные адаптеры могут работать.

## Полезные curl

Создать telegram-парсер:

```bash
curl -X POST http://localhost:8080/admin/jobs \
  -H 'Content-Type: application/json' \
  -d '{"source_type":"telegram","source_config":{"channel":"example","limit":50}}'
```

Срез ПИ (подставьте ключ из seed / UI):

```bash
curl -H "Authorization: Bearer test-pi-api-key-change-me" \
  "http://localhost:8080/api/v1/events"
```

## Логи

```bash
docker compose logs -f ca-api
docker compose logs -f cp-workers
docker compose logs -f cp-workers-web
```

## Типичные проблемы

| Проблема | Действие |
|----------|----------|
| Frontend 000 / нет контейнеров | `docker compose up -d` (без `--build`, если registry недоступен, но образы уже есть) |
| Job не берётся | Смотреть `ENABLED_ADAPTERS` / `WORKER_FAMILIES` нужного сервиса |
| LLM не работает | `DEEPSEEK_API_KEY` в `.env`, перезапуск `cp-workers` / `cp-workers-web` |
| Generate профиля 503 | `DEEPSEEK_API_KEY` в `.env` + `env_file` у `ca-api`, перезапуск `ca-api` |
| Изменения UI не видны | Пересобрать `ca-frontend` |

## Границы при разработке

- Не добавлять прямой доступ к БД из CP workers.
- Не коммитить `.env`, `data/`, API-ключи.
- Изменение формы данных — через `contracts/` (см. [contracts.md](contracts.md)).