233 lines
6.0 KiB
Markdown
233 lines
6.0 KiB
Markdown
# Build Variants - Руководство
|
||
|
||
Проект поддерживает два режима работы: **frontend** (без БД) и **full** (с MongoDB).
|
||
|
||
## Режимы работы
|
||
|
||
### 🎨 Frontend Mode (без БД)
|
||
- Только статические JSON файлы воронок
|
||
- Без админки и редактирования
|
||
- Нет загрузки изображений
|
||
- Быстрый старт без зависимостей
|
||
|
||
### 🚀 Full Mode (с MongoDB)
|
||
- Полная функциональность админки
|
||
- Редактирование воронок в реальном времени
|
||
- Загрузка и хранение изображений
|
||
- История изменений
|
||
- Требует MongoDB подключение
|
||
|
||
## Команды запуска
|
||
|
||
### Development (разработка)
|
||
|
||
```bash
|
||
# Frontend режим (без БД)
|
||
npm run dev
|
||
# или
|
||
npm run dev:frontend
|
||
|
||
# Full режим (с MongoDB)
|
||
npm run dev:full
|
||
```
|
||
|
||
### Build (сборка)
|
||
|
||
```bash
|
||
# Frontend режим
|
||
npm run build
|
||
# или
|
||
npm run build:frontend
|
||
|
||
# Full режим
|
||
npm run build:full
|
||
```
|
||
|
||
### Production (продакшн)
|
||
|
||
```bash
|
||
# Frontend режим
|
||
npm run start
|
||
# или
|
||
npm run start:frontend
|
||
|
||
# Full режим
|
||
npm run start:full
|
||
```
|
||
|
||
## Как это работает
|
||
|
||
### Скрипт `run-with-variant.mjs`
|
||
|
||
Все команды используют скрипт `/scripts/run-with-variant.mjs`, который:
|
||
|
||
1. Принимает команду и вариант: `node run-with-variant.mjs dev full`
|
||
2. Устанавливает environment переменные:
|
||
- `FUNNEL_BUILD_VARIANT=full|frontend`
|
||
- `NEXT_PUBLIC_FUNNEL_BUILD_VARIANT=full|frontend`
|
||
3. Запускает Next.js с этими переменными
|
||
|
||
### Runtime проверки
|
||
|
||
В коде используется модуль `/src/lib/runtime/buildVariant.ts`:
|
||
|
||
```typescript
|
||
import { IS_FRONTEND_ONLY_BUILD, IS_FULL_SYSTEM_BUILD } from '@/lib/runtime/buildVariant';
|
||
|
||
// В API endpoints
|
||
if (IS_FRONTEND_ONLY_BUILD) {
|
||
return NextResponse.json(
|
||
{ error: 'Not available in frontend mode' },
|
||
{ status: 403 }
|
||
);
|
||
}
|
||
|
||
// Для условной логики
|
||
if (IS_FULL_SYSTEM_BUILD) {
|
||
// Код который работает только с БД
|
||
}
|
||
```
|
||
|
||
### Константы
|
||
|
||
```typescript
|
||
import { BUILD_VARIANTS } from '@/lib/constants';
|
||
|
||
BUILD_VARIANTS.FRONTEND // 'frontend'
|
||
BUILD_VARIANTS.FULL // 'full'
|
||
```
|
||
|
||
## Environment файлы
|
||
|
||
### `.env.local` (НЕ включать build variant!)
|
||
|
||
```env
|
||
# ❌ НЕ НАДО: NEXT_PUBLIC_FUNNEL_BUILD_VARIANT=full
|
||
# Вместо этого используйте команды npm run dev:full / dev:frontend
|
||
|
||
# MongoDB (нужно только для full режима)
|
||
MONGODB_URI=mongodb://localhost:27017/witlab-funnel
|
||
|
||
# Базовый URL
|
||
NEXT_PUBLIC_BASE_URL=http://localhost:3000
|
||
```
|
||
|
||
**Важно:** `NEXT_PUBLIC_FUNNEL_BUILD_VARIANT` НЕ должна быть в `.env.local`!
|
||
Она устанавливается автоматически через команды.
|
||
|
||
### `.env.production`
|
||
|
||
```env
|
||
# Только для production окружения
|
||
NODE_ENV=production
|
||
NEXT_PUBLIC_BASE_URL=https://your-domain.com
|
||
```
|
||
|
||
## API Endpoints
|
||
|
||
Все API endpoints автоматически проверяют режим работы:
|
||
|
||
### `/api/images/[filename]` - GET, DELETE
|
||
- ✅ Full mode: возвращает изображения из MongoDB
|
||
- ❌ Frontend mode: 403 Forbidden
|
||
|
||
### `/api/images` - GET
|
||
- ✅ Full mode: список всех изображений
|
||
- ❌ Frontend mode: 403 Forbidden
|
||
|
||
### `/api/images/upload` - POST
|
||
- ✅ Full mode: загрузка изображений в MongoDB
|
||
- ❌ Frontend mode: 403 Forbidden
|
||
|
||
### `/api/funnels/*`
|
||
- ✅ Full mode: CRUD операции с воронками
|
||
- ❌ Frontend mode: 403 Forbidden
|
||
|
||
## Типичные сценарии
|
||
|
||
### Локальная разработка с админкой
|
||
|
||
```bash
|
||
# 1. Запустить MongoDB
|
||
mongod --dbpath ./data
|
||
|
||
# 2. Запустить в full режиме
|
||
npm run dev:full
|
||
|
||
# 3. Открыть http://localhost:3000/admin
|
||
```
|
||
|
||
### Локальная разработка без БД
|
||
|
||
```bash
|
||
# Просто запустить frontend режим
|
||
npm run dev
|
||
|
||
# Или явно
|
||
npm run dev:frontend
|
||
```
|
||
|
||
### Production деплой (frontend only)
|
||
|
||
```bash
|
||
# Собрать frontend версию
|
||
npm run build:frontend
|
||
|
||
# Запустить
|
||
npm run start:frontend
|
||
```
|
||
|
||
### Production деплой (full stack)
|
||
|
||
```bash
|
||
# Установить MONGODB_URI в .env.production
|
||
echo "MONGODB_URI=mongodb://..." > .env.production
|
||
|
||
# Собрать full версию
|
||
npm run build:full
|
||
|
||
# Запустить
|
||
npm run start:full
|
||
```
|
||
|
||
## Troubleshooting
|
||
|
||
### Проблема: "Image serving not available"
|
||
|
||
**Причина:** Запущен frontend режим, а используется API для изображений
|
||
|
||
**Решение:** Перезапустить в full режиме:
|
||
```bash
|
||
npm run dev:full
|
||
```
|
||
|
||
### Проблема: "Cannot connect to MongoDB"
|
||
|
||
**Причина:** MongoDB не запущен или неправильный URI
|
||
|
||
**Решение:**
|
||
1. Проверить что MongoDB запущен: `mongosh`
|
||
2. Проверить MONGODB_URI в `.env.local`
|
||
3. Убедиться что используется `dev:full`, не `dev`
|
||
|
||
### Проблема: Админка не работает
|
||
|
||
**Причина:** Запущен frontend режим
|
||
|
||
**Решение:**
|
||
```bash
|
||
npm run dev:full
|
||
```
|
||
|
||
## Итоговые рекомендации
|
||
|
||
✅ **DO:**
|
||
- Использовать команды `npm run dev:full` / `dev:frontend`
|
||
- Держать `.env.local` без `NEXT_PUBLIC_FUNNEL_BUILD_VARIANT`
|
||
- Проверять `IS_FRONTEND_ONLY_BUILD` в API endpoints
|
||
|
||
❌ **DON'T:**
|
||
- Не добавлять `NEXT_PUBLIC_FUNNEL_BUILD_VARIANT` в `.env.local`
|
||
- Не проверять `process.env.NEXT_PUBLIC_FUNNEL_BUILD_VARIANT` напрямую
|
||
- Не смешивать логику frontend и full режимов
|