# Общая документация проекта: Туристический агрегатор "EasySite & YalArba"

**Версия:** 1.0 (Первичная)  
**Дата:** 4 декабря 2025 года  
**Статус:** Активная разработка  
**Контакт поддержки:** valitovgaziz@yandex.ru

---

## 🎯 Общее описание проекта

Проект представляет собой **полноценную туристическую экосистему**, состоящую из двух взаимосвязанных платформ:

1. **EasySite (easysite102.ru)** – B2B-платформа для владельцев туристических объектов (отели, санатории, рестораны, достопримечательности), позволяющая создавать, управлять и продвигать свои услуги в автоматическом режиме.

2. **YalArba (yalarba.ru)** – B2C-платформа для туристов, предоставляющая поиск, бронирование, планирование маршрутов и отзывы о местах отдыха.

Обе системы объединены общей бизнес-логикой, базой данных и API, что обеспечивает целостность данных и взаимодействие между поставщиками услуг и конечными пользователями.

---

## 🏗️ Архитектура системы

### Технологический стек:

| Компонент | Технологии |
|-----------|------------|
| **Frontend (EasySite)** | Nuxt.js 3, Vue 3, TypeScript, SSR |
| **Frontend (YalArba)** | Vue 3, Vue Router, Pinia, Vite |
| **Backend (API)** | Go (Golang), Chi Router, GORM |
| **База данных** | PostgreSQL (несколько инстансов) |
| **Веб-сервер** | Nginx с SSL (Let's Encrypt) |
| **Контейнеризация** | Docker, Docker Compose |
| **Мониторинг** | Встроенная аналитика, логгирование |

---

## 📦 Состав сервисов (Docker-контейнеры)

### Основные сервисы:

1. **easysite** – Nuxt.js приложение (easysite102.ru)
2. **yalarba** – Vue.js SPA приложение (yalarba.ru)
3. **api_tp** – REST API для YalArba (Go)
4. **api_yal** – REST API для EasySite (Go)
5. **api_bb** – REST API для "Бегущий Башкир" (Go)
6. **db, db_bb** – PostgreSQL базы данных
7. **nginx** – Веб-сервер с reverse proxy и SSL
8. **certbot** – Автоматическое обновление SSL-сертификатов
9. **analytics** – Сервис сбора статистики (Node.js)

---

## 🔄 Взаимодействие компонентов

```
Турист (yalarba.ru) → API_TP → БД (поиск, отзывы, маршруты)
Владелец (easysite102.ru) → api_yal → БД (добавление объектов, управление)
Администратор → Nginx + аналитика (мониторинг, логи)
```

---

## 🎯 Ключевые функции платформ

### EasySite (B2B):
- ✅ Автоматическое создание сайтов для объектов
- ✅ Управление услугами, ценами, описаниями
- ✅ Загрузка фото и медиаконтента
- ✅ Система модерации объектов
- ✅ Аналитика посещений и бронирований
- ✅ Личный кабинет владельца

### YalArba (B2C):
- ✅ Поиск мест отдыха с фильтрами
- ✅ Просмотр отзывов и рейтингов
- ✅ Личный профиль туриста
- ✅ Система избранного и истории
- ✅ Построение маршрутов
- ✅ Обратная связь и поддержка

---

## 🗄️ Базы данных

### Основные сущности:
- **Пользователи** (туристы, владельцы, администраторы)
- **Объекты** (отели, санатории, рестораны и др.)
- **Услуги** (предложения объектов)
- **Отзывы и рейтинги**
- **Бронирования** (в разработке)
- **Маршруты и избранное**

---

## 🔐 Безопасность

- JWT-аутентификация с refresh-токенами
- Ролевая модель доступа (user, moderator, admin)
- Защита от XSS, CSRF, SQL-инъекций
- Rate limiting на API
- HTTPS (Let's Encrypt)
- Логирование и мониторинг

---

## 🚀 Развертывание

### Требования:
- Docker & Docker Compose
- Node.js 18+ (для разработки)
- Go 1.21+ (для сборки API)
- PostgreSQL 15+

### Запуск в production:
```bash
docker-compose up -d
```

### Переменные окружения:
- `DATABASE_URL` – строка подключения к PostgreSQL
- `JWT_SECRET` – секретный ключ для токенов
- `SMTP_*` – настройки email-рассылок
- `TELEGRAM_BOT_TOKEN` – для уведомлений

---

## 📊 Мониторинг и аналитика

- Встроенный сбор статистики посещений
- Логирование запросов и ошибок
- Health-чекеры для всех сервисов
- Интеграция с внешними системами (Google Analytics, Sentry – в планах)

---

## 🗺️ Дорожная карта развития

### Ближайшие планы:
1. ✅ Базовая версия EasySite и YalArba
2. 🔄 Интеграция платежной системы
3. 🔄 Мобильное приложение (PWA)
4. 🔄 Система бронирования онлайн
5. 🔄 Мультиязычность (i18n)
6. 🔄 Расширенная аналитика для владельцев

---

## 🛠️ Поддержка и разработка

### Команда:
- **Разработчик:** Валитов Газиз (https://valitovgaziz.ru)
- **Техподдержка:** support@easysite102.ru
- **Telegram-бот:** для уведомлений и мониторинга

### Репозитории:
- Фронтенд EasySite: `./yalarba/easySite/`
- Фронтенд YalArba: `./yalarba/serv_spa/`
- API-сервисы: `./yalarba/api_*`, `./BB/api_bb`

---

## 📄 Связанная документация

- [Документация EasySite](./docs.md#easysite)
- [Документация API (YalArba)](./docs.md#api-tp)
- [Документация YalArba (SPA)](./docs.md#yalarba)
- [Docker Compose конфигурация](./docker-compose.yml)

---

## ✅ Статус проекта на 04.12.2025

| Компонент | Статус | Примечание |
|-----------|--------|------------|
| EasySite (Nuxt) | ✅ Рабочий прототип | Базовая функциональность |
| YalArba (Vue SPA) | ✅ Базовая структура | Требуется наполнение |
| API (Go) | ✅ Основные эндпоинты | Работа с пользователями |
| База данных | ✅ Настроена | Две инстанса PostgreSQL |
| SSL/Nginx | ✅ Работает | Автообновление сертификатов |
| Аналитика | ✅ Логирование | Базовый сбор статистики |
| Деплой | ✅ Docker Compose | Готово к production |

---

**Примечание:** Данная документация является первичной и будет дополняться по мере развития проекта. Все изменения в архитектуре и API должны быть задокументированы в соответствующих разделах.