app_umbrix/PROJECT-STRUCTURE.md

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