# Памятка для frontend-команды

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

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

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

Этот документ фиксирует рабочую модель для отдельной frontend-команды, которая ведёт `qadam-web` независимо от backend-команды. Здесь зафиксированы репозитории, точки входа, контрактный процесс, правила handoff и минимальный release-gate.

## 1. Модель владения

- `qadam-web` ведёт отдельная frontend-команда.
- `qadam-core` ведёт backend/platform-команда.
- Источник истины по UI, frontend runtime и web delivery: `qadam-web`.
- Источник истины по API, Prisma, auth-модели, OpenAPI и канонической проектной документации: `qadam-core`.
- Production уже развернут из `qadam-core` и `qadam-web`.
- Внутри `qadam-web` теперь есть два приложения: `apps/web` и `apps/roadmap`. По умолчанию зона ответственности frontend-команды — `apps/web`; `apps/roadmap` считается внутренним сервисом документации и меняется только отдельным change package.
- Старый checkout `/data/uzbek` остаётся только как legacy-копия и не должен использоваться для новой разработки.

## 2. Канонические репозитории

- Frontend: `https://git.2fab.app/eldar/qadam-web.git`
- Backend и API-контракт: `https://git.2fab.app/eldar/qadam-core.git`

## 3. Каноническая документация и точки входа

- Общий индекс документации: [docs/README.md](../README.md)
- Roadmap проекта: [docs/project/roadmap.md](../project/roadmap.md)
- Execution checkpoints проекта: [docs/project/execution-checkpoints.md](../project/execution-checkpoints.md)
- Project change log: [docs/project/project-change-log.md](../project/project-change-log.md)
- Текущее состояние платформы и production: [docs/project/current-state.md](../project/current-state.md)
- Инженерные правила проекта: [docs/governance/engineering-principles.md](../governance/engineering-principles.md)
- Человекочитаемая карта API: [docs/architecture/api-routes.md](../architecture/api-routes.md)
- Общие API conventions: [docs/architecture/api-conventions.md](../architecture/api-conventions.md)
- Backend change-log для frontend-команды: [docs/frontend/frontend-change-log.md](./frontend-change-log.md)
- Frontend remediation backlog: [docs/frontend/frontend-adoption-backlog.md](./frontend-adoption-backlog.md)
- Документ о разделении репозиториев: [docs/frontend/frontend-separate-repo-plan.md](./frontend-separate-repo-plan.md)
- Локальная копия этой памятки во frontend-репозитории: `qadam-web/docs/frontend-handoff.md`
  Это намеренно более короткая локальная версия, чтобы не плодить два равноправных источника истины.

## 4. Swagger, OpenAPI и контрактные артефакты

### Runtime

- Swagger UI: `https://qadam.2fab.app/api/docs`
- OpenAPI JSON: `https://qadam.2fab.app/api/openapi.json`

### Версионируемые артефакты

В `qadam-core`:
- `apps/api/openapi/openapi.json`

В `qadam-web`:
- `openapi/openapi.json`
- `apps/web/src/shared/api/generated/openapi.d.ts`
- `apps/roadmap/` — отдельный внутренний сервис документации для домена `qadam-roadmap.2fab.app`

## 5. Быстрый старт для frontend-команды

```bash
git clone https://git.2fab.app/eldar/qadam-web.git
cd qadam-web
pnpm install
cp .env.example .env
pnpm generate:api-contract
pnpm dev
```

Если нужен локальный backend:

```bash
git clone https://git.2fab.app/eldar/qadam-core.git
cd qadam-core
pnpm install
cp .env.example .env
pnpm build
pnpm dev
```

## 6. Минимальная локальная связка для cookie-based auth

В `qadam-web/.env`:
- `NEXT_PUBLIC_API_URL=http://localhost:5001/api/v1`
- `API_URL=http://localhost:5001/api/v1`

В `qadam-core/.env`:
- `PORT=5001`
- `CORS_ORIGIN=http://localhost:3000`

Ожидаемая локальная схема:
- frontend: `http://localhost:3000`
- backend: `http://localhost:5001`

Такой режим сохраняет текущую браузерную cookie-based auth модель без самодельного frontend auth-обхода.

## 7. Ключевые переменные окружения frontend

Смотри `qadam-web/.env.example`.

Ключевые переменные:
- `NEXT_PUBLIC_API_URL` — публичный URL API для браузера
- `API_URL` — server-side URL API для Next.js server components и middleware
- `OPENAPI_SCHEMA_URL` — необязательный внешний источник схемы для codegen
- `QADAM_PROJECT_ROOT` — project root для roadmap/docs портала
- `QADAM_ROADMAP_STORAGE_DIR` — storage для загруженных roadmap-документов и комментариев

## 8. Канонический контрактный процесс

1. Изменение API начинается в `qadam-core`.
2. В `qadam-core` обновляется код, OpenAPI schema и `apps/api/openapi/openapi.json`.
3. Обновлённый artifact переносится в `qadam-web/openapi/openapi.json`.
4. Во frontend запускается `pnpm generate:api-contract`.
5. Только после этого меняются queries, mutations, server actions, UI и SSR-слой.

Frontend не должен придумывать собственные transport-типы поверх устаревшего контракта, если endpoint уже может быть описан в OpenAPI.

## 9. Распределение ответственности между командами

- Изменение API, DTO, auth-модели и OpenAPI artifact в `qadam-core` — ответственность backend/platform change package.
- Синхронизация `openapi/openapi.json` в `qadam-web` и прогон codegen — обязательная часть того же change package до передачи работы frontend-команде.
- Если frontend обнаружил contract drift, он не чинит типы вручную, а поднимает запрос на обновление backend artifact.
- Изменения UI и пользовательских сценариев в `qadam-web` не должны скрыто менять backend-контракт или auth-модель.

## 10. Release handoff между backend и frontend

Каждый backend change package, который меняет API или поведение web-flow, должен передаваться frontend-команде вместе с четырьмя обязательными артефактами:

- ссылка на commit или branch в `qadam-core`;
- обновлённый `apps/api/openapi/openapi.json`;
- запись в [docs/frontend/frontend-change-log.md](./frontend-change-log.md) по endpoint-уровню: что добавлено, что изменено, что несовместимо;
- явное указание, нужны ли новые env, migration, feature flag или UI-изменения.

Если пакет реально требует действий от frontend, он должен появиться в блоке `Что сейчас должна сделать frontend-команда` на `https://qadam-roadmap.2fab.app`, а frontend-команда после получения пакета должна отметить там один из статусов:

- `В работе`
- `Сделано`
- `Игнорировать`

Если запись changelog носит только информационный характер и не требует действий, backend-команда обязана явно указать в записи `Требуется действие frontend: нет`, чтобы на портале не показывались кнопки подтверждения.

Отдельно от backend handoff существует [frontend-adoption-backlog.md](./frontend-adoption-backlog.md): это remediation backlog по самому `qadam-web`, где фиксируются уже не backend deliverables, а текущие красные зоны frontend-кода и quality gate.

Каждый frontend release package, который зависит от нового backend-контракта, должен содержать:

- ссылку на commit в `qadam-web`;
- подтверждение, что `pnpm generate:api-contract` и `pnpm check:api-contract` пройдены;
- список маршрутов или сценариев, которые нужно smoke-проверить после релиза;
- указание, есть ли блокирующие backend gaps или временные product limitations.
- обновление статуса соответствующего backend-пакета на `qadam-roadmap.2fab.app`, если он был опубликован как `ready_for_frontend`.

## 10.1. Как реально происходит stage-релиз

Текущая каноническая модель такая:

- backend-команда и frontend-команда работают в своих репозиториях независимо;
- согласованный релизный момент наступает после merge в `main`;
- отдельный stage-сервер автоматически забирает `main` и разворачивает актуальную версию для UI-проверки;
- текущая машина не должна использоваться как обязательный ручной deploy-контур для frontend-проверок.

Практический вывод для frontend-команды:

1. работать в своей ветке;
2. закрывать package и PR;
3. подтверждать readiness относительно backend handoff;
4. после merge в `main` ждать stage auto deploy и уже там смотреть итоговую интеграцию.

## 11. Auth-контур, который нельзя менять молча

Для web-клиента каноническая модель авторизации сейчас такая:

- access cookie: `qadam_at`
- refresh cookie: `qadam_rt`
- основной браузерный сценарий: same-domain cookie auth
- bearer auth поддерживается backend как дополнительный режим для non-web клиентов, но не заменяет браузерный сценарий

Нельзя:

- переводить web на bearer-only модель без отдельного backend и infra решения;
- менять cookie naming, path, same-site policy или refresh-flow без синхронного backend/infrastructure change package;
- обходить `src/shared/api` и generated contract без явной и документированной причины;
- строить новый auth-layer только внутри `qadam-web`, если он расходится с `qadam-core`.

## 12. Минимальный acceptance gate

Для `qadam-web`:

- `pnpm generate:api-contract`
- `pnpm check:api-contract`
- `pnpm check-types`
- `pnpm build`

Для `qadam-core`, если change package меняет контракт:

- `pnpm export:openapi`
- `pnpm check-types`
- `pnpm test`
- `pnpm build`

## 13. Что нельзя делать

- Нельзя импортировать backend-исходники в `qadam-web`.
- Нельзя держать параллельные несинхронизированные OpenAPI artifacts.
- Нельзя использовать legacy workspace `/data/uzbek` как рабочую площадку новой frontend-разработки.
- Нельзя изменять API-модель на уровне UI-адаптеров без фиксации этого изменения в OpenAPI и документации.
- Нельзя передавать задачу между командами только устно, без commit/reference и без обновлённого контракта.