From 0c49f27e765a20ee1296093ad07df392e08e3ae1 Mon Sep 17 00:00:00 2001 From: Umbrix Dev Date: Wed, 4 Feb 2026 05:25:10 +0300 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20=D0=94=D0=BE=D0=B1=D0=B0=D0=B2?= =?UTF-8?q?=D0=BB=D0=B5=D0=BD=D1=8B=20=D0=BE=D0=B1=D1=83=D1=87=D0=B0=D1=8E?= =?UTF-8?q?=D1=89=D0=B8=D0=B5=20=D0=BA=D0=BE=D0=BC=D0=BC=D0=B5=D0=BD=D1=82?= =?UTF-8?q?=D0=B0=D1=80=D0=B8=D0=B8=20=D0=B2=20=D0=BA=D0=BE=D0=B4=20+=20PR?= =?UTF-8?q?OJECT-STRUCTURE.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- PROJECT-STRUCTURE.md | 298 +++++++++++++++++++++++++++++++++++ app/api/create-user/route.ts | 7 +- app/page.tsx | 6 +- 3 files changed, 309 insertions(+), 2 deletions(-) create mode 100644 PROJECT-STRUCTURE.md diff --git a/PROJECT-STRUCTURE.md b/PROJECT-STRUCTURE.md new file mode 100644 index 0000000..b337242 --- /dev/null +++ b/PROJECT-STRUCTURE.md @@ -0,0 +1,298 @@ +# 📚 Структура проекта Umbrix VPN (для обучения) + +## 🗂️ Основные папки + +### `app/` - Страницы и API (Next.js 13 App Router) +Главная папка приложения. Каждая подпапка = страница сайта. + +``` +app/ +├── page.tsx → Главная страница (/) +├── layout.tsx → Общий шаблон для всех страниц (header, footer) +├── globals.css → Глобальные стили CSS +├── favicon.ico → Иконка сайта +│ +├── plans/ +│ └── page.tsx → Страница тарифов (/plans) +│ +├── setup/ +│ └── page.tsx → Страница настройки VPN (/setup) +│ +├── help/ +│ └── page.tsx → Страница помощи (/help) +│ +├── subscription/ +│ └── [token]/ +│ └── page.tsx → Страница подписки (/subscription/abc123) +│ [token] = динамический параметр URL +│ +└── api/ → Backend API (серверные функции) + ├── create-user/ + │ └── route.ts → POST /api/create-user + │ Создает нового пользователя в Marzban + │ + ├── user-subscription/ + │ └── route.ts → GET /api/user-subscription?telegramId=123 + │ Получает информацию о подписке + │ + └── proxy/ + └── [...path]/ + └── route.ts → GET /api/proxy/* + Проксирует запросы к Marzban панели +``` + +**Как это работает:** +- `page.tsx` = React компонент, который рендерит HTML страницу +- `route.ts` = API endpoint (backend функция) +- `[token]` = динамическая часть URL (можно получить через `params.token`) + +--- + +### `lib/` - Утилиты (переиспользуемые функции) + +``` +lib/ +├── logger.ts → Логирование (debug, info, warn, error) +│ Автоматически отключает debug в production +│ +├── constants.ts → Константы (URL Marzban, подписки) +│ Чтобы не хардкодить URL в разных местах +│ +├── telegram-utils.ts → Работа с Telegram WebApp API +│ getTelegramData() - получить данные пользователя +│ +└── marzban-api.ts → Функции для работы с Marzban API + (получение пользователей, создание и т.д.) +``` + +**Зачем это нужно:** +- **Не дублировать код** - одна функция используется везде +- **Легко менять** - изменил в одном месте, работает везде +- **Читабельность** - понятно что делает функция по имени + +--- + +### `types/` - TypeScript типы + +``` +types/ +├── marzban.ts → Типы для Marzban API +│ interface MarzbanUser { username, status, expire, ... } +│ interface CreateUserRequest { ... } +│ +└── telegram.ts → Типы для Telegram WebApp + interface TelegramUser { id, username, ... } +``` + +**Зачем:** +- **Автодополнение** - VS Code подсказывает поля объектов +- **Проверка ошибок** - TypeScript не даст передать неправильные данные +- **Документация** - видно какие поля должны быть в объекте + +--- + +### `components/` - React компоненты + +``` +components/ +├── QRCodeModal.tsx → Модальное окно с QR кодом +└── ReferralModal.tsx → Модальное окно с реферальной ссылкой +``` + +**Что такое компонент:** +- Переиспользуемая часть UI (кнопка, модалка, форма) +- Можно использовать в разных страницах +- Пример: `` + +--- + +### `hooks/` - React хуки + +``` +hooks/ +└── useTelegramWebApp.ts → Хук для работы с Telegram WebApp API + const { webApp } = useTelegramWebApp() +``` + +**Что такое хук:** +- Функция для переиспользования логики +- Начинается с `use` +- Используется внутри компонентов + +--- + +### `public/` - Статические файлы + +``` +public/ +├── next.svg → Картинки, доступные по URL +└── vercel.svg → /next.svg → public/next.svg +``` + +--- + +## 📄 Конфигурационные файлы + +### `.env.local` - Секретные переменные +```bash +MARZBAN_ADMIN_USERNAME=admin +MARZBAN_ADMIN_PASSWORD=секрет +``` +**НЕ КОММИТИТСЯ В GIT!** (в `.gitignore`) + +--- + +### `package.json` - Зависимости проекта +```json +{ + "dependencies": { + "next": "13.5.1", // Фреймворк + "react": "18.2.0", // Библиотека UI + "tailwindcss": "3.3.3" // CSS фреймворк + }, + "scripts": { + "dev": "next dev", // npm run dev - локальная разработка + "build": "next build", // npm run build - сборка для production + "start": "next start" // npm start - запуск production + } +} +``` + +--- + +### `tsconfig.json` - Настройки TypeScript +```json +{ + "compilerOptions": { + "paths": { + "@/*": ["./*"] // Позволяет писать import '@/lib/logger' + } // вместо import '../../lib/logger' + } +} +``` + +--- + +### `tailwind.config.ts` - Настройки Tailwind CSS +```typescript +module.exports = { + content: ["./app/**/*.{js,ts,jsx,tsx}"], // Где искать классы + theme: { + extend: { + colors: { + primary: "#3b82f6" // Свои цвета + } + } + } +} +``` + +--- + +### `next.config.js` - Настройки Next.js +```javascript +module.exports = { + reactStrictMode: true, // Строгий режим React + images: { + domains: ['example.com'] // Разрешенные домены для картинок + } +} +``` + +--- + +## 🔄 Как работает проект + +### 1. Пользователь открывает сайт +``` +app.umbrix.net → app/page.tsx +``` + +### 2. Компонент запрашивает данные Telegram +```typescript +import { getTelegramData } from '@/lib/telegram-utils'; + +const { telegramId, telegramUsername } = getTelegramData(); +``` + +### 3. Делает запрос к API +```typescript +const response = await fetch('/api/user-subscription?telegramId=' + telegramId); +const data = await response.json(); +``` + +### 4. API обращается к Marzban +```typescript +// app/api/user-subscription/route.ts +const marzbanResponse = await fetch('https://panel.umbrix.net/api/users'); +``` + +### 5. Возвращает данные пользователю +```typescript +return NextResponse.json({ success: true, data: userData }); +``` + +--- + +## 🎨 Где что менять + +### Изменить текст на главной странице +→ `app/page.tsx` + +### Добавить новую страницу +→ Создать `app/новая-страница/page.tsx` + +### Изменить логику API +→ `app/api/*/route.ts` + +### Добавить новую утилиту +→ Создать `lib/моя-утилита.ts` + +### Изменить стили +→ `app/globals.css` или Tailwind классы в JSX + +### Добавить переменные окружения +→ `.env.local` (не забудь в `.env.example`) + +--- + +## 🛠️ Полезные команды + +```bash +# Установить зависимости +npm install + +# Запустить локально (http://localhost:3000) +npm run dev + +# Собрать для production +npm run build + +# Запустить production версию +npm start + +# Проверить TypeScript ошибки +npx tsc --noEmit + +# Проверить Git статус +git status + +# Закоммитить изменения +git add . +git commit -m "Описание изменений" +git push +``` + +--- + +## 📖 Полезные ссылки + +- **Next.js документация**: https://nextjs.org/docs +- **React документация**: https://react.dev +- **TypeScript**: https://www.typescriptlang.org/docs +- **Tailwind CSS**: https://tailwindcss.com/docs +- **Telegram WebApp**: https://core.telegram.org/bots/webapps + +--- + +**Совет**: Начни с изменения текстов в `app/page.tsx`, потом постепенно переходи к более сложным вещам! diff --git a/app/api/create-user/route.ts b/app/api/create-user/route.ts index 629e950..efbf797 100644 --- a/app/api/create-user/route.ts +++ b/app/api/create-user/route.ts @@ -1,5 +1,10 @@ +// API endpoint для создания нового пользователя VPN +// POST /api/create-user +// Принимает: { planType, telegramId, telegramUsername, firstName, lastName } +// Возвращает: { success: true, token, username, subscriptionUrl } + import { NextRequest, NextResponse } from 'next/server'; -import { randomUUID } from 'crypto'; +import { randomUUID } from 'crypto'; // Криптографически безопасная генерация UUID import { MARZBAN_PANEL_URL, getSubscriptionUrl } from '@/lib/constants'; import { logger } from '@/lib/logger'; import type { PlanType, CreateUserRequest, CreateUserResponse } from '@/types/marzban'; diff --git a/app/page.tsx b/app/page.tsx index 507b467..3b24231 100644 --- a/app/page.tsx +++ b/app/page.tsx @@ -1,4 +1,8 @@ -'use client'; +// Главная страница приложения (Home Page) +// Показывает статус подписки пользователя и кнопки действий +// URL: https://app.umbrix.net/ + +'use client'; // Next.js 13: это клиентский компонент (с useState, useEffect) import { useState, useEffect } from 'react'; import { useRouter } from 'next/navigation';