Backend

Конфигурация

Локально удобно пользоваться user secrets

• PublicOrigin__Uri: Публичный домен, по которому доступен API. Вынесен отдельно а не берется из заголовков запроса, поскольку frontend может ходить по внутренней сети, и домен там будет неверным.

Хранилища данных

• ConnectionStrings__AttendPostgresDatabase: Строка подключения к БД Postgres, используется в EFCore и healthcheck.

Аутентификация

Аутентификация ведется через Cookie. Клиенты с других доменов должны находиться в списке доступных origin-ов для того чтобы присылать cookie из браузера.

Предусмотрено два механизма аутентификации, для production и для тестирования при работе разработчиков.

При существовании секции Oauth__MIREA используется она. Её необходимо указывать только для Production. В противном случае используется Development аутентификация, где данные о пользователе берутся из конфигурации.

Подтверждения студентов через QR код

• StudentSelfApproveLinkOptions__DelayBetweenCreatingLinks: TimeSpan время между показами нового QR кода
• StudentSelfApproveLinkOptions__LinkLifetime: TimeSpan время валидности QR кода
• StudentSelfApproveLinkOptions__LinkTemplate: Шаблон строки для string.Format, который будет использоваться для подстановки единственного аргумента - токена подтверждения посещения

Автоматическое создание занятий

• CreateLessonFromScheduleOptions__RangeToScan: Период времени, который будет захвачен при создании занятий от момента начала создания занятий.

Production

Указывается только при развертывании на продакшн сервере

• Oauth__MIREA__ClientId: id приложения для аутентификации через login.mirea.ru
• Oauth__MIREA__ClientSecret: секрет приложения для аутентификации через login.mirea.ru
• Oauth__MIREA__AuthorizationEndpoint: адрес авторизации
• Oauth__MIREA__TokenEndpoint: адрес получения токена
• Oauth__MIREA__UserInformationEndpoint: адрес получения информации о пользователе

Система login.mirea.ru может возвращать не только идентификатор человека, для обхода этой особенности данные о пользователе запрашиваются из системы ТАНДЕМ, если информация о человеке не может быть взята из БД. При ошибке во время этого процесса или при отказе пользователя аутентифицироваться он будет перенаправлен на страницу /auth_error. API проект ничего не предоставляет по маршруту. Его должен обработать некоторый фронтенд, что будет расположен на том же домене, что и API. При перенаправлении может присутствовать query параметр ReturnUrl, на который необходимо перенаправить пользователя после ознакомления с информацией о произошедшей ситуации.

Development

• Oauth__MIREAStatic__Claims__<индекс>__(Type|Value): Массив объектов, описыващих клеймы пользователя, под которым будет произведена аутентификация. Для корректной работы желательно указать все клеймы, что настроены в MIREAOptions.cs

Id пользователя, под которым происходит аутентификация можно переопределить, указав заголовок human-id. При наличии он перекроет id, указанный в конфигурации. Это полезно для тестирования различных ролей, этот же маханизм используется в автоматических тестах.

Для аутентификации через данный механизм из инструментов по типу Postman/Insomnia можно выполнить запрос на /debug-login(доступен только в Development режиме).

Sentry

В проекте добавлен Senrty с трассировками, для настройки можно использовать опции Sentry

Миграции

Миграции как и все модели данных находятся в src/AttendDatabase. Для работы с миграциями нужно указывать Startup проект через -s Например, для создания новой необходимо выполнить следующие команды bash cd src/AttendDatabase dotnet ef migrations add ИМЯ_МИГРАЦИИ -s ..\API\API.csproj

Разработка

Для обращения к сервису желательно использовать не http[s]://localhost:(5025|5026), а http[s]://127.0.0.1.nip.io:(5025|5026), так как это необходимо для корректной работы с Cookie.

Порты

5025 HTTP1.1 (dev TLS/prod no TLS)

Данный порт используется для gRPC Web + аутентификации с Oauth.

Для работы аутентификации в dev режиме используется TLS(для верной работы с Secure Cookie). В продакшене он не используется, так как эту работу на себя берет выше стоящий прокси.

5026 HTTP2 (no TLS)

Используется для взаимодействия с Frontend по внутренней сети.

Добавление enum в сущности

Чтобы созданные enum были подходящими для postgres, после добавления их в сущность нужно указать на их существование:

В src/AttendDatabase/AttendDbContext.cs добавляется строка modelBuilder.HasPostgresEnum<(название enum)>();

В src/AttendDatabase/DlHelper.cs добавляется строка dataSourceBuilder.MapEnum<(название enum)>();

Использование базы данных для выполнения фоновых работ

Ссылка на скачивание данных указывается в appsettings.json в поле ConnectionStrings__BackgroundScheduleLinks

В проекте используется библиотека Quartz - библиотека планирования задач. Для выполнения только одной задачи (без возможности параллельного включения одной и той же задачи) можно подключить БД в appsettings.json для Quartz через ConnectionStrings__QuartzDatabase.

Чтобы подключаемая БД появилась, нужно создать новую базу данных и провести в нее миграции из файла

В противном случае (без подключения БД) будет использоваться RAM память, что запустит две и более задачи (триггера)

Настройка частоты срабатывания сервиса делается через строку BackgroundScheduleMode в appsettings.json. Там используется cron-выражение

Настройка частоты срабатывания сервиса расписания "в моменте" делается в CurrentDayScheduleMode в appsettings.json также через cron-выражение.