app_umbrix/PROJECT-README.md

# 🚀 Umbrix VPN - Telegram Mini App

Проект Next.js с интеграцией страницы подписки Marzban для Telegram Mini App.

## 📁 Структура проекта

```
stackblitz-project/
├── app/
│   ├── page.tsx                    # Главная страница VPN
│   ├── layout.tsx                  # Root layout
│   ├── globals.css                 # Глобальные стили
│   ├── api/
│   │   └── proxy/
│   │       └── [...path]/
│   │           └── route.ts        # API прокси для Marzban
│   └── subscription/
│       └── [token]/
│           └── page.tsx            # Страница подписки
├── hooks/
│   └── useTelegramWebApp.ts        # Telegram WebApp API integration
├── public/                         # Статика
└── package.json                    # Зависимости
```

## 🎯 Что реализовано

### ✅ Главная страница (`/`)
- VPN щит с анимацией подключения/отключения
- Статус подписки
- Кнопки действий: пробный период, покупка, настройки
- Навигация в "Моя подписка"

### ✅ Страница подписки (`/subscription/[token]`)
- **User Info Card**: трафик, прогресс-бар, срок действия
- **Протоколы**: группировка по VLESS, VMess, Trojan
- **Копирование**: отдельные ссылки и все сразу
- **Deep Links**: открытие в Hiddify/Clash/V2RayNG
- **Telegram UI**: адаптировано под Telegram тему

### ✅ API Proxy (`/api/proxy/[...path]`)
- Проксирует запросы к Marzban серверу
- Обходит CORS
- Логирование и обработка ошибок

### ✅ Telegram WebApp Hook
- Интеграция с Telegram WebApp API
- MainButton, BackButton, HapticFeedback
- Theme colors, User info
- Popups и alerts

## 🚀 Запуск проекта

### 1. Установка зависимостей

```bash
npm install
```

Или если нужно переустановить:
```bash
rm -rf node_modules package-lock.json
npm install
```

### 2. Запуск dev сервера

```bash
npm run dev
```

Откроется на http://localhost:3000

### 3. Тестирование страницы подписки

Открой в браузере:
```
http://localhost:3000/subscription/Vm9kb3JvZF8sMTc2OTczMDU2NQtUnJh9gxkj
```

## 🎨 Дизайн

### Цветовая схема
- **Фиолетовый** (`purple-600`) - Primary actions
- **Синий** (`blue-600`) - Secondary actions
- **Зелёный** (`green-500`) - Success/Active
- **Красный** (`red-500`) - Danger/Limited
- **Градиенты**: `from-slate-900 via-slate-800 to-slate-900`

### Адаптивность
- Мобильная первая (Mobile-first)
- Полностью responsive
- Touch-friendly кнопки (min 44px)

## 📱 Telegram Mini App

### Интеграция

1. **Создать бота через @BotFather**:
   ```
   /newbot
   Имя: Umbrix VPN
   Username: umbrix_bot
   ```

2. **Настроить Web App**:
   ```
   /newapp
   Выбрать бота: @umbrix_bot
   Title: VPN Подписка
   Description: Управление VPN подпиской
   URL: https://ваш-домен.vercel.app
   ```

3. **Добавить кнопку в бот**:
   ```python
   from telegram import InlineKeyboardButton, InlineKeyboardMarkup, WebAppInfo
   
   button = InlineKeyboardButton(
       text="🔗 Моя подписка",
       web_app=WebAppInfo(url="https://ваш-домен.vercel.app/subscription/TOKEN")
   )
   ```

### Тестирование в Telegram

Отправь боту команду `/start` и нажми на кнопку Mini App.

## 🔧 Настройка

### Изменить URL Marzban сервера

В `app/subscription/[token]/page.tsx`:
```typescript
const response = await fetch(`https://ВАШ-ДОМЕН.com/sub/${token}/`, {
  headers: { 'Accept': 'text/html' },
});
```

### Добавить свой токен

В `app/page.tsx`:
```tsx
<Link href="/subscription/ВАШ-ТОКЕН">
```

### Кастомизация цветов

В `tailwind.config.ts`:
```typescript
theme: {
  extend: {
    colors: {
      primary: '#8b5cf6', // Фиолетовый
      // ... другие цвета
    }
  }
}
```

## 📦 Деплой

### Vercel (рекомендовано)

```bash
# 1. Установить Vercel CLI
npm i -g vercel

# 2. Деплой
vercel --prod
```

Или через UI:
1. Загрузить проект на GitHub
2. Импортировать в Vercel
3. Deploy!

### Другие платформы

- **Netlify**: `npm run build` → `netlify deploy`
- **Cloudflare Pages**: Connect GitHub → Auto deploy
- **Railway**: Connect GitHub → Deploy

## 🐛 Troubleshooting

### "Module not found: lucide-react"
```bash
npm install lucide-react
```

### "Cannot find module '@/hooks/useTelegramWebApp'"
Проверь, что файл создан в `hooks/useTelegramWebApp.ts`

### Telegram WebApp не определяется
1. Открывай только через Telegram Mini App
2. Для dev добавь проверку:
```typescript
if (typeof window !== 'undefined' && window.Telegram?.WebApp) {
  // Telegram код
}
```

### CORS ошибки с Marzban
Используй API proxy: `/api/proxy/[...path]`

## 📚 Документация

- **Next.js**: https://nextjs.org/docs
- **Telegram WebApp**: https://core.telegram.org/bots/webapps
- **Lucide Icons**: https://lucide.dev/
- **Tailwind CSS**: https://tailwindcss.com/docs

## 🎯 Roadmap

- [ ] QR коды для ссылок
- [ ] Статистика использования (графики)
- [ ] Push уведомления о лимитах
- [ ] Sharing в Telegram Stories
- [ ] Выбор серверов по геолокации
- [ ] Speed test
- [ ] Payments integration

## 📝 Changelog

### v1.0.0 (30.01.2026)
- ✅ Страница подписки с парсингом HTML
- ✅ Telegram WebApp интеграция
- ✅ API Proxy для Marzban
- ✅ Копирование ссылок с haptic feedback
- ✅ Deep links в VPN приложения
- ✅ Адаптивный дизайн

---

**Made with ❤️ for Umbrix VPN**  
**Powered by**: Next.js, Telegram WebApp API, Marzban