Tech Spec Backend Gradebook

Техническое задание на разработку бэкенда модуля "Электронный журнал"

Ниже — структура ТЗ (общий шаблон, см. также Getting Started). Команда заполняет каждый раздел своим содержанием; текст в квадратных скобках — подсказка, что писать, а не готовый ответ.

1. Назначение модуля

Модуль Электронный журнал предназначен для автоматизации учета успеваемости и посещаемости студентов. Бэкенд-часть модуля обеспечивает логику для выставления и хранения оценок, фиксации пропусков занятий, а также предоставляет API для интеграции с личными кабинетами студентов и преподавателей.

2. Функциональные требования

Модуль обеспечивает полный цикл учета успеваемости, посещаемости и академической активности. В системе предусмотрено разграничение прав: преподаватели имеют доступ к выставлению и редактированию оценок, студенты к просмотру собственной успеваемости.

Учет посещаемости: фиксация присутствия, отсутствия, а также опозданий на занятия. Комментирование оценок: возможность для преподавателя оставлять короткие текстовые заметки к баллам. Журнал изменений: запись истории редактирования оценок для предотвращения несанкционированных изменений и разрешения спорных ситуаций. Расчет итоговых показателей: автоматический подсчет средневзвешенного балла студента. Система уведомлений: генерация предупреждений для кураторов и администрации о критическом уровне неуспеваемости или большом количестве пропусков у конкретных студентов.

2.1. Основные функции

• [Функция 1]-Добавление новых записей: возможность сервера принять от преподавателя и сохранить в базу данных новую оценку или отметку о пропуске занятия.
• [Функция 2]-Просмотр и получение из базы данных и выдача список оценок.
• [Функция 3]-Изменение существующих данных: возможность бэкенда скорректировать уже выставленную оценку или статус посещаемости в случае ошибки преподавателя.
• [Функция 4]-Удаление записей: возможность полностью удалить ошибочно созданную строку из журнала.
• [Функция 5]-Базовый расчет успеваемости: функция вычисления простого среднего арифметического балла студента по выбранной дисциплине.

2.2. Пользовательские сценарии

Сценарий 1: [Название сценария]

1. [Действие пользователя / другого модуля]
2. [Что делает backend]
3. [Что происходит с данными]

3. Нефункциональные требования

• Производительность: [Время ответа API на запросы чтения данных журнала не должно превышать 200 мс при 50 одновременных запросах.]
• Безопасность: [Доступ к эндпоинтам модификации данных разрешен только пользователям с ролями «Преподаватель» и «Администратор». Студенты имеют доступ только на чтение и исключительно своих собственных данных.]
• Совместимость: [Код должен быть написан на Python, использовать Pydantic-схемы для валидации запросов/ответов и SQLAlchemy для работы с БД, полностью интегрируясь в общую структуру.]

4. Интерфейсы

4.1. API Endpoints

Согласовывается с frontend-командой этого же модуля до начала Модуля 2 — что это значит и как оформлять, см. 🔌 API-контракт.

|POST| /grades | Выставить новую оценку студенту | Объект Grade | 400 (оценка не 2-5)| |GET| /lessons/{id}/grades| Получить ведомость оценок за занятие | Массив Grade |404 (урок не найден)| |PUT| /grades/{id} | Скорректировать оценку или комментарий | Измененный Grade | 403 (нет прав) | |DELETE| /grades/{id} | Удалить ошибочную запись из журнала | {"status": "ok"}| 403(нет прав) | |POST| /attendance | Отметить/обновить посещаемость | Объект Attend | 405 (неверный статус) | |GET| /students/{id}/grades | Просмотр оценок студента | Массив Grade | 406 (чужой профиль) | |GET| /students/{id}/attendance| Просмотр пропусков студента | Массив Attend | 406 (чужой профиль) | |GET| /students/{id}/gpa | Расчет среднего балла (GPA) по предметам |(4.25) | 407 (нет оценок) |

4.2. Взаимодействие с другими модулями

• [Модуль Расписание]: [Журнал заглядывает туда, чтобы проверить А был ли вообще такой урок в расписании?, прежде чем разрешить учителю поставить за него оценку]

5. Структура базы данных

5.1. Таблицы

Таблица: [grades(Оценки)]

Поле	Тип	Описание
id	Integer	Первичный ключ
...	...	...

6. Критерии приёмки

• Все функции реализованы
• Тесты написаны и проходят (pytest)
• CI зелёный (pytest + flake8)
• Раздел 4.1 согласован с specification-frontend.md этого модуля (см. чек-лист в 🔌 API-контракт)
• Pull Request создан и принят

7. Приложения

[Схемы, диаграммы, если нужны]