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

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

- Статус документа: living document
- Актуально на: 2 апреля 2026 года
- Владелец: backend/platform-команда
- Пересмотр: при изменении приоритетов, последовательности пакетов разработки или статуса фаз
- Область применения: стратегический и ближайший план развития проекта
- Связанные документы:
  - [Текущее состояние](./current-state.md)
  - [Требования](./requirements.md)
  - [Execution checkpoints](./execution-checkpoints.md)
  - [OpenAPI gaps](../architecture/openapi-gaps.md)
  - [Product roadmap и delivery checklist](../Agents/product-roadmap.md)

_Актуальный рабочий 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](../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](../architecture/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](./execution-checkpoints.md).
- Хронология завершённых change packages: [docs/project/project-change-log.md](./project-change-log.md).
- Детализированный feature-backlog: [docs/Agents/product-roadmap.md](../Agents/product-roadmap.md).
- Платформенный статус: [specs/qadam-platform/implementation.md](../../specs/qadam-platform/implementation.md).
- Реальное состояние сервера: [docs/project/current-state.md](./current-state.md).