vodorod/app_umbrix

Fork 0

Files

Umbrix Dev 0c49f27e76 📚 Добавлены обучающие комментарии в код + PROJECT-STRUCTURE.md

2026-02-04 05:25:10 +03:00

9.3 KiB

Raw Permalink Blame History

📚 Структура проекта 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 (кнопка, модалка, форма)
Можно использовать в разных страницах
Пример: <QRCodeModal url="..." />

`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` - Секретные переменные

MARZBAN_ADMIN_USERNAME=admin
MARZBAN_ADMIN_PASSWORD=секрет

НЕ КОММИТИТСЯ В GIT! (в .gitignore)

`package.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

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]  // Позволяет писать import '@/lib/logger'
    }                  // вместо import '../../lib/logger'
  }
}

`tailwind.config.ts` - Настройки Tailwind CSS

module.exports = {
  content: ["./app/**/*.{js,ts,jsx,tsx}"],  // Где искать классы
  theme: {
    extend: {
      colors: {
        primary: "#3b82f6"  // Свои цвета
      }
    }
  }
}

`next.config.js` - Настройки Next.js

module.exports = {
  reactStrictMode: true,  // Строгий режим React
  images: {
    domains: ['example.com']  // Разрешенные домены для картинок
  }
}

🔄 Как работает проект

1. Пользователь открывает сайт

app.umbrix.net → app/page.tsx

2. Компонент запрашивает данные Telegram

import { getTelegramData } from '@/lib/telegram-utils';

const { telegramId, telegramUsername } = getTelegramData();

3. Делает запрос к API

const response = await fetch('/api/user-subscription?telegramId=' + telegramId);
const data = await response.json();

4. API обращается к Marzban

// app/api/user-subscription/route.ts
const marzbanResponse = await fetch('https://panel.umbrix.net/api/users');

5. Возвращает данные пользователю

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)

🛠️ Полезные команды

# Установить зависимости
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, потом постепенно переходи к более сложным вещам!

9.3 KiB Raw Permalink Blame History Unescape Escape