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

1О проекте

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

• Магазин — Каталог, корзина, оформление заказов, приём платежей
• Маркетплейс — Мультипродавцовая платформа с комиссией и рейтингами
• Доска объявлений — Публикация, модерация, категории, продвижение

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

Критичные особенности Payload 3.x

• getPayload({ config }), НЕ устаревший payload.init()
• @payload-config path alias → ./payload.config.ts в корне проекта
• Server Actions: 'use server' обязателен для serverFunction
• handleServerFunctions из @payloadcms/next требует /* webpackIgnore: true */ dynamic import
• RootLayout из @payloadcms/next/layouts рендерит свой html/body — нельзя вкладывать
• @payloadcms/next/css ОБЯЗАТЕЛЬНО импортировать в layout для стилей админки

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

Hooks: createNotification — beforeChange hook на Orders, автоматически создаёт уведомление при новом заказе.

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

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

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

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

CSS-переменные

• --sf-primary / --sf-secondary / --sf-accent
• --sf-bg / --sf-text
• --sf-border-radius
• --sf-font-heading / --sf-font-body

7-9Дорожная карта

10.5Инфраструктурный аудит и план улучшений

По результатам комплексного аудита платформы выявлены критичные и рекомендованные улучшения. Задачи отсортированы по приоритету: от безопасности и стабильности до UX-полировки.

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

• PM2 частые рестарты (18+) — Решено: importMap настроен для multi-tenant, DB column tenant_id исправлен, sharp установлен.
• /admin 500 ошибка после добавления Customers — Решено: ALTER TABLE payload_preferences_rels ADD COLUMN customers_id.
• React hydration #418 — Решено через route groups: (site)/ и (payload)/ с отдельными html/body.
• Missing Payload CSS — Решено: обязательный импорт @payloadcms/next/css в (payload)/layout.tsx.
• Email пишется в консоль — Ок: нужен email-адаптер (Resend/SendGrid). Пока не критично.
• Multi-tenant plugin не настроен — Решено: плагин подключён, customTenantField настроен, DB column переименован.

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                  # Лендинг MyStores
│   └── api/                          # Custom API routes
├── components/
│   ├── tenant/                       # TenantContext, ThemeStyles, CustomerAuth
│   ├── 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/                           # Предустановленные темы
├── views/                            # View компоненты
└── modules/                          # Переиспользуемые модули

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

# Деплой на продакшен
cd /var/www/marketplace && npm run build && pm2 restart siteforge

# Проверить статус
pm2 status siteforge

# Логи
pm2 logs siteforge --lines 50 --nostream

# Установить новый плагин Payload
cd /var/www/marketplace && npm install @payloadcms/plugin-seo
npm run build && pm2 restart siteforge

# Тест API
curl -s http://localhost:3010/api/tenants | head -200

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

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

Открыть UX-аудит и анализ конкурентов →