Update README.md

README.md

@@ -1,20 +1,127 @@
-# timetable-backend
-Бэкэнд сервиса расписания студентов физфака
+# Сервис расписания
 
-# Установка
-## Google API
-* Чтобы подключить Google API, нужно создать приложение в google cloud console , получить client_secret.json
-и закинуть его в репозиторий
+Серверная часть сервиса хранения и управления информацией о расписании
 
-* https://developers.google.com/calendar/api/quickstart/python
+## Функционал
+1. Управление учебными группами, аудиториями
+2. Управление событями, комменатриями к событиям
+3. Управление преподавателями, фотографиями преподователей и комментариями к преподавателям
 
-## dotenv
-* Переименовать `.env.example` в `.env`
-* Внести в `.env` корректные переменные окружения
+- Про понятия использоованные в этом пункте можно почитать ниже(см. Основные абстракции)
 
 ## Запуск
-```console
-foo@bar:~$ python3 -m venv venv
-foo@bar:~$ pip install -r requirements.txt
-foo@bar:~$ uvicorn --reload --log-level debug calendar_backend.routes.base:app
+
+1. Перейдите в папку проекта
+
+2. Создайте виртуальное окружение командой и активируйте его:
+    ```console
+    foo@bar:~$ python3 -m venv venv
+    foo@bar:~$ source ./venv/bin/activate  # На MacOS и Linux
+    foo@bar:~$ venv\Scripts\activate  # На Windows
+    ```
+
+3. Установите библиотеки
+    ```console
+    foo@bar:~$ pip install -r requirements.txt
+    foo@bar:~$ pip install -r requirements.dev.txt
+    ```
+4. Запускайте приложение!
+    ```console
+    foo@bar:~$ python -m calendar_backend
+    ```
+
+## ENV-variables description
+
+- `DB_DSN=postgresql://postgres@localhost:5432/postgres` – Данные для подключения к БД
+- `STATIC_PATH` - путь до папки, в которой лежит статика. например, фотографии преподавателей
+- `REQUIRE_REVIEW_PHOTOS` - требовать ли ревью фотографии преподавателя(Если нет, то она сразу ппоявится в выдаче. Если да, то нужно будет подтверждение этой фотографии от пользователя с достаточными скоупами)
+- `REQUIRE_REVIEW_LECTURER_COMMENT` - требовать ли ревью комментариев к преподавателям(аналогично `REQUIRE_REVIEW_PHOTOS`)
+- `REQUIRE_REVIEW_EVENT_COMMENT`- требовать ли ревью комментариев к событиям(аналогично `REQUIRE_REVIEW_PHOTOS`)
+- `SUPPORTED_FILE_EXTENSIONS` - поддеедживаемые форматы файлов. На данный момент форматы конкретно изображений.
+- Остальные общие для всех АПИ параметры описаны [тут](https://github.com/profcomff/.github/wiki/%5Bbackend%5D-Настройки-приложения)
+
+## Основные абстракции
+
+- `Учебная группа`. Имеет поля: номер, имя. В имя записывается название кафедры. В номер - номер группы, например 442м
+- `Преподаватель`. Имеет поля: Имя, Фамилия, Отчество, Описание. Описание можно загружать текстом в формате .md
+- `Фотография преподавателя`. Имеет отношение к конкретному преподавателю. Загрузить может любой пользователь и в зависимости от настроек приложения(см ENV-variables description) может выдаваться по запросу сразу или после аппрува этой фотографии от модератора. Ревью может быть как положительным, так и отрицательным.
+- `Комментарий к преподавателю`. Имеет отношение к конкретному преподавателю. Загрузить может любой пользователь и в зависимости от настроек приложения(см ENV-variables description) может выдаваться по запросу сразу или после аппрува этого комментария от модератора. Ревью может быть как положительным, так и отрицательным.
+- `Аудитория`. Имеет поля: номер и направление(север, юг), здание, урл до карты здания в Яндекс картах, например.
+- `Событие`. Одно событие может происходить сразу в нескольких аудиториям, сразу для нескольких групп, несколькими преподавателями. Событие имеет название, время начала и конца. Событие может быть не только парой, но и чем то иным. Например, пара - это событие. Мероприятие "Первый снег" - это событие
+- `Комментарий к событию`. Имеет отношение к конкретному событию. Загрузить может любой пользователь и в зависимости от настроек приложения(см ENV-variables description) может выдаваться по запросу сразу или после аппрува этого комментария от модератора. Ревью может быть как положительным, так и отрицательным.
+
+
+## Сценарий использования
+
+### Создать группу
+
+Дёрнуть ручку `POST /group`. вы передаете 
+```json
+{
+  "name": "string", // название кафедры
+  "number": "string" // номер группы
+}
+```
+
+### Создать аудиторию
+
+Дёрнуть ручку `POST /room`. вы передаете 
+```json
+{
+  "name": "string", // название аудитории
+  "building": "string", // название здания (например, Физический факультет)
+  "building_url": "string", // урл до карты здания
+  "direction": "North" // север/юг(если здание == Физический факультет)
+}
+```
+
+### Создать преподавателя
+
+Дёрнуть ручку `POST /lecturer`. вы передаете 
+```json
+{
+  "first_name": "string", // имя
+  "middle_name": "string", // фамилия
+  "last_name": "string", // отчество
+  "description": "string" // описание в формате .md
+}
+```
+
+### Создать событие
+
+Дёрнуть ручку `POST /event`. вы передаете 
+```json
+{
+  "name": "string", // название
+  "room_id": [0], // айдишники аудиторий, в которых оно проходит
+  "group_id": [0], // айдишники групп, у которых оно проходит
+  "lecturer_id": [0], // айдишники преподавателей, которые его ведут
+  "start_ts": "2023-10-29T06:07:09.827Z", // время начала
+  "end_ts": "2023-10-29T06:07:09.827Z" // время конца
+}
+```
+
+### Получить список необработнных модераторами фотографий преподавателей
+
+Дёрнуть ручку `GET /lecturer/photo/review`
+
+### Ревью фотографии
+
+Дёрнуть ручку `POST /lecturer/photo/review/{id}`. вы передаете 
+```json
+{
+  "action": "Approved" // Подтвердить фотографии или ("Declined")
+}
 ```
+
+### Ревью комментария
+
+Дёрнуть ручку `POST /lecturer/{lecturer_id}/comment/{id}/review`. вы передаете action в query-string. С комментариями к событиям аналогично
+
+## Contributing
+
+- Основная [информация](https://github.com/profcomff/.github/wiki/%255Bdev%255D-Backend-%25D1%2580%25D0%25B0%25D0%25B7%25D1%2580%25D0%25B0%25D0%25B1%25D0%25BE%25D1%2582%25D0%25BA%25D0%25B0) по разработке наших приложений
+
+- [Ссылка](https://github.com/profcomff/timetable-api/blob/main/CONTRIBUTING.md) на страницу с информацией по разработке timetable-api
+
+