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:

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:

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)

# Сборка и запуск
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.

---

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.

---

Основные 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. Критично: 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	Деплой, скрипты, .env
ENVIRONMENTS.md	Переменные окружения
docs/TELEGRAM_MINIAPP_FLOW.md	Поток Telegram Mini App и tg/auth

---

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