Перейти к основному содержимому

ADR 0008 — Frontend stack для Оптимы

Копия ADR из репозитория: backend/docs/adr/0008-frontend-stack.md. Канонический текст — в репозитории; портал обновляется командой npm run sync:adr.

Дата: 2026-06-11 Статус: Принято

Контекст​

Backend готов (auth, WB-accounts, catalog, RBAC). Frontend был пустой заготовкой. Нужен веб-интерфейс для селлера: dashboard, продукты, заказы, аналитика. API — отдельный NestJS на api.optimawb.ru, контракт в OpenAPI.

Решение​

Стек: Next.js 16 (App Router) + React 19 + TypeScript + Tailwind CSS v4 + shadcn/ui Pkg manager: npm Server state: TanStack Query E2E: Playwright Unit tests: Vitest

Обоснование​

  • Next.js App Router — гибрид: публичные страницы (лендинг, вход) с SSR/SSG, dashboard — client-heavy с TanStack Query.
  • shadcn/ui — готовые accessible-компоненты под формы и таблицы селлера.
  • OpenAPI codegen — type-safe клиент к существующему NestJS API.
  • Standalone Docker — совместимость с Coolify (output: "standalone").
  • Инфраструктура mono-loop (/op, Gate 1, CI-шаблоны) уже рассчитана на этот стек.

Последствия​

Положительные​

  • Единый TypeScript-стек с backend.
  • Готовые CI/CD и Dockerfile.
  • Playwright e2e в Gate 1.
  • shadcn/ui ускоряет UI-модули.

Отрицательные / trade-offs​

  • Node runtime в production (не static nginx-only SPA).
  • Next.js сложнее Vite SPA; SSR не нужен для 90% экранов за логином.
  • SEO публичного контента частично дублируется Docusaurus (docs.optimawb.ru).

Альтернативы рассмотрены​

ВариантПочему не выбран
Vite + React Router (SPA)Проще деплой, но нет SSR для лендинга; расходится с M6-планом
RemixМеньше экосистема/шаблонов в репозитории
Nuxt / SvelteKitКоманда и mono-loop ориентированы на React

Что меняется в инфраструктуре​

  • frontend/ scaffolded (Next.js + shadcn + TanStack Query + Playwright + Vitest)
  • frontend/CLAUDE.md создан
  • .github/workflows/frontend-ci.yml создан
  • Coolify app optima-frontend → optimawb.ru
  • Gate 1 расширен на frontend (lint, typecheck, test, build, e2e)

Связанные​

  • ADR-0012 — app shell, маршруты, navigation registry
  • M6 plan: docs/superpowers/plans/2026-06-04-m6-frontend-onboarding.md
  • Spike walkthrough: docs/superpowers/guides/frontend-spike-walkthrough.md