.

docs/API.md

@@ -894,7 +894,7 @@ API возвращает `409 Conflict`; соседние интервалы и
 
 | Метод | URL | Назначение |
 |-------|-----|------------|
-| `GET` | `/api/edu-office/schedule/quality?semesterId=&versionId=` | Итоговая оценка, метрики и объяснимый список проблем выбранной версии |
+| `GET` | `/api/edu-office/schedule/quality?semesterId=&versionId=` | Итоговая оценка, метрики и объяснимый список проблемных правил выбранной версии |
 | `GET` | `/api/edu-office/schedule/quality/recommendations?semesterId=&versionId=&scheduleRuleSlotId=&lessonDate=` | Проверенные локальные варианты улучшения опубликованного занятия |
 
 Доступ имеют только `ADMIN` и `EDUCATION_OFFICE`. `versionId` необязателен: без него
@@ -921,7 +921,7 @@ override текущей публикации. Для них доступны о
   "score": 84,
   "rawPenalty": 17,
   "lessonCount": 36,
-  "totalProblemCount": 5,
+  "totalProblemCount": 1,
   "problemsTruncated": false,
   "metrics": [
     {
@@ -935,11 +935,16 @@ override текущей публикации. Для них доступны о
   ],
   "problems": [
     {
-      "id": "GROUP_GAP:2026-09-14:31:18",
+      "id": "RULE:24",
       "type": "GROUP_GAP",
       "severity": "MEDIUM",
-      "title": "Окно в расписании группы",
-      "penalty": 2,
+      "title": "Правило «Архитектура систем» снижает качество",
+      "description": "3 занятия этого правила снижают оценку: Окно в расписании группы; Избыточно крупная аудитория",
+      "penalty": 8,
+      "scheduleRuleId": 24,
+      "affectedLessonCount": 3,
+      "problemTypes": ["GROUP_GAP", "ROOM_OVERSIZED"],
+      "issueLabels": ["Окно в расписании группы", "Избыточно крупная аудитория"],
       "scheduleRuleSlotId": 31,
       "lessonDate": "2026-09-14",
       "optimizable": true
@@ -949,8 +954,11 @@ override текущей публикации. Для них доступны о
 ```
 
 `score` находится в диапазоне от 0 до 100 и нормализует сумму объяснимых штрафов
-относительно числа занятий. Поле `totalProblemCount` содержит полный размер результата,
-а массив `problems` ограничен 300 элементами; `problemsTruncated` сообщает об усечении.
+относительно числа занятий. Нарушения сначала рассчитываются для каждого фактического
+занятия, затем объединяются по `scheduleRuleId`: `penalty` хранит сумму всех штрафов правила,
+`affectedLessonCount` — число затронутых занятий, `problemTypes` и `issueLabels` — все его
+категории и объяснения. Поле `totalProblemCount` содержит число проблемных правил, а массив
+`problems` ограничен 300 элементами; `problemsTruncated` сообщает об усечении.
 
 Рекомендации подбирают другой эффективный временной слот того же учебного дня либо
 подходящую активную аудиторию. Занятия, уже закреплённые ручным override, исключаются.