anal-front/docs/architecture.md

Архитектура проекта

Дата актуализации: 2026-06-22

Базовый принцип

Проект следует Feature-Sliced Design в прагматичном варианте: слой добавляется только тогда, когда у него есть реальная ответственность. Главный рабочий поток сейчас построен вокруг страниц auth и dashboard, защищенного layout и общего shared-инструментария.

Слои

src/
  app/       # инициализация приложения, router, providers, базовые стили
  pages/     # route-level страницы и их page-specific model/api/ui
  widgets/   # крупные композиционные блоки, собирающие entities/features/shared
  entities/  # доменные сущности
  shared/    # инфраструктура, API client, базовый UI, helpers, local UI-kit

features сейчас не используется намеренно. Например, logout используется только внутри widgets/protected-app-layout, поэтому orchestration живет в widget model, а не в отдельном feature slice. Если действие начнет использоваться в нескольких независимых flows, его можно поднять в features/logout-session.

Правила импортов

• Верхние слои могут импортировать нижние: app -> pages -> widgets -> features -> entities -> shared.
• Нижние слои не импортируют верхние.
• Между слайсами одного слоя не должно быть cross-imports.
• Внутри одного слайса допускаются относительные импорты между сегментами.
• Внешний код импортирует слайс через public API index.ts.
• Generated API не импортируется напрямую из app/pages/widgets/entities. Используется facade @/shared/api.

Текущие ключевые слайсы

pages/dashboard

src/pages/dashboard/
  api/
    competenceMapAnalyticsApi.ts
  model/
    chartData.ts
    constants.ts
    dashboardStore.ts
    emptyState.ts
    error.ts
    filterDefinitions.ts
    filterDraft.ts
    filters.ts
    formatters.ts
    queryKeys.ts
    sorting.ts
    tooltip.ts
    types.ts
  ui/
    DashboardPage.vue
    ReportsView.vue
    CompetenceMapFilters.vue
    CompetenceMapToolbar.vue
    components/
    styles/

Dashboard page владеет аналитическими фильтрами, вкладками, API wrappers, DTO-to-view helpers, табличной сортировкой, tooltip templates и page-specific компонентами. TanStack Query отвечает за server state cache; ручной response cache удален.

pages/auth

src/pages/auth/
  model/
    loginSchema.ts
    redirect.ts
    useAuthLogin.ts
  ui/

UI формы не содержит schema и redirect validation. Эти правила находятся в model-сегменте и покрыты unit-тестами.

widgets/protected-app-layout

Widget собирает защищенную часть приложения: header, sidebar, page content, footer и scroll-up. Здесь живут current-user composition, logout orchestration, sidebar route matching, route preload и persisted expanded groups. shared/ui/AppSidebar остается pure UI и не знает про Vue Router.

shared/api

Содержит API client, auth token primitives, refresh/session infrastructure, error normalization, generated API и public facade. Прикладной код импортирует endpoint functions и DTO-типы через @/shared/api, а не из generated-api.

Generated и vendor-зоны

Эти зоны исключены из FSD/formatting-оценки как generated/vendor:

• src/shared/api/generated-api
• src/shared/model/generated-zod
• src/shared/ui-kit

Ручные wrappers, adapters и page models не должны попадать в эти исключения.

Проверки архитектуры

Основная команда:

bun run check:full

Она запускает ESLint, Steiger, unit tests, typecheck/build и Playwright E2E. Для быстрой проверки FSD-границ:

bun run lint:fsd

Перед передачей изменений заказчику lint:fsd должен проходить без ошибок или иметь явно задокументированное точечное исключение.