Описание каталогов для Backend compose - Используется для хранения конфигурационных файлов, связанных с Docker Compose. Docker Compose - это инструмент для определения и запуска многоконтейнерных Docker-приложений. Он использует YAML-файлы для описания конфигурации приложения, включая определение различных сервисов (контейнеров), их зависимостей, сетевых настроек, томов и других параметров. Каталог "compose" используется для централизованного хранения всей конфигурационной информации, необходимой для развертывания многоконтейнерного приложения с помощью Docker Compose. config - Содержит в себе конфигурационные файлы в формате JSON. Эти конфигурационные файлы предназначены для централизованного хранения и управления различными настройками, используемыми в системе. Такой подход позволяет легко настраивать и изменять параметры без необходимости вносить изменения в исходный код. dist - Содержит в себе скомпиленные файлы конфигурации для билда проекта. Папка dist (от слова distribution - “распределение”) используется для хранения оптимизированных файлов рабочего сайта. docs - Хранит всю документацию по коду проекта. От проекта к проекту содержимое каталога может отличаться, но вот основное содержимое папки docs:
catalogs/ - Содержит файлы с названием всех сущностей в переводе на русский язык. commands.md - файл, который содержит описание всех команд по бэку. launch.md - файл, который содержит команды, необходимые для запуска проекта с помощью контейнера. node_modules - Хранит все установленные в проекте пакеты (библиотеки, фреймворки и другие зависимости), необходимые для работы проекта. В контексте веб-разработки, каталог node_modules является очень важной частью любого проекта, использующего Node.js и пакетный менеджер, такой как npm или yarn (в нашем случае второй вариант). Когда мы устанавливаем пакеты в проект с помощью команды yarn add <package>, эти пакеты загружаются и сохраняются в каталоге node_modules. Рассмотрим основные функции каталога node_modules: Хранение зависимостей: Все установленные в проекте пакеты, их версии и связи между ними сохраняются в этом каталоге. Обеспечение доступа к пакетам: Код проекта может импортировать и использовать любые пакеты, находящиеся в node_modules. Управление версиями: Каждый пакет устанавливается в свою собственную папку внутри node_modules, что позволяет избежать конфликтов версий между пакетами. Ускорение разработки: Не нужно вручную загружать и управлять каждой зависимостью - пакетный менеджер автоматически устанавливает и обновляет необходимые пакеты. prisma - Содержит файлы и подкаталоги для работы с базой данных. Cодержит следующие файлы и подкаталоги: schema.prisma: Это основной файл конфигурации Prisma, где определяются модели данных, соединения с базой данных и другие настройки. migrations/: Этот каталог содержит SQL-файлы с миграциями, которые представляют изменения, внесенные в схему базы данных. Миграции позволяют отслеживать и управлять изменениями в структуре базы данных. src - Основной каталог, содержащий исходный код проекта. Содержит следующие подкаталоги:
adm - Содержит файлы и подкаталоги, связанные с административными и управленческими компонентами приложения. Вот примерное содержимое папки adm: authRoutes/: Этот подкаталог и файлы содержащиеся внутри него предназначены для получения информации о текущих логинах пользователя, аутентифицированных в запросе. config/: В этом подкаталоге содержится файл passport.ts для настройки аутентификации администраторов (admins) в веб-приложении. graph/: Содержит подкаталог services, в котором определяются типы и резолверы. services/: В этом каталоге определяются конфигурации для сервиса. businessTests - Содержит подкаталоги и файлы с тестами. В разных проектах будут разные тесты, связанные с определенными запросами и сервисами. cli - Каталог для запуска одноразовых скриптов. Во всех проектах содержится файл helloCtx.ts, в котором с помощью createContext() создаётся контекст приложения. После чего, он получает доступ к нужному сервису и вызывает различные методы. Запускается скрипт при помощи команд, прописанных в начале файла. Содержит следующие подкаталоги:
decorators - Содержит файл Cacheable.ts, в котором представлена реализация декоратора Cacheable. Данная реализация направлена на повышение производительности и эффективности приложения за счет кэширования результатов выполнения методов, с учетом ограничений на размер и время жизни кэша. gen - Содержит файл genGQSchemes.ts, который описывает скрипт для генерации TypeScript-файлов для GraphQL API. Он использует библиотеку @graphql-codegen/core и несколько плагинов для этой библиотеки, чтобы сгенерировать TypeScript-типы и резолверы на основе существующей GraphQL-схемы. generated - Содержит сгенерированные Prisma файлы. Папка graph содержит файлы, связанные с GraphQL-компонентами приложения. Вот стандартное содержимое папки graph:
Файл typeDefs.ts, обеспечивает централизованное управление определениями типов GraphQL, загружая их из различных файлов и объединяя их в единое определение mergedTypeDefs. Это упрощает организацию и использование типов GraphQL в приложении. Файл resolvers.ts, обеспечивает централизованное управление resolver-функциями GraphQL-API, загружая их из различных файлов и объединяя их в единый объект mergedResolvers. Это упрощает организацию и использование resolver-функций в приложении. Файл schema.ts, создает единую GraphQL схему, объединяя определения типов (typeDefs) и resolvers (resolvers). Это упрощает управление GraphQL-схемой в приложении, так как все необходимые компоненты объединены в одном месте. init - Каталог, который хранит в себе проиниченные сущности. рассмотрим следующее содержимое: Папка common - После того, как мы внесём в meta/addCatalogs.ts предзаполненные поля, с помощью метода .addPredefinedElements и выполним yarn regen создастся файл в этой папке, который будет содержать enum для той сущности, для которой были предзаполнены поля. Папка elastic - Содержит следующие файлы: bootstrap.ts - описывает функцию для создания и управления индексами в Elasticsearch (Elasticsearch - это распределенная, высокопроизводительная система поиска и анализа данных). Основная задача этого кода - гарантировать, что все необходимые индексы Elasticsearch созданы и находятся в правильном состоянии. Он позволяет легко управлять индексами, включая удаление и повторное создание при необходимости. genJobs.ts - В этом файле генерируется объект genJobs, который принимает тип ElasticJobs (экспортируется из файла type.ts) с конфигурациями для различных типов сущностей. Папка roles - Отвечает за управление ролями и правами доступа пользователей. В файле initRolesToPermissions.ts определяются наборы разрешений для различных ролей, таких как: Администратор информационной безопасности (InformationSecurityAdmin) Центр компетенций (CompeetenceCenter) Поддержка приложений (ApplicationSupport) Специалист по маркетингу (MarkertingSpecialist) А также, формируется массив объектов permissionsOfRole, где каждый объект содержит идентификатор роли и массив идентификаторов разрешений, назначенных этой роли. Файл initTestManagers.ts - Содержит набор тестовых учетных записей менеджеров с предопределенными ролями (например: менеджер, администратор, комментатор, аналитик и тд.) для тестирования приложения. Это позволяет легко инициализировать необходимые учетные записи пользователей без необходимости создавать их вручную. integrationClients - Нужно придумать название для этого каталога В IntegrationClient.ts реализуется класс IntegrationClient, который является оберткой для других методов, обеспечивая дополнительные возможности, такие как отслеживание запросов, обработка ошибок и мониторинг производительности. В файле hooksTypes.ts определены три интерфейса ClientBeforeRequestArgs, ClientAfterRequestArgs и ClientOnErrorArgs, которые описывают форму данных, передаваемых различным функциям обратного вызова в клиентском приложении. Они используются в качестве типов для аргументов в методах beforeRequest(), afterRequest() и onError() соответственно. meta - Содержит описание всех сущностей в проекте. В файле addCatalogs.ts определяется общая структура данных, включая их основные атрибуты (название сущности, её полей и их типов), связи с другими объектами и ограничения на заполнение полей. В файле addMenu.ts определяется структура меню навигации для проекта. Сначала создаётся новая группа меню с заголовком и иконкой, затем указываются все пункты входящие в это меню. types - Каталог, содержащий определения енумов TypeScript для различных сущностей в проекте. utils - Каталог, содержащий вспомогательные функции, константы и другие утилиты. workers - Содержит файлы, в которых выполняются разные задачи в определенной последовательности для конкретных сущностей. К примеру, в папке aggregates в файле aggregatesWorker.ts происходит обработка различных фоновых задач, связанных с вычислением и пересчетом различных типов агрегатов, таких как данные о пассажирах, билетах и перевозчиках. Описание каталогов для Frontend docs - Хранит всю документацию по коду проекта. commands.md - файл, который содержит описание всех команд по фронту. configuration.md - файл, который служит для документирования и управления конфигурацией проекта. Он описывает, как проект загружает свои конфигурации из двух источников: файлов конфигурации и переменных окружения. Ниже будут кратко описаны основные цели этого файла:
Определение источников конфигурации:
Описывается, что конфигурация загружается из файлов default.json и ${ENV}.json, а также из переменных окружения. Переменные окружения имеют приоритет. Обработка конфигурационных файлов:
Уточняется, как происходит загрузка конфигурации из файлов, включая информацию о том, что если оба файла существуют, они будут объединены, и ${ENV}.json будет иметь приоритет. Предупреждение о безопасности:
Указано, что файл default.json хранится в системе контроля версий (git), поэтому важно не включать в него секретную информацию (например, пароли и учетные данные базы данных). Документация переменных конфигурации:
Таблица предоставляет информацию о каждой конфигурационной переменной, включая её ключ, соответствующую переменную окружения, тип, обязательность, значение по умолчанию и назначение. node_modules - Аналогично каталогу на бэкенде. В данном каталоге содержатся все установленные пакеты. Если в проекте нет нужных зависимостей, то их можно добавить уже ранее упомянутой командой yarn add <package> и по завершению установки в node_modules добавится папка с названием этого пакета.
src/ - Основной каталог, содержащий исходный код проекта. Может содержать следующие каталоги: Папка adm содержит файлы и подкаталоги, связанные с административными или управленческими компонентами приложения. Вот содержимое папки adm:
После создания новой сущности в мете и выполнения команды yarn regen в этом каталоге автоматически генерируется папка с названием той сущности, которую добавили. А также в ней буду созданы дефолтные папки для:
создания новой записи (Create), для редактирования (Edit), Например, мы создаём сущность для пользователей (users), для неё у нас будет создана папка users с подпапками UserCreate, UserEdit, UserList и UserShow.
В этих папках будут находиться дефолтные (с пометкой DO NOT EDIT! THIS IS GENERATED FILE) файлы, например DefaultUserCreate.tsx, DefaultUserEdit.tsx, DefaultUserList.tsx и DefaultUserShow.tsx. А также в каждой папке будет находиться файл index.tsx, в котором импортируется дефолтный файл.
Если потребуется изменить какую-либо страницу, то в таком случае создаётся кастомный файл, для этого копируем дефолтный файл и переименовываем с Default в Custom. После чего в файле index.tsx меняем импорт на нужный.
В этом каталоге содержится файл DebugPage.tsx, который предоставляет интерфейс для переключения режима отладки и отображения информации о ролях и разрешениях пользователю. Он позволяет разработчикам легко видеть текущие роли и разрешения.
Содержит файлы для отображения виджетов на странице Этот каталог содержит файлы для настройки и инициализации клиента Apollo, который используется для взаимодействия с GraphQL API. К примеру, в файле getApollo.tsx создаётся клиент Apollo, который будет использоваться для выполнения запросов к GraphQL API, а также происходит обработка ошибок, загрузка файлов и настройка кеширования ответов для оптимизации работы с данными.
authProvider -Каталог, предназначенный для управления аутентификацией и авторизацией пользователей. config - Каталог, для хранения конфигураций. Содержит два файла, рассмотрим назначение каждого из них:
config.ts - файл представляет собой функцию getConfig, которая используется для загрузки конфигурации приложения из внешнего JSON-файла (/config.json) и объединения её с переменными окружения. Подробное описание цели этого файла: Загрузка конфигурации:
Функция отправляет запрос на получение конфигурационного файла (config.json), который содержит настройки приложения, такие как API-эндпоинты, ключи и другие параметры. Объединение с переменными окружения:
После получения данных из config.json, функция проверяет, есть ли соответствующие переменные окружения. Если они определены (например, VITE_APP_ADMIN_RECAPTCHA_PUBLIC_KEY), то они имеют приоритет и заменяют значения из JSON. Это позволяет легко изменять конфигурацию приложения без необходимости редактирования файла. Возвращение конфигурации:
Функция возвращает промис, который разрешается в объект, содержащий объединенные конфигурационные параметры. Это позволяет другим частям приложения легко получать доступ к настройкам. Файл config.ts с функцией getConfig служит для гибкой и безопасной конфигурации приложения, обеспечивая удобный способ загрузки и объединения настроек.
envConfig.ts - файл определяет объект envConfig, который используется для хранения конфигурационных значений, связанных с окружением приложения. Подробное описание цели этого файла: Определение конфигурации окружения:
Объект envConfig содержит параметры, которые могут изменяться в зависимости от среды, в которой выполняется приложение (например, разработка, тестирование или продакшн). Хранение переменных окружения:
Поле spaces получает значение из переменной окружения REACT_APP_SPACES. Если переменная не установлена, используется значение по умолчанию — строка '{SPACES}'. Это позволяет разработчикам легко настраивать приложение с помощью переменных окружения. Гибкость и удобство:
Объект envConfig позволяет централизованно управлять конфигурацией, что упрощает доступ и изменение значений в разных частях приложения. Файл envConfig.ts с объектом envConfig служит для хранения и управления конфигурационными значениями окружения приложения, обеспечивая гибкость и безопасность в настройках.
contexts - разберусь позже dataProvider - Каталог, содержащий логику взаимодействия с GraphQL API через клиент Apollo. В этом каталоге есть файл getCustomMethods.ts, который содержит функцию getCustomMethods. Этот метод принимает экземпляр ApolloClient и возвращает объект с методами для взаимодействия с GraphQL API. Эти методы позволяют выполнять различные операции, такие как запросы и мутации. После чего эти методы можно использовать для различных компонентов.
generated - Каталог, в котором содержатся сгенерированные типы по каждой сущности. А именно в файле graphql.ts можно найти graphql - схему для каждой сущности и затем применять в сервисах, резолверах и тд. В файле graphql.schema.json содержится схема GraphQL, которая описывает доступные типы данных и операции в API. Кратко рассмотрим применение: Валидация данных:
Скалярные типы могут использоваться для валидации входящих данных в запросах и мутациях. Например, если поле ожидает тип Date, API будет проверять, соответствует ли переданная строка формату даты. Генерация документации:
Описание типов помогает разработчикам и пользователям API понять, какие данные ожидаются и как с ними работать. Это улучшает взаимодействие с API и упрощает его использование. Инструменты разработки:
Инструменты, такие как GraphQL Playground или Apollo Client, могут использовать эту схему для предоставления автозаполнения и документации в процессе разработки. Папка i18n (internationalization) в проекте содержит файлы, связанные с локализацией и переводом приложения на различные языки. Типичное содержимое папки i18n включает в себя: два подкаталога en для переводов на английский язык и ru для переводов на русский язык. Файлы index.ts в папках en и ru в отличии от enCatalogs.ts и ruCatalogs.ts не перегенериваются и в них можно добавлять переводы для различных ошибок и уведомлений не затрагивая изначальную структуру каталогов. layout - Каталог, который используется для организации и управления структурой пользовательского интерфейса (UI) приложения. Вот основное содержимое этого каталога:
AppBar.tsx - содержит компонент для создания верхней панели навигации. Основные функции:
Адаптивный интерфейс:
Используется хук useMediaQuery для определения, является ли устройство мобильным (широкий экран ниже определенного размера). Это позволяет динамически изменять содержимое панели в зависимости от размера экрана. Управление темой:
Хук useTheme используется для управления темой приложения. Рендеринг верхней панели:
Компонент RaAppBar (верхняя панель React Admin) используется для отображения панели. В зависимости от размера экрана, может отображаться либо панель инструментов (ToolBar), либо ничего (для мобильных устройств). Логотип и навигация:
Внутри панели рендерится логотип (иконка), который является ссылкой на главную страницу (/). Используется компонент Link для навигации. Гибкость компоновки:
Используются компоненты Box из Material-UI для создания гибкой компоновки, что позволяет легко управлять пространством между элементами. Layout.tsx - основной файл, который содержит дочерние компоненты в каталоге. В дальнейшем именно он будет импортироваться в главный файл App.tsx.
Menu.tsx (дефолтный генерируемый файл) и CustomMenu.tsx (используется вместо дефолтного, не генерится) - определяет компонент Menu, который отвечает за отображение бокового меню в приложении на основе React Admin. Основные функции:
Управление состоянием бокового меню:
Используется хук useSidebarState для получения состояния (открыто или закрыто) бокового меню. Получение прав доступа:
Хук usePermissions используется для получения прав доступа пользователя. Это позволяет динамически отображать элементы меню в зависимости от разрешений. Динамическое создание меню:
menuData формируется путем объединения дополнительных элементов меню, полученных из функции getAdditionalMenu. Отображение элементов меню:
Если у пользователя есть право доступа к определенному элементу (dashboards.main), отображается элемент DashboardMenuItem. Затем происходит итерация по menuData, и каждый элемент отображается с помощью компонента MenuItem. Стилизация и анимация:
Компонент Box используется для стилизации, включая ширину, отступы и анимацию при изменении состояния бокового меню. Анимация реализуется с использованием системы переходов Material-UI. SubMenu.tsx - отвечает за отображение компонентов подменю. В этом файле можно изменить отображение пунктов подменю, например, убрать иконки или изменить положение.
themes.ts - содержит компоненты для темной и светлой тем. В этом файле определяется, то как элементы на страницах будут отображаться (задаются отступы, радиусы скругления, цвета, размеры, шрифты и др.) и анимироваться для каждой темы. Для этого используются классы из библиотеки material-ui.
Colors.tsx - содержит енум для каждого цвета, используемого в проекте. Не является обязательным файлом в этом каталоге, но удобно держать все цвета проекта в одном месте и использовать в любой части кода.
types - нужно ли описывать? uiLib - Каталог с заготовленными компонентами. В проекте часто используются однотипные конструкции, такие как отображение кнопок, выбора даты, рейтинга в формате звезд или окошко для загрузки файла и др. Чтобы не перегружать код и не копипастить одно и то же, в каталоге uiLib уже хранится большая часть таких компонентов, которые можно импортировать куда угодно. От проекта к проекту эти компоненты будут расширяться в соответствии с запросами.
utils/ - Каталог, содержащий вспомогательные функции, константы и другие утилиты. Файл regExps.ts содержит регулярные выражения, которые используются для валидации различных типов входных данных в JavaScript.
Эти регулярные выражения используются для проверки ввода данных пользователем, чтобы обеспечить соответствие необходимым критериям.
widgets - Каталог, содержащий компоненты с готовым оформление для разных типов полей. Виджеты используются практически на всех страницах в проекте для более привлекательного оформления находящихся на них элементов.
К тому же, все виджеты имеют общий стиль, что придает целостности всему проекту.
*дополнительно (возможно не обязательно) App.tsx - Корневой компонент приложения.
.gitignore - Файл, указывающий, какие файлы и каталоги должны быть исключены из Git-репозитория.
package.json - Файл, содержащий информацию о проекте и его зависимостях.
tsconfig.json - Файл конфигурации TypeScript, определяющий параметры компиляции.
README.md - Файл, содержащий описание проекта и инструкции по установке и использованию.
Создание документации по платформе