ospab.host/.github/copilot-instructions.md

Copilot Instructions for Ospabhost 8.1

Архитектура и основные компоненты

• Монорепозиторий: две части — backend (Express, TypeScript, Prisma) и frontend (React, Vite, TypeScript).
• Backend:
  • Точка входа: backend/src/index.ts (Express, маршруты /api/*, CORS, логирование, WebSocket).
  • Модули: backend/src/modules/* — домены (auth, admin, ticket, check, blog, notification, user, session, qr-auth, storage, payment, account, sitemap), каждый экспортирует маршруты и сервисы.
  • Интеграция с MinIO: для S3-совместимого хранилища, параметры из .env.
  • ORM: Prisma, схема — backend/prisma/schema.prisma, миграции и seed-скрипты — в backend/prisma/.
  • Статические файлы чеков: backend/uploads/checks (доступны по /uploads/checks).
• Frontend:
  • SPA на React + Vite, точка входа: frontend/src/main.tsx.
  • Страницы: frontend/src/pages/*, компоненты: frontend/src/components/*.
  • Авторизация: frontend/src/context/authcontext.tsx (контекст, хуки).
  • Дашборд: frontend/src/pages/dashboard/mainpage.tsx — реализует сайдбар, вкладки, загрузку данных пользователя, обработку токена, обновление данных через кастомное событие userDataUpdate.
  • Локализация: поддержка ru/en через useTranslation и LocaleProvider.

Ключевые паттерны и конвенции

• API: все маршруты backend — с префиксом /api/.
• Модули backend: каждый домен — отдельная папка, экспортирует маршруты и сервисы.
• Работа с MinIO: все операции S3 через MinIO SDK, параметры берутся из .env.
• Статусные поля: для Check, Ticket, Post, StorageBucket — строковые статусы (pending, approved, open, published, active и др.).
• Пароли: генерируются через generateSecurePassword (для консольных учётных данных S3).
• Описание тарифа: для StoragePlan — цена за GB, трафик, операции.
• Frontend: авторизация через контекст, проверка токена, автоматический logout при ошибке 401.
• Дашборд: вкладки и права оператора/админа определяются по полям operator и isAdmin в userData, обновление данных через событие userDataUpdate.
• Уведомления: email и push через web-push, шаблоны в notification/email.service.ts.
• QR-аутентификация: временные коды с TTL 60 сек, статусы pending, confirmed, expired.

Сборка, запуск и workflow

• Backend:
  • npm run dev — запуск с hot-reload (ts-node-dev).
  • npm run build — компиляция TypeScript.
  • npm start — запуск собранного кода.
  • PM2: npm run pm2:start, pm2:restart, etc. для production.
• Frontend:
  • npm run dev — запуск Vite dev server.
  • npm run build — сборка TypeScript + Vite.
  • npm run preview — предпросмотр production-сборки.
  • npm run lint — проверка ESLint.

Интеграции и взаимодействие

• Frontend ↔ Backend: через REST API (/api/*), авторизация через JWT-токен в localStorage, WebSocket для real-time обновлений.
• Backend ↔ MinIO: для S3 хранилища, параметры из .env.
• OAuth: поддержка Google, GitHub, VK, Yandex через Passport.js.
• Push-уведомления: через web-push API, подписки в PushSubscription.
• Prisma: миграции и seed-скрипты — в backend/prisma/.

Внешние зависимости

• Backend: express, prisma, axios, bcrypt, jsonwebtoken, multer, dotenv, minio, web-push, passport, ws.
• Frontend: react, react-dom, react-router-dom, tailwindcss, axios, quill, recharts, xterm.

Примеры ключевых файлов

• backend/src/index.ts — точка входа, маршрутизация, WebSocket.
• backend/src/modules/storage/storage.service.ts — интеграция с MinIO.
• backend/prisma/schema.prisma — схема данных (User, StorageBucket, Ticket, etc.).
• frontend/src/pages/dashboard/mainpage.tsx — дашборд, обработка токена, сайдбар, вкладки.
• frontend/src/context/authcontext.tsx — авторизация, JWT, logout.

Особенности и conventions

• CORS: разрешены origins из .env (PUBLIC_APP_ORIGIN, etc.).
• Логирование: каждый запрос логируется с датой и методом через logger.
• Статические файлы: чеки доступны по /uploads/checks.
• Пароли для S3 консоли: генерируются еженедельно, хэшируются.
• Frontend: сайдбар и вкладки строятся динамически, права по userData, локализация через useTranslation.
• Блог: Rich Text через Quill, статусы draft, published, archived.
• Тикеты: автоназначение операторам, внутренние комментарии.

---

Обновляйте этот файл при изменении архитектуры, workflow или паттернов. Для уточнения разделов — дайте обратную связь!