w-funnel/docs/FUNNEL_ROUTING.md

# Маршрутизация воронок в witlab-funnel

## Оптимизированный процесс открытия воронки

### Проблема (до оптимизации)
При переходе по `/soulmate`:
1. Загружалась страница `[funnelId]/page.tsx`
2. Проверялась база данных (медленно)
3. Делался client/server redirect на `/soulmate/onboarding`
4. **Метрики фиксировали загрузку промежуточной страницы**

### Решение (после оптимизации)

#### 1. Server-side redirects (next.config.ts)
```typescript
async redirects() {
  return [
    {
      source: '/soulmate',
      destination: '/soulmate/onboarding',
      permanent: false // 307 redirect
    },
    // ... автоматически генерируется для всех воронок из BAKED_FUNNELS
  ];
}
```

**Преимущества:**
- ✅ Редирект на уровне CDN/сервера (мгновенный)
- ✅ Нет промежуточной загрузки страницы
- ✅ Метрики видят только финальный URL `/soulmate/onboarding`
- ✅ Query параметры сохраняются автоматически

#### 2. Frontend-only режим (buildVariant.ts)
```typescript
// В frontend-only режиме БД вообще не проверяется
if (IS_FRONTEND_ONLY_BUILD) {
  return null; // Сразу используем BAKED_FUNNELS
}
```

**Преимущества:**
- ✅ Нет обращений к MongoDB в production
- ✅ Быстрая загрузка (только статика)
- ✅ Не нужен backend для работы воронок

## Поток открытия воронки (оптимизированный)

### Frontend-only режим (production)
```
Пользователь → /soulmate
       ↓
[Server-side redirect]  // Мгновенно, без загрузки страницы
       ↓
/soulmate/onboarding
       ↓
Рендер первого экрана
       ↓
📱 Пользователь видит контент
```

**Время:** ~100-200ms (только загрузка и рендер экрана)

### Full-system режим (dev/admin)
```
Пользователь → /soulmate
       ↓
[Server-side redirect проверяет наличие в BAKED_FUNNELS]
       ↓
  Есть в BAKED_FUNNELS?
  ├─ Да → Redirect на /soulmate/onboarding
  └─ Нет → [funnelId]/page.tsx → Проверка БД → Redirect
       ↓
/soulmate/onboarding
       ↓
Загрузка из БД или BAKED_FUNNELS
       ↓
Рендер первого экрана
```

## Ключевые файлы

### 1. next.config.ts
- Генерирует server-side redirects из `BAKED_FUNNELS`
- Работает на этапе build-time
- Редиректы происходят на уровне CDN/сервера

### 2. src/lib/runtime/buildVariant.ts
- Определяет режим сборки: `frontend` или `full`
- `IS_FRONTEND_ONLY_BUILD` - флаг для проверки режима

### 3. src/app/[funnelId]/page.tsx
- Fallback для воронок из БД (не в BAKED_FUNNELS)
- В frontend-only режиме БД не проверяется
- Используется только в full-system режиме

### 4. src/lib/funnel/bakedFunnels.ts
- Автогенерируется из JSON файлов
- Содержит все статические воронки
- Используется для генерации redirects

## Режимы сборки

### Frontend-only (production)
```bash
FUNNEL_BUILD_VARIANT=frontend npm run build
```

**Характеристики:**
- Нет обращений к MongoDB
- Только статические воронки из BAKED_FUNNELS
- Максимальная скорость загрузки
- Деплой на CDN/static hosting

### Full-system (dev/staging)
```bash
FUNNEL_BUILD_VARIANT=full npm run build
```

**Характеристики:**
- Поддержка MongoDB
- Воронки из БД + BAKED_FUNNELS
- Админка для редактирования
- Требует backend сервер

## Метрики

### До оптимизации
```
Pageview: /soulmate          ← Промежуточная загрузка
Pageview: /soulmate/onboarding ← Финальная страница
```

### После оптимизации
```
Pageview: /soulmate/onboarding ← Только финальная страница
```

**Результат:** Метрики чистые, без артефактов промежуточных загрузок.

## Query параметры (UTM и др.)

Server-side redirects **автоматически сохраняют** все query параметры:

```
/soulmate?utm_source=google&utm_campaign=test
  ↓ редирект
/soulmate/onboarding?utm_source=google&utm_campaign=test
```

## Производительность

### Метрики загрузки
| Этап | До оптимизации | После оптимизации |
|------|----------------|-------------------|
| Time to First Byte (TTFB) | ~300-500ms | ~50-100ms |
| First Contentful Paint (FCP) | ~800-1200ms | ~200-400ms |
| Промежуточные загрузки | 1 | 0 |
| Обращения к БД | 1-2 | 0 (frontend-only) |

### CDN/Edge Network
Server-side redirects работают на уровне CDN:
- Vercel Edge Functions
- Cloudflare Workers
- AWS CloudFront Functions
- Nginx/Apache rewrites

## Добавление новой воронки

### 1. Создайте JSON файл
```json
// funnels/my-funnel.json
{
  "meta": {
    "id": "my-funnel",
    "firstScreenId": "welcome"
  },
  "screens": [...]
}
```

### 2. Запустите скрипт генерации
```bash
npm run bake-funnels
```

### 3. Пересоберите проект
```bash
npm run build
```

**Результат:** Redirect автоматически создается в next.config.ts:
```
/my-funnel → /my-funnel/welcome
```

## Отладка

### Проверка redirects
```bash
# В dev режиме
npm run dev
curl -I http://localhost:3000/soulmate

# Должно быть:
# HTTP/1.1 307 Temporary Redirect
# Location: /soulmate/onboarding
```

### Проверка режима сборки
```typescript
console.log(IS_FRONTEND_ONLY_BUILD); // true или false
console.log(BUILD_VARIANT); // "frontend" или "full"
```

### Логи redirects
В консоли при сборке:
```
✓ Compiled successfully
✓ Generated redirects:
  - /soulmate → /soulmate/onboarding
  - /soulmate-small → /soulmate-small/onboarding
```

## Best Practices

1. **Всегда используйте firstScreenId** в meta воронки
2. **Frontend-only для production** - максимальная производительность
3. **Full-system только для dev/admin** - когда нужна БД
4. **Не удаляйте [funnelId]/page.tsx** - нужен для fallback
5. **Query параметры сохраняются** - не нужно их передавать вручную

## Troubleshooting

### Redirect не работает
- Проверьте что воронка есть в BAKED_FUNNELS
- Убедитесь что firstScreenId указан
- Пересоберите проект: `npm run build`

### Метрики показывают промежуточную загрузку
- Проверьте что redirects настроены в next.config.ts
- Убедитесь что используется production build
- Проверьте что CDN/хостинг поддерживает redirects

### Воронка из БД не открывается
- Убедитесь что режим сборки `full`
- Проверьте что MongoDB доступна
- Проверьте логи в консоли сервера