From a4cc4f9de6f0be4b8f044de5068a4d5e54148292 Mon Sep 17 00:00:00 2001 From: AI Assistant Date: Thu, 19 Feb 2026 10:36:41 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B0=D0=BA=D1=82=D1=83=D0=B0=D0=BB?= =?UTF-8?q?=D1=8C=D0=BD=D0=BE=D0=B5=20=D0=BE=D0=BF=D0=B8=D1=81=D0=B0=D0=BD?= =?UTF-8?q?=D0=B8=D0=B5=20=D0=BF=D1=80=D0=BE=D0=B5=D0=BA=D1=82=D0=B0=20AiF?= =?UTF-8?q?orm?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 224 ++++++++++++++++++++++++++---------------------------- 1 file changed, 107 insertions(+), 117 deletions(-) diff --git a/README.md b/README.md index f8a9cff..ee52445 100644 --- 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