Веб-форма и 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

Languages

TypeScript 57.4%

Python 37%

Shell 1.9%

CSS 1.6%

PLpgSQL 1%

Other 0.9%

README.md Unescape Escape

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