План работы после выделения frontend в отдельный репозиторий

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

• Статус документа: working reference
• Актуально на: 28 марта 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении backend/frontend handoff-процесса, ownership-модели или API change workflow
• Область применения: операционная модель взаимодействия backend/platform-команды и отдельной frontend-команды
• Связанные документы:
  • Карта API-маршрутов
  • Текущее состояние
  • Инженерные принципы

Цель документа

Этот документ больше не описывает гипотетический split. Разделение уже выполнено. Его задача теперь другая: зафиксировать post-cutover operating model, границы ответственности между командами и оставшийся технический план до зрелого delivery-контура.

1. Ключевой вывод

Разделение frontend уже состоялось:

• qadam-web существует как отдельный репозиторий и автономно собирается;
• qadam-core существует как отдельный backend/platform-репозиторий;
• production уже разворачивается из qadam-core и qadam-web.

Следующий этап теперь не про сам split, а про доведение этой модели до управляемой работы двух команд.

2. Что уже сделано

• Созданы и запушены репозитории qadam-core и qadam-web.
• Production переведён на split-репозитории.
• Backend публикует Swagger UI и OpenAPI JSON.
• В qadam-core есть канонический OpenAPI artifact: apps/api/openapi/openapi.json.
• В qadam-web есть локальный mirror artifact: openapi/openapi.json.
• Frontend генерирует типы и contract layer из собственного artifact.
• Для core product-срезов frontend уже использует generated request/response types.
• Основной web runtime уже живёт в apps/web/src/app и FSD-подобных слоях src/shared, src/entities, src/features, src/widgets, src/views.
• Публичный каталог уже переведён на searchParams-based filters, SSR-prefetch и infinite scroll.
• Базовый web auth-layer уже работает через proxy.ts, React Query auth queries/mutations и cookie refresh flow.
• SVGR pipeline уже настроен, а иконки живут в apps/web/src/shared/icons.
• Подготовлен отдельный handoff-документ для frontend-команды.
• Roadmap-портал читает канонические документы из qadam-core/docs.

3. Целевая operating model

После split проект должен жить в такой схеме:

Gitea
  -> qadam-core
  -> qadam-web

qadam-core
  -> backend code
  -> Prisma schema and migrations
  -> OpenAPI source of truth
  -> canonical docs/specs

qadam-web
  -> frontend code
  -> mirrored OpenAPI artifact
  -> generated TS contract
  -> own web delivery contour

Production
  -> /api/* -> qadam-core
  -> /*     -> qadam-web

Эта модель сохраняет единый публичный домен и текущую cookie-based auth схему.

4. Модель владения между командами

• Backend/platform-команда владеет qadam-core.
• Frontend-команда владеет qadam-web.
• Изменения API, Prisma, auth-модели, cookie policy и OpenAPI — зона ответственности qadam-core.
• Изменения UI, SSR, client routing, web UX и web runtime — зона ответственности qadam-web.
• Каноническая документация проекта живёт в qadam-core/docs.
• Локальные frontend-инструкции допускаются в qadam-web/docs, но не должны противоречить qadam-core/docs.

5. Граница взаимодействия между репозиториями

Источник истины по контракту

• Контракт рождается только в qadam-core.
• apps/api/openapi/openapi.json — канонический committed artifact.
• qadam-web/openapi/openapi.json — рабочее зеркало для frontend codegen.

Что frontend больше не должен делать

• Импортировать backend-исходники.
• Зависеть от Prisma или backend workspace-пакетов как от runtime/build prerequisite.
• Вводить ручной transport layer в обход generated contract без зафиксированной причины.

Что backend должен передавать frontend-команде

• обновлённый OpenAPI artifact;
• changelog изменений контракта;
• информацию о breaking changes;
• информацию о required env, migrations, flags и runtime-ограничениях.

6. Что ещё не доведено до зрелого состояния

Контрактный слой во frontend

• Generated contract ещё не покрывает admin API и остаточный legacy API-layer полностью.
• Нужно добить перевод старых ручных response/request типов на OpenAPI-generated слой.
• Нужно убрать прямые fetch-вызовы и несистемные transport-обходы в admin/reference и других остаточных срезах.

Структура qadam-web

• В репозитории остаются исторические дублирующиеся UI/API-слои: components, lib, src/components, src/lib.
• Нужно сократить legacy-код и убрать конкурирующие паттерны.

Auth и registration UX

• Frontend auth-скелет уже есть, но registration UI всё ещё не синхронизирован до конца с новым backend-контрактом register/buyer, register/seller и buyer profile flow.
• Нельзя считать web auth fully completed, пока qadam-web не перестанет опираться на legacy /auth/register как на рабочее допущение.

Delivery-контур

• Docker/image-based runtime ещё не стал каноническим способом доставки.
• CI/CD для split-репозиториев нужно довести до обязательного quality gate уровня.
• Нужен web smoke/e2e-контур для регрессионной защиты.

7. Следующий технический план

Этап 1. Контрактная стабилизация

• Дожать generated contract до admin API и остаточного legacy API-layer.
• Убрать ручной drift в qadam-web там, где уже есть OpenAPI.
• Зафиксировать и поддерживать единый handoff-процесс между командами.

Этап 2. Репозиторионная чистка

• Убрать исторически дублирующиеся frontend-слои и dead code.
• Убрать остаточное operational-использование /data/uzbek.
• Свести README, docs и actual runtime-контур к одному состоянию.

Этап 3. Quality gates

• Ввести минимальный web smoke/e2e-контур.
• Довести CI для qadam-core до обязательного check-types + test + build + export:openapi.
• Довести CI для qadam-web до обязательного generate:api-contract + check:api-contract + check-types + build.

Этап 4. Delivery

• Подготовить image-based delivery для qadam-core и qadam-web.
• Зафиксировать image naming, tagging и rollback-путь.
• После этого уходить от host-based deploy как от единственного production-контура.

8. Критерии зрелого post-cutover состояния

Модель split можно считать доведённой до конца, когда одновременно выполнены условия:

1. qadam-core и qadam-web являются единственными активными репозиториями новой разработки.
2. Frontend полностью собирается и развивается без доступа к старому общему workspace/legacy checkout.
3. Frontend получает основной API-контракт только через OpenAPI artifact и codegen.
4. Есть отдельный CI/CD и image-based delivery для обоих репозиториев.
5. Production и release-процесс не зависят от legacy workspace /data/uzbek.