Структура пользовательского интерфейса

Обзор

Пользовательский интерфейс системы «СВЯЗКА» построен на React 19 с использованием TypeScript. Исходный код находится в каталоге frontend-react/src/. Сборка выполняется через Vite, стилизация --- через Tailwind CSS, компоненты интерфейса основаны на библиотеке Radix UI.

Каталог frontend-react/src/

src/
├── api/
│   └── client.ts              # прослойка обращений к серверу (Axios)
├── assets/
│   └── react.svg              # статические ресурсы
├── components/
│   ├── layout/                # общая разметка: обёртка и боковое меню
│   │   ├── Layout.tsx
│   │   └── Sidebar.tsx
│   ├── modals/                # всплывающие окна
│   │   ├── DocumentModal.tsx
│   │   ├── OriginalModal.tsx
│   │   ├── YandexImportModal.tsx
│   │   ├── MoveItemModal.tsx
│   │   ├── ModalContainer.tsx
│   │   └── index.ts
│   ├── ui/                    # базовые элементы интерфейса (Radix UI)
│   │   ├── badge.tsx
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   ├── dialog.tsx
│   │   ├── dropdown-menu.tsx
│   │   ├── input.tsx
│   │   ├── popover.tsx
│   │   ├── progress.tsx
│   │   ├── tabs.tsx
│   │   ├── toast.tsx
│   │   ├── toaster.tsx
│   │   └── tooltip.tsx
│   └── ColumnFilterPopover.tsx  # фильтрация по колонкам таблицы
├── hooks/                     # пользовательские перехватчики
│   ├── useModalRouter.ts      # управление окнами через адресную строку
│   ├── useToast.ts            # уведомления
│   └── useDebounce.ts         # задержка ввода
├── pages/                     # страницы приложения (по одной на маршрут)
│   ├── Dashboard.tsx
│   ├── Archive.tsx
│   ├── Processing.tsx
│   ├── DocTypes.tsx
│   ├── Groups.tsx
│   ├── Search.tsx
│   ├── Registries.tsx
│   ├── RegistryWizard.tsx
│   ├── RegistryResults.tsx
│   ├── Settings.tsx
│   └── YandexImports.tsx
├── types/
│   └── index.ts               # описания типов TypeScript
├── App.tsx                    # корневой компонент с маршрутизацией
├── main.tsx                   # точка входа приложения
├── App.css                    # стили приложения
└── index.css                  # глобальные стили

Назначение каталогов

api/

Единственный файл client.ts содержит все обращения к серверу. Используется библиотека Axios с базовым адресом, задаваемым переменной окружения VITE_API_URL. Подробнее --- в разделе «Прослойка обращений к серверу».

components/layout/

Два файла, формирующих общую разметку всех страниц:

• Layout.tsx --- обёртка, отрисовываемая для каждого маршрута. Включает боковое меню, область основного содержимого и контейнер для всплывающих окон. Состояние «свёрнуто/развёрнуто» боковой панели сохраняется в localStorage.
• Sidebar.tsx --- боковое меню с девятью пунктами навигации. Каждый пункт снабжён значком из библиотеки Lucide. При сворачивании панели названия пунктов скрываются, вместо них появляются всплывающие подсказки.

components/modals/

Всплывающие окна, открываемые поверх основного содержимого страницы. Управляются через параметры адресной строки (подробнее --- в описании перехватчика useModalRouter):

• DocumentModal.tsx --- окно просмотра и редактирования извлечённых данных документа.
• OriginalModal.tsx --- окно просмотра исходного файла (изображение страницы до обработки).
• YandexImportModal.tsx --- окно выбора файлов для импорта с Яндекс.Диска.
• MoveItemModal.tsx --- окно переноса файла или папки в другое место архива.
• ModalContainer.tsx --- контейнер, который считывает параметры из адресной строки и решает, какое окно отобразить.

components/ui/

Базовые элементы интерфейса, построенные на библиотеке Radix UI. Каждый компонент оборачивает соответствующий примитив Radix и добавляет стилизацию через Tailwind CSS с помощью вспомогательной функции cn(). Эти компоненты используются на всех страницах приложения: кнопки, карточки, диалоговые окна, вкладки, всплывающие меню, индикаторы прогресса, значки, поля ввода, уведомления и подсказки.

hooks/

Пользовательские перехватчики React:

• useModalRouter --- управляет состоянием всплывающих окон через параметры адресной строки (?doc=, ?original=, ?archive=). Поддерживает наложение окон друг на друга: например, окно просмотра исходника может открываться поверх окна документа.
• useToast --- система уведомлений. Одновременно отображается не более трёх уведомлений, каждое закрывается автоматически через пять секунд.
• useDebounce --- задержка обновления значения (используется для отложенного поиска при вводе текста).

pages/

Каждый файл соответствует одному экрану приложения. Все страницы подробно описаны в руководстве пользователя. Список маршрутов и соответствующих страниц приведён в разделе маршрутизация.

types/

Файл index.ts содержит описания типов TypeScript для всех основных сущностей: задание обработки (Job), документ (Document), группа документов (DocumentGroup), файл архива (ArchiveFile), узел дерева папок (FolderNode), сведения об использовании ресурсов (Usage), состояние пакетной обработки (BatchOverview) и вложенные типы для данных, извлечённых из содержимого файла, из имени файла и после дополнительной обработки.

Точка входа

Файл main.tsx создаёт корневой элемент React и отрисовывает компонент App в режиме строгой проверки (StrictMode).

Компонент App (App.tsx) настраивает:

1. Клиент запросов (React Query) --- время устаревания данных одна минута, повторный запрос при возврате к окну браузера отключён.
2. Маршрутизатор (React Router) --- определяет все маршруты приложения внутри общей разметки Layout.
3. Систему уведомлений (Toaster) --- глобальный компонент для вывода кратковременных сообщений.

Сборка и разделение кода

Vite разбивает итоговый код на несколько частей для ускорения загрузки:

Часть	Содержимое
vendor-react	ядро React
vendor-radix	компоненты Radix UI
vendor-query	React Query и Axios
vendor-charts	библиотека графиков Recharts
vendor-utils	прочие вспомогательные библиотеки

Сервер разработки запускается на порту 3000 и перенаправляет обращения /api/* и /health на серверную часть.

Используемые библиотеки

Библиотека	Версия	Назначение
React	19.2	основа пользовательского интерфейса
React Router	7.11	маршрутизация (переходы между страницами)
TanStack React Query	5.90	получение и сохранение данных с сервера
Radix UI	1.x	доступные базовые компоненты интерфейса
Axios	1.13	обращения к серверу по протоколу HTTP
Recharts	3.6	графики и диаграммы
Lucide React	---	значки интерфейса
Tailwind CSS	---	утилитарная стилизация
TypeScript	5.9	статическая типизация