Partizap Frontend — Brainstorm Log

Date: 2026-02-03 Participants: Dmitriy + Claude (Opus 4.5) Goal: Определить архитектуру фронтенда для маркетплейса автозапчастей Partizap

Входные данные

Документы, использованные в брейншторме

Документ	Путь	Роль
MVP Design v2.9	`approved/partizap_mvp-design.md`	Канонический источник по бэкенду
Контракты v5	`approved/partizap_ADR/autoparts-contracts-v5.md`	Схема БД, связи, домены
DB Structure JSON	`approved/partizap_DB-structure.json`	Source of truth по схеме (27 таблиц)
Wireframes	`autoparts-wireframes.vue`	Vue 3 SFC, 6 экранов (desktop + mobile)
ТЗ основное	`ТЗ основное.md`	Бизнес-требования на русском
Conversation log	`conversion.txt`	Предыдущие решения и разрешённые противоречия
ADR-001..009	`approved/partizap_ADR/`	Устаревшие (Medusa.js), заменены MVP design

Зафиксированные ранее решения (из conversion.txt)

Backend: PHP Slim 4 (НЕ Medusa.js)
Auth: PHP Sessions + HttpOnly cookies (НЕ JWT)
Pagination: Cursor-based с HMAC-signed cursors (НЕ offset)
IDs: SERIAL integers (НЕ UUID v7)
Schema source: DB JSON (27 таблиц) — каноничен
Deploy: VPS (Hetzner/Selectel)

Принятые решения (в хронологическом порядке)

1. Режим рендеринга

Вопрос: SSR / SSG / Hybrid?

Решение: Hybrid

SSR для публичных страниц (SEO-критичные: каталог, карточки, профили)
SPA для приватных (кабинет, добавление объявления)
Конфигурация через routeRules в nuxt.config.ts

2. UI-компоненты

Вопрос: Nuxt UI / PrimeVue / Headless (Reka UI + Tailwind)?

Решение: Nuxt UI

Глубокая интеграция с Nuxt
Построен на Tailwind + Reka UI (headless)
Темизация, доступность из коробки

3. State management

Вопрос: Pinia / Composables only / Гибрид?

Решение: Pinia + composables гибрид

Pinia для глобального состояния (auth, geo, favorites)
Composables для локального (фильтры каталога, формы, UI-состояние)
Правило: если состояние нужно на 2+ несвязанных страницах — Pinia, иначе composable

4. API-клиент

Вопрос: useFetch/$fetch / Кастомный клиент на ofetch / Axios?

Решение: useFetch / $fetch (встроенный ofetch)

Обёртка для CSRF (читает cookie, ставит X-CSRF-TOKEN)
Проброс session cookie при SSR через useRequestHeaders
Типизированные endpoint-функции в entities/*/api/

5. Структура проекта

Вопрос: Feature-based / Nuxt-стандартный / FSD-адаптированный / Nuxt Layers?

Контекст: Высокая вероятность масштабирования с MVP. Обсуждалась целесообразность FSD.

Решение: FSD-адаптированный под Nuxt

Стандартные Nuxt-директории для роутинга (pages/, server/)
Бизнес-логика в FSD-структуре (shared, entities, features, widgets)
Модуль nuxt-fsd для авто-импорта и защиты от нарушения слоёв
Dependency rule: shared → entities → features → widgets → pages

6. Формы

Вопрос: Nuxt UI Form + Zod / VeeValidate + Zod / Кастомные composables?

Решение: Nuxt UI Form + Zod

<UForm> с нативной поддержкой Zod-схем
Схемы валидации в entities/ — переиспользуются на Nitro-сервере

7. Изображения

Вопрос: @nuxt/image / Кастомный <img>?

Решение: @nuxt/image

<NuxtPicture> для WebP + JPEG fallback
Lazy loading, responsive srcset
Загрузка (upload) — кастомный composable useImageUpload

8. Интернационализация

Вопрос: Без i18n на MVP / @nuxtjs/i18n сразу?

Решение: @nuxtjs/i18n сразу

Русский как основной, структура готова к добавлению языков
Несмотря на YAGNI — пользователь решил заложить

9. SEO

Вопрос: @nuxtjs/seo (комбайн) / useSeoMeta + ручная настройка?

Решение: @nuxtjs/seo

Schema.org (Product, Offer, LocalBusiness)
Динамический sitemap
robots.txt
OG-images

10. Версия Nuxt

Вопрос (добавлен при написании плана): Nuxt 3 (EOL 31 июля 2026) или Nuxt 4 (stable v4.3)?

Решение: Nuxt 4

Nuxt 3 EOL через ~6 месяцев
Nuxt 4 стабильный, новая app/ директория нативно поддерживает FSD
Nuxt UI v4 требует Nuxt 4
Нет необходимости в миграции через полгода

Итоговый tech stack

Категория	Решение
Framework	Nuxt 4 (v4.3+)
Language	TypeScript (strict)
UI	Nuxt UI v4 (Tailwind 4 + Reka UI)
State	Pinia + composables
API	$fetch / useFetch + CSRF wrapper
Forms	Nuxt UI `<UForm>` + Zod
Images	@nuxt/image (`<NuxtPicture>`)
i18n	@nuxtjs/i18n
SEO	@nuxtjs/seo
Architecture	FSD (nuxt-fsd module)
Testing	Vitest + @nuxt/test-utils
Linting	@nuxt/eslint + Prettier
Rendering	Hybrid (SSR + SPA route rules)
Deploy	Node.js (Nitro) на VPS

Артефакты

Файл	Описание
`docs/plans/2026-02-03-frontend-architecture-design.md`	Дизайн-документ (8 секций, утверждён)
`docs/plans/2026-02-03-frontend-init-plan.md`	Implementation plan (15 tasks)
`docs/plans/2026-02-03-frontend-brainstorm-log.md`	Этот файл — лог брейншторма

Ключевые архитектурные решения, требующие внимания при реализации

CSRF: PHP отдаёт CSRF_TOKEN cookie, фронтенд читает и ставит в X-CSRF-TOKEN header на мутирующие запросы
SSR cookie forwarding: При серверном рендеринге Nitro проксирует cookies пользователя к PHP API через useRequestHeaders(['cookie']), ответные Set-Cookie пробрасываются обратно
Cursor pagination UI: Wireframes показывают numbered pagination, но cursor-based не поддерживает произвольный переход — реализовывать как "Загрузить ещё"
Deferred features в UI: SMS-авторизация, сообщения, отзывы — UI-заглушки готовить, но функционал отложить
Телефон продавца: В products нет поля phone — загружать через отдельный endpoint по клику "Показать телефон"
Geo persistence: Cookie geo_city_id для SSR + клиент; для залогиненных — синхронизация с users.city_id
FSD discipline: Строгий dependency rule через nuxt-fsd preventCrossImports

Partizap Frontend — Brainstorm Log ​

Входные данные ​

Документы, использованные в брейншторме ​

Зафиксированные ранее решения (из conversion.txt) ​

Принятые решения (в хронологическом порядке) ​

1. Режим рендеринга ​

2. UI-компоненты ​

3. State management ​

4. API-клиент ​

5. Структура проекта ​

6. Формы ​

7. Изображения ​

8. Интернационализация ​

9. SEO ​

10. Версия Nuxt ​

Итоговый tech stack ​

Артефакты ​

Ключевые архитектурные решения, требующие внимания при реализации ​