Техническая документация

1. О проекте

SiteForge — SaaS-платформа для создания маркетплейсов, интернет-магазинов и досок объявлений. Пользователь выбирает тип сайта, модули, тему — и получает готовую платформу за минуты. Каждый сайт = отдельный тенант в Payload CMS. Платформа управляет данными, медиа, заказами, отзывами и уведомлениями через единую инсталляцию Payload.

2. Инфраструктура и доступы

3. Архитектура

• ▸Next.js 16.2.6 — App Router, Server Components, Server Actions, standalone output
• ▸Payload CMS 3.85.x — headless CMS, PostgreSQL, REST + GraphQL API, Lexical editor
• ▸Мультитенантность — через @payloadcms/plugin-multi-tenant (настроен, customTenantField, tenant selector в админке)
• ▸Route Groups — (site)/ для витрины, (payload)/ для админки Payload. У каждой группы свой layout с html/body
• ▸Изоляция данных — по tenant relationship в каждой коллекции. Доступ фильтруется через access control
• ▸Tailwind CSS 4 — стилизация, shadcn/ui компоненты
• ▸withPayload() — в next.config.ts, авто-генерирует importMap при build

4. Коллекции Payload CMS

5. Модульная система

tenant.modules — JSON-массив активных модулей. Каждый модуль управляет доступностью функционала. Хук useModule(name) проверяет наличие модуля в контексте.

6. Тематизация

tenant.theme — JSON с настройками внешнего вида. Компонент ThemeStyles инжектит CSS-переменные. Контекст TenantContext предоставляет данные через хуки useTenant() и useModule(name).

{
  "colors": {
    "primary": "#7c3aed",
    "secondary": "#06b6d4",
    "accent": "#f1f5f9",
    "bg": "#ffffff",
    "text": "#1e293b"
  },
  "fonts": {
    "heading": "Inter",
    "body": "Inter"
  },
  "borderRadius": "8px"
}

6 предустановленных тем + произвольные цвета через админку. Утилитарные классы: .sf-btn-primary, .sf-card, .sf-badge, .sf-link, .sf-input

7. Маршруты

8. Ключевые компоненты и контексты

9. Плагины Payload CMS — анализ и план

Payload CMS имеет 13 официальных плагинов. Ниже — анализ каждого в контексте SiteForge, приоритет и статус.

Установленные

Приоритет 1 — Обязательные (✅ Все выполнены)

Приоритет 2 — Рекомендуемые

Приоритет 3 — Полезные

Нужные функции (не плагины Payload)

10. Дорожная карта разработки

План основан на результатах UX-аудита (подробности на отдельной странице), анализе конкурентов и текущем состоянии платформы. Фазы выстроены по принципу максимального влияния на конверсию и пользовательский опыт. Каждая фаза = 1-2 недели разработки.

Фаза 0 — Выполнено (базовая инфраструктура)

Фаза 1 — Критичный UX (P0) — ВЫПОЛНЕНО

Все задачи P0 реализованы. Гостевой чекаут, прогресс-бар, доставка на карточке, breadcrumbs, toast-уведомления.

Фаза 2 — Продуктовый UX (P1) — ВЫПОЛНЕНО (6/6)

Все 6 задач реализованы. Социальные входы VK/Google (NextAuth.js), Quick View, рекомендации, CSV импорт, фильтры, отзывы с фото + рейтинг продавца.

Фаза 3 — Рост и удержание (P2) — ВЫПОЛНЕНО (11/11)

Функции для масштабирования платформы и повышения возврата пользователей. Все 11 задач выполнены. Промокоды, PWA, ЮKassa, уведомления, SEO, Schema.org, карточка товара, Wishlist, отслеживание заказов — всё готово.

Фаза 4 — Масштабирование (P3) — ВЫПОЛНЕНО (5/5)

Все 5 стратегических функций реализованы.

По команде заказчика

11. Известные проблемы и решения

12. Структура ключевых файлов

src/
├── app/
│   ├── (payload)/              # Payload CMS admin + API
│   │   ├── admin/[[...segments]]/page.tsx
│   │   ├── api/[...slug]/route.ts
│   │   ├── graphql/route.ts
│   │   └── layout.tsx          # RootLayout from @payloadcms/next
│   ├── (site)/                 # Публичные страницы
│   │   ├── [siteId]/           # Страницы тенанта
│   │   │   ├── layout.tsx      # TenantProvider + CustomerAuth + ThemeStyles
│   │   │   ├── page.tsx        # Главная (Hero, категории, новинки)
│   │   │   ├── catalog/        # Каталог с фильтрами
│   │   │   ├── product/[id]/   # Карточка товара + ProductClient
│   │   │   ├── cart/           # Корзина + чекаут
│   │   │   ├── search/         # Поиск
│   │   │   ├── favorites/      # Избранное
│   │   │   ├── compare/        # Сравнение (макс 4)
│   │   │   ├── account/        # Личный кабинет
│   │   │   ├── auth/           # Логин/регистрация покупателя
│   │   │   ├── order-success/  # Подтверждение заказа
│   │   │   └── admin/          # Админ-панель тенанта
│   │   ├── onboarding/         # 5-шаговый wizard
│   │   ├── editor/             # Визуальный редактор
│   │   ├── login/              # Авторизация платформы
│   │   ├── demo/               # Демо
│   │   ├── tz/                 # Эта страница
│   │   └── page.tsx            # Лендинг SiteForge
│   └── api/                    # Custom API routes
├── components/
│   ├── tenant/                 # TenantContext, ThemeStyles, CustomerAuth, CartScript
│   ├── tenant-admin/           # Sidebar, Header для админки тенанта
│   └── ui/                     # shadcn/ui компоненты
├── payload/
│   ├── collections/            # Tenants, Users, Sites, Media
│   ├── collections/modules/   # Products, Categories, Orders, Reviews, etc.
│   ├── hooks/                  # createNotification
│   └── payload.config.ts       # Основной конфиг Payload
├── themes/                     # Предустановленные темы (ozon.ts, types.ts)
├── views/                      # View компоненты (HomeView, CartView, etc.)
└── modules/                    # Переиспользуемые модули (Header, ProductCard, etc.)

13. Команды для работы

14. UX-аудит и анализ конкурентов

Подробный UX-аудит платформы, анализ мировых практик e-commerce и классифайдов, пожелания пользователей, приоритетные рекомендации (P0-P3), а также сравнительный анализ конкурентов в России и мире вынесены на отдельную страницу.