aiform_prod/README.md

# AiForm — платформа приёма обращений о защите прав потребителя

Веб-форма и Telegram Mini App для подачи обращений о защите прав потребителя. Интеграция с CRM (vTiger), n8n, SMS-верификация и авторизация через Telegram.

---

## Назначение

- **Веб:** форма на https://aiform.clientright.ru — описание проблемы, загрузка документов, подтверждение заявления.
- **Telegram Mini App:** тот же функционал внутри бота (@klientprav_bot) с авторизацией по Telegram (без SMS при первом заходе).
- Черновики, восстановление сессии, статусы заявок (черновик, в работе, готово).

---

## Стек

| Компонент | Технология |
|-----------|------------|
| **Backend** | Python 3.11, FastAPI (async) |
| **Frontend** | React 18, TypeScript, Vite, Ant Design |
| **БД** | PostgreSQL, MySQL (полисы/CRM), Redis (сессии) |
| **Очереди** | RabbitMQ |
| **Хранилище** | S3 (Timeweb Cloud) |
| **Автоматизация** | n8n (воркфлоу, вебхуки) |
| **Интеграции** | Telegram Mini App SDK, SMS (сервис провайдера) |

---

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

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

**Backend:**
```bash
cd backend
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8200
```

**Frontend:**
```bash
cd frontend
npm install
npm run dev -- --host 0.0.0.0 --port 5175
```

Форма: http://localhost:5175  
API: http://localhost:8200  
Swagger: http://localhost:8200/docs  

### Продакшн (Docker)

```bash
# Сборка и запуск
docker-compose -f docker-compose.prod.yml up -d --build

# Или скрипт деплоя (git push + пересборка)
./deploy-to-prod.sh
```

- **Frontend (prod):** порт 5176 → внутри 3000  
- **Backend (prod):** network_mode: host, порт 8200  

Подробнее: [DEPLOYMENT.md](DEPLOYMENT.md).

---

## Telegram Mini App

- Открытие формы из бота → загрузка aiform.clientright.ru в WebView.
- Фронт определяет контекст (URL/referrer/user-agent) и подгружает `telegram-web-app.js` только в Mini App.
- При наличии `initData` вызывается `POST /api/v1/tg/auth`; бэкенд проверяет подпись, дергает n8n, создаёт сессию в Redis и возвращает `session_token`, `unified_id`, `has_drafts`.
- В Mini App: компактный скин, заявки «В работе» скрыты, кнопка «Выход» закрывает приложение. В вебе для заявок «В работе» — кнопка «Просмотреть в Telegram» (ссылка на @klientprav_bot).

Подробнее: [docs/TELEGRAM_MINIAPP_FLOW.md](docs/TELEGRAM_MINIAPP_FLOW.md).

---

## Основные API (v1)

| Метод | Путь | Назначение |
|-------|------|------------|
| POST | `/api/v1/tg/auth` | Авторизация по Telegram initData |
| POST | `/api/v1/session/verify` | Проверка сессии по session_token |
| POST | `/api/v1/session/logout` | Выход, удаление сессии из Redis |
| POST | `/api/v1/sms/send` | Отправка SMS-кода |
| POST | `/api/v1/sms/verify` | Проверка SMS-кода |
| GET | `/api/v1/claims/drafts/list` | Список черновиков (по unified_id / phone / session_id) |
| GET | `/api/v1/claims/drafts/{claim_id}` | Данные черновика |
| DELETE | `/api/v1/claims/drafts/{claim_id}` | Удаление черновика (не для in_work) |
| POST | `/api/v1/claims/wizard` | Получение плана (wizard) по описанию |
| POST | `/api/v1/claims/approve` | Подтверждение заявления (отправка в обработку) |
| POST | `/api/v1/documents/upload` | Загрузка документа |
| GET | `/api/v1/events/claim-plan/{session_token}` | SSE: данные заявления (claim:plan) |

Полный список — в Swagger: `/docs`.

---

## Структура проекта

```
ticket_form/
├── backend/                 # FastAPI
│   ├── app/
│   │   ├── main.py
│   │   ├── config.py
│   │   ├── api/              # Роутеры (claims, sms, session, telegram_auth, n8n_proxy, documents, …)
│   │   └── services/
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/                 # React + Vite
│   ├── src/
│   │   ├── pages/            # ClaimForm.tsx — основная форма
│   │   ├── components/form/ # Step1Phone, StepDraftSelection, StepWizardPlan, …
│   │   └── ...
│   ├── package.json
│   └── Dockerfile.prod
├── docker-compose.prod.yml
├── deploy-to-prod.sh
├── .env                      # Не в git: TELEGRAM_BOT_TOKEN, N8N_*, БД, Redis, S3
├── README.md                 # Этот файл
├── DEPLOYMENT.md             # Деплой DEV → PROD
├── ENVIRONMENTS.md           # Переменные окружения
└── docs/
    ├── TELEGRAM_MINIAPP_FLOW.md
    └── ...                   # Доп. документация по n8n, OCR, CRM
```

---

## Окружения и конфиг

- **DEV:** форма на 5177, бэкенд на 8201 (см. docker-compose.dev.yml при наличии).
- **PROD:** https://aiform.clientright.ru (frontend за nginx, backend на 8200).

Переменные окружения: [ENVIRONMENTS.md](ENVIRONMENTS.md). Критично: `TELEGRAM_BOT_TOKEN`, `N8N_TG_AUTH_WEBHOOK`, БД, Redis, S3.

---

## Git

- **Репозиторий (prod):** http://147.45.146.17:3002/negodiy/aiform_prod.git  
- Клонирование: `git clone http://147.45.146.17:3002/negodiy/aiform_prod.git`  
- После изменений: `git add . && git commit -m "feat: описание" && git push`  
- Деплой на сервер: `./deploy-to-prod.sh` (при необходимости).

---

## Документация

| Файл | Содержание |
|------|------------|
| [DEPLOYMENT.md](DEPLOYMENT.md) | Деплой, скрипты, .env |
| [ENVIRONMENTS.md](ENVIRONMENTS.md) | Переменные окружения |
| [docs/TELEGRAM_MINIAPP_FLOW.md](docs/TELEGRAM_MINIAPP_FLOW.md) | Поток Telegram Mini App и tg/auth |

---

**Автор:** Фёдор + AI Assistant  
**Обновлено:** январь 2026