Roadmap развития проекта

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

• Статус документа: living document
• Актуально на: 2 апреля 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении приоритетов, последовательности пакетов разработки или статуса фаз
• Область применения: стратегический и ближайший план развития проекта
• Связанные документы:
  • Текущее состояние
  • Требования
  • Execution checkpoints
  • OpenAPI gaps
  • Product roadmap и delivery checklist

Актуальный рабочий roadmap на 2 апреля 2026 года.

1. Принцип планирования

Roadmap строится не от максимального количества фич, а от логики вывода проекта в управляемый production:

1. Сначала стабилизация и устранение расхождений.
2. Затем доведение MVP-потоков до рабочего качества.
3. Затем масштабирование в сторону CRM, growth и монетизации.

2. Фаза A — Stabilization & Transferability

Цель

Сделать текущий production технически предсказуемым, снять риск дрейфа между кодом, документацией и сервером и подготовить проект к передаче другой команде без потери управляемости.

Обязательные результаты

• Русскоязычная каноническая документация в порядке.
• Зафиксированы канонические инженерные принципы проекта и Definition of Done.
• Реальный статус платформы зафиксирован в docs/project/current-state.md.
• Есть единый runbook по эксплуатации.
• Есть отдельные runbook по backup/restore, incident response и post-deploy checklist.
• Исправлены отставшие unit-тесты и сломанные quality gates.
• Есть детальный план и уже созданные bootstrap-репозитории qadam-core и qadam-web.
• Есть отдельный frontend handoff-документ с git, OpenAPI и контрактным workflow.
• Зафиксирована модель работы отдельной frontend-команды в qadam-web.
• Есть детальный план перехода на управляемый docker-контур.
• Зафиксирована текущая host-based модель деплоя и целевая migration-модель.
• Production runtime переведён на qadam-core и qadam-web.
• Есть ownership model, change-package standard, execution checkpoints и project-level changelog.
• Есть машиночитаемый docs quality gate.

Задачи

• Синхронизировать docs/, specs/ и фактический код.
• Зафиксировать правила передачи проекта другой команде, обязательность тестового покрытия и русскоязычной документации.
• Зафиксировать ownership, change-package process, checkpoints и changelog как обязательный delivery-контур.
• Убрать ложные статусы вроде not-started в платформенных спеках.
• Починить backend unit-тесты, которые отстали от refresh-token логики и buyer profile поведения.
• Убрать документальный и инфраструктурный drift вокруг frontend repo split и docker migration.
• Зафиксировать split-репозитории как единственный operational-контур новой разработки и текущего production.
• Довести roadmap-портал до состояния, в котором каноническая markdown-документация нормально перелинкована и читается как единая система.

3. Фаза B — MVP Completion

Цель

Довести уже существующие buyer/seller/admin-потоки до качества, достаточного для ручного product validation.

Обязательные результаты

• Seller может пройти путь: профиль -> айтем -> модерация -> лиды.
• Buyer может пройти путь: просмотр -> карточка -> лид -> кабинет.
• Admin может модерировать айтемы и работать с базовыми операционными сценариями.
• Публичные страницы пригодны для SSR и базового SEO.

Приоритетный порядок

1. Seller item workflow.
2. Buyer profile и buyer cabinet.
3. Admin moderation.
4. Reviews и их статусная модель.
5. Публичный seller profile и SEO-слой.
6. Минимальный web smoke baseline на stage, который ловит buyer/seller/admin regressions до ручной UI-проверки.

4. Фаза C — PMF Validation

Цель

Не расширять платформу вслепую, а проверить реальный спрос со стороны seller и buyer.

Обязательные результаты

• Управляемое наполнение каталога.
• Работающая воронка лидов.
• Базовая операционная аналитика по лидам, продавцам и активным айтемам.
• Понимание unit economics для CPL-модели.

Что можно делать только после завершения фазы B

• Масштабирование acquisition.
• Активный GTM по seller side.
• Введение платных seller-инструментов.

5. Фаза D — CRM v1.0

