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)

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

Преимущества:

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

2. Frontend-only режим (buildVariant.ts)

// В 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)

FUNNEL_BUILD_VARIANT=frontend npm run build

Характеристики:

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

Full-system (dev/staging)

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 файл

// funnels/my-funnel.json
{
  "meta": {
    "id": "my-funnel",
    "firstScreenId": "welcome"
  },
  "screens": [...]
}

2. Запустите скрипт генерации

npm run bake-funnels

3. Пересоберите проект

npm run build

Результат: Redirect автоматически создается в next.config.ts:

/my-funnel → /my-funnel/welcome

Отладка

Проверка redirects

# В dev режиме
npm run dev
curl -I http://localhost:3000/soulmate

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

Проверка режима сборки

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 доступна
• Проверьте логи в консоли сервера