@@ -1,2 +1,142 @@
|
||||
# UniVerse
|
||||
|
||||
UniVerse — backend (ASP.NET Core) для университетской платформы расписания, лекций, отзывов и геймификации.
|
||||
|
||||
## Что внутри
|
||||
|
||||
- Расписание/события и сущности: курсы, лекции, аудитории (locations)
|
||||
- Отзывы студентов с фоновым LLM-анализом (качество/тональность/теги)
|
||||
- Геймификация: XP/уровни, монеты, достижения
|
||||
- JWT-аутентификация и роли (`Admin`, `Teacher`, `Student`)
|
||||
- Swagger/OpenAPI в Development
|
||||
|
||||
## Технологии
|
||||
|
||||
- .NET 10 / ASP.NET Core
|
||||
- PostgreSQL + EF Core (Npgsql)
|
||||
- Serilog
|
||||
- Swagger (Swashbuckle)
|
||||
|
||||
## Структура репозитория
|
||||
|
||||
Код backend лежит в папке `backend/` и собран в solution `backend/UniVerse.sln`:
|
||||
|
||||
- `backend/UniVerse.Api` — Web API (контроллеры, middleware, background services)
|
||||
- `backend/UniVerse.Application` — DTO, интерфейсы сервисов, маппинги
|
||||
- `backend/UniVerse.Domain` — доменные сущности/enum/исключения
|
||||
- `backend/UniVerse.Infrastructure` — EF Core, миграции, реализации сервисов, внешние клиенты
|
||||
|
||||
## Требования
|
||||
|
||||
- .NET SDK 10 (`dotnet --version` должен показать `10.x`)
|
||||
- PostgreSQL 14+ (или Docker для поднятия Postgres)
|
||||
|
||||
## Конфигурация
|
||||
|
||||
Основные настройки лежат в `backend/UniVerse.Api/appsettings.json`:
|
||||
|
||||
- `ConnectionStrings:DefaultConnection` — строка подключения к Postgres
|
||||
- `Jwt:*` — секрет/issuer/audience и сроки жизни токенов
|
||||
- `Cors:Origins` — origin’ы фронтенда
|
||||
- `Llm:*` — настройки LLM (OpenAI-compatible)
|
||||
- `ModeusApi:*` — настройки интеграции с Modeus
|
||||
|
||||
Можно переопределять через переменные окружения в формате `Section__Key`, например:
|
||||
|
||||
- `ConnectionStrings__DefaultConnection`
|
||||
- `Jwt__Secret`
|
||||
- `Llm__ApiKey`
|
||||
- `ModeusApi__ApiKey`
|
||||
|
||||
## Быстрый старт (локально)
|
||||
|
||||
1) Поднять Postgres (пример через Docker):
|
||||
|
||||
```bash
|
||||
docker run --rm --name universe-postgres \
|
||||
-e POSTGRES_DB=universe \
|
||||
-e POSTGRES_USER=postgres \
|
||||
-e POSTGRES_PASSWORD=postgres \
|
||||
-p 5432:5432 \
|
||||
postgres:16
|
||||
```
|
||||
|
||||
2) Применить миграции (первый раз потребуется `dotnet-ef`):
|
||||
|
||||
```bash
|
||||
dotnet tool install --global dotnet-ef
|
||||
|
||||
cd backend
|
||||
dotnet ef database update \
|
||||
--project UniVerse.Infrastructure \
|
||||
--startup-project UniVerse.Api
|
||||
```
|
||||
|
||||
3) Запустить API:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
dotnet run --project UniVerse.Api --launch-profile http
|
||||
```
|
||||
|
||||
По умолчанию (профиль `http`) API поднимется на `http://localhost:5019`.
|
||||
Swagger UI доступен в Development по адресу: `http://localhost:5019/swagger`.
|
||||
|
||||
## Запуск в Docker
|
||||
|
||||
В `backend/UniVerse.Api/Dockerfile` настроена сборка контейнера API.
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
docker build -f UniVerse.Api/Dockerfile -t universe-api .
|
||||
|
||||
docker run --rm -p 8080:8080 \
|
||||
-e ASPNETCORE_URLS=http://+:8080 \
|
||||
-e ConnectionStrings__DefaultConnection="Host=host.docker.internal;Port=5432;Database=universe;Username=postgres;Password=postgres" \
|
||||
universe-api
|
||||
```
|
||||
|
||||
Примечание: на Linux `host.docker.internal` может быть недоступен — проще запускать Postgres тоже в Docker и соединять контейнеры в одной сети.
|
||||
|
||||
## Аутентификация
|
||||
|
||||
- `POST /api/v1/auth/login/dev` — дев-логин (только в `Development`). Удобно для локальной разработки.
|
||||
- `POST /api/v1/auth/login/microsoft` — заготовка под Microsoft Entra ID (сейчас не реализовано).
|
||||
- `POST /api/v1/auth/refresh`, `POST /api/v1/auth/logout`, `GET /api/v1/auth/me`
|
||||
|
||||
Большинство методов API защищены `[Authorize]`.
|
||||
|
||||
## Фоновый LLM-анализ отзывов
|
||||
|
||||
Сервис `LlmProcessingBackgroundService` раз в ~2 минуты берёт отзывы со статусом `Pending` и прогоняет через LLM-клиент.
|
||||
LLM-ключ задаётся через `Llm:ApiKey`.
|
||||
|
||||
Если ключ не задан или внешний сервис недоступен — анализ будет ретраиться, а ошибки логироваться.
|
||||
|
||||
## Интеграция с Modeus
|
||||
|
||||
Эндпоинты синхронизации доступны только администратору:
|
||||
|
||||
- `POST /api/v1/sync/schedule`
|
||||
- `POST /api/v1/sync/rooms`
|
||||
- `POST /api/v1/sync/employees`
|
||||
- `GET /api/v1/sync/status`
|
||||
|
||||
Ключ (если нужен) задаётся через `ModeusApi:ApiKey`.
|
||||
|
||||
## Карта API (high-level)
|
||||
|
||||
Базовый префикс: `/api/v1`.
|
||||
|
||||
- `/auth` — логин/refresh/logout/me
|
||||
- `/users` — профиль/статистика/достижения/транзакции (часть методов — только `Admin`)
|
||||
- `/courses` — курсы и теги (CRUD в основном для `Admin`)
|
||||
- `/lectures` — лекции, записи, посещаемость, отзывы
|
||||
- `/reviews` — отзывы (создание студентом; модерация/реанализ для `Admin`)
|
||||
- `/tags` — теги + дерево тегов
|
||||
- `/locations` — аудитории/локации
|
||||
- `/achievements` — достижения
|
||||
- `/sync` — синхронизация с внешним расписанием (только `Admin`)
|
||||
|
||||
Точные схемы запросов/ответов удобнее смотреть в Swagger.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user