docs: актуальное описание проекта AiForm
This commit is contained in:
AI Assistant
224
README.md
224
README.md
@@ -1,173 +1,163 @@
|
|||||||
# 🚀 Ticket Form Intake Platform
|
# AiForm — платформа приёма обращений о защите прав потребителя
|
||||||
|
|
||||||
**Платформа цифровой приёмки обращений для other.clientright.ru**
|
Веб-форма и Telegram Mini App для подачи обращений о защите прав потребителя. Интеграция с CRM (vTiger), n8n, SMS-верификация и авторизация через Telegram.
|
||||||
|
|
||||||
- **Backend**: Python FastAPI (async)
|
|
||||||
- **Frontend**: React 18 + TypeScript
|
|
||||||
- **Database**: PostgreSQL + MySQL + Redis
|
|
||||||
- **Queue**: RabbitMQ
|
|
||||||
- **Storage**: S3 Timeweb Cloud
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🎯 Быстрый старт
|
## Назначение
|
||||||
|
|
||||||
### 📍 **Визуальный доступ:**
|
- **Веб:** форма на https://aiform.clientright.ru — описание проблемы, загрузка документов, подтверждение заявления.
|
||||||
|
- **Telegram Mini App:** тот же функционал внутри бота (@klientprav_bot) с авторизацией по Telegram (без SMS при первом заходе).
|
||||||
После запуска доступны по адресам:
|
- Черновики, восстановление сессии, статусы заявок (черновик, в работе, готово).
|
||||||
|
|
||||||
```
|
|
||||||
Frontend (форма):
|
|
||||||
http://147.45.146.17:5175/
|
|
||||||
|
|
||||||
Backend API:
|
|
||||||
http://147.45.146.17:8200/
|
|
||||||
|
|
||||||
API Документация (Swagger UI):
|
|
||||||
http://147.45.146.17:8200/docs ← Интерактивная!
|
|
||||||
|
|
||||||
Gitea (Git репозиторий):
|
|
||||||
http://147.45.146.17:3002/
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🔧 Установка и запуск
|
## Стек
|
||||||
|
|
||||||
### **Backend (FastAPI):**
|
| Компонент | Технология |
|
||||||
|
|-----------|------------|
|
||||||
|
| **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
|
```bash
|
||||||
cd backend
|
cd backend
|
||||||
|
|
||||||
# Создаём виртуальное окружение
|
|
||||||
python3 -m venv venv
|
python3 -m venv venv
|
||||||
source venv/bin/activate
|
source venv/bin/activate # Windows: venv\Scripts\activate
|
||||||
|
|
||||||
# Устанавливаем зависимости
|
|
||||||
pip install -r requirements.txt
|
pip install -r requirements.txt
|
||||||
|
|
||||||
# Запускаем сервер
|
|
||||||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8200
|
uvicorn app.main:app --reload --host 0.0.0.0 --port 8200
|
||||||
```
|
```
|
||||||
|
|
||||||
### **Frontend (React):**
|
**Frontend:**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd frontend
|
cd frontend
|
||||||
|
|
||||||
# Устанавливаем зависимости
|
|
||||||
npm install
|
npm install
|
||||||
|
|
||||||
# Запускаем dev сервер
|
|
||||||
npm run dev -- --host 0.0.0.0 --port 5175
|
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 + пересборка)
|
||||||
React (5175) → FastAPI (8200) → [Redis, RabbitMQ, PostgreSQL]
|
./deploy-to-prod.sh
|
||||||
↓
|
|
||||||
OCR Service (8001)
|
|
||||||
OpenRouter AI
|
|
||||||
FlightAware API
|
|
||||||
↓
|
|
||||||
PHP Bridge → Vtiger CRM
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### **Что НЕ трогаем:**
|
- **Frontend (prod):** порт 5176 → внутри 3000
|
||||||
|
- **Backend (prod):** network_mode: host, порт 8200
|
||||||
|
|
||||||
✅ CRM Vtiger (работает как работала)
|
Подробнее: [DEPLOYMENT.md](DEPLOYMENT.md).
|
||||||
✅ MySQL полисы (только READ)
|
|
||||||
✅ Существующий PHP код
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🗄️ Базы данных
|
## Telegram Mini App
|
||||||
|
|
||||||
| База | Назначение | Хост |
|
- Открытие формы из бота → загрузка aiform.clientright.ru в WebView.
|
||||||
|------|------------|------|
|
- Фронт определяет контекст (URL/referrer/user-agent) и подгружает `telegram-web-app.js` только в Mini App.
|
||||||
| PostgreSQL | Логи, метрики, новые данные | 147.45.189.234:5432 |
|
- При наличии `initData` вызывается `POST /api/v1/tg/auth`; бэкенд проверяет подпись, дергает n8n, создаёт сессию в Redis и возвращает `session_token`, `unified_id`, `has_drafts`.
|
||||||
| MySQL | Проверка полисов (READ) | localhost:3306 |
|
- В Mini App: компактный скин, заявки «В работе» скрыты, кнопка «Выход» закрывает приложение. В вебе для заявок «В работе» — кнопка «Просмотреть в Telegram» (ссылка на @klientprav_bot).
|
||||||
| Redis | Кеш, Rate Limiting | localhost:6379 |
|
|
||||||
|
Подробнее: [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/
|
ticket_form/
|
||||||
├─ backend/ ← Python FastAPI
|
├── backend/ # FastAPI
|
||||||
│ ├─ app/
|
│ ├── app/
|
||||||
│ │ ├─ main.py
|
│ │ ├── main.py
|
||||||
│ │ ├─ api/
|
│ │ ├── config.py
|
||||||
│ │ ├─ services/
|
│ │ ├── api/ # Роутеры (claims, sms, session, telegram_auth, n8n_proxy, documents, …)
|
||||||
│ │ └─ models/
|
│ │ └── services/
|
||||||
│ └─ requirements.txt
|
│ ├── requirements.txt
|
||||||
│
|
│ └── Dockerfile
|
||||||
├─ frontend/ ← React TypeScript
|
├── frontend/ # React + Vite
|
||||||
│ ├─ src/
|
│ ├── src/
|
||||||
│ │ ├─ components/
|
│ │ ├── pages/ # ClaimForm.tsx — основная форма
|
||||||
│ │ ├─ pages/
|
│ │ ├── components/form/ # Step1Phone, StepDraftSelection, StepWizardPlan, …
|
||||||
│ │ └─ api/
|
│ │ └── ...
|
||||||
│ └─ package.json
|
│ ├── package.json
|
||||||
│
|
│ └── Dockerfile.prod
|
||||||
└─ .env ← Конфигурация
|
├── 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
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🔌 API Endpoints
|
## Окружения и конфиг
|
||||||
|
|
||||||
### **Документы:**
|
- **DEV:** форма на 5177, бэкенд на 8201 (см. docker-compose.dev.yml при наличии).
|
||||||
- `POST /api/v1/documents/upload` - Загрузка в S3
|
- **PROD:** https://aiform.clientright.ru (frontend за nginx, backend на 8200).
|
||||||
- `POST /api/v1/documents/scan` - OCR + Vision
|
|
||||||
|
|
||||||
### **Рейсы:**
|
Переменные окружения: [ENVIRONMENTS.md](ENVIRONMENTS.md). Критично: `TELEGRAM_BOT_TOKEN`, `N8N_TG_AUTH_WEBHOOK`, БД, Redis, S3.
|
||||||
- `GET /api/v1/flights/check` - Проверка статуса
|
|
||||||
|
|
||||||
### **Обращения:**
|
|
||||||
- `POST /api/v1/claims/submit` - Создание обращения
|
|
||||||
|
|
||||||
### **Полисы:**
|
|
||||||
- `GET /api/v1/policies/verify` - Проверка полиса
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🐛 Отладка
|
## Git
|
||||||
|
|
||||||
### **Логи:**
|
- **Репозиторий (prod):** http://147.45.146.17:3002/negodiy/aiform_prod.git
|
||||||
```bash
|
- Клонирование: `git clone http://147.45.146.17:3002/negodiy/aiform_prod.git`
|
||||||
# FastAPI
|
- После изменений: `git add . && git commit -m "feat: описание" && git push`
|
||||||
tail -f backend/logs/app.log
|
- Деплой на сервер: `./deploy-to-prod.sh` (при необходимости).
|
||||||
|
|
||||||
# PostgreSQL логи
|
|
||||||
SELECT * FROM logs ORDER BY created_at DESC LIMIT 50;
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📝 Git
|
## Документация
|
||||||
|
|
||||||
```bash
|
| Файл | Содержание |
|
||||||
# Репозиторий
|
|------|------------|
|
||||||
http://147.45.146.17:3002/negodiy/erv-platform
|
| [DEPLOYMENT.md](DEPLOYMENT.md) | Деплой, скрипты, .env |
|
||||||
|
| [ENVIRONMENTS.md](ENVIRONMENTS.md) | Переменные окружения |
|
||||||
# Клонирование
|
| [docs/TELEGRAM_MINIAPP_FLOW.md](docs/TELEGRAM_MINIAPP_FLOW.md) | Поток Telegram Mini App и tg/auth |
|
||||||
git clone http://147.45.146.17:3002/negodiy/erv-platform.git
|
|
||||||
|
|
||||||
# Push изменений
|
|
||||||
git add .
|
|
||||||
git commit -m "Your message"
|
|
||||||
git push origin main
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Автор**: AI Assistant + Фёдор
|
**Автор:** Фёдор + AI Assistant
|
||||||
**Дата**: 24.10.2025
|
**Обновлено:** январь 2026
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user