# 📓 ERV Platform — лог сессии и шпаргалка (14.11.2025)
Документ составлен, чтобы любой ИИ-ассистент мгновенно разобрался, как устроена цифровая приёмка заявок ERV, где искать настройки и как чинить основные сценарии.
---
## 1. Картина в целом
- **Фронтенд:** React + Ant Design (`erv_platform/frontend`). Собирается `docker-compose` сервисом `frontend`, крутится на `localhost:5173`, но в прода заходит через nginx. Главная страница — `src/pages/ClaimForm.tsx`, шаги формы разбиты на компоненты `src/components/form/Step*.tsx`.
- **Бэкенд:** FastAPI (`erv_platform/backend`). Поднимается на `:8100`, все публичные вызовы идут через `/api/v1/...`. Отвечает за:
- SMS-сервис и верификацию телефона (`app/services/sms_service.py`).
- Проксирование вызовов в n8n (`app/api/n8n_proxy.py`), чтобы фронт не видел прямые webhook URL.
- SSE для live-обновлений (AI Drawer / документооборот — отдельные роуты в `app/api/sse.py`).
- Хелперы для логов, Redis, RabbitMQ, file uploads.
- **n8n:** `https://n8n.clientright.pro` (прод) и `http://147.45.146.17:5678` (dev). Здесь собраны все длинные сценарии: поиск/создание контакта, проверка полиса, создание проекта, загрузка документов, вызовы PHP-операций CRM. FastAPI знает только их прокси-URL.
- **CRM:** vTiger `https://crm.clientright.ru`. Кастомные веб-сервисы лежат в `include/Webservices/*`. Главные операции:
-`CreateWebContact` — ищет/создаёт контакт.
-`CreateWebProject` — ищет/создаёт проект по номеру полиса + контакту.
-`CreateWebClaim` — создаёт заявку (HelpDesk) и теперь двусторонне линкует её с проектом (см. правки от 14.11).
- **Хранилища:** Redis (host `crm.clientright.ru:6379`, pass `CRM_Redis_Pass_2025_Secure!`) для сессий, SMS-кодов и claim-состояния. S3 (TWC Storage) + Nextcloud (`office.clientright.ru:8443`) для файлов. RabbitMQ (`185.197.75.249:5672`) для асинхронных задач.
---
## 2. Где живут секреты и настройки
- **`.env`** лежит в `erv_platform/.env` (в git не попадает). Туда уезжают все токены/пароли:
-`N8N_*_WEBHOOK` ссылки,
-`CRM_USERNAME/CRM_ACCESSKEY` для PHP скриптов,
- SMTP, SMS-шлюзы, S3 ключи.
- **docker-compose** (`erv_platform/docker-compose.yml`) подсовывает в контейнеры только безопасные значения (Redis, RabbitMQ, н8n webhooks). Всё остальное backend читает из `.env` через `pydantic`-настройки (`backend/app/config.py`).
- **SSH** — доп.профиль нужно заносить в `~/.ssh/config` (правило от Фёдора). Для CI/CD используем отдельный ключ `cursor-server`.
- **Cron/Cache:** папка `/var/www/fastuser/data/www/crm.clientright.ru/cache` запрет на любые изменения (хранит данные крона CRM).
---
## 3. Пользовательский сценарий ERV (по шагам)
### Шаг 1. Верификация телефона
1.`Step1Phone.tsx` берёт 10 цифр, добавляет префикс `+7` только визуально, в API уходит `7XXXXXXXXXX`.
2.`/api/v1/sms/send` → `sms_service.py` сохраняет код в Redis по ключу `sms:code:{phone}` (rate-limit временно отключён).
3.`/api/v1/sms/verify` при успехе вызывает `/api/n8n/contact/create`, куда передаётся `phone` + `session_id`.
4. n8n вызывает CRM `CreateWebContact`. Либо возвращает существующий `contact_id`, либо создаёт новый и выставляет `is_new_contact=true`.
5. n8n также генерирует `claim_id` (UUID вида `CLM-2025-11-14-XXXX`) и начинает сессию в Redis `claim:{claim_id}`с TTL 48ч.
### Шаг 2. Полис
1.`Step2Policy.tsx` шлёт полис на `/api/n8n/policy/check`.
2. n8n проверяет валидность номера, ищет проект через `CreateWebProject`. Если проекта нет, создаёт в CRM:
3. Ответ сохраняет `project_id`, `is_new_project`, срок действия полиса, pdf-выписку и т.д., всё докладывается в Redis-сессию.
### Шаги 3-4. Тип события, документы, выплаты
1.В`ClaimForm.tsx` собраны все поля формы. Состояние хранится в `useState` и синхронизируется с Redis через вызовы n8n (при каждом шаге есть endpoint вида `/api/v1/claim/save-field`, который кладёт патчи в Redis).
2. Загрузка документов идёт через `/api/n8n/upload/file` (multipart). Backend пересылает файл в n8n, там:
- Файл кладётся в S3 `s3.twcstorage.ru/erv/{claim_id}/...`.
-В Redis фиксируется метаданные, генерится SSE-ивент про статус OCR/AI.
3. Платёжные реквизиты, email и прочие финальные данные отправляются так же через n8n, чтобы единообразно писать в Redis.
### Финал. Создание заявки
1.`/api/n8n/claim/create` собирает весь контекст из Redis, вызывает CRM `CreateWebClaim`.
2.`CreateWebClaim.php`:
- нормализует ID (поддержка форматов `12x123`/`123`),
- создаёт HelpDesk запись с`ticketstatus = рассмотрение`,
- проставляет поле `cf_2066 = 33x{project_id}` (связь на проект),
-с 14.11 добавляет запись в `vtiger_crmentityrel` (двусторонняя связь Project ↔ HelpDesk),
- логирует в `logs/CreateWebClaim.log`.
3. Ответ возвращает `ticket_id`, `ticket_number`, статусы. n8n завершает сессию, двигает файлы в Nextcloud (папка проекта + claim-id подпапка) и создаёт ZIP для страховой через `CopyToS3`.
---
## 4. Логи и отладка
- **FastAPI**: `docker-compose logs backend -f`. Внутри контейнера — `/app/logs/*.log`.
5.**claim_id на фронте** — приходит из n8n, хранится в состоянии и Redis, при сбросе форма очищает поле.
6.**Документы** — upload не падает, даже если n8n ответил пустотой; backend возвращает заглушку `{success:true}`.
---
## 6. Как разворачивать / тестировать
```bash
cd /var/www/fastuser/data/www/crm.clientright.ru/erv_platform
cp .env.example .env # если впервые
docker-compose up -d --build
# Логи
docker-compose logs -f backend
# Прогнать e2e happy flow:
# 1) открыть http://localhost:5173
# 2) пройти шаги с DEV кодом (кнопка в Step1Phone.tsx)
# 3) загрузить фейковый pdf (tmp/test.pdf)
# 4) убедиться, что в CRM появился контакт/проект/заявка
```
Unit-тестов почти нет, поэтому проверяем сценарии вручную через UI + смотрим n8n executions.
---
## 7. Частые вопросы / рецепты
- **Где поменять тайм-ауты n8n?** В каждом HTTP Request node (раздел Options → Timeout). Для CreateWebProject выставляем ≥ 60 сек.
- **Как отключить/включить SMS rate limit?** В`sms_service.py` вокруг `sms_rate:{phone}` есть блок, сейчас закомментирован.
- **Как сменить webhook URL?** Поправить `.env`, затем `docker-compose restart backend`. Файлы: `backend/app/config.py` и `backend/app/api/n8n_proxy.py`.
- **Как добавить новое поле в заявку?**
1. Добавить state в `ClaimForm.tsx`.
2. Пробросить пропсы в нужный `Step*`.
3.На backend — endpoint `claim/save-field`.
4.В n8n — расширить Redis JSON / CRM payload.
- **Куда падут загруженные файлы?** Сначала `s3.twcstorage.ru/erv/{claim}`, после подтверждения — Nextcloud (`Папка в Nextcloud` кнопка в карточке проекта).
| CRM Contact | `include/Webservices/CreateWebContact.php` | Не создаёт дубликаты |
| CRM Project | `include/Webservices/CreateWebProject.php` | Поиск проекта по полису |
| CRM Claim | `include/Webservices/CreateWebClaim.php` | Создание заявки + связь |
| Описания AI | `crm_extensions/AI_DRAWER_*` | Документация по SSE/AI |
---
## 9. Что ещё улучшить (бэклог)
- Вернуть и настроить адекватный rate-limit SMS (фича готова, достаточно раскомментировать и подобрать окна).
- Причесать docker-compose: убрать локальные `redis/postgres` сервисы, раз мы ходим наружу.
- Добавить автотесты для Redis claim session (pytest + fakeredis).
-В n8n вынести повторяющиеся фрагменты (Redis fetch/patch) в sub-workflows.
---
Документ обновлён 14.11.2025, автор: GPT-5.1 Codex (по просьбе Фёдора). Если что-то меняется — дополняй файл, чтобы у будущих ассистентов была единая точка правды.
---
## 10. Ticket Form Intake (other.clientright.ru → новая платформа)
1.**Развёрнули отдельный стек `ticket_form`:**
- Скопировали структуру `erv_platform`, переименовали сервисы в `ticket_form_frontend`/`ticket_form_backend`.
- Порты: фронт `5175`, бек `8200`. `docker-compose.yml` читает переменные `TICKET_FORM_*`, backend берёт `.env` из корня `ticket_form`.
- Backend конфиг (`app/config.py`) получил новые значения `app_name`, `redis_prefix=ticket_form:`, актуальные `backend_url/frontend_url`.
2.**Frontend:**
- Vite proxy теперь стучится на `host.docker.internal:8200`.
- Добавлен шаг `StepDescription` между телефоном и полисом — пользователь оставляет свободное описание кейса.
-Все`fetch` привязаны к относительным путям `/api/...`, чтобы прокси корректно отрабатывал и у фронта, и у прода.
-В`Step3Payment` debug-код SMS сохраняется в стейте и отображается отдельным блоком с кнопкой “Скопировать”, исчезает только после успешной проверки.
3.**Backend:**
- Новый endpoint `POST /api/v1/claims/description` принимает `session_id` + текст проблемы и публикует событие в Redis канал `ticket_form:description`. n8n слушает его и запускает AI-агента.
- Добавлено логирование всех операций публикации (см. `backend/app/api/claims.py`).
- Dockerfile backend и скрипты запуска переведены на порт 8200.
4.**Интеграции / инфраструктура:**
- Контейнеры пересобраны (`docker compose up -d --build`). Redis внутри compose отключился (порт занят боевым), но не нужен — ходим во внешний.
- n8n воркфлоу уже ловит новые события и может отправлять рекомендации (план: ИИ формирует список документов → сохраняем в Redis → фронт подхватывает перед шагом загрузок).
5.**Что дальше (ticket_form):**
- Договориться о формате ответа AI агента (JSON с`required_documents`, `summary`, `extra_questions`).
-На фронте научиться подтягивать рекомендации из Redis и строить динамические шаги загрузок.
- Определить конечный набор endpoint’ов н8н для загрузки файлов/финала (аналог ERV, но под ticket_form сценарий).
