Qadam Roadmap
← Назад к библиотеке
проектspecs/qadam-platform/implementation.md

Qadam Platform — статус реализации

Обновлён 1 апр. 2026 г., 12:41 · 0 комментариев

ИсходникСкачать

Qadam Platform — статус реализации

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

  • Статус документа: living document
  • Актуально на: 31 марта 2026 года
  • Владелец: backend/platform-команда
  • Пересмотр: при изменении платформенной архитектуры, roadmap или статуса реализации
  • Область применения: канонические платформенные spec-документы для текущего ядра Qadam
  • Связанные документы:

Статус: in-progress

1. Foundation

  • Split-репозитории qadam-core и qadam-web с pnpm workspace внутри каждого репозитория
  • Общие пакеты @repo/prisma, @repo/shared, @repo/eslint-config, @repo/typescript-config
  • Prisma schema, migrations, seed
  • Prisma data layer оформлен как отдельный пакет с generated client и select helpers
  • Backend skeleton на NestJS
  • Frontend skeleton на Next.js App Router
  • Базовый production deploy на текущем сервере
  • Автоматизированный backup baseline и off-host retention на production-сервере
  • Базовый OpenAPI/Swagger-контур опубликован на production (/api/docs, /api/openapi.json)
  • Web получил первый generated OpenAPI contract layer для request types
  • В репозитории зафиксирован versioned OpenAPI artifact и root sync/check workflow
  • Для auth + leads + catalog + reviews + public seller profile + buyer reviews cabinet реализован generated response contract layer во frontend
  • Seller leads экран переведён на общий query/mutation слой без прямых fetch-вызовов
  • Публичный reviews flow и форма отправки отзыва переведены на общий query/mutation слой без прямых fetch-вызовов
  • Roadmap-портал закрыт от доступа через primary host и больше не полагается только на nginx/basic-auth bypass prevention
  • Refresh token consume стал атомарным и больше не допускает reuse race через отдельные GET/DEL
  • Trust proxy ограничен loopback proxy, поэтому throttling различает реальных клиентов за nginx
  • API production runtime больше не слушает внешний интерфейс и закрыт за loopback-only reverse proxy
  • Публичная доступность айтема унифицирована для catalog, public seller profile, lead write-path и review write-path
  • SELLER_STAFF перестал направляться во frontend в неподдержанный seller area
  • Созданы и запушены bootstrap-репозитории qadam-core и qadam-web
  • qadam-web собирается из собственного OpenAPI artifact и не требует backend checkout для codegen/build
  • Production runtime переведён на qadam-core и qadam-web
  • Roadmap-портал вынесен из apps/web в отдельный standalone runtime apps/roadmap и отдельный systemd unit qadam-roadmap
  • [~] Документация приведена к актуальному состоянию, но ещё требует регулярного сопровождения
  • [~] Docker-контур уже начат: для api есть актуальный Dockerfile, compose manifest и подтверждённый container smoke, но production всё ещё канонически host-based
  • [~] Legacy checkout /data/uzbek всё ещё лежит на сервере, но больше не является production source of truth

2. Auth и аккаунты

  • Регистрация
  • Логин
  • GET /auth/me
  • Logout
  • Refresh token rotation через httpOnly cookies
  • [~] Набор unit-тестов отставал от refresh-token реализации и должен поддерживаться актуальным
  • SMS / phone verification

3. Buyer

  • Базовый buyer module на backend
  • GET /me/profile
  • POST /me/profile
  • PATCH /me/profile
  • Buyer leads API
  • Buyer reviews API
  • [~] Buyer cabinet присутствует во frontend, но не доведён до полноценного UX
  • [~] Buyer profile flow требует продуктовой и UI-доработки
  • Полноценный buyer onboarding

4. Seller

  • Seller profile API
  • Seller items API
  • Seller leads API
  • Seller staff API
  • Seller cabinet routes во frontend
  • [~] Seller onboarding и seller profile ещё не завершены с продуктовой точки зрения
  • [~] Item workflow реализован частично и требует доводки статусов, UX и smoke-проверок
  • Telegram notifications
  • Финальная статусная модель seller-операций

