📊 Полный анализ системы тарифов с выбором локаций

- PRICING-LOCATION-ANALYSIS.md (45KB): технический анализ Marzban API
- IMPLEMENTATION-SUMMARY.md (12KB): краткая выжимка для разработки
- MINI_APP_ARCHITECTURE.md: обновленная архитектура

Ключевые решения:
✅ Скидки за период: -10% (3м), -15% (6м), -20% (год)
✅ Выбор локаций из реальных нод Marzban
✅ Мультишаговая воронка: тариф → период → локации → оплата
❌ Динамическое ценообразование отклонено
⏸️ Семейные планы отложены на V2.0 (требуют Device Monitor)
✅ Реферальная система уже работает

MVP план: 2 недели (20 часов)
- Week 1: Backend API (8h) - /api/nodes + /api/create-user updates
- Week 2: Frontend UI (12h) - мультишаговый /app/plans/page.tsx

IMPLEMENTATION-SUMMARY.md

@@ -0,0 +1,306 @@
+# 📋 Краткая выжимка: План реализации тарифов с локациями
+
+**Дата**: 8 февраля 2026  
+**Статус**: ✅ Анализ завершен, готово к реализации
+
+---
+
+## 🎯 Цель
+
+Реализовать систему покупки VPN с:
+1. ✅ Выбором тарифа (Start/Plus/Max)
+2. ✅ Выбором периода (1м/3м/6м/год) с показом скидок
+3. ✅ Выбором локаций (нод) из Marzban
+4. ✅ Оплатой через payment gateway
+5. ✅ Автоматическим созданием пользователя с выбранными нодами
+
+---
+
+## 📊 Итоги анализа
+
+### ✅ Что работает:
+- Тарифы (Start/Plus/Max) - UI готов
+- SetupWizard с выбором локаций - UI готов
+- API создания пользователей - работает
+- Реферальная система - полностью реализована (+7 дней за друга, +30 за milestone)
+
+### ❌ Что НЕ работает:
+- Выбор локаций не сохраняется в Marzban
+- Нет скидок за период оплаты
+- Нет связи между UI выбора локаций и реальными нодами
+
+### ⚠️ Что отклонено:
+- ❌ Динамическое ценообразование (премиум локации дороже)
+- ⏸️ Семейные планы (отложены на V2.0, требуют Device Monitor Service)
+
+---
+
+## 🚀 MVP Roadmap (2 недели)
+
+### Week 1: Backend API (8-10 часов)
+```typescript
+1. [3h] Создать /api/nodes
+   - Получить список нод из Marzban API
+   - Форматировать для фронтенда (id, name, country, ping)
+   - Фильтровать только connected ноды
+
+2. [5h] Обновить /api/create-user
+   - Добавить параметры: period, locationIds
+   - Получить список inbounds для выбранных нод
+   - Создать пользователя с кастомными inbounds
+   - Добавить функцию getPlanConfig(planType, period) с расчетом скидок
+```
+
+### Week 2: Frontend UI (10-12 часов)
+```typescript
+3. [8h] Переработать /app/plans/page.tsx
+   - Шаг 1: Выбор тарифа (Start/Plus/Max)
+   - Шаг 2: Выбор периода (1м/3м/6м/год)
+     - Показать экономию: "💰 Экономия 297₽ при оплате на год"
+   - Шаг 3: Выбор локаций
+     - Загрузить из /api/nodes
+     - Ограничить по тарифу (Start=1, Plus=3, Max=все)
+   - Шаг 4: Кнопка "Оплатить"
+
+4. [2h] Добавить компоненты
+   - PeriodSelector - карточки периодов со скидками
+   - LocationSelector - чекбоксы локаций с флагами
+   - PriceSummary - итоговая цена с экономией
+
+5. [2h] Стилизация под Telegram Mini App
+```
+
+---
+
+## 💰 Скидки за период
+
+```
+1 месяц:  0%  (базовая цена)
+3 месяца: -10% (экономия ~270₽ на Plus)
+6 месяцев: -15% (экономия ~540₽ на Plus)
+1 год:    -20% (экономия ~720₽ на Plus)
+```
+
+**Примеры**:
+- Plus (299₽/мес):
+  - 1 месяц: 299₽
+  - 3 месяца: 807₽ (вместо 897₽) → экономия 90₽
+  - 6 месяцев: 1523₽ (вместо 1794₽) → экономия 271₽
+  - 1 год: 2870₽ (вместо 3588₽) → экономия 718₽
+
+---
+
+## 🔧 Техническая реализация
+
+### 1. API: GET /api/nodes
+
+```typescript
+// Возвращает список доступных локаций
+{
+  "success": true,
+  "locations": [
+    {
+      "id": 1,
+      "name": "🇳🇱 Нидерланды",
+      "address": "193.168.175.128",
+      "ping": "15ms",
+      "country": "NL"
+    },
+    {
+      "id": 2,
+      "name": "🇺🇸 США",
+      "address": "194.113.210.187",
+      "ping": "120ms",
+      "country": "US"
+    }
+  ]
+}
+```
+
+### 2. API: POST /api/create-user (обновленный)
+
+```typescript
+// Принимает:
+{
+  "planType": "plus",
+  "period": "3months",
+  "locationIds": [1, 2, 5],  // NEW
+  "telegramId": 12345,
+  "telegramUsername": "john_doe"
+}
+
+// Логика:
+1. Получить список нод по locationIds
+2. Получить список inbounds для этих нод
+3. Создать mapping:
+   {
+     vless: ["VLESS TCP Node1", "VLESS Reality Node2"],
+     vmess: ["VMess WS Node1"],
+     trojan: ["Trojan TCP Node1"]
+   }
+4. Создать пользователя с этими inbounds
+5. Рассчитать expire с учетом period:
+   - 1month: +30 дней
+   - 3months: +90 дней
+   - 6months: +180 дней
+   - 1year: +365 дней
+```
+
+### 3. Frontend: Мультишаговый выбор
+
+```
+┌─────────────────────────────────────┐
+│ Шаг 1: Тариф                        │
+│ ⭕ Start (1 локация)                │
+│ ⭕ Plus (3 локации)  ← выбран       │
+│ ⭕ Max (все локации)                │
+└─────────────────────────────────────┘
+           ↓
+┌─────────────────────────────────────┐
+│ Шаг 2: Период                       │
+│ ⭕ 1 месяц  - 299₽                  │
+│ ⭕ 3 месяца - 807₽ (экономия 90₽)  │ ← выбран
+│ ⭕ 6 мес    - 1523₽ (экономия 271₽)│
+│ ⭕ 1 год    - 2870₽ (экономия 718₽)│
+└─────────────────────────────────────┘
+           ↓
+┌─────────────────────────────────────┐
+│ Шаг 3: Локации (выберите 3)        │
+│ ☑ 🇳🇱 Нидерланды (15ms)            │ ← выбран
+│ ☐ 🇩🇪 Германия (20ms)              │
+│ ☑ 🇺🇸 США (120ms)                  │ ← выбран
+│ ☐ 🇸🇬 Сингапур (180ms)             │
+│ ☑ 🇯🇵 Япония (160ms)               │ ← выбран
+│ ☐ 🇬🇧 UK (35ms)                    │
+│                                     │
+│ [Перейти к оплате 807₽ →]          │
+└─────────────────────────────────────┘
+```
+
+---
+
+## 🎁 Реферальная система (уже работает!)
+
+**Текущая реализация**:
+```typescript
+// Endpoints:
+POST /api/referral/track    // Записать реферала
+GET  /api/referral/stats    // Получить статистику
+
+// Бонусы:
++7 дней за каждого друга
++30 дней milestone за каждые 5 друзей
+
+// Формула:
+bonusDays = (referralCount * 7) + (Math.floor(referralCount / 5) * 30)
+
+// Примеры:
+1 друг:   +7 дней
+5 друзей: +65 дней (35 + 30 milestone)
+10 друзей: +130 дней (70 + 60 milestone)
+```
+
+**Что можно улучшить в V1.1**:
+- Визуальные badges (Bronze/Silver/Gold)
+- Leaderboard на странице /referral
+- Уведомления в Telegram при milestone
+
+---
+
+## 🚫 Семейные планы - Почему отложены?
+
+**Проблема**: Marzban **НЕ имеет** встроенного механизма ограничения устройств.
+
+**Что НЕ доступно**:
+```json
+// В UserCreate API нет:
+{
+  "device_limit": 5,       // ❌
+  "ip_limit": 5,           // ❌
+  "max_connections": 5     // ❌
+}
+```
+
+**Что есть**:
+```json
+{
+  "online_at": "2026-02-08T10:30:00Z",  // ✅ Последняя активность
+  "sub_last_user_agent": "v2rayNG"      // ✅ User agent
+}
+```
+
+**Варианты решения**:
+
+| Вариант | Точность | Сложность | Время |
+|---------|----------|-----------|-------|
+| 1. Мониторинг `online_at` | ❌ Низкая | Средняя | 8h |
+| 2. IP-based мониторинг | ❌ Низкая | Низкая | 4h |
+| 3. Xray патчи | ✅ Высокая | Очень высокая | 80h+ |
+| 4. Sub-users (5 аккаунтов) | ✅ Высокая | Средняя | 12h |
+| 5. **Без ограничений + ToS** | N/A | Нулевая | 0h |
+| 6. **Log monitor (V2.0)** | ✅ Высокая | Высокая | 40h |
+
+**Решение для MVP**: Отложить на V2.0, для MVP - полагаться на ToS и честность пользователей.
+
+**Решение для V2.0**: Разработать Device Monitor Service с парсингом Xray логов в реальном времени.
+
+---
+
+## 📅 Timeline
+
+### Неделя 1 (Backend):
+- [ ] День 1-2: Создать /api/nodes (3 часа)
+- [ ] День 3-5: Обновить /api/create-user с period + locationIds (5 часов)
+
+### Неделя 2 (Frontend):
+- [ ] День 1-3: Переработать /app/plans/page.tsx (8 часов)
+- [ ] День 4: Компоненты PeriodSelector + LocationSelector (2 часа)
+- [ ] День 5: Стилизация + тестирование (2 часа)
+
+### Неделя 3-4 (Payment + Testing):
+- [ ] Интеграция YooKassa/Stripe
+- [ ] Webhook для обработки оплат
+- [ ] E2E тесты полной воронки
+- [ ] n8n bot updates
+
+---
+
+## 🎯 KPI успеха
+
+**Метрики для отслеживания**:
+1. Конверсия выбора периода:
+   - Сколько % выбирают 1м/3м/6м/год?
+   - Какой период дает наибольший LTV?
+
+2. Выбор локаций:
+   - Топ-3 популярных локации
+   - Сколько % пользователей меняют дефолтный выбор?
+
+3. Реферальная программа:
+   - % пользователей с рефералами
+   - Average referral count per user
+   - Impact на retention
+
+4. Revenue:
+   - ARPU (Average Revenue Per User)
+   - LTV (Lifetime Value)
+   - Churn rate
+
+---
+
+## 📞 Следующие действия
+
+1. ✅ Анализ завершен
+2. ✅ Feedback учтен:
+   - ❌ Динамическое ценообразование отклонено
+   - ⏸️ Семейные планы отложены на V2.0
+   - ✅ Реферальная система работает
+3. ⏳ **Начать разработку MVP** (2 недели)
+4. ⏳ Выбрать payment gateway (YooKassa?)
+5. ⏳ Setup Telegram bot webhook для уведомлений
+
+---
+
+**Полная документация**: См. `PRICING-LOCATION-ANALYSIS.md` (1400+ строк детального анализа)
+
+**Готов к старту!** 🚀

MINI_APP_ARCHITECTURE.md

@@ -0,0 +1,223 @@
+# 🚀 Umbrix Mini App - Полная Архитектура (PRO LEVEL)
+
+## Принципы (Best Practices):
+1. **Telegram Bot = Минимум** - только /start → Open WebApp
+2. **Mini App = Все** - вся логика, UI, воронка продаж
+3. **No localStorage** - только API + MariaDB
+4. **Telegram WebApp SDK** - интеграция с Telegram UI
+
+---
+
+## 📱 **User Journey (Воронка Продаж)**
+
+### **Scenario 1: Новый пользователь БЕЗ реферала**
+```
+1. User clicks: https://t.me/Dorod_vps_bot
+2. Bot sends: "👋 Привет! 🚀 Открыть Umbrix" → WebApp button
+3. User opens: https://app.umbrix.net
+4. Mini App shows: Onboarding Flow
+   ├── Welcome Screen (Telegram.WebApp.initData)
+   ├── Language Selection (RU/EN/UZ)
+   ├── Plan Selection (Shared/Dedicated/Premium)
+   └── Create Account Button
+5. Account created → Dashboard
+6. Dashboard shows:
+   ├── Subscription Status (Active / Expired / Trial)
+   ├── QR Code + Links
+   ├── Referral Button → Copy link
+   ├── Help Button
+   └── Settings Button
+```
+
+### **Scenario 2: Новый пользователь С рефералом**
+```
+1. User clicks: https://t.me/Dorod_vps_bot?start=ref_john_doe
+2. Bot extracts: referrerId = "john_doe"
+3. Bot opens: https://app.umbrix.net?ref=john_doe
+4. Mini App shows: "🎁 Вы перешли по ссылке от john_doe! +7 дней бесплатно"
+5. Onboarding Flow (same as above)
+6. On Account Create:
+   ├── POST /api/create-user (with referrerId)
+   ├── POST /api/referral/track (award +7 days to john_doe)
+   └── Both get bonuses
+7. Dashboard → показывает trial статус + bonus days
+```
+
+### **Scenario 3: Существующий пользователь (возврат)**
+```
+1. User opens: https://t.me/Dorod_vps_bot → WebApp
+2. Mini App detects: Telegram.WebApp.initDataUnsafe.user.id
+3. API Check: GET /api/user-subscription?telegramId=12345
+4. Response: { hasSubscription: true, token: "...", status: "active" }
+5. Mini App redirects: /dashboard (skip onboarding)
+6. Dashboard shows:
+   ├── Subscription details
+   ├── Days remaining: "23 дня осталось"
+   ├── QR Code + Links
+   └── Referral stats: "3 друга, +21 день заработано"
+```
+
+### **Scenario 4: Пользователь с истекшей подпиской**
+```
+1. API Check: { hasSubscription: true, status: "expired" }
+2. Dashboard shows:
+   ├── ⚠️ "Подписка истекла 5 дней назад"
+   ├── "Пригласите 2 друзей для продления" (gamification)
+   ├── "Или оплатите" → Payment Button
+   └── Referral progress bar: [■■■□□] 3/5 friends
+```
+
+---
+
+## 🗂️ **Структура файлов Mini App**
+
+```
+/app
+├── page.tsx                    # 🏠 Landing / Onboarding (если новый user)
+├── dashboard/
+│   └── page.tsx               # 📊 Dashboard (если есть подписка)
+├── plans/
+│   └── page.tsx               # 💎 Plan Selection (выбор тарифа)
+├── referral/
+│   └── page.tsx               # 🎁 Referral Stats (уже есть!)
+├── help/
+│   └── page.tsx               # ❓ Help / FAQ (уже есть!)
+├── setup/
+│   └── page.tsx               # 🔧 Setup Wizard (инструкции по настройке)
+└── subscription/
+    └── [token]/
+        └── page.tsx           # 📲 Subscription Details (QR код, ссылки)
+
+/components
+├── OnboardingFlow.tsx         # 🎬 Onboarding steps (language, plan, create)
+├── PlanCard.tsx               # 💳 Plan card (Shared/Dedicated/Premium)
+├── SubscriptionStatus.tsx     # ✅ Status badge (Active/Expired/Trial)
+├── ReferralProgress.tsx       # 📈 Progress bar (3/5 friends)
+├── QRCodeModal.tsx            # ✅ Уже есть
+├── ReferralModal.tsx          # ✅ Уже есть
+└── SetupWizard.tsx            # ✅ Уже есть
+
+/lib
+├── telegram-webapp.ts         # 🔌 Telegram WebApp SDK wrapper
+├── marzban-api.ts            # ✅ Уже есть
+└── constants.ts              # ✅ Уже есть
+```
+
+---
+
+## 🎨 **UI Components (Telegram WebApp Style)**
+
+### **1. OnboardingFlow.tsx**
+```tsx
+// Multi-step onboarding (Welcome → Language → Plan → Create)
+// Uses Telegram.WebApp.BackButton, .MainButton
+// Stores state in React (NOT localStorage)
+```
+
+### **2. PlanCard.tsx**
+```tsx
+// Карточка тарифа с ценой, features, "Выбрать" кнопкой
+// Props: { plan, price, features[], selected, onClick }
+// Design: Telegram-style card (rounded, shadow, accent color)
+```
+
+### **3. SubscriptionStatus.tsx**
+```tsx
+// Badge: "✅ Активна до 15.03.2026" / "⚠️ Истекла" / "🎁 Trial (7 дней)"
+// Color-coded: green/red/blue
+// Props: { status, expiryDate, daysRemaining }
+```
+
+### **4. ReferralProgress.tsx**
+```tsx
+// Progress bar: [■■■□□] 3/5 friends → +30 days bonus!
+// Shows: current referrals, next milestone, bonus amount
+// Props: { referralCount, bonusDays }
+```
+
+---
+
+## 🔄 **API Endpoints (уже есть + новые)**
+
+### **Existing:**
+- ✅ POST /api/create-user
+- ✅ GET /api/user-subscription
+- ✅ POST /api/referral/track
+- ✅ GET /api/referral/stats
+
+### **New (to add):**
+```typescript
+// Check if user exists by Telegram ID
+GET /api/user-check?telegramId=12345
+Response: { exists: boolean, username?: string, status?: string }
+
+// Get plan details
+GET /api/plans
+Response: { plans: [{ id, name, price, features[] }] }
+
+// Create payment link
+POST /api/create-payment
+Body: { username, plan, amount }
+Response: { paymentUrl: string, orderId: string }
+```
+
+---
+
+## 📋 **Implementation Priority**
+
+### **Phase 1: Core Flow (СЕЙЧАС)**
+1. ✅ Упростить n8n workflow (DONE)
+2. Create OnboardingFlow.tsx (Welcome → Language → Plan → Create)
+3. Update app/page.tsx (detect new vs existing user)
+4. Create app/dashboard/page.tsx (show subscription status)
+5. Create PlanCard.tsx component
+
+### **Phase 2: Referral Integration**
+6. Update OnboardingFlow to accept ?ref=USERNAME
+7. Pass referrerId to /api/create-user
+8. Add ReferralProgress.tsx to dashboard
+9. Test full referral flow
+
+### **Phase 3: Payment**
+10. Add /api/plans endpoint
+11. Add /api/create-payment endpoint
+12. Integrate payment gateway (crypto)
+13. Add webhook for payment confirmation
+
+### **Phase 4: Polish**
+14. Telegram WebApp SDK integration (BackButton, MainButton, theme)
+15. i18n (RU/EN/UZ)
+16. Error handling + loading states
+17. Analytics (track conversions)
+
+---
+
+## 🎯 **Key Differences from Current Code**
+
+| Current | New (PRO) |
+|---------|-----------|
+| Bot имеет 3 команды + кнопки | Bot только /start → WebApp |
+| Нет onboarding flow | Full onboarding в Mini App |
+| localStorage для данных | API + MariaDB only |
+| Нет gamification | Referral progress bar |
+| Нет выбора плана в UI | Plan selection screen |
+| Нет payment flow | Integrated payment |
+| Нет Telegram theme | Uses Telegram.WebApp.themeParams |
+
+---
+
+## 💡 **Pro Tips**
+
+1. **Telegram WebApp SDK**: используй `Telegram.WebApp.MainButton` для кнопок действий
+2. **No localStorage**: только API, чтобы работало на всех устройствах
+3. **Gamification**: показывай прогресс реферальной программы (мотивация!)
+4. **Mobile-first**: Mini App всегда открывается на мобильном
+5. **Fast loading**: минимизируй API calls, cache в React state
+6. **Error handling**: graceful fallback если нет Telegram.WebApp
+7. **i18n ready**: структура для перевода на другие языки
+
+---
+
+## 🚀 **Next Steps**
+
+Создам полную структуру Mini App с учетом этой архитектуры!