Qadam Roadmap
← Назад к библиотеке
проектdocs/frontend/frontend-handoff.md

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

Обновлён 14 апр. 2026 г., 17:16 · 0 комментариев

ИсходникСкачать

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

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

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

Этот документ фиксирует рабочую модель для отдельной 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. Каноническая документация и точки входа

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-команды

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:

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 по endpoint-уровню: что добавлено, что изменено, что несовместимо;
  • явное указание, нужны ли новые env, migration, feature flag или UI-изменения.

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

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

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

Отдельно от backend handoff существует 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 и без обновлённого контракта.