Sauron Frontend

Frontend-приложение для мониторинга проектов, интеграций, постов, упоминаний, алертов и словарей.

Проект использует архитектуру FSD

Что умеет приложение

• выбор активной организации
• работа с проектами внутри организации
• просмотр постов и упоминаний
• управление правилами алертов
• создание и редактирование интеграций
• управление blacklist / whitelist / catastrophic lists
• просмотр dashboard-экранов
• настройки организации
• локализованный интерфейс
• аутентификация
• fallback 404

На login-странице также есть временные mock-аккаунты для быстрого входа в development/demo-сценариях: если выбранного mock-пользователя нет в backend, он создаётся автоматически при первом входе.

Технологический стек

• Vue 3
• TypeScript
• Vite
• Vue Router
• Pinia
• Pinia Colada
• Nuxt UI
• Vue I18n
• Zod
• @hey-api/openapi-ts
• Storybook
• Vitest
• Playwright
• Ultracite / Oxlint / Oxfmt

Архитектура

Слои

• src/app Точка входа, глобальные провайдеры, layouts, router.
• src/pages Route-bound экраны и page-level orchestration.
• src/widgets Крупные UI-секции, собирающие несколько features/entities.
• src/features Переиспользуемые бизнес-взаимодействия и view-model логика.
• src/entities Доменные сущности, API-обёртки, мапперы и типы.
• src/shared Инфраструктура: generated API client, базовые UI-компоненты, i18n, роуты, утилиты.

Что важно в этом проекте

• backend-контракты берутся из generated OpenAPI client
• Pinia Colada используется как основной механизм server state
• обычные Pinia stores применяются только для UI/client state и orchestration
• raw DTO не должны напрямую протекать в presentation, если нужна нормализация
• generated files в src/shared/api/generated/** считаются read-only

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

Поток данных в проекте выглядит так:

1. OpenAPI-спецификация лежит в openapi/openapi.yml.
2. Из неё генерируется клиент в src/shared/api/generated.
3. Глобальная конфигурация клиента задаётся в src/shared/api/config.ts.
4. Доменные обёртки над generated API лежат в src/entities/*/api.
5. Query/mutation flow строится через Pinia Colada.
6. Компоненты и страницы получают уже нормализованные данные через stores/composables.

Особенности API flow

• базовый URL читается из VITE_BACKEND_URL
• bearer token подставляется централизованно через setApiAccessToken()
• для HTTP-запросов включён timeout 5s
• timeout-ошибки нормализуются в читаемое для обычного пользователя сообщение с метаданными запроса

Полезные файлы:

State management

В проекте используются два уровня состояния:

1. Server state через Pinia Colada

Используется для:

• backend lists
• details
• loading / error / refresh state
• refetch и invalidation

Примеры:

• src/entities/project/api/projects.ts
• src/entities/integration/api/integrations.ts
• src/entities/mention/api/mentions.ts

2. UI/client state через Pinia stores

Используется для:

• выбранной организации
• активного проекта
• локальной session state
• modal/tab/filter state
• compose-level orchestration

Примеры:

• src/entities/organization/model/useOrganizationsStore.ts
• src/entities/project/model/useOrganizationProjectsStore.ts
• src/features/integration/model/useProjectBackendIntegrationsStore.ts
• src/features/keyword/model/useProjectKeywordListsStore.ts

Persistence

Через pinia-plugin-persistedstate сохраняются:

• user session
• selected organization

Файлы:

• src/app/providers/pinia.ts
• src/entities/user/model/useUserStore.ts

Основные страницы и пользовательские сценарии

Login

Файлы:

• src/pages/login/ui/LoginPage.vue
• src/widgets/login/ui/SignInForm/SignInForm.vue
• src/widgets/login/ui/SignUpForm/SignUpForm.vue
• src/widgets/login/ui/MockAccountsCard/MockAccountsCard.vue

Функции:

• sign in / sign up
• mock accounts для development/demo
• redirect на исходный маршрут после логина

Organization Selection

Файлы:

• src/pages/organization-selection/ui/OrganizationSelectionPage.vue

Функции:

• выбор активной организации
• создание организации
• переход к запрошенному ранее маршруту

Home

Файлы:

• src/pages/home/ui/HomePage.vue

Функции:

• список проектов текущей организации
• создание/редактирование/удаление проекта
• входная точка в project workspace

Project Workspace

Файлы:

• src/pages/project/ui/ProjectPage/ProjectPage.vue

Вкладки:

• mentions
• overview
• alerts
• integrations
• lists

Dashboards

Файлы:

• src/pages/data/**

Settings

Файлы:

• src/pages/settings/ui/SettingsPage.vue

Функции:

• просмотр organization metadata
• редактирование текущей организации из general settings

Not Found

Файлы:

• src/pages/not-found/ui/NotFoundPage.vue

Роутинг

Основной router:

• src/app/providers/router.ts

Основные маршруты:

• /
• /login
• /organizations/select
• /dashboards
• /projects
• /user
• /settings
• catch-all 404

Route guard:

• если организация не выбрана, пользователь переводится на экран выбора организации
• login / organization selection / 404 работают в plain layout

Константы маршрутов лежат в:

• src/shared/model/routes.ts

UI, i18n и layouts

UI

Базовый UI построен на Nuxt UI.

Точка входа:

• src/main.ts

Shared UI primitives:

• src/shared/ui/**

Локализация

Локали:

• en
• ru

Файлы:

• src/shared/lib/i18n/config.ts
• src/shared/lib/i18n/messages/en.ts
• src/shared/lib/i18n/messages/ru.ts

Layouts

Файлы:

• src/app/layouts/DefaultLayout.vue

В проекте есть:

• dashboard-layout для основных внутренних экранов
• plain-layout для login, organization-selection и 404

Несколько полезных мест для старта

• src/main.ts
• src/app/providers/router.ts
• src/app/layouts/DefaultLayout.vue
• src/shared/api/config.ts
• src/pages/home/ui/HomePage.vue
• src/pages/project/ui/ProjectPage/ProjectPage.vue

Тестирование

Unit tests

Vitest работает в jsdom.

Конфиг:

• vitest.config.ts

E2E

Используется Playwright.

Конфиг:

• playwright.config.ts

Поведение:

• локально использует dev server
• в CI использует preview server

OpenAPI и generated code

Спецификация:

• openapi/openapi.yml

Генерация:

• openapi-ts.config.ts

Выход:

• src/shared/api/generated

Важно:

• при изменении backend contract сначала обновляется OpenAPI spec, затем регенерируется клиент

INfo

• timeout API-запросов установлен в 5 секунд
• на login-странице есть mock-аккаунты для быстрого входа
• на mentions-экране в development могут использоваться локальные mock data, если backend ещё не отдаёт упоминания
• в репозитории есть legacy-папка src/ogranization с опечаткой в названии; она не является основной архитектурной точкой входа

Полезные документы внутри репозитория