Цель

Превратить Qadam из каталога и lead marketplace в продукт с регулярной ценностью для продавца.

Основные блоки

• Календарь и расписание.
• Клиентская база.
• Онлайн-запись.
• Ролевая модель CRM.
• SaaS billing.

6. Фаза E — Transactional Platform

Цель

Перейти от CPL-only модели к гибридной, а затем и к транзакционной модели.

Основные блоки

• Интеграция оплат.
• Комиссионная модель.
• Единый buyer wallet/journey.
• Финансовый слой и отчётность.

7. Ближайший план разработки

Закрытый пакет

• Документация приведена к каноническому виду.
• Backend test contour и type gate снова зелёные после auth/registration/openapi drift.
• Runbook по текущему серверу зафиксирован.
• Инженерные принципы передачи проекта, тестирования и документации зафиксированы.
• В backend поднят базовый Swagger/OpenAPI-контур как первый исполнимый шаг к frontend repo split.
• В apps/web подключён первый generated OpenAPI contract layer, и сняты runtime-зависимости от @repo/shared/@repo/prisma.
• В репозитории зафиксирован versioned OpenAPI artifact и CI-проверка contract drift.
• Для auth + leads backend уже публикует точные response-схемы, а frontend использует generated response types.
• Seller leads экран переведён на общий query/mutation слой без прямых fetch-обходов.
• Для catalog + reviews + public seller profile + buyer reviews cabinet backend уже публикует точные response-схемы, а frontend использует generated response types.
• Публичный reviews flow и форма отправки отзыва переведены на общий query/mutation слой без прямых fetch-вызовов.
• Устранён контрактный drift вокруг GET /me/reviews: backend, OpenAPI и frontend снова синхронизированы.
• Buyer profile и seller profile уже исключены из активного OpenAPI gap backlog: их response schemas опубликованы и больше не считаются blocker'ом для generated profile contract.
• Auth auxiliary, Staff и Reference data теперь тоже публикуют точные response schemas и выведены из активного OpenAPI gap backlog.
• Seller Items, Admin Dashboard и Admin Moderation теперь тоже публикуют точные response schemas; активный frontend-значимый OpenAPI gap backlog закрыт полностью.
• Закрыт критичный security bypass roadmap-портала: основной домен больше не открывает /roadmap, а mutation routes режут cross-origin POST.
• Refresh token rotation усилена до атомарного single-use consume в Redis.
• Rate limiting behind nginx теперь опирается на доверенный loopback proxy, а не на адрес reverse proxy.
• API больше не слушает внешний интерфейс сервера и закрыт за локальным nginx-proxy.
• Публичная доступность айтема унифицирована для каталога, public seller profile, лидов и отзывов.
• SELLER_STAFF больше не редиректится в неподдержанный seller area.
• Созданы и запушены отдельные bootstrap-репозитории qadam-core и qadam-web.
• qadam-core и qadam-web автономно проходят install/build-контур.
• qadam-web собирается из собственного openapi/openapi.json, а не требует backend checkout для codegen.
• Подготовлен отдельный frontend handoff-документ с git, OpenAPI и правилами интеграции.
• Frontend handoff продублирован внутри qadam-web, чтобы новая frontend-команда не зависела от legacy workspace /data/uzbek.
• Production runtime переключён с /data/uzbek на qadam-core и qadam-web.
• qadam-roadmap.2fab.app теперь читает документы из qadam-core/docs, а не из legacy checkout.
• Roadmap-портал вынесен из apps/web в отдельный standalone-сервис apps/roadmap; основной продуктовый frontend больше не содержит встроенный roadmap runtime.
• Roadmap-портал теперь корректно открывает относительные markdown-ссылки между docs, specs и docs/Agents.
• Зафиксирована и доведена до рабочего вида модель передачи задач между backend/platform-командой и отдельной frontend-командой.
• Исторические implementation plans из /plans проаудированы, а их выводы формально перенесены в канонические документы.
• Закрыты базовые документальные gaps по backup/restore, incident response, environment matrix и post-deploy checklist.
• Введены project-level execution checkpoints и отдельный project change log.
• В qadam-core добавлен исполнимый docs quality gate pnpm check:docs.
• Для qadam-core добавлены repo-side Gitea quality gate, PR review/security template и живой self-hosted runner; первый workflow run уже подтверждён со статусом success.
• Product media переведены на S3-compatible object storage (DigitalOcean Spaces) без изменения frontend-контракта upload endpoint { url }.
• Seller item moderation flow стабилизирован на backend: item lifecycle теперь идёт через DRAFT -> PENDING -> ACTIVE/REJECTED, seller может отозвать айтем с модерации, а seller/admin responses публикуют seller-visible moderation feedback.
• Admin operational surface доведён до рабочего backend-контура: появился GET /admin/sellers с фильтрами и item counters, а seller-facing protected routes теперь возвращают явные ACCOUNT_UNDER_REVIEW / ACCOUNT_BLOCKED после admin status change.
• CP-303 закрыт: в qadam-core уже работают backend metrics/readiness, внешний uptime/TLS monitoring для api, web и roadmap, а operational alerts уходят в отдельный Telegram-канал без ручного polling.
• CP-302 закрыт: на сервере уже работает автоматический backup baseline с локальной верификацией, state file и off-host retention в S3-compatible storage.
• CP-301 уже переведён из чистого baseline в live runtime: на сервер установлен Docker Engine, data-root вынесен на /mnt/qadam100gb/docker, registry/image delivery для qadam-core/api подтверждён, а production /api/* уже обслуживается qadam-api-container.service через nginx upstream qadam_api_backend -> 127.0.0.1:5002.
• Для qadam-core/api уже есть не только image baseline и compose-based shadow smoke, но и source-controlled reversible cutover path; legacy qadam-api.service теперь остаётся rollback-контуром, а не каноническим production runtime.
• Для qadam-web уже добавлен product web image baseline: registry namespace git.2fab.app/eldar/qadam-web-app подтверждён publish/pull smoke, а shadow runtime уже поднимается на 127.0.0.1:3002 от registry image без локального next build на production-сервере.
• Следующий шаг в CP-301 теперь смещён с api на production cutover qadam-web, а затем на выравнивание qadam-roadmap, чтобы убрать временную mixed-runtime фазу.

Sprint 1

• Завершено на backend: новый registration API (check-availability, register/buyer, register/seller, password reset, add-buyer-role) и buyer profile flow (POST/PATCH /me/profile, children, interests).
• Не держать profile flow в ожидании новых backend schema fixes: buyer/seller profile responses уже закрыты в OpenAPI и выведены из active gap backlog.
• Синхронизировать qadam-web, который ведёт отдельная frontend-команда, с backend-контрактом POST /me/profile, PATCH /me/profile, POST /auth/register/buyer и POST /auth/register/seller.
• Вести эту работу не по памяти, а через отдельный remediation backlog docs/frontend/frontend-adoption-backlog.md, где разложены contract drift, response-shape drift и tooling/type debt.
• Добавить UI-обработку отсутствующего buyer profile вместо неявного поведения.
• Закрыть этот поток регрессионными backend/web-проверками по уровню риска.

Sprint 2

• Seller item, admin moderation и admin operational surface уже стабилизированы на backend; минимальный stage-oriented smoke baseline для web уже добавлен и подтверждён живым прогоном на stage (10/10 проверок зелёные), но автоматический запуск после deploy и browser-level e2e остаются отдельным follow-up внутри CP-204.
• Reviews backend-контур теперь замкнут: новые отзывы идут через PENDING, seller complaint flow переводит спорный отзыв в PENDING_MODERATION, admin review moderation уже вынесена в отдельные /admin/moderation/reviews routes, а публичные aggregates считают только PUBLISHED.
• Не считать CP-205 закрытым раньше времени: backend-ядро review flow уже готово, но frontend adoption buyer/public/admin/seller review screens и web smoke/e2e остаются отдельным follow-up.
• CP-206 уже начат на backend: public seller profile очищен до явного публичного контракта и начал отдавать backend-generated seo block для SSR/metadata; stage smoke уже включает public seller profile, поэтому незакрытый хвост теперь не в baseline, а во frontend adoption SEO metadata.
• Не распыляться на новые backend contract fixes для admin, пока не закрыт базовый web regression baseline на buyer/seller/admin маршрутах.
• Seller notifications больше не ограничены settings-only baseline: backend уже публикует seller-facing connect link для Telegram onboarding, принимает internal webhook бота и выпускает одноразовые verification codes через безопасный deep-link flow.
• SMTP-capable email fallback/provider для seller lead notifications уже подготовлен на backend, и owner-facing status-change delivery тоже больше не является пустым флагом: при обновлении статуса активным SELLER_STAFF backend шлёт owner-уведомление по статусам из SELLER_STATUS_CHANGE_NOTIFY_STATUSES. Следующий notifications follow-up должен касаться уже не базового delivery, а transport hardening, retries и возможного расширения на новые actor/source-of-change сценарии.
• После seller/admin stabilization взять Reviews и Public seller profile / SEO как отдельные MVP-пакеты с собственными execution checkpoints.

Sprint 3

• Использовать уже закрытый backend contract-layer и нулевой active backlog из openapi-gaps.md, чтобы frontend-команда сняла ручные response-типы на Seller Items, Admin Dashboard и Admin Moderation.
• Довести Swagger/OpenAPI, artifact export и web codegen до устойчивого contract-layer для admin API и остаточного legacy API-layer уже на стороне потребления, а не за счёт новых backend schema fixes.
• Расширить generated response contract с core product-срезов на admin API и остаточный legacy API-layer.
• Закрыть остаточный cleanup из исторических web-планов: убрать дублирующиеся frontend-слои и legacy-код из qadam-web, включая components/lib и прямые fetch-обходы общего DAL.
• Убрать остаточное legacy-использование /data/uzbek из активного engineering workflow.

Sprint 4

• Backup automation и off-host retention уже закрыты как отдельный delivery package; следующий инфраструктурный фокус — не backup baseline, а image-based delivery.
• Для qadam-core/api уже подтверждён не только базовый container runtime, но и живой production cutover; следующий шаг — не переделывать api, а довести до такого же уровня qadam-web.
• Для qadam-web уже подтверждён registry-backed shadow runtime; следующий шаг — довести это до production cutover и rollback-процедуры без простоя.
• После этого подготовить container baseline для qadam-roadmap и затем унифицировать mixed runtime в единый app-level container contour.
• Усилить object storage контур: при необходимости добавить CDN-fronting, lifecycle policy и off-host retention поверх уже включённого S3-compatible storage для product media.
• Не смешивать этот пакет с roadmap storage: qadam-roadmap может временно оставаться на локальном диске, пока для него отдельно не появятся требования по off-host storage.
• Зафиксировать следующий исполнимый пакет app-level docker migration: web + migrate, уже учитывая что api на production cutover переведён.
• Подготовить отказ от временной mixed-runtime модели после подтверждения container delivery для qadam-web.

8. Что не должно происходить сейчас

• Нельзя начинать CRM, платежи и мобильные приложения до стабилизации текущего ядра.
• Нельзя расширять roadmap новыми крупными направлениями, пока buyer/seller/admin-потоки не доведены до рабочего качества.
• Нельзя считать старые Docker-скрипты production-истиной без отдельной ревизии.
• Нельзя использовать /data/uzbek как рабочую площадку новой разработки после cutover на split-репозитории.

9. Канонический backlog для команды

• Стратегический roadmap: этот файл.
• Операционный статус этапов: docs/project/execution-checkpoints.md.
• Хронология завершённых change packages: docs/project/project-change-log.md.
• Детализированный feature-backlog: docs/Agents/product-roadmap.md.
• Платформенный статус: specs/qadam-platform/implementation.md.
• Реальное состояние сервера: docs/project/current-state.md.