# Qadam Platform — продуктовый и архитектурный контур

## Паспорт документа

- Статус документа: working spec
- Актуально на: 28 марта 2026 года
- Владелец: backend/platform-команда
- Пересмотр: при изменении платформенной архитектуры, roadmap или статуса реализации
- Область применения: канонические платформенные spec-документы для текущего ядра Qadam
- Связанные документы:
  - [Текущее состояние](../../docs/project/current-state.md)
  - [Roadmap](../../docs/project/roadmap.md)
  - [Индекс документации](../../docs/README.md)

## 1. Назначение платформы

Qadam — маркетплейс и операционная платформа для дополнительного образования в Узбекистане. Базовая задача продукта — быстро и качественно соединять родителей и учеников с учебными центрами, онлайн-школами и частными преподавателями.

Ключевой базовый путь:

1. Пользователь находит курс или учебный центр.
2. Изучает карточку айтема.
3. Оставляет лид.
4. Продавец получает лид и обрабатывает его.
5. Платформа фиксирует это как бизнес-событие и основу для будущей монетизации.

## 2. Аудитории и роли

### Buyer

- Родитель или ученик.
- Ищет курсы, оставляет заявки, пишет отзывы, ведёт персональный кабинет.

### Seller

- Офлайн-школа.
- Онлайн-школа.
- Частный репетитор или индивидуальный эксперт.

### Seller Staff

- Сотрудник организации продавца.
- Нужен для дальнейшего развития CRM, управления преподавателями и операционными ролями.

### Admin

- Модерация контента.
- Управление справочниками.
- Операционный контроль качества каталога и лидов.

## 3. Центральная доменная сущность

Главная сущность платформы — `Item`.

`Item` представляет конкретный образовательный продукт: курс, программу, услугу, занятие или предложение продавца. Именно вокруг `Item` строятся:

- каталог и поиск;
- карточка курса;
- лиды;
- отзывы;
- модерация;
- SEO-слой;
- будущая биллинговая логика.

## 4. Продуктовые блоки текущего ядра

### 4.1. Авторизация

- Регистрация и логин по email/phone + password.
- Работа через `httpOnly` cookies.
- Refresh-flow с ротацией refresh token.

### 4.2. Каталог

- Публичная выдача айтемов.
- Фильтрация и поиск.
- Детальная страница айтема.
- Публичные страницы продавца.

### 4.3. Buyer-кабинет

- Профиль пользователя.
- Мои лиды.
- Мои отзывы.

### 4.4. Seller-кабинет

- Профиль организации.
- Управление айтемами.
- Управление лидами.
- Управление сотрудниками.

### 4.5. Admin-слой

- Очередь модерации.
- Базовые дашборды и сводки.
- Управление справочниками.

### 4.6. Внутренняя документация

- Отдельный домен `qadam-roadmap.2fab.app`.
- Просмотр канонических markdown-документов из `qadam-core/docs` с переходами в связанные `specs` и `docs/Agents`.
- Комментарии к документам.
- Загрузка и удаление файлов.

## 5. Архитектурная модель

### Репозиторий

- Два канонических репозитория: `qadam-core` и `qadam-web`.
- Внутри каждого репозитория используется `pnpm` workspace.
- Общие пакеты покрывают Prisma, shared-схемы и build/config слой; отдельный UI workspace-пакет не является частью текущего production-контура.

### Backend

- NestJS + Fastify.
- Глобальный API prefix: `/api/v1`.
- Prisma как ORM для operational database.
- Redis для token-логики, кэша и инфраструктурных задач.

### Frontend

- Next.js App Router.
- React Server Components по умолчанию для публичных страниц.
- TanStack Query для hydration и client-side серверного состояния.
- `next-intl` для i18n.

### Инфраструктура

- Текущий production работает как host deployment.
- `systemd` для запуска API, product web и roadmap-service.
- `nginx` как reverse proxy.
- PostgreSQL и Redis на хосте.
- TLS через Let’s Encrypt.

## 6. Модель данных верхнего уровня

На платформе существуют следующие доменные блоки:

- `Account` и связанная auth-модель.
- `Buyer` с профилями родителя или ученика.
- `Seller` с профилем организации или индивидуального преподавателя.
- `SellerStaff` и будущие performer/CRM-сущности.
- `Item` как центральная продаваемая сущность.
- `Lead` как заявка пользователя.
- `Review` как отзыв на айтем.
- `Subject`, `Location` и другие справочники.
- `Tracking/Event` для аналитики и наблюдаемости поведения пользователей.

## 7. Ключевые продуктовые правила

- Публиковаться в каталоге должны только валидные и допущенные к публикации айтемы.
- Buyer и Seller не должны получать доступ к чужим кабинетным данным.
- Весь frontend получает данные только через backend API, а не напрямую из базы.
- Каноническая валидация и transport-контракт определяются backend-схемами в `packages/shared` и публикуются во frontend через OpenAPI artifact.
- Публичные страницы должны быть совместимы с SSR и SEO.

## 8. Ограничения текущего этапа

- Платформа ещё не является завершённым коммерческим продуктом.
- CRM, платежи и продвинутая аналитика находятся за пределами текущего ядра.
- Часть buyer/seller/admin-потоков присутствует в коде, но ещё требует доводки до production-grade качества.

## 9. Канонический следующий фокус

Ближайший приоритет — не расширение количества направлений, а завершение уже реализованного ядра:

1. Стабилизация и quality gates.
2. Доведение buyer/seller/admin сценариев.
3. Подготовка к GTM и PMF validation.