From cf5c13ff847f62315ed654868b03bcde0e12828a Mon Sep 17 00:00:00 2001
From: Sergey Karmanov <ppoocpel8888@gmail.com>
Date: Tue, 28 Apr 2026 16:35:23 +0300
Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8=D0=BB=20re?=
 =?UTF-8?q?adme?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Copilot <copilot@github.com>
---
 README.md | 140 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 140 insertions(+)

diff --git a/README.md b/README.md
index baaaa5d..993191b 100644
--- a/README.md
+++ b/README.md
@@ -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.
+