From 753696cc93993dddbd0c323c438d7f1b2ece1f20 Mon Sep 17 00:00:00 2001 From: Georgiy Syralev Date: Wed, 26 Nov 2025 21:43:57 +0300 Subject: [PATCH] update README --- ospabhost/CONTRIBUTIONS.md | 972 +++------- ospabhost/README.md | 1139 +---------- ospabhost/backend/package.json | 2 + .../prisma/add_custom_storage_plan.sql | 18 + .../20250115_add_rate_limiting/migration.sql | 2 + .../20250427_add_panel_vps_id/migration.sql | 6 - .../migration.sql | 18 + .../migration.sql | 4 + .../migration.sql | 13 + .../migration.sql | 22 + ospabhost/backend/prisma/schema.prisma | 103 +- .../backend/prisma/storage_plans_seed.sql | 24 + ospabhost/backend/src/index.ts | 65 +- .../src/modules/admin/admin.controller.ts | 163 +- .../backend/src/modules/admin/admin.routes.ts | 9 +- .../src/modules/auth/auth.controller.ts | 13 +- .../src/modules/auth/passport.config.ts | 6 +- .../src/modules/notification/email.service.ts | 72 +- .../notification/notification.controller.ts | 194 +- .../notification/notification.routes.ts | 6 +- .../src/modules/storage/fileScanner.ts | 273 +++ .../src/modules/storage/storage.routes.ts | 236 ++- .../src/modules/storage/storage.service.ts | 945 ++++++++- .../src/modules/ticket/ticket.controller.ts | 649 +++++-- .../backend/src/types/passport-vkontakte.d.ts | 39 +- ospabhost/backend/src/websocket/server.ts | 2 +- ospabhost/frontend/package-lock.json | 18 + ospabhost/frontend/package.json | 1 + ospabhost/frontend/public/github.png | Bin 0 -> 2822 bytes ospabhost/frontend/public/google.png | Bin 0 -> 8182 bytes ospabhost/frontend/public/yandex.png | Bin 0 -> 3368 bytes .../src/components/AdminPricingTab.tsx | 325 ++++ .../src/components/AdminTestingTab.tsx | 170 ++ ospabhost/frontend/src/components/QRLogin.tsx | 4 +- .../frontend/src/components/VKOneTap.tsx | 3 + ospabhost/frontend/src/config/api.ts | 50 +- .../frontend/src/context/WebSocketContext.tsx | 31 +- .../frontend/src/context/authcontext.tsx | 16 +- ospabhost/frontend/src/hooks/useSocket.ts | 107 +- .../frontend/src/pages/dashboard/admin.tsx | 1595 ++++++++++----- .../frontend/src/pages/dashboard/checkout.tsx | 602 ++++-- .../frontend/src/pages/dashboard/mainpage.tsx | 11 +- .../src/pages/dashboard/storage-bucket.tsx | 1720 +++++++++++++++++ .../src/pages/dashboard/storage-utils.ts | 85 + .../frontend/src/pages/dashboard/storage.tsx | 515 +++-- .../src/pages/dashboard/ticketresponse.tsx | 142 -- .../frontend/src/pages/dashboard/tickets.tsx | 48 +- .../src/pages/dashboard/tickets/detail.tsx | 533 +++-- .../src/pages/dashboard/tickets/index.tsx | 535 +++-- .../src/pages/dashboard/tickets/new.tsx | 21 +- .../frontend/src/pages/dashboard/types.ts | 53 + ospabhost/frontend/src/pages/login.tsx | 30 +- ospabhost/frontend/src/pages/register.tsx | 19 +- ospabhost/frontend/src/pages/s3plans.tsx | 647 ++++--- ospabhost/frontend/src/utils/apiClient.ts | 1 + ospabhost/frontend/src/utils/uploadDB.ts | 142 ++ ospabhost/frontend/tsconfig.node.json | 1 + ospabhost/frontend/vite.config.ts | 6 +- 58 files changed, 8674 insertions(+), 3752 deletions(-) create mode 100644 ospabhost/backend/prisma/add_custom_storage_plan.sql create mode 100644 ospabhost/backend/prisma/migrations/20250115_add_rate_limiting/migration.sql delete mode 100644 ospabhost/backend/prisma/migrations/20250427_add_panel_vps_id/migration.sql create mode 100644 ospabhost/backend/prisma/migrations/20251123130000_add_storage_plan/migration.sql create mode 100644 ospabhost/backend/prisma/migrations/20251123130500_alter_storage_bucket_plan_fk/migration.sql create mode 100644 ospabhost/backend/prisma/migrations/20251125120000_add_storage_console_credentials/migration.sql create mode 100644 ospabhost/backend/prisma/migrations/20251126_add_custom_storage_plan/migration.sql create mode 100644 ospabhost/backend/prisma/storage_plans_seed.sql create mode 100644 ospabhost/backend/src/modules/storage/fileScanner.ts create mode 100644 ospabhost/frontend/public/github.png create mode 100644 ospabhost/frontend/public/google.png create mode 100644 ospabhost/frontend/public/yandex.png create mode 100644 ospabhost/frontend/src/components/AdminPricingTab.tsx create mode 100644 ospabhost/frontend/src/components/AdminTestingTab.tsx create mode 100644 ospabhost/frontend/src/components/VKOneTap.tsx create mode 100644 ospabhost/frontend/src/pages/dashboard/storage-bucket.tsx create mode 100644 ospabhost/frontend/src/pages/dashboard/storage-utils.ts delete mode 100644 ospabhost/frontend/src/pages/dashboard/ticketresponse.tsx create mode 100644 ospabhost/frontend/src/utils/uploadDB.ts diff --git a/ospabhost/CONTRIBUTIONS.md b/ospabhost/CONTRIBUTIONS.md index 121da2a..34a5949 100644 --- a/ospabhost/CONTRIBUTIONS.md +++ b/ospabhost/CONTRIBUTIONS.md @@ -1,10 +1,10 @@ -# 🤝 Contributing to Ospabhost 8.1 +# Contributing to Ospabhost 8.1 -Thank you for considering contributing to **Ospabhost 8.1**! This document provides guidelines and instructions for contributing to the project. +Thank you for considering contributing to **Ospabhost 8.1**! This document provides guidelines for contributing. --- -## 📋 Table of Contents +## Table of Contents - [Code of Conduct](#code-of-conduct) - [Getting Started](#getting-started) @@ -13,21 +13,14 @@ Thank you for considering contributing to **Ospabhost 8.1**! This document provi - [Commit Guidelines](#commit-guidelines) - [Pull Request Process](#pull-request-process) - [Testing Requirements](#testing-requirements) -- [Documentation](#documentation) -- [Contact](#contact) --- -## 📜 Code of Conduct +## Code of Conduct ### Our Pledge -We pledge to make participation in our project a harassment-free experience for everyone, regardless of: -- Age, body size, disability, ethnicity -- Gender identity and expression -- Level of experience -- Nationality, personal appearance, race, religion -- Sexual identity and orientation +We pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity, level of experience, nationality, personal appearance, race, religion, sexual identity and orientation. ### Our Standards @@ -42,25 +35,22 @@ We pledge to make participation in our project a harassment-free experience for - Trolling, insulting comments, personal attacks - Public or private harassment - Publishing others' private information without permission -- Other conduct which could reasonably be considered inappropriate ### Enforcement -Violations of the Code of Conduct can be reported to: +Violations can be reported to: - **Email:** support@ospab.host - **Telegram:** @ospab_support -All complaints will be reviewed and investigated promptly and fairly. - --- -## 🚀 Getting Started +## Getting Started ### Prerequisites -Before you begin, ensure you have the following installed: +Before you begin, ensure you have: -```bash +\\\ash # Node.js (v24.x or higher) node --version @@ -72,714 +62,382 @@ mysql --version # Git git --version -``` +\\\ ### Fork and Clone -1. **Fork the repository** on GitHub: - - Click "Fork" button at https://github.com/Ospab/ospabhost8.1 - +1. **Fork the repository** on GitHub 2. **Clone your fork locally:** - ```bash + \\\ash git clone https://github.com/YOUR_USERNAME/ospabhost8.1.git cd ospabhost8.1/ospabhost - ``` + \\\ 3. **Add upstream remote:** - ```bash + \\\ash git remote add upstream https://github.com/Ospab/ospabhost8.1.git - git remote -v - ``` + \\\ ### Setup Development Environment #### Backend Setup -```bash +\\\ash cd backend # Install dependencies npm install -# Copy environment template +# Copy environment file cp .env.example .env -# Edit .env with your local configuration -nano .env +# Setup database +npx prisma migrate deploy -# Generate Prisma client -npx prisma generate - -# Run migrations -npx prisma migrate dev - -# Seed database (optional) -npx prisma db seed - -# Start development server +# Run in development mode npm run dev -``` +\\\ #### Frontend Setup -```bash +\\\ash cd frontend # Install dependencies npm install -# Copy environment template +# Copy environment file cp .env.example .env -# Edit .env -nano .env - # Start development server npm run dev -``` - -#### Database Setup - -```sql --- Create database -CREATE DATABASE ospab CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; - --- Create user (optional) -CREATE USER 'ospab_user'@'localhost' IDENTIFIED BY 'secure_password'; -GRANT ALL PRIVILEGES ON ospab.* TO 'ospab_user'@'localhost'; -FLUSH PRIVILEGES; -``` +\\\ --- -## 🔄 Development Workflow +## Development Workflow -### Branch Strategy +### Create Feature Branch -We follow **Git Flow** workflow: - -``` -main # Production-ready code - ├── develop # Development branch - │ ├── feature/ # New features - │ ├── fix/ # Bug fixes - │ ├── refactor/ # Code refactoring - │ └── docs/ # Documentation updates - └── hotfix/ # Critical production fixes -``` - -### Creating a Feature Branch - -```bash -# Ensure you're on latest develop -git checkout develop -git pull upstream develop - -# Create feature branch +\\\ash git checkout -b feature/your-feature-name +# or for bug fixes: +git checkout -b fix/bug-description +\\\ -# Example: -git checkout -b feature/add-payment-gateway -git checkout -b fix/proxmox-connection -git checkout -b docs/api-examples -``` +### Make Changes -### Branch Naming Convention +1. Make your changes following the coding standards below +2. Ensure tests pass: \ +pm run test\ +3. Build successfully: \ +pm run build\ -| Type | Pattern | Example | -|------|---------|---------| -| Feature | `feature/` | `feature/panel-websocket` | -| Bug Fix | `fix/` | `fix/sso-timestamp-validation` | -| Hotfix | `hotfix/` | `hotfix/critical-security-patch` | -| Refactor | `refactor/` | `refactor/prisma-queries` | -| Docs | `docs/` | `docs/sso-integration` | -| Test | `test/` | `test/panel-api-integration` | +### Commit Changes -### Staying Updated +\\\ash +# Stage your changes +git add . -```bash -# Fetch latest changes from upstream -git fetch upstream +# Commit with a descriptive message +git commit -m "feat: Add new storage feature" -# Merge upstream changes into your branch -git checkout feature/your-feature -git merge upstream/develop +# Push to your fork +git push origin feature/your-feature-name +\\\ -# Or rebase (preferred for cleaner history) -git rebase upstream/develop -``` +### Create Pull Request + +1. Go to your fork on GitHub +2. Click "Compare & pull request" +3. Write a clear description of your changes +4. Reference any related issues: "Fixes #123" +5. Submit the PR --- -## 📝 Coding Standards +## Coding Standards -### TypeScript Style Guide +### Backend (Express/TypeScript) -#### File Structure +- Use **TypeScript** for type safety +- Follow **camelCase** for variables and functions +- Use **PascalCase** for classes and interfaces +- Keep functions small and focused +- Add JSDoc comments for public methods +- Use async/await instead of promises -```typescript -// 1. Imports (external first, then internal) -import express from 'express'; -import { PrismaClient } from '@prisma/client'; -import { authenticateJWT } from '../middleware/auth'; -import { validateRequest } from '../utils/validation'; - -// 2. Types/Interfaces -interface CreateServerRequest { - tariffId: number; - osId: number; -} - -// 3. Constants -const PROXMOX_TIMEOUT = 30000; -const MAX_SERVERS_PER_USER = 10; - -// 4. Main code -export class ServerService { - // Implementation -} - -// 5. Helper functions -function generateServerName(userId: number): string { - return `server-${userId}-${Date.now()}`; -} - -// 6. Exports -export default ServerService; -``` - -#### Naming Conventions - -```typescript -// Classes: PascalCase -class ServerService {} -class ProxmoxApi {} - -// Interfaces: PascalCase with "I" prefix (optional) -interface IUser {} -interface ServerConfig {} - -// Functions: camelCase -function createServer() {} -function validateEmail(email: string): boolean {} - -// Variables: camelCase -const userCount = 42; -let isActive = true; - -// Constants: SCREAMING_SNAKE_CASE -const API_BASE_URL = 'https://api.ospab.host'; -const MAX_RETRY_ATTEMPTS = 3; - -// Private properties: prefix with underscore (optional) -class Example { - private _privateField: string; - public publicField: string; -} - -// Files: kebab-case -// server-service.ts -// proxmox-api.ts -// auth-middleware.ts -``` - -#### Code Style - -```typescript -// ✅ GOOD: Explicit types -function calculateTotal(price: number, quantity: number): number { - return price * quantity; -} - -// ❌ BAD: Implicit any -function calculateTotal(price, quantity) { - return price * quantity; -} - -// ✅ GOOD: Async/await -async function getUser(id: number): Promise { - const user = await prisma.user.findUnique({ where: { id } }); - return user; -} - -// ❌ BAD: Promise chaining -function getUser(id: number) { - return prisma.user.findUnique({ where: { id } }) - .then(user => user); -} - -// ✅ GOOD: Error handling -async function createServer(userId: number): Promise { - try { - const server = await prisma.server.create({ - data: { userId, name: generateServerName(userId) } - }); - return server; - } catch (error) { - console.error('Failed to create server:', error); - throw new Error('Server creation failed'); - } -} - -// ✅ GOOD: Destructuring -const { id, username, email } = user; - -// ❌ BAD: Multiple property access -const id = user.id; -const username = user.username; -const email = user.email; - -// ✅ GOOD: Optional chaining -const serverName = user?.servers?.[0]?.name ?? 'N/A'; - -// ❌ BAD: Nested checks -const serverName = user && user.servers && user.servers[0] - ? user.servers[0].name - : 'N/A'; -``` - -### React/Frontend Standards - -```tsx -// ✅ GOOD: Functional components with TypeScript -interface UserCardProps { - user: User; - onEdit: (id: number) => void; -} - -export const UserCard: React.FC = ({ user, onEdit }) => { - const handleEdit = () => { - onEdit(user.id); - }; - - return ( -
-

{user.username}

- -
- ); -}; - -// ✅ GOOD: Custom hooks -function useServerData(userId: number) { - const [servers, setServers] = useState([]); - const [loading, setLoading] = useState(true); - - useEffect(() => { - async function fetchServers() { - try { - const response = await api.get(`/users/${userId}/servers`); - setServers(response.data); - } catch (error) { - console.error('Failed to fetch servers:', error); - } finally { - setLoading(false); - } - } - fetchServers(); - }, [userId]); - - return { servers, loading }; -} - -// ✅ GOOD: Tailwind CSS classes organized -
- Content -
-``` - -### Prisma Schema Conventions - -```prisma -// ✅ GOOD: Explicit relations -model User { - id Int @id @default(autoincrement()) - username String @unique - email String @unique - createdAt DateTime @default(now()) - updatedAt DateTime @updatedAt - - servers Server[] @relation("UserServers") - tickets Ticket[] @relation("UserTickets") - - @@map("users") -} - -model Server { - id Int @id @default(autoincrement()) - name String - userId Int - user User @relation("UserServers", fields: [userId], references: [id], onDelete: Cascade) - - @@index([userId]) - @@map("servers") -} -``` - ---- - -## 💬 Commit Guidelines - -### Commit Message Format - -We follow **Conventional Commits** specification: - -``` -(): - - - -