Skip to content

teacher_guide.md

Latest commit

 

History

History
106 lines (78 loc) · 6.89 KB

teacher_guide.md

File metadata and controls

106 lines (78 loc) · 6.89 KB

Руководство преподавателя (Teacher)

Документ для команды обучения: как пользоваться системой CodeReview 1C, что доступно в роли Teacher и как формировать пользовательские нормы.

1. Роль Teacher и доступы

Роль Teacher предназначена для экспертов, которые помогают формировать и уточнять нормы.

Доступно:

  • запускать проверки как обычный пользователь (создавать свои запуски);
  • смотреть результаты проверок своих запусков;
  • открывать раздел обучения (Обучение);
  • просматривать каталог норм (статические и LLM‑нормы);
  • создавать пользовательские нормы.

Недоступно:

  • управление пользователями, компаниями, кошельками;
  • админские логи (доступ/Сaddy);
  • административные действия с запусками.

Как получить роль:

  • администратор назначает роль в админке: список пользователей → поле Роль → teacher.

2. Вход и навигация

  1. Войдите в систему под своим аккаунтом.
  2. В верхнем меню появится пункт Обучение.
  3. Откройте Обучение → вкладка Нормы.
  4. Для работы с кодом запуска используйте вкладку Новые нормы в карточке запуска.

3. Каталог норм (просмотр)

Вкладка Нормы включает каталог норм:

  • Источник: Статический анализатор или LLM нормы.
  • Поиск по norm_id, названию или разделу.
  • Карточка нормы раскрывается и показывает:
    • раздел/категорию;
    • текст нормы;
    • подсказки детекта и обоснование (если есть);
    • источник.

Задача преподавателя: сверять нормы, выявлять дубли, фиксировать пробелы.

4. Создание пользовательских норм

Ниже каталога — форма «Пользовательские нормы». Эти нормы пока не участвуют в автоматическом анализе, но сохраняются в БД для экспертизы и дальнейшей интеграции.

4.1 Обязательные поля

  • norm_id: уникальный идентификатор (латиница и подчёркивания).
    Рекомендуемый формат: TEACHER_YYYY_NNN или CUSTOM_001.
  • Название: короткое понятное название нормы.
  • Раздел: область знаний (например, Запросы, Транзакции, Безопасность).
  • Область: где применяется (сервер, клиент, общий модуль, запросы).
  • Текст нормы: основное правило и критерий нарушения.

4.2 Дополнительные поля (рекомендуется)

  • Серьёзность: critical | major | minor | info.
  • Тип детектора: например custom (если ручная/экспертная норма).
  • Тип проверки: manual, llm или static.
  • Источник: документ/раздел (если есть).
  • Выдержка: пример или цитата из документа.
  • Применимо к коду: включено по умолчанию.
  • Активна: включено по умолчанию.
  • Версия: обычно 1.

5. Создание нормы из выделения кода

Это основной способ фиксировать новую норму, когда вы нашли проблему в коде.

  1. Откройте запуск и перейдите на вкладку Новые нормы.
  2. В блоке «Исходный код запуска» откройте нужный файл.
  3. Выделите фрагмент кода (строки содержат формат NNN: код).
  4. Нажмите кнопку Создать норму в закреплённой панели сверху.
  5. Форма откроется с предзаполненным полем «Пример/выдержка» (текст выделения).
  6. Заполните обязательные поля и сохраните.

Важно: выделение обрабатывается только после нажатия кнопки Создать норму.

6. Рекомендуемый процесс обучения

  1. Просмотрите запуск: статические нарушения и предложения LLM.
  2. Для корректных, но отсутствующих в нормах проблем:
    • создайте норму через выделение кода;
    • задайте корректную серьёзность;
    • добавьте понятный текст правила и область применения.
  3. Для некорректных предложений LLM:
    • отмечайте как отклонённые (это помогает статистике качества).
  4. Регулярно сверяйте новые нормы с каталогом, чтобы избегать дублей.

7. Ограничения текущей версии

  • Пользовательские нормы сохраняются, но не используются в автоматическом анализе.
    Они попадут в работу после отбора и подключения командой разработки.
  • Создание нормы не требует перезапуска системы, но фиксируется в БД.

8. Подсказки по качеству норм

  • Норма должна быть проверяемой (по коду видно, что нарушено).
  • Формулировка должна быть конкретной и измеримой.
  • В примере лучше показывать именно ошибку, а не общий фрагмент.

Если нужна помощь с формулировкой или классификацией — пишите в команду разработки.