app_umbrix/IMPLEMENTATION-SUMMARY.md

📋 Краткая выжимка: План реализации тарифов с локациями

Дата: 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 часов)

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 часов)

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

// Возвращает список доступных локаций
{
  "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 (обновленный)

// Принимает:
{
  "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₽ →]          │
└─────────────────────────────────────┘

---

🎁 Реферальная система (уже работает!)

Текущая реализация:

// 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 НЕ имеет встроенного механизма ограничения устройств.

Что НЕ доступно:

// В UserCreate API нет:
{
  "device_limit": 5,       // ❌
  "ip_limit": 5,           // ❌
  "max_connections": 5     // ❌
}

Что есть:

{
  "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+ строк детального анализа)

Готов к старту! 🚀