Обновил документацию

README.md

@@ -1,2 +1,58 @@
 # ModeusSchedule.MSAuth
 
+## Зачем нужен этот сервис
+
+ModeusSchedule.MSAuth — это вспомогательный HTTP-сервис, который автоматизирует авторизацию в Microsoft, заходит в веб-интерфейс Modeus и извлекает свежий `id_token` (JWT). Этот токен затем может использоваться другими компонентами вашей системы для обращения к API Modeus без ручного входа пользователя. Проект устраняет необходимость хранить пользовательские cookie, а также упрощает раздачу короткоживущих токенов другим сервисам через REST‑эндпоинт.
+
+## Ключевые возможности
+
+- Браузерная авторизация через Playwright и Chromium в режиме headless.
+- Кэширование токена на 20 минут, чтобы избежать лишних логинов.
+- Ограничение параллельных попыток авторизации (возврат HTTP 429, если процесс уже идет).
+- Опциональная защита API ключом (заголовок `X-API-Key`).
+- Простой REST‑эндпоинт `GET /auth/ms`, который возвращает JSON `{ "jwt": "..." }`.
+
+## Как это работает
+
+1. Сервис при старте проверяет, что заданы параметры подключения к Modeus и учетные данные Microsoft (`MODEUS_URL`, `MS_USERNAME`, `MS_PASSWORD`).
+1. При первом запросе Playwright поднимает headless Chromium и логинится в Modeus через Microsoft IDP.
+1. После успешного входа токен `id_token` извлекается из `sessionStorage`, сохраняется в памяти и отдается клиенту.
+1. Пока токен свежий, новые запросы обслуживаются из кэша. Как только TTL истекает, запускается новая авторизация.
+
+## Конфигурация
+
+| Параметр | Где задается | Назначение |
+| --- | --- | --- |
+| `MODEUS_URL` | `appsettings.json` / переменные окружения | URL портала Modeus (например, `https://<название вуза>.modeus.org/`). |
+| `MS_USERNAME` | `appsettings.json` / переменные окружения | Логин сервисной учетной записи Microsoft 365. |
+| `MS_PASSWORD` | `appsettings.json` / переменные окружения | Пароль от этой учетной записи. |
+| `API_KEY` *(опционально)* | `appsettings.json` / переменные окружения | Если задан, сервис будет требовать заголовок `X-API-Key`. |
+
+## Быстрый старт
+
+1. Установите .NET 9 SDK и Playwright (будет поставлен автоматически при первом запуске).
+1. Создайте файл `appsettings.Development.json` или задайте переменные окружения с параметрами из таблицы выше.
+1. Соберите и запустите сервис:
+
+```bash
+cd src
+dotnet run
+```
+
+1. Выполните запрос:
+
+```bash
+curl -H "X-API-Key: <ваш ключ>" http://localhost:5000/auth/ms
+```
+
+В ответ вы получите JSON с полем `jwt`. При повторных вызовах в пределах времени жизни кэша сервис не будет заново входить в Microsoft.
+
+## Безопасность и эксплуатация
+
+- Используйте отдельную сервисную учетную запись Microsoft с минимально необходимыми правами.
+- Ограничьте доступ к эндпоинту по сети (VPN, reverse proxy) и включите проверку `API_KEY`.
+- Логи Playwright могут содержать диагностическую информацию, поэтому убедитесь, что они не раскрывают пароли.
+
+## Лицензия
+
+Проект распространяется под лицензией MIT. Подробнее в файле [`LICENSE`](LICENSE).