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

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

- Статус документа: working reference
- Актуально на: 28 марта 2026 года
- Владелец: backend/platform-команда
- Пересмотр: при изменении backend/frontend handoff-процесса, ownership-модели или API change workflow
- Область применения: операционная модель взаимодействия backend/platform-команды и отдельной frontend-команды
- Связанные документы:
  - [Карта API-маршрутов](../architecture/api-routes.md)
  - [Текущее состояние](../project/current-state.md)
  - [Инженерные принципы](../governance/engineering-principles.md)

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

Этот документ больше не описывает гипотетический 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 проект должен жить в такой схеме:

```text
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`.