431 lines
16 KiB
Markdown
431 lines
16 KiB
Markdown
# Shop Platform
|
|
|
|
Полнофункциональный интернет-магазин с RESTful API на Fastify и современным React фронтендом с темной темой в стиле Telegram.
|
|
|
|
## ✨ Возможности
|
|
|
|
### Для клиентов
|
|
- 🛍️ Каталог товаров с фильтрацией и поиском
|
|
- 🛒 Корзина покупок с сохранением состояния
|
|
- 📱 Полностью адаптивный дизайн (мобильная и десктопная версии)
|
|
- 🔍 Поиск товаров
|
|
- 📂 Категории товаров с древовидной структурой
|
|
- 📄 Детальные страницы товаров с изображениями
|
|
- ⭐ Система отзывов и рейтингов
|
|
- 📍 Управление адресами доставки
|
|
- 📦 История заказов
|
|
- 🎨 Темная тема в стиле Telegram
|
|
|
|
### Для администраторов
|
|
- 👥 Управление пользователями и ролями
|
|
- 🔐 Система прав доступа (RBAC)
|
|
- 📦 Управление заказами и статусами
|
|
- 🛍️ Управление товарами и категориями
|
|
- 📝 Модерация отзывов
|
|
- 📊 Админ-панель с интуитивным интерфейсом
|
|
|
|
### Для сотрудников
|
|
- 📦 Просмотр и редактирование всех заказов
|
|
- 🔄 Изменение статусов заказов
|
|
- 🛒 Управление корзиной
|
|
|
|
## 🚀 Технологии
|
|
|
|
### Backend
|
|
- **Fastify 4** - быстрый веб-фреймворк для Node.js
|
|
- **PostgreSQL** - реляционная база данных
|
|
- **Swagger/OpenAPI** - автоматическая документация API с валидацией
|
|
- **DAO Pattern** - паттерн доступа к данным
|
|
- **JWT** - аутентификация через JSON Web Tokens
|
|
- **MinIO** - объектное хранилище для файлов и изображений
|
|
- **YAML Config** - конфигурация через YAML файл
|
|
- **RBAC** - система ролей и прав доступа
|
|
|
|
### Frontend
|
|
- **React 18** - современная UI библиотека
|
|
- **Vite** - быстрый сборщик и dev-сервер
|
|
- **React Router** - клиентский роутинг
|
|
- **Axios** - HTTP клиент для API запросов
|
|
- **CSS Variables** - темная тема с переменными
|
|
|
|
## 📋 Требования
|
|
|
|
- Node.js >= 18.0.0
|
|
- PostgreSQL >= 12.0
|
|
- npm или yarn
|
|
- MinIO (опционально, для хранения файлов)
|
|
|
|
## 🛠️ Установка
|
|
|
|
### 1. Клонирование репозитория
|
|
|
|
```bash
|
|
git clone https://git.mylocaldomain.online/abakumov-a-a/store-platform.git
|
|
cd shop-platform
|
|
```
|
|
|
|
### 2. Установка зависимостей
|
|
|
|
**Backend:**
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
**Frontend:**
|
|
```bash
|
|
cd client
|
|
npm install
|
|
cd ..
|
|
```
|
|
|
|
### 3. Настройка базы данных
|
|
|
|
1. Создайте базу данных PostgreSQL:
|
|
```bash
|
|
createdb shop_platform
|
|
```
|
|
|
|
2. Выполните SQL скрипты в порядке:
|
|
```bash
|
|
psql -U postgres -d shop_platform -f sql/1_schema.sql
|
|
psql -U postgres -d shop_platform -f sql/2_seed_data.sql
|
|
psql -U postgres -d shop_platform -f sql/3_triggers.sql
|
|
psql -U postgres -d shop_platform -f sql/4_indexes.sql
|
|
psql -U postgres -d shop_platform -f sql/5_settings_init.sql
|
|
```
|
|
|
|
### 4. Настройка конфигурации
|
|
|
|
Отредактируйте `conf/config.yml` или установите переменные окружения:
|
|
|
|
```yaml
|
|
database:
|
|
host: ${POSTGRES_HOST:localhost}
|
|
port: ${POSTGRES_PORT:5432}
|
|
user: ${POSTGRES_USER:postgres}
|
|
password: ${POSTGRES_PASSWORD:password}
|
|
database: ${POSTGRES_DB:shop_platform}
|
|
|
|
web:
|
|
host: ${WEB_HOST:0.0.0.0}
|
|
http_port: ${WEB_HTTP_PORT:80}
|
|
https_port: ${WEB_HTTPS_PORT:443}
|
|
tsl: ${WEB_TSL:false}
|
|
|
|
minio:
|
|
endPoint: ${MINIO_ENDPOINT:localhost}
|
|
port: ${MINIO_PORT:9000}
|
|
useSSL: ${MINIO_USE_SSL:false}
|
|
accessKey: ${MINIO_ACCESS_KEY:minioadmin}
|
|
secretKey: ${MINIO_SECRET_KEY:minioadmin}
|
|
```
|
|
|
|
## ⚙️ Конфигурация
|
|
|
|
Конфигурация загружается из файла `conf/config.yml` с поддержкой переменных окружения.
|
|
|
|
### Основные секции конфигурации:
|
|
|
|
- **database** - настройки PostgreSQL
|
|
- **web** - настройки веб-сервера (порты, TLS)
|
|
- **minio** - настройки объектного хранилища (опционально)
|
|
- **keycloak** - настройки Keycloak (опционально)
|
|
|
|
### Переменные окружения:
|
|
|
|
Все значения можно переопределить через переменные окружения:
|
|
```bash
|
|
export POSTGRES_HOST=localhost
|
|
export POSTGRES_PORT=5432
|
|
export WEB_HTTP_PORT=3000
|
|
export MINIO_ENDPOINT=localhost
|
|
```
|
|
|
|
## 🏃 Запуск
|
|
|
|
### Backend
|
|
|
|
**Режим разработки:**
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
**Продакшн режим:**
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
Сервер будет доступен по адресу из конфигурации (по умолчанию `http://0.0.0.0:80`)
|
|
|
|
### Frontend
|
|
|
|
**Режим разработки:**
|
|
```bash
|
|
cd client
|
|
npm run dev
|
|
```
|
|
|
|
Фронтенд будет доступен по адресу `http://localhost:3000`
|
|
|
|
**Сборка для продакшена:**
|
|
```bash
|
|
cd client
|
|
npm run build
|
|
```
|
|
|
|
Собранные файлы будут в папке `client/dist/`
|
|
|
|
## 📚 API Документация
|
|
|
|
После запуска сервера Swagger документация доступна по адресу:
|
|
- **Swagger UI**: http://localhost:80/docs (или указанный порт)
|
|
- **Swagger JSON**: http://localhost:80/docs/json
|
|
|
|
Все эндпоинты имеют валидацию запросов и ответов через JSON Schema.
|
|
|
|
## 🔐 Система ролей и прав доступа
|
|
|
|
Проект использует систему ролей (RBAC) с гранулярными правами доступа:
|
|
|
|
### Роли:
|
|
- **customer** - клиент (базовые права)
|
|
- **employee** - сотрудник (просмотр и редактирование заказов)
|
|
- **manager** - менеджер (расширенные права управления)
|
|
- **owner** - владелец (почти все права)
|
|
- **admin** - администратор (полные права)
|
|
|
|
### Права доступа:
|
|
- `products.view`, `products.create`, `products.edit`, `products.delete`
|
|
- `orders.view`, `orders.create`, `orders.edit`, `orders.view_own`
|
|
- `categories.view`, `categories.create`, `categories.edit`, `categories.delete`
|
|
- `reviews.view`, `reviews.create`, `reviews.moderate`, `reviews.delete`
|
|
- `users.view`, `users.edit`, `users.delete`
|
|
- `cart.manage`
|
|
- `admin.all` - полные права администратора
|
|
|
|
Управление правами доступно в админ-панели через интерфейс редактирования ролей.
|
|
|
|
## 🔌 Основные API Endpoints
|
|
|
|
### Аутентификация (Auth)
|
|
- `POST /api/v1/auth/register` - Регистрация
|
|
- `POST /api/v1/auth/login` - Вход
|
|
- `POST /api/v1/auth/telegram` - Вход через Telegram
|
|
- `GET /api/v1/auth/me` - Получить текущего пользователя
|
|
- `POST /api/v1/auth/change-password` - Изменить пароль
|
|
|
|
### Товары (Products)
|
|
- `GET /api/v1/products` - Список товаров (с пагинацией и фильтрацией)
|
|
- `GET /api/v1/products/:id` - Детали товара
|
|
- `POST /api/v1/products` - Создать товар (требует прав)
|
|
- `PUT /api/v1/products/:id` - Обновить товар
|
|
- `DELETE /api/v1/products/:id` - Удалить товар
|
|
|
|
### Категории (Categories)
|
|
- `GET /api/v1/categories` - Список категорий
|
|
- `GET /api/v1/categories/tree` - Дерево категорий
|
|
- `GET /api/v1/categories/:id` - Детали категории
|
|
|
|
### Заказы (Orders)
|
|
- `GET /api/v1/orders` - Список заказов (с учетом роли)
|
|
- `GET /api/v1/orders/:id` - Детали заказа
|
|
- `POST /api/v1/orders` - Создать заказ
|
|
- `PUT /api/v1/orders/:id` - Обновить заказ
|
|
- `PUT /api/v1/orders/:id/status` - Изменить статус заказа
|
|
|
|
### Корзина (Cart)
|
|
- `GET /api/v1/cart` - Получить корзину
|
|
- `POST /api/v1/cart/items` - Добавить товар в корзину
|
|
- `PUT /api/v1/cart/items/:id` - Обновить количество
|
|
- `DELETE /api/v1/cart/items/:id` - Удалить товар из корзины
|
|
- `DELETE /api/v1/cart` - Очистить корзину
|
|
|
|
### Адреса (Addresses)
|
|
- `GET /api/v1/addresses` - Список адресов пользователя
|
|
- `POST /api/v1/addresses` - Добавить адрес
|
|
- `PUT /api/v1/addresses/:id` - Обновить адрес
|
|
- `DELETE /api/v1/addresses/:id` - Удалить адрес
|
|
- `PUT /api/v1/addresses/:id/set-default` - Установить адрес по умолчанию
|
|
|
|
### Отзывы (Reviews)
|
|
- `GET /api/v1/reviews` - Список отзывов
|
|
- `GET /api/v1/reviews/product/:productId` - Отзывы товара
|
|
- `POST /api/v1/reviews` - Создать отзыв
|
|
- `PUT /api/v1/reviews/:id` - Обновить отзыв
|
|
- `DELETE /api/v1/reviews/:id` - Удалить отзыв
|
|
|
|
### Админ-панель (Admin)
|
|
- `GET /api/v1/users` - Список пользователей
|
|
- `GET /api/v1/roles` - Список ролей
|
|
- `GET /api/v1/roles/:id/permissions` - Права роли
|
|
- `POST /api/v1/roles/:id/permissions` - Добавить право роли
|
|
- `DELETE /api/v1/roles/:id/permissions/:permissionId` - Удалить право роли
|
|
- `GET /api/v1/permissions` - Список всех прав доступа
|
|
|
|
## 📁 Структура проекта
|
|
|
|
```
|
|
shop-platform/
|
|
├── client/ # React фронтенд
|
|
│ ├── src/
|
|
│ │ ├── api/ # API клиенты
|
|
│ │ │ ├── admin/ # Админ API
|
|
│ │ │ └── client.js # Базовый клиент
|
|
│ │ ├── components/ # React компоненты
|
|
│ │ │ ├── admin/ # Админ компоненты
|
|
│ │ │ └── ... # Общие компоненты
|
|
│ │ ├── pages/ # Страницы приложения
|
|
│ │ │ ├── admin/ # Админ страницы
|
|
│ │ │ └── ... # Пользовательские страницы
|
|
│ │ ├── utils/ # Утилиты
|
|
│ │ └── App.jsx # Главный компонент
|
|
│ ├── package.json
|
|
│ └── vite.config.js
|
|
├── conf/
|
|
│ └── config.yml # Конфигурационный файл
|
|
├── src/
|
|
│ ├── dao/ # Data Access Objects
|
|
│ │ ├── BaseDAO.js # Базовый DAO
|
|
│ │ ├── UserDAO.js
|
|
│ │ ├── ProductDAO.js
|
|
│ │ ├── OrderDAO.js
|
|
│ │ ├── RoleDAO.js
|
|
│ │ ├── PermissionDAO.js
|
|
│ │ └── ...
|
|
│ ├── routes/ # API маршруты
|
|
│ │ └── v1/ # Версия API v1
|
|
│ │ ├── auth.js
|
|
│ │ ├── products.js
|
|
│ │ ├── orders.js
|
|
│ │ ├── roles.js
|
|
│ │ ├── permissions.js
|
|
│ │ └── ...
|
|
│ ├── plugins/ # Fastify плагины
|
|
│ │ ├── authenticate.js # JWT аутентификация
|
|
│ │ ├── authorize.js # Проверка прав доступа
|
|
│ │ ├── dao.js # DAO плагин
|
|
│ │ └── minio.js # MinIO плагин
|
|
│ └── utils/ # Утилиты
|
|
├── sql/ # SQL скрипты
|
|
│ ├── 1_schema.sql # Схема БД
|
|
│ ├── 2_seed_data.sql # Начальные данные
|
|
│ ├── 3_triggers.sql # Триггеры
|
|
│ ├── 4_indexes.sql # Индексы
|
|
│ └── 5_settings_init.sql # Настройки
|
|
├── tests/ # Тесты
|
|
├── app.js # Главный файл приложения
|
|
├── package.json
|
|
└── README.md
|
|
```
|
|
|
|
## 🎨 UI/UX Особенности
|
|
|
|
- **Темная тема** в стиле Telegram с использованием CSS переменных
|
|
- **Адаптивный дизайн** для мобильных и десктопных устройств
|
|
- **Плавающие панели** для корзины, заказов и настроек
|
|
- **Модальные окна** для редактирования данных
|
|
- **Toggle switches** вместо стандартных чекбоксов
|
|
- **Интуитивная навигация** с вынесенными кнопками в нижний правый угол
|
|
|
|
## 🔒 Безопасность
|
|
|
|
- JWT токены для аутентификации
|
|
- Хеширование паролей через bcrypt
|
|
- Проверка прав доступа на уровне API
|
|
- Валидация входных данных через JSON Schema
|
|
- CORS настройки для защиты от несанкционированных запросов
|
|
- Проверка владения ресурсами (пользователи могут редактировать только свои данные)
|
|
|
|
## 🧪 Тестирование
|
|
|
|
```bash
|
|
# Запуск всех тестов
|
|
npm test
|
|
|
|
# Запуск тестов в watch режиме
|
|
npm run test:watch
|
|
|
|
# Запуск только unit тестов
|
|
npm run test:unit
|
|
|
|
# Запуск integration тестов
|
|
npm run test:integration
|
|
```
|
|
|
|
## 📝 Разработка
|
|
|
|
### Добавление нового DAO
|
|
|
|
1. Создайте файл в `src/dao/`:
|
|
```javascript
|
|
import { BaseDAO } from './BaseDAO.js';
|
|
|
|
export class NewDAO extends BaseDAO {
|
|
constructor(pool) {
|
|
super(pool, 'table_name');
|
|
}
|
|
|
|
// Кастомные методы
|
|
async findCustom() {
|
|
const result = await this.pool.query('SELECT * FROM table_name');
|
|
return result.rows;
|
|
}
|
|
}
|
|
```
|
|
|
|
2. Зарегистрируйте в `src/plugins/dao.js`
|
|
|
|
### Добавление новых роутов
|
|
|
|
1. Создайте файл в `src/routes/v1/`:
|
|
```javascript
|
|
export default async function newRoutes(fastify, options) {
|
|
const { NewDAO } = fastify.dao;
|
|
|
|
fastify.get('/new', {
|
|
schema: {
|
|
tags: ['new'],
|
|
summary: 'Получить список',
|
|
security: [{ bearerAuth: [] }]
|
|
},
|
|
preHandler: [
|
|
fastify.authenticate,
|
|
fastify.checkPermission(['new.view'])
|
|
]
|
|
}, async (request, reply) => {
|
|
const data = await NewDAO.findAll();
|
|
return { success: true, data };
|
|
});
|
|
}
|
|
```
|
|
|
|
2. Файл автоматически загрузится через `@fastify/autoload`
|
|
|
|
## 🔧 Переменные окружения
|
|
|
|
Основные переменные окружения:
|
|
|
|
**База данных:**
|
|
- `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`
|
|
|
|
**Веб-сервер:**
|
|
- `WEB_HTTP_PORT`, `WEB_HTTPS_PORT`, `WEB_HOST`, `WEB_TSL`
|
|
|
|
**MinIO:**
|
|
- `MINIO_ENDPOINT`, `MINIO_PORT`, `MINIO_USE_SSL`, `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY`
|
|
|
|
**Keycloak (опционально):**
|
|
- `KEYCLOAK_HOST`, `KEYCLOAK_PORT`, `KEYCLOAK_REALM`, `KEYCLOAK_CLIENT_ID`, `KEYCLOAK_CLIENT_SECRET`
|
|
|
|
## 📄 Лицензия
|
|
|
|
ISC
|
|
|
|
## 👥 Авторы
|
|
|
|
Проект создан для интернет-магазина.
|
|
|
|
## 🔗 Репозиторий
|
|
|
|
Git репозиторий: https://git.mylocaldomain.online/abakumov-a-a/store-platform.git
|