Этот проект объединяет:
- Backend на Node.js/Express (TypeScript) с PostgreSQL
- Frontend на Vite + Vue 3
- Серверные и клиентские скрипты для RAGE:MP (ресурс
freeroam)
Документация описывает установку, запуск, API и интеграцию игрового режима с веб-частью.
backend/src/index.ts— точка входа API-сервера (Express)src/db.ts— подключение к PostgreSQL (pg.Pool), утилита транзакцийsrc/routes/productsRoutes.ts— API «витрина» товаров и покупкиsrc/routes/wholesaleProductsRoutes.ts— API оптовых товаров и заказовswagger.js— конфигурация Swagger (OpenAPI) для/api-docspackage.json— скрипты и зависимости backend.env— переменные окружения (пример см. ниже)
frontend/vite-project/src/— Vue 3 приложение (SPA), dev-сервер Vite:http://localhost:5173package.json— скрипты фронтенда
packages/freeroam/index.js— серверные скрипты RAGE:MP (игровая логика)client_packages/— клиентские скрипты RAGE:MPfreeroam/authBrowser.js— CEF-браузер авторизации/регистрации (открывает UI с фронта)
conf.json— конфигурация сервера RAGE:MP (порты, ресурсы)docs/— вспомогательные диаграммы (Excalidraw)
- Node.js 18+ (рекомендуется LTS)
- PostgreSQL 13+ (локальный или доступный по сети)
- npm (или pnpm/yarn — при желании, команды адаптируйте)
- Для запуска сервера RAGE:MP — установленный сервер и корректная структура ресурсов
- Установите зависимости backend:
cd backend
npm i
- Установите зависимости frontend:
cd frontend/vite-project
npm i
Файл backend/.env (уже присутствует в репозитории) содержит пример значений:
DB_HOST=localhost
DB_PORT=5432
DB_NAME=mydb
DB_USER=admin
DB_PASSWORD=admin
DATABASE_URL=postgres://admin:admin@localhost:5432/mydb
# Необязательно:
# PORT=3000
Примечания:
- Сервер читает переменные
DB_HOST,DB_PORT,DB_NAME,DB_USER,DB_PASSWORD(см.backend/src/db.ts). PORTпо умолчанию 3000 (см.backend/src/index.ts).DATABASE_URLможно хранить для совместимости, но текущий код использует дискретные переменные.
- База данных: убедитесь, что PostgreSQL запущен и доступен с параметрами из
.env. - Backend (порт по умолчанию 3000):
cd backend
npm run dev # ts-node src/index.ts
# или
npm run build && npm start
- Frontend (Vite dev server на 5173):
cd frontend/vite-project
npm run dev
- Swagger UI: http://localhost:3000/api-docs
CORS настроен на http://localhost:5173 (см. backend/src/index.ts). При изменении порта фронтенда — обновите origin в CORS-мидлваре.
При старте backend выполняется поэтапная инициализация (см. backend/src/index.ts):
- Таблица
users— создаётся при отсутствии, добавляется тестовый пользовательtestuser / password(bcrypt). - Таблицы витрины:
products— ВАЖНО: в dev-режиме дропается и пересоздаётся, затем заполняется тестовыми товарами (см.initializeProductsDatabase()вproductsRoutes.ts).purchases— создаётся, если отсутствует.
- Таблицы опта (
wholesaleProductsRoutes.ts):wholesale_products,wholesale_orders,wholesale_order_items— создаются при отсутствии; базовый товар добавляется, если таблица пуста.
Предупреждение: логика дропа/транкейта в products подходит только для разработки. Для продакшена отключите авто-дроп.
Базовый префикс: /api
-
Аутентификация (
backend/src/index.ts):- POST
/api/login- Body:
{ username, password } - Ответ 200:
{ message, user: { id, username } }
- Body:
- POST
/api/register- Body:
{ username, password } - Ответ 201:
{ message, user }
- Body:
- POST
-
Товары (витрина) (
backend/src/routes/productsRoutes.ts):- GET
/api/products— список всех товаров - GET
/api/products/category/:category— фильтр по категории - POST
/api/purchase- Body:
{ productId, quantity?, userId? }—productIdможет быть числом илиtemp-... - Ответ 201:
{ message, purchaseId, product: { id, name, price, totalPrice } }
- Body:
- GET
/api/purchases/user/:userId— история покупок пользователя
- GET
-
Опт (
backend/src/routes/wholesaleProductsRoutes.ts):- GET
/api/wholesale/products— список оптовых товаров - POST
/api/wholesale/orders- Body:
{ items: [{ productId: number, quantity: number }, ...] } - Транзакционно проверяет остатки, создаёт заказ, позиции, уменьшает
stock
- Body:
- GET
-
Swagger: см. http://localhost:3000/api-docs (
backend/swagger.js).
Примеры запросов (curl):
# Регистрация
curl -X POST http://localhost:3000/api/register \
-H "Content-Type: application/json" \
-d '{"username":"testuser2","password":"secret123"}'
# Логин
curl -X POST http://localhost:3000/api/login \
-H "Content-Type: application/json" \
-d '{"username":"testuser","password":"password"}'
# Все товары
curl http://localhost:3000/api/products
# Покупка товара
curl -X POST http://localhost:3000/api/purchase \
-H "Content-Type: application/json" \
-d '{"productId":1,"quantity":2,"userId":1}'
# Оптовые товары
curl http://localhost:3000/api/wholesale/products
# Оптовый заказ
curl -X POST http://localhost:3000/api/wholesale/orders \
-H "Content-Type: application/json" \
-d '{"items":[{"productId":1,"quantity":3}]}'
- Конфиг сервера:
conf.jsonport: 22105 (игровой),http-port: 22106modules:["nodejs"]resources: включаетfreeroamи др.
- Серверный ресурс:
packages/freeroam/index.js- Система «мячей»: спавн/сбор объектов, статистика, команды (
/getpos,/spawnball,/testorder,/ballstats,/checkbalance,/resetballs,/debugballs,/showpositions) - Обработка «покупки» из веб-интерфейса — событие
processPurchaseсопоставляет заказ с количеством «мячей» для спавна
- Система «мячей»: спавн/сбор объектов, статистика, команды (
- Клиент:
client_packages/freeroam/authBrowser.js- Открывает CEF-браузер на
http://localhost:5173/register - Настраивает курсор/радар/чат при открытии/закрытии
- Открывает CEF-браузер на
Примечания по связке:
- Backend CORS разрешает
http://localhost:5173. Оставьте фронтенд на этом порту, либо поменяйте origin вbackend/src/index.ts. - Для работы CEF нужно, чтобы фронтенд dev-сервер был доступен по адресу из
authBrowser.js.
- Backend (
backend/package.json):npm run dev— запуск через ts-nodenpm run build— компиляция TypeScript вdist/npm start— запускdist/index.js
- Frontend (
frontend/vite-project/package.json):npm run dev— Vite dev server (5173)npm run build— сборка фронтендаnpm run preview— предпросмотр сборки
- Порт backend: переменная
PORTили 3000 по умолчанию. - Происхождение CORS:
backend/src/index.ts, полеoriginдляcors(). - Инициализация данных: отключите дроп/транкейты для prod (см.
initializeProductsDatabase). - Swagger: файл
backend/swagger.jsподключается напрямую, храните его в корнеbackend/.
- При старте выводятся шаги инициализации и статусы подключения к БД (см.
backend/src/index.ts). - Глобальный обработчик ошибок отправляет 500 и логирует стек.
- Используйте транзакции через
withTransaction()для связанных операций (см. wholesale-заказ).
Не указана.