Журнал оценок кажется простой таблицей «студент × задание». Внутри это три таблицы, одна нормализованная структура и пересчёт, который запускается по флагу. Если отчёт или плагин читает оценки напрямую, он наследует все особенности этой структуры: скрытые оценки, переопределённые значения, неоконченный пересчёт. Ниже разобрано, как работает Grade API и на что опираться при чтении, на примере задач электронной зачётной книжки.
Три таблицы
| Таблица | Что хранит | Ключевые поля |
|---|---|---|
grade_items | Столбцы журнала: каждый оцениваемый элемент, категория и итог курса | courseid, itemtype, itemmodule, iteminstance, itemnumber, grademax, grademin, gradepass, hidden, needsupdate |
grade_categories | Дерево категорий и правила агрегации | courseid, parent, aggregation |
grade_grades | Оценки: одна строка на пользователя и элемент | itemid, userid, rawgrade, finalgrade, hidden, locked, overridden |
grade_grades_history | Журнал изменений оценок | те же поля плюс источник и время изменения |
Поле itemtype различает природу элемента: mod (оценка модуля), manual (ручной элемент), category (итог категории), course (итог курса). Для оценок модулей вместе с ним заполнены itemmodule (например, quiz) и iteminstance (id экземпляра модуля). Нумерация itemnumber нужна, если модуль выставляет несколько оценок, например за разные части задания.
Откуда оценки берутся: rawgrade и finalgrade
Модуль, например тест, не пишет в grade_grades сам. Он вызывает Grade API, передавая rawgrade: оценку «как есть» из своей таблицы. Журнал применяет к ней настройки: масштабирование под максимальный балл элемента, правила агрегации, скрытие, блокировку и ручное переопределение преподавателем. Результат записывается в finalgrade. Поэтому для показа студенту нужно значение finalgrade, а rawgrade нужен разве что для диагностики расхождений.
Ручное переопределение (overridden) стоит помнить отдельно: преподаватель может вручную исправить итог, и вычисления модуля его уже не изменят. Если в зачётке видна оценка, не совпадающая с результатом теста, чаще всего причина именно в этом. Описание структуры дано в документации по оцениванию и в справке по журналу оценок.
Чтение через API
Для получения оценок конкретного элемента есть функция grade_get_grades() из lib/gradelib.php. Она принимает курс, тип элемента, модуль, экземпляр и пользователя (или список пользователей) и возвращает структуру с оценками и признаками видимости.
require_once($CFG->libdir . '/gradelib.php');
$grades = grade_get_grades($courseid, 'mod', 'quiz', $quizid, $userid);
$item = reset($grades->items);
if ($item && isset($item->grades[$userid])) {
$g = $item->grades[$userid];
$value = $g->grade; // итог в шкале элемента
$hidden = $g->hidden; // признак скрытия
$text = $g->str_grade; // уже отформатированный вид
}
Чтение итога курса выполняют через объект элемента:
$courseitem = grade_item::fetch_course_item($courseid);
$final = $courseitem->get_final($userid); // итог пользователя или null
Обратите внимание на возвращаемое значение: null означает, что оценки нет, и это отличается от нуля. В зачётке оценка «не выставлена» и «ноль баллов» — разные состояния, и показывать их нужно по-разному.
Для отображения оценки в том виде, как она настроена в курсе (баллы, проценты, буквы, шкала), используют форматирование журнала: grade_format_gradevalue() учитывает тип отображения. Это избавляет от самодельных пересчётов, которые расходятся с тем, что видит студент в журнале.
Скрытые оценки и доступ
Прямой SQL-запрос к grade_grades легко написать и опасно использовать: он не знает про скрытость. Оценка может быть скрыта у элемента, у конкретного пользователя или до определённой даты (в поле hidden хранится либо флаг, либо метка времени). Студент не должен видеть то, что скрыто в журнале. Если плагин показывает оценки студенту или его куратору, фильтр по видимости обязателен: вернее всего брать данные через API, который учитывает права, а при работе напрямую проверять hidden и обращаться за правами, например на просмотр скрытых оценок. Есть и другие нюансы: заблокированные оценки (locked), оценки для приостановленных зачислений, элементы из других курсов.
Помните и про персональные данные: оценки относятся к ним, плагин, который их хранит или передаёт наружу, должен реализовывать Privacy API. Подробнее в статье про 152-ФЗ в Moodle.
Запись оценок
Если плагин выставляет оценки сам, он не должен писать в grade_grades напрямую. Для модуля используется grade_update(), который принимает источник (компонент), курс, тип, модуль, экземпляр, номер элемента, массив оценок и данные элемента. Функция создаёт элемент, если его ещё нет, записывает оценки, отправляет события и ставит флаг пересчёта. Для произвольного значения, не привязанного к модулю, заводится ручной элемент (itemtype = 'manual'), и оценки пишутся в него. Прямая запись минует историю и события, поэтому отчёты, подписанные на изменения, ничего не узнают.
Пересчёт
Когда меняется настройка категории, весов или максимального балла, затронутые элементы получают флаг needsupdate. Пересчёт выполняется при открытии отчёта или явным вызовом grade_regrade_final_grades($courseid). Если плагин читает значения, не вызвав пересчёт, он может получить старые итоги. В отчётах по многим курсам это превращается в медленные запросы: пересчёт тяжёлый. Поэтому перед массовым чтением итогов проверяйте флаг и пересчитывайте нужные курсы заранее, например в плановой задаче, а не в момент, когда пользователь открывает страницу. Про фоновые задачи — в отдельной статье.
Реагировать на изменения оценок можно через события, в частности \core\event\user_graded: наблюдатель получит уведомление и сможет обновить свою таблицу.
Типы оценок: числа, шкалы, текст
Значение в finalgrade не всегда баллы. Тип элемента (gradetype) может быть числовым, шкалой или текстом, и от этого зависит интерпретация. Для шкалы, например «не зачтено, зачтено», в finalgrade хранится порядковый номер выбранного пункта, начиная с единицы, а названия пунктов лежат в самой шкале. Если вывести просто число, студент увидит «2» вместо «зачтено». Правильно загрузить шкалу элемента и взять название по номеру или, что надёжнее, воспользоваться форматированием журнала. Текстовый тип не содержит числа вообще: это комментарий, который в расчётах не участвует.
Поэтому в зачётке различают четыре случая: числовая оценка в баллах, оценка-шкала («зачтено»), процент и отсутствие оценки. Универсальная функция форматирования, которая всё сводит к баллам, ломает как раз второй случай. В журналах колледжей, где итог — «зачёт» или пятибалльная оценка, шкалы встречаются постоянно, и именно их обычно делают источником для ведомости.
Производительность при массовом чтении
Одиночные вызовы API удобны, но для ведомости на группу в 25 человек и десять дисциплин они дадут сотни запросов. Полезны две привычки. Первая: передавать grade_get_grades() список пользователей, а не вызывать функцию в цикле. Вторая: читать по курсу, а не по студенту; сгруппировать выборку по курсам и пересчитывать журнал один раз на курс. Если API неудобен для задачи и вы решаетесь на прямой запрос, обязательно присоединяйте grade_items и учитывайте скрытость, блокировку и тип элемента, а изменения структуры журнала в новых версиях Moodle (пока они не пришли) закладывайте в проверки при каждом обновлении. Об обновлении версий я писала в статье про обновление Moodle: в нём я всегда проверяю плагины, читающие журнал.
Классы и функции журнала: справка
| Класс или функция | Для чего |
|---|---|
grade_item::fetch() | Найти элемент журнала по курсу, типу, модулю и экземпляру |
grade_item::fetch_course_item() | Получить итоговый элемент курса |
grade_item::get_final() | Итоговая оценка пользователя по элементу |
grade_grade::fetch() | Строка оценки пользователя со всеми признаками |
grade_get_grades() | Прочитать оценки элемента с учётом видимости |
grade_update() | Записать оценки модуля через API |
grade_format_gradevalue() | Показать значение так, как настроено в курсе |
grade_regrade_final_grades() | Пересчитать итоги курса |
Расхождение «в журнале одно, в зачётке другое»
Эту жалобу я встречаю чаще остальных, и причин у неё обычно четыре. Оценка переопределена вручную, поэтому она не следует за модулем. Итог скрыт от студента, а отчёт его показал или наоборот. Элемент помечен на пересчёт, и в таблице лежит предыдущее значение. Или оценка по шкале прочитана как число. Диагностику начинаю с конкретной строки grade_grades: смотрю rawgrade, finalgrade, overridden, hidden и флаг пересчёта у элемента. Пять полей почти всегда объясняют разницу без догадок.
Что это значит для зачётной книжки
Электронная зачётная книжка, работающая как local-плагин, читает из журнала итоги по элементам курсов и выводит их в ведомость с официальной формулировкой («зачтено», «отлично» и т. п.). Принципы, которые из этого вытекают:
- брать
finalgradeи форматировать через API журнала, а не пересчитывать самостоятельно; - различать «нет оценки» и «ноль»;
- учитывать скрытые и заблокированные оценки по тем же правилам, что журнал;
- не хранить копию оценок без необходимости, а если хранится, обновлять её по событию и сверять пересчётом;
- для итоговой ведомости фиксировать значение и дату на момент выставления: журнал может измениться позже.
Последний пункт самый спорный: ведомость — документ, и менять её задним числом из-за пересчёта нельзя. Поэтому в таких случаях значение копируют в таблицу плагина, привязывают к событию, а журнал используют как источник и для контроля. Сходные задачи решают и отчёты, о них можно прочитать на странице про отчёты Moodle под регламент.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.