new file: main_dc/yalarba/easySite/easySite/documentation/docs.md
add documentation for easysite102.ru nuxt.js fronend
This commit is contained in:
@@ -0,0 +1,428 @@
|
|||||||
|
# 📚 Документация проекта 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. Для более детальной информации по конкретным модулям обращайтесь к соответствующей секции документации.
|
||||||
Reference in New Issue
Block a user