Бэк рейтинга преподов

[viribus-issue-bot]

Выполнить постановку, разработать API

Постановка задачи должна быть выполнена учитывая: https://github.com/profcomff/.github/issues/47#issuecomment-2284598378

[Temmmmmo]

Функциональность

Хранение

1. Списка преподавателей
2. Списка отзывов(и оценок) на конкретного преподавателя
3. Предметов обучения

Получение

1. Агрегированных оценок преподавателей
2. Отсортированного списка преподавателей по:
   • предметам
   • оценкам

Администрирование

1. Отзывов на преподавателей

Дополнительно

Оценка преподавателя

Каждый пользователь может оставлять комментарий к какому-либо преподавателю, при этом можно указать 3 типа оценок: оценка доброты (mark_kindness), оценка халявности (mark_freebie) и оценка понятности (mark_clarity). В отдельности каждая оценка принимает целые значения из сегмента [-2, 2]. Назовем отдельной общей оценкой - среднее арифметическое оценок по одному критерию для конкретного преподавателя. Тогда общая оценка преподавателя (general_mark) - это среднее арифметическое всех отдельных общих оценок.

[Temmmmmo]

Структуры данных

Таблицы

Lecturer

id - Integer - primary key 
subject - String - not nullable - Учебный предмет
timetable_id - Integer - unique, not nullable - Айди преподавателя в timetable-api
comments - Array[Comment] - relation Lecturer-Comment One-to-Many - Список комментариев конкретного преподавателя

Comment

id - Integer - primary key
create_ts - Date - not nullable - Время создания комментария
update_ts - Date - not nullable - Время изменения комментария
subject - String - not nullable - Учебный предмет
text - String - nullable - Текст сообщения
mark_kindness - Integer - not nullable - Оценка доброты
mark_freebie - Integer - not nullable - Оценка халявности
mark_clarity - Integer - not nullable - Оценка понятности
lecturer_id - Integer - not nullable - ID преподавателя в таблице Lecturer
review_status - Enum("PENDING", "DISMISSED", "APPROVED") - not nullable - Статус проверки комментария. PENDING - комментарий на проверке. DISMISSED - комментарий отклонен. APPROVED - комментарий одобрен

LecturerUserComment

id - Integer - primary key
lecturer_id - Integer
user_id - Integer
create_ts - Datetime

[Temmmmmo]

Запросы

Lecturer

1. Получить преподавателя по id

GET lecturer/{id}

QUERY: info: string - возможные значения 'comments', 'mark'. Если info == comments, то возвращаются комментарии к преподавателю. Если info == mark, то возвращаются общие оценки по комментариям.

Пример ответа JSON { id: integer, subject: string, timetable_id: integer, mark_kindness: integer, mark_freebie: integer, mark_clarity: integer, comments: array[Comment] }

2. Получить всех преподавателей

GET lecturer

QUERY: limit: integer, offset: integer, order_by: string, info: string, subject: string.

limit - максимальное количество возвращаемых преподавателей

offset - нижняя граница получения преподавателей, т.е. если по дефолту первым возвращается преподаватель с условным номером N, то при наличии ненулевого offset будет возвращаться преподаватель с номером N + offset

order_by - возможные значения 'mark', 'name'. 'mark'- возвращается список преподавателей отсортированных по общей оценке или 'name' - возвращается список преподавателей отсортированных по ФИО

info - возможные значения 'comments', 'mark'. comments - возвращает список комментариев к преподавателю. mark - возвращается список преподавателей с полями оценок

subject - возвращает всех преподавателей, для которых subject == lectrurer.subject

Пример ответа JSON { items: { id: integer, subject: string, timetable_id: integer, mark_kindness: integer, mark_freebie: integer, mark_clarity: integer, comments: array[Comment], }, limit: integer, offset: integer, total: integer }

3. Создать преподавателя

POST lecturer Depends rating.lecturer.create BODY: JSON { subject: string, timetable_id: int )

Пример ответа JSON { id: integer, subject: string, timetable_id: integer }

4. Удалить преподавателя

DELETE lecturer/{id} Depends rating.lecturer.delete Пример ответа JSON { status: string, message: string }

Comment

1. Получить комментарий на конкретного преподавателя по id

GET comment/{id}

PATH: id: int

Пример ответа JSON { id: integer, create_ts: datetime, update_ts: datetime, subject: string, text: string, mark_kindness: int, mark_freebie: int, mark_clarity: int, lecturer_id: int, }

2. Получить все комментарии

GET /comment

QUERY: limit: integer, offset: integer, order_by: string, info: string, subject: string, lecturer_id: integer, unreviewed: bool unreviewed: Depends rating.comment.review limit - максимальное количество возвращаемых комментариев

offset - нижняя граница получения комментариев, т.е. если по дефолту первым возвращается комментарий с условным номером N, то при наличии ненулевого offset будет возвращаться комментарий с номером N + offset

order_by - возможное значение 'create_ts' - возвращается список комментариев отсортированных по времени создания

lecturer_id - вернет все комментарии для преподавателя с конкретным id, по дефолту возвращает вообще все аппрувнутые комментарии.

get_unreviewed - вернет все непроверенные комментарии, если True. По дефолту False.

Пример ответа JSON { items: { id: integer, create_ts: datetime, update_ts: datetime, subject: string, text: string, mark_kindness: int, mark_freebie: int, mark_clarity: int, lecturer_id: int }, limit: integer, offset: integer, total: integer }

3. Создать комментарий

POST /lecturer/{lecturer_id}/comment

PATH: lecturer_id: int

Если анонимный: BODY: JSON { create_ts: datetime, update_ts: datetime, subject: string, text: string, mark_kindness: int, mark_freebie: int, mark_clarity: int, lecturer_id: int, } В случае не анонимного в теле запроса также будет поле user_id: int

Пример ответа JSON { id: integer, create_ts: datetime, update_ts: datetime, subject: string, text: string, mark_kindness: int, mark_freebie: int, mark_clarity: int, lecturer_id: int, }

4. Изменить комментарий (Ревью коммента)

Depends: rating.comment.review

PATCH comment/{id}

PATH: id: int

BODY: JSON { update_ts: datetime, review_status: string }

Пример ответа JSON { id: integer, create_ts: datetime, update_ts: datetime, subject: string, text: string, mark_kindness: int, mark_freebie: int, mark_clarity: int, lecturer_id: int, review_status: string }

5. Удалить комментарий

DELETE comment/{id}

PATH: id: int

Пример ответа JSON { status: string, message: string }

[grigoriev-semyon]

@Temmmmmo также, надо проследить, чтобы ошибки возвращались в формате:

1. Exception design
2. Model design