# 📚 Документация проекта EasySite

## 🏗️ Общая архитектура проекта

**EasySite** - это полноценная платформа для создания сайтов, построенная на Nuxt.js 3 с использованием server-side rendering и автоматической генерацией сайтов.

### Технологический стек:
- **Frontend**: Nuxt.js 3, Vue 3, TypeScript
- **Backend**: Nuxt Server (API Routes) (Golang, gorm, chi)
- **Стилизация**: Кастомные CSS-переменные, компонентный подход
- **SEO**: Автоматическая sitemap, мета-теги
- **Деплой**: Node.js сервер

---

## 📁 Структура приложения

### Маршрутизация (Routing)

#### Основные маршруты:

**Публичные страницы:**
- `/` - Главная страница с CTA и шагами создания сайта
- `/about` - Страница "О компании" с информацией о команде
- `/contact` - Контакты
- `/news` - Новости
- `/objects` - Каталог объектов/сайтов
- `/partner` - Партнерская программа
- `/requisites` - Реквизиты компании
- `/reviews` - Отзывы пользователей
- `/rules` - Правила использования
- `/support` - Поддержка
- `/vacations` - Возможности/предложения

**Страницы соглашений:**
- `/agreements/privacy` - Политика конфиденциальности
- `/agreements/userAgreement` - Пользовательское соглашение

**Аутентификация:**
- `/auth/login` - Вход в систему
- `/auth/register` - Регистрация

**Пользовательская зона:**
- `/profile` - Профиль пользователя
- `/profile/edit` - Редактирование профиля
- `/profile/settings` - Настройки аккаунта
- `/objects/create` - Создание нового объекта
- `/objects/my-objects` - Мои объекты/сайты
- `/reviews/write` - Написание отзыва
- `/support/create` - Создание обращения в поддержку

**Вспомогательные:**
- `/plugins/auth` - Плагин аутентификации

---

## 🎯 Бизнес-логика

### 1. Процесс создания сайта (3 шага)

#### Шаг 1: Регистрация (`/auth/register`)
```typescript
// Пример бизнес-логики регистрации
interface RegisterData {
  email: string;
  password: string;
  confirmPassword: string;
  // ... другие поля
}

// Валидация:
// 1. Проверка уникальности email
// 2. Сложность пароля
// 3. Согласие с пользовательским соглашением
// 4. Создание верификационного токена
```

#### Шаг 2: Добавление услуг (`/objects/create`)
```typescript
interface Service {
  id: string;
  title: string;
  description: string;
  category: string;
  price?: number;
  images: string[];
  features: string[];
  // ... другие поля
}

// Процесс:
// 1. Пользователь заполняет информацию об услугах
// 2. Загрузка изображений
// 3. Категоризация
// 4. Сохранение в базу данных
```

#### Шаг 3: Генерация сайта (`/objects/my-objects`)
```typescript
// Автоматическая генерация включает:
// 1. Создание уникального URL (поддомен или путь)
// 2. Генерация HTML-страниц на основе шаблонов
// 3. Наполнение контентом из профиля пользователя
// 4. SEO-оптимизация
// 5. Публикация на хостинге
```

---

## 🔐 Система аутентификации

### Файлы аутентификации:
```
server/
├── api/
│   ├── auth/
│   │   ├── login.post.ts     # POST /api/auth/login
│   │   ├── register.post.ts  # POST /api/auth/register
│   │   └── logout.post.ts    # POST /api/auth/logout
├── middleware/
│   ├── auth.ts              # Глобальный middleware
└── utils/
    └── auth.ts              # Утилиты аутентификации
```

### Flow аутентификации:
1. **Регистрация** → создание аккаунта + email верификация
2. **Вход** → JWT токен + refresh токен
3. **Защита роутов** → middleware проверка
4. **Выход** → инвалидация токенов

---

## 🗺️ Карта сайта (Sitemap)

### Конфигурация (`nuxt.config.ts`)
```typescript
sitemap: {
  siteUrl: 'https://easysite102.ru',
  sources: ['/api/__sitemap__/urls'],  // Динамические URL
  exclude: ['/admin/**', '/private/**'],
  defaults: {
    changefreq: 'daily',
    priority: 0.7,
    lastmod: new Date().toISOString()
  }
}
```

### Генерация динамических URL:
```typescript
// server/api/__sitemap__/urls.ts
export default defineEventHandler(async () => {
  const objects = await db.objects.findMany({
    where: { published: true }
  })
  
  return objects.map(object => ({
    loc: `/objects/${object.slug}`,
    lastmod: object.updatedAt,
    changefreq: 'weekly'
  }))
})
```

---

## 🎨 Компоненты и страницы

### Главная страница (`index.vue`)
**Особенности:**
- Hero-секция с gradient text
- 3-шаговый процесс создания сайта
- Адаптивный дизайн (mobile-first)
- SEO-оптимизация через `useSeoMeta()`

### Страница "О нас" (`about.vue`)
**Структура:**
1. Hero секция с изображением
2. Блок "Наш путь" (текст + статистика)
3. Команда (текущая + открытые позиции)
4. Ценности компании
5. CTA секция

**SEO настройки:**
```typescript
useSeoMeta({
  title: 'О компании - EasySite',
  description: 'Узнайте больше о нашей компании...',
  ogTitle: 'О компании - EasySite',
  ogDescription: 'Узнайте больше...',
})
```

---

## 🎯 Ключевые компоненты системы

### 1. Layout система (`layouts/default.vue`)
```vue
<template>
  <div class="app-layout">
    <AppHeader />
    <NuxtPage />
    <AppFooter />
  </div>
</template>
```

### 2. Навигация
- Главное меню для публичных страниц
- Боковое меню для авторизованных пользователей
- Breadcrumbs для сложных путей

### 3. Формы
- Регистрация/авторизация
- Создание объекта
- Редактирование профиля
- Написание отзывов
- Обращения в поддержку

---

## 🛠️ API Endpoints

### Публичные API:
```
GET    /api/objects            # Список объектов
GET    /api/objects/:id        # Детали объекта
GET    /api/reviews            # Отзывы
GET    /api/news               # Новости
```

### Защищенные API:
```
POST   /api/auth/login         # Вход
POST   /api/auth/register      # Регистрация
POST   /api/auth/logout        # Выход

GET    /api/profile            # Профиль
PUT    /api/profile            # Обновление профиля

POST   /api/objects            # Создание объекта
GET    /api/user/objects       # Мои объекты
PUT    /api/objects/:id        # Обновление объекта
DELETE /api/objects/:id        # Удаление объекта

POST   /api/reviews            # Создание отзыва
POST   /api/support/tickets    # Обращение в поддержку
```

---

## 🏗️ Структура базы данных (пример)

```sql
-- Пользователи
CREATE TABLE users (
  id UUID PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  name VARCHAR(100),
  avatar_url TEXT,
  verified BOOLEAN DEFAULT false,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP
);

-- Объекты/Сайты
CREATE TABLE objects (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  title VARCHAR(255) NOT NULL,
  slug VARCHAR(255) UNIQUE NOT NULL,
  description TEXT,
  template_id VARCHAR(50),
  status VARCHAR(50) DEFAULT 'draft',
  settings JSONB,
  published_at TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW()
);

-- Услуги
CREATE TABLE services (
  id UUID PRIMARY KEY,
  object_id UUID REFERENCES objects(id),
  title VARCHAR(255) NOT NULL,
  description TEXT,
  price DECIMAL(10,2),
  position INTEGER
);
```

---

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

### Переменные окружения:
```env
# База данных
DATABASE_URL=postgresql://...

# JWT
JWT_SECRET=your_jwt_secret_key
JWT_REFRESH_SECRET=your_refresh_secret_key

# Email
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your_email@gmail.com
SMTP_PASS=your_app_password

# Домены
BASE_URL=https://easysite102.ru
CLIENT_URL=https://easysite102.ru

# Telegram уведомления
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id
```

### Команды для запуска:
```bash
# Установка
npm install

# Разработка
npm run dev

# Сборка
npm run build

# Продакшен
npm run preview

# Деплой
npm run deploy
```

---

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

### Встроенные метрики:
1. **SEO метрики** - через sitemap и meta теги
2. **Производительность** - Lighthouse scores
3. **Аналитика** - Google Analytics/Tag Manager
4. **Ошибки** - Sentry/Bugsnag

### Кастомизация:
```typescript
// Плагин для аналитики
// plugins/analytics.ts
export default defineNuxtPlugin(() => {
  // Инициализация аналитики
  useGtag({
    config: { id: 'G-XXXXXXXXXX' }
  })
})
```

---

## 🛡️ Безопасность

### Реализованные меры:
1. **CSRF защита** - для всех POST запросов
2. **XSS защита** - санитизация пользовательского ввода
3. **SQL инъекции** - использование ORM с параметризованными запросами
4. **JWT токены** - с ограниченным временем жизни
5. **Rate limiting** - ограничение запросов
6. **CORS политики** - настройка доменов

---

## 🔧 Расширение функционала

### Планы развития:
1. **Шаблоны сайтов** - добавление новых дизайнов
2. **Мультиязычность** - i18n поддержка
3. **Платежная система** - подписки и платежи
4. **Аналитика сайтов** - статистика посещений
5. **Мобильное приложение** - через Capacitor/PWA

---

## 📋 Чеклист для нового разработчика

1. [ ] Установить Node.js 18+
2. [ ] Клонировать репозиторий
3. [ ] Установить зависимости `npm install`
4. [ ] Настроить `.env` файл
5. [ ] Запустить БД (PostgreSQL)
6. [ ] Выполнить миграции `npm run db:migrate`
7. [ ] Запустить dev сервер `npm run dev`
8. [ ] Проверить доступность по `localhost:3000`
9. [ ] Протестировать регистрацию пользователя
10. [ ] Проверить генерацию сайта

---

## 🆘 Поддержка и устранение неисправностей

### Частые проблемы:

1. **Sitemap не генерируется**
   - Проверить настройки в `nuxt.config.ts`
   - Убедиться что `siteUrl` правильный
   - Проверить доступность `/api/__sitemap__/urls`

2. **Аутентификация не работает**
   - Проверить JWT секреты
   - Убедиться в правильности middleware
   - Проверить cookies настройки

3. **Не загружаются изображения**
   - Проверить конфигурацию `@nuxt/image`
   - Убедиться в правильности путей
   - Проверить права доступа

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

---

Эта документация покрывает основные аспекты проекта EasySite. Для более детальной информации по конкретным модулям обращайтесь к соответствующей секции документации.