valitovgaziz
2941b14b38
- Moved contents of main_dc/yalarba/easySite/easySite/ up to easySite/ - Updated docker-compose.yml build context path - Deleted empty nested easySite/ directory
428 lines
13 KiB
Markdown
428 lines
13 KiB
Markdown
# 📚 Документация проекта 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. Для более детальной информации по конкретным модулям обращайтесь к соответствующей секции документации. |