docs: актуальное описание проекта AiForm

2026-02-19 10:36:41 +03:00
parent 2e45786e46
commit a4cc4f9de6
1 changed files with 107 additions and 117 deletions
--- a/README.md
+++ b/README.md
@@ -1,173 +1,163 @@
-# 🚀 Ticket Form Intake Platform
+# AiForm — платформа приёма обращений о защите прав потребителя

-**Платформа цифровой приёмки обращений для other.clientright.ru**
-
- **Backend**: Python FastAPI (async)
- **Frontend**: React 18 + TypeScript
- **Database**: PostgreSQL + MySQL + Redis
- **Queue**: RabbitMQ
- **Storage**: S3 Timeweb Cloud
+Веб-форма и Telegram Mini App для подачи обращений о защите прав потребителя. Интеграция с CRM (vTiger), n8n, SMS-верификация и авторизация через Telegram.

 ---

-## 🎯 Быстрый старт
+## Назначение

-### 📍 **Визуальный доступ:**
-
-После запуска доступны по адресам:
-
-```
-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/
-```
+- **Веб:** форма на https://aiform.clientright.ru — описание проблемы, загрузка документов, подтверждение заявления.
+- **Telegram Mini App:** тот же функционал внутри бота (@klientprav_bot) с авторизацией по Telegram (без SMS при первом заходе).
+- Черновики, восстановление сессии, статусы заявок (черновик, в работе, готово).

 ---

-## 🔧 Установка и запуск
+## Стек

-### **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
 cd backend
-
-# Создаём виртуальное окружение
 python3 -m venv venv
-source venv/bin/activate
-
-# Устанавливаем зависимости
+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 (React):**
-
+**Frontend:**
 ```bash
 cd frontend
-
-# Устанавливаем зависимости
 npm install
-
-# Запускаем dev сервер
 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

-```
-React (5175) → FastAPI (8200) → [Redis, RabbitMQ, PostgreSQL]
-                              ↓
-                        OCR Service (8001)
-                        OpenRouter AI
-                        FlightAware API
-                              ↓
-                        PHP Bridge → Vtiger CRM
+# Или скрипт деплоя (git push + пересборка)
+./deploy-to-prod.sh
 ```

-### **Что НЕ трогаем:**
+- **Frontend (prod):** порт 5176 → внутри 3000  
+- **Backend (prod):** network_mode: host, порт 8200  

-✅ CRM Vtiger (работает как работала)  
-✅ MySQL полисы (только READ)  
-✅ Существующий PHP код  
+Подробнее: [DEPLOYMENT.md](DEPLOYMENT.md).

 ---

-## 🗄️ Базы данных
+## Telegram Mini App

-| База | Назначение | Хост |
-|------|------------|------|
-| PostgreSQL | Логи, метрики, новые данные | 147.45.189.234:5432 |
-| MySQL | Проверка полисов (READ) | localhost:3306 |
-| Redis | Кеш, Rate Limiting | localhost:6379 |
+- Открытие формы из бота → загрузка 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/        ← Python FastAPI
-│   ├─ app/
-│   │   ├─ main.py
-│   │   ├─ api/
-│   │   ├─ services/
-│   │   └─ models/
-│   └─ requirements.txt
-│
-├─ frontend/       ← React TypeScript
-│   ├─ src/
-│   │   ├─ components/
-│   │   ├─ pages/
-│   │   └─ api/
-│   └─ package.json
-│
-└─ .env           ← Конфигурация
+├── 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
 ```

 ---

-## 🔌 API Endpoints
+## Окружения и конфиг

-### **Документы:**
- `POST /api/v1/documents/upload` - Загрузка в S3
- `POST /api/v1/documents/scan` - OCR + Vision
+- **DEV:** форма на 5177, бэкенд на 8201 (см. docker-compose.dev.yml при наличии).
+- **PROD:** https://aiform.clientright.ru (frontend за nginx, backend на 8200).

-### **Рейсы:**
- `GET /api/v1/flights/check` - Проверка статуса
-
-### **Обращения:**
- `POST /api/v1/claims/submit` - Создание обращения
-
-### **Полисы:**
- `GET /api/v1/policies/verify` - Проверка полиса
+Переменные окружения: [ENVIRONMENTS.md](ENVIRONMENTS.md). Критично: `TELEGRAM_BOT_TOKEN`, `N8N_TG_AUTH_WEBHOOK`, БД, Redis, S3.

 ---

-## 🐛 Отладка
+## Git

-### **Логи:**
-```bash
-# FastAPI
-tail -f backend/logs/app.log
-
-# PostgreSQL логи
-SELECT * FROM logs ORDER BY created_at DESC LIMIT 50;
-```
+- **Репозиторий (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` (при необходимости).

 ---

-## 📝 Git
+## Документация

-```bash
-# Репозиторий
-http://147.45.146.17:3002/negodiy/erv-platform
-
-# Клонирование
-git clone http://147.45.146.17:3002/negodiy/erv-platform.git
-
-# Push изменений
-git add .
-git commit -m "Your message"
-git push origin main
-```
+| Файл | Содержание |
+|------|------------|
+| [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 + Фёдор  
-**Дата**: 24.10.2025
-
-
+**Автор:** Фёдор + AI Assistant  
+**Обновлено:** январь 2026