Система оценки студентов

Это приложение на базе Streamlit, предназначенное для автоматизированного сбора, анализа и формирования единого рейтинга студентов. Система принимает на вход разрозненные Excel и CSV таблицы (ведомости посещаемости, списки оценок, данные об участии в мероприятиях), автоматически распознает их структуру и рассчитывает итоговые баллы.

Основные возможности

• Мультизагрузка: Обработка множества файлов (Excel/CSV) одновременно.
• Умный парсинг:
  • Автоматическое определение заголовков таблиц.
  • Распознавание типов таблиц: Посещаемость, Успеваемость, Активности.
  • Поиск колонок с ФИО, ID и группой (поддержка нечеткого поиска).
• Гибкая настройка:
  • Возможность переопределить распознанные заголовки и типы колонок через UI.
  • Настройка весов для разных типов активности (Хакатоны, Статьи, Спорт и др.).
• Ручной ввод: Добавление баллов вручную для отдельных студентов.
• Фильтрация: Поддержка "белого списка" (реестра) студентов кафедры.
• Экспорт: Генерация итогового Excel-файла с рейтингом, детализацией начислений и статистикой по группам.

Установка и запуск

Требования

• Python 3.10+
• Библиотеки из requirements.txt

Запуск приложения

Поместите все файлы в одну директорию (или настройте структуру пакетов, если используете папку core/) и выполните команду:

streamlit run app.py

Приложение откроется в браузере по адресу http://localhost:8501.

Использование

1. Загрузка данных: Перетащите файлы с таблицами в область загрузки.
2. Загрузка списка кафедры (опционально): Загрузите файл со списком всех студентов, чтобы отсеять лишних людей из рейтинга.
3. Настройка параметров: Укажите максимальные баллы за успеваемость и посещаемость.
4. Проверка распознавания: В блоке "Контроль распознавания" просмотрите загруженные таблицы. Если заголовки или колонки определились неверно, скорректируйте их вручную и нажмите "Сохранить профиль".
5. Формирование отчета: Нажмите кнопку "Сформировать итоговый отчёт".
6. Результат: Ознакомьтесь с таблицей рейтинга и скачайте Excel-файл.

Конфигурация

Файл rules.json содержит ключевые настройки:

• attendance: символы, обозначающие присутствие (+), отсутствие (н) и уважительную причину (у).
• activity_kinds: список типов активностей.
• activity_points_default: баллы по умолчанию за разные роли (Участник, Победитель и т.д.).

Структура проекта

• app.py: Точка входа, интерфейс Streamlit.
• infer.py: Логика распознавания заголовков и типов колонок.
• extract.py: Извлечение данных из таблиц (оценки, посещаемость).
• scoring.py: Агрегация баллов и расчет рейтинга.
• ingest.py: Чтение Excel (с учетом объединенных ячеек) и CSV.
• rules.json: Справочник правил и настроек.

---

Техническая документация

Обзор архитектуры

Приложение построено по конвейерному принципу (Pipeline):

1. Ingest (Загрузка сырых данных)
2. Inference (Анализ структуры и метаданных)
3. Extraction (Извлечение нормализованных данных)
4. Scoring (Сведение данных и расчет баллов)
5. Export (Генерация отчетов)

Описание модулей

1. app.py (Интерфейс)

Главный файл приложения. Отвечает за:

• Отрисовку виджетов Streamlit.
• Управление состоянием сессии (st.session_state).
• Взаимодействие с пользователем для коррекции распознавания (Header Overrides, Column Mapping).
• Запуск процесса расчета.

2. ingest.py (Загрузка данных)

Отвечает за чтение файлов.

• Ключевая функция: load_tables_from_uploads.
• Особенность: Функция _sheet_to_matrix_with_merged корректно обрабатывает объединенные ячейки в Excel, "размножая" значение родительской ячейки на все объединенные, что критично для сложных шапок таблиц.

3. infer.py (Логика распознавания)

Мозг системы, отвечающий за понимание того, что находится в таблице.

• detect_header_block: Эвристический алгоритм поиска шапки таблицы (ищет строки с наибольшим количеством заполненных текстовых ячеек).
• infer_schema: Определяет тип таблицы (Attendance/Grades/Activity) и маппинг колонок (где ФИО, где Оценки) на основе ключевых слов (fuzzy matching через rapidfuzz или difflib).
• SYN словарь: Содержит синонимы для поиска колонок (например, "студент", "fio", "name").

4. extract.py (Извлечение данных)

Преобразует "сырые" DataFrame в унифицированный список записей (evidence rows).

• extract_attendance_wide: Считает процент посещаемости. Поддерживает символы из rules.json.
• extract_grades_wide: Парсит оценки. Умеет работать с:
  • Числовыми оценками (2, 3, 4, 5).
  • Зачетами (зач/незач -> 5/2).
  • Баллами (конвертирует 0-100 в 2-5).
  • Форматами вида "5 (отл)".
• make_student_key: Создает уникальный ключ студента для дальнейшего объединения (приоритет ID, иначе ФИО+Группа).

5. scoring.py (Расчет рейтинга)

• unify_students: Объединяет записи об одном студенте из разных файлов (справляется с опечатками в ФИО).
• compute_scores:
  • Агрегирует данные по категориям (A - Успеваемость, B - Посещаемость, C - Активность, X - Ручное).
  • Применяет весовые коэффициенты (acad_max, att_max).
  • Формирует итоговые DataFrame: ranking_df (краткий), detail_df (с обоснованием каждого балла).

6. entity.py

Отвечает за нормализацию сущностей (студентов). Содержит логику дедупликации студентов на основе графа связности (если в одной таблице Иванов Иван + ID 123, а в другой ID 123 + Иванов И., система поймет, что это один человек).

7. utils.py и rules.json

• rules.json: Хранит конфигурацию.
  • Словарь баллов для активностей (Участник/Призёр/Победитель).
• utils.py: Функции нормализации текста (norm_text, norm_name) для улучшения качества поиска и сравнения строк.

Алгоритм работы с баллами

1. Посещаемость: Рассчитывается доля (0.0 - 1.0). Если доля < att_threshold (порог), баллы обнуляются. Иначе умножается на att_max.
2. Успеваемость: Средняя оценка нормализуется в диапазон 0..1 и умножается на acad_max.
3. Активность: Суммируются фиксированные баллы за каждое мероприятие согласно rules.json (например, Хакатон Победитель = 14 баллов).

Расширение функционала

Для добавления нового типа активности:

1. Откройте rules.json.
2. Добавьте название в массив activity_kinds.
3. Добавьте расценки в объект activity_points_default.
4. (Опционально) Добавьте ключевые слова в ACTIVITY_KIND_KEYWORDS в файле infer.py для автоопределения.