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

- 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
This commit is contained in:
Umbrix Dev
2026-02-08 09:16:55 +03:00
parent 27f76cbd10
commit a0f5d69448
3 changed files with 1751 additions and 0 deletions

306
IMPLEMENTATION-SUMMARY.md Normal file
View File

@@ -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+ строк детального анализа)
**Готов к старту!** 🚀

223
MINI_APP_ARCHITECTURE.md Normal file
View File

@@ -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 с учетом этой архитектуры!

1222
PRICING-LOCATION-ANALYSIS.md Normal file

File diff suppressed because it is too large Load Diff