ticket-system/frontend-client/FRONTEND_ARCHITECTURE.md

Архитектура Frontend-клиента (Next.js 14)

1. Базовые принципы

• Стек: Next.js 14 (App Router), React 18, TypeScript, Tailwind CSS.
• UI/UX: Темная тема (#121212), акцентный цвет #E32636. Иконки — строго lucide-react.
• Компоненты: Никакого кастомного CSS. Только утилитные классы Tailwind.

2. Управление состоянием (State Management)

• Глобальный стейт (Zustand):
  • authStore: Хранит JWT-токен и данные профиля. Обязательно использовать persist middleware (хранить в localStorage).
  • cartStore: Хранит выбранные места (CartSeat с ticketId). ЗАПРЕЩЕНО использовать persist. Корзина живет только в памяти страницы, так как лок места на бэкенде временный (TTL в Redis).

3. Работа с API и Сетью (КРИТИЧЕСКИ ВАЖНО)

• Базовый URL: ЗАПРЕЩЕНО хардкодить localhost или прямые IP в исходном коде. Всегда использовать process.env.NEXT_PUBLIC_API_URL с фоллбэком.
• Клиент: Axios инстанс (src/api/client.ts).
• Авторизация: Интерсептор автоматически добавляет Authorization: Bearer <token> из authStore.
• Обработка ошибок: Все вызовы API оборачивать в try/catch. Бизнес-ошибки (например, 409 Conflict) обрабатывать локально с показом Toast-уведомлений.

4. Структура директорий

• src/app/ — Роутинг (Pages, Layouts).
• src/components/ — Переиспользуемые UI компоненты.
• src/api/ — API-клиенты и типизация ответов бэкенда.
• src/store/ — Zustand-хранилища.

5. Интерактивность и Навигация (КРИТИЧЕСКИ ВАЖНО)

• ЗАПРЕЩЕНО создавать "мертвые" кнопки навигации.
• Любой элемент UI, который визуально выглядит как кнопка перехода на другую страницу, ОБЯЗАН быть обернут в компонент <Link href="..."> из next/link или иметь обработчик onClick={() => router.push('...')}.
• Если для кнопки пока нет API (например, Apple Wallet), она должна выводить toast("Функция в разработке").

6. Карта маршрутизации (Screen Flow)

[ Каталог турниров : / ] (Главная) ├── Клик по турниру ──> [ Схема зала : /events/[id]/seats ] │ ├── Клик "Назад" ──> (возврат на /) │ └── Клик "Оплатить" ──> [ Оформление заказа : /checkout ] │ └── Успех ──> [ Мои билеты : /tickets ] │ ├── Клик в TabBar "Билеты" ──> [ Мои билеты : /tickets ] (Требует авторизации) │ └── Клик по карточке ──> [ Электронный билет (QR) : /tickets/[ticket_id] ] │ └── Клик "Назад" ──> (возврат на /tickets) │ └── Клик в TabBar "Профиль" ──> [ Профиль : /profile ] (Если нет токена -> редирект на /login)