164 lines
6.8 KiB
Markdown
164 lines
6.8 KiB
Markdown
# 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
|