5. Catalog и публичные страницы

  • Публичный каталог
  • Страница айтема /item/[slug]
  • Public seller profile /sellers/[id]
  • API для subjects и locations
  • [~] SEO-слой частично присутствует, но не завершён
  • [~] Фильтры и визуальная часть каталога ещё требуют доработки
  • Карта и геопоиск
  • Structured data, sitemap, canonical SEO-completion

6. Leads и reviews

  • Создание лидов
  • Лиды у buyer и seller
  • Базовый reviews flow
  • [~] Расширенная статусная модель лидов пока не доведена до финальной
  • [~] Модерация отзывов неполная
  • CPL billing
  • Нотификации по лидам

7. Admin

  • Admin routes и backend-модуль
  • Базовая статистика
  • Очередь модерации айтемов
  • CRUD по reference data на API-уровне
  • [~] Реальная ролевая модель админов ещё не завершена
  • [~] UI админки требует доводки
  • Полный moderation workflow для отзывов
  • Операционные роли root/verifier/analyst/marketing

8. Tracking и аналитика

  • Базовый tracking endpoint
  • Infrastructure layer для event logging
  • Структурное JSON-логирование через Pino и nestjs-pino
  • Optional Axiom transport в production при наличии credentials
  • Append-only таблица EventLog в Prisma schema
  • Внешний uptime/TLS monitoring и Telegram alert delivery baseline
  • [~] Product analytics и seller-facing метрики реализованы частично
  • Полноценная аналитическая витрина
  • PMF, funnel и billing-аналитика

9. Документация и roadmap-портал

  • Отдельный домен qadam-roadmap.2fab.app
  • Basic auth
  • Чтение markdown напрямую из папки docs/
  • Переходы в specs и docs/Agents по относительным markdown-ссылкам
  • Архив processed plans скрывается по умолчанию и показывается только через Show archived
  • Upload/delete/comment для документов
  • TLS и отдельный host routing
  • Отдельный standalone runtime qadam-roadmap на 127.0.0.1:3001
  • Отдельный operational docs/feedback портал для frontend-команды на qadam-roadmap.2fab.app

10. Quality Gates

  • Production build backend
  • Production build frontend
  • Repo-side quality gate на Gitea Actions с self-hosted runner
  • Исправлен production entrypoint API
  • Исправлено использование legacy frontend tree в production
  • Backend unit-тесты синхронизированы с текущей логикой auth и buyer profile
  • [~] Runtime OpenAPI-контур работает, artifact export и CI drift check уже введены, core product-срезы уже живут на generated response types, но pipeline ещё нужно дотянуть до admin/legacy API-layer
  • Frontend automated tests
  • [~] Полноценный CI/CD quality gate уже введён для qadam-core, но ещё не доведён для qadam-web
  • Web smoke/e2e контур

11. Ближайшие следующие шаги

  1. Завершить buyer profile / buyer cabinet flow.
  2. Масштабировать generated response contract layer с core product-срезов на admin API и остаточный legacy API-layer.
  3. Убрать дублирующиеся frontend-слои и остаточный legacy-хвост в qadam-web.
  4. Добавить базовые smoke/e2e-проверки на web.
  5. Довести начатый docker/image-based delivery до web + registry + cutover и только после этого отказываться от host-based deploy как единственного runtime.

12. Сессионные заметки

2026-03-27

  • Документация приведена к каноническому русскоязычному набору.
  • Подтверждена рабочая production-модель: systemd + nginx + host services.
  • Зафиксировано, что проект находится в состоянии in-progress, а не not-started.
  • Поднят базовый OpenAPI/Swagger-контур и опубликован на production-домене.
  • В apps/web подключён первый generated OpenAPI contract layer и убраны runtime DTO-зависимости от backend/shared пакетов.
  • В репозитории зафиксирован versioned OpenAPI artifact, а CI теперь проверяет contract drift автоматически.
  • Core product-срез catalog + reviews + public seller profile + buyer reviews cabinet переведён на generated response contract и общий API-layer.
  • Отдельный security-hardening пакет закрыл roadmap host bypass, refresh race, throttling behind proxy и дрейф публичной доступности айтемов.
  • API дополнительно закрыт на loopback bind, чтобы не обходить nginx напрямую по host port.
  • Созданы и запушены bootstrap-репозитории qadam-core и qadam-web, оба подтверждены автономной установкой и сборкой.
  • Production runtime и roadmap-портал переведены на qadam-core и qadam-web; /data/uzbek остался только как legacy checkout.