Техническое задание: Веб-приложение "Homework Checker" (MVP) - v1.2 ======================================================================== 1. Общее описание и цели проекта --------------------------------- 1.1. Название проекта ~~~~~~~~~~~~~~~~~~~~~ Homework Checker 1.2. Цель ~~~~~~~~~ Разработать минимально жизнеспособный продукт (MVP) веб-приложения для автоматизации процесса сдачи и проверки домашних заданий в рамках учебных курсов. Приложение должно упростить взаимодействие между преподавателями и студентами, обеспечить прозрачность оценок и обратной связи. 1.3. Целевая аудитория ~~~~~~~~~~~~~~~~~~~~~~ * **Преподаватели:** ведущие курсы, репетиторы. * **Студенты:** учащиеся курсов. * **Администраторы:** управление системой и пользователями. 1.4. Ключевые ограничения ~~~~~~~~~~~~~~~~~~~~~~~~~~ Проект разработан за 3 часа с применением методологии **Extreme Programming (XP)**. Это диктует выбор технологий (Python/Django) и фокус на простоте и скорости реализации, а также определяет приоритеты функциональных требований. 1.5. Методология разработки ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Проект следует принципам **Extreme Programming**: - Парное программирование (code review через pull requests) - Непрерывная интеграция (CI/CD с автоматическими тестами) - Частые релизы (итеративная разработка) - Простой дизайн (YAGNI - You Aren't Gonna Need It) - Рефакторинг (постоянное улучшение кода) - Коллективное владение кодом (все участники команды работают над всеми частями) - Тест-ориентированная разработка (TDD) 2. Роли пользователей и их права --------------------------------- В системе предусмотрено 3 роли: 2.1. Студент (Student) ~~~~~~~~~~~~~~~~~~~~~~ * Может просматривать список курсов, на которые он записан. * Может просматривать список домашних заданий в рамках каждого курса. * Может загружать файл с решением для каждого задания (повторная загрузка заменяет предыдущий файл). * Может просматривать свою оценку и текстовый отзыв от преподавателя по каждому заданию. * Может просматривать таблицу со всеми своими оценками по всем курсам. * **Не может** видеть чужие работы, создавать курсы и задания, проверять работы. * **Не имеет** доступа к админ-панели Django. 2.2. Преподаватель (Teacher) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * Может создавать, редактировать и удалять **Курсы** через веб-интерфейс. * Может создавать, редактировать и удалять **Домашние задания** в рамках своих курсов через веб-интерфейс. * Может записывать студентов на свои курсы через веб-интерфейс. * Может просматривать список всех отправок по каждому из своих заданий. * Может скачивать файлы, отправленные студентами. * Может выставлять оценку (число) и оставлять текстовый отзыв для каждой отправки через веб-интерфейс. * Может фильтровать работы по статусу (все/непроверенные/проверенные). * **Не может** видеть курсы других преподавателей (если не добавлен как co-teacher). * **Не имеет** доступа к админ-панели Django (только через веб-интерфейс). 2.3. Администратор (Superuser) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * Имеет полный доступ к системе через админ-панель Django. * Может создавать и управлять учетными записями всех пользователей. * Может назначать роли "Студент" или "Преподаватель" пользователям. * Исполняет все функции Преподавателя, но в рамках всей системы. * Может управлять всеми курсами, заданиями и отправками. 3. Функциональные требования ----------------------------- *Приоритеты:* **P0** - Must-Have (обязательно для MVP), **P1** - Should-Have (желательно, но можно отложить). 3.1. Модуль аутентификации ~~~~~~~~~~~~~~~~~~~~~~~~~~~ * **FR-1 (P0):** Пользователи должны иметь возможность зарегистрироваться в системе (``register``), указав роль. * **FR-2 (P0):** Пользователи должны иметь возможность войти в систему (``login``) и выйти из нее (``logout``). * **FR-3 (P0):** Неавторизованные пользователи перенаправляются на страницу входа при попытке доступа к защищенным страницам. 3.2. Функционал для Студента (веб-интерфейс) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * **FR-4 (P0): Список курсов и домашних заданий (Dashboard):** * После входа студент видит страницу со списком курсов, на которые он записан. * При переходе на страницу курса отображается список домашних заданий этого курса. * Каждый элемент списка ДЗ содержит: заголовок, срок сдачи, статус ("Сдано" / "Не сдано" / "Оценено"). * **FR-5 (P0): Страница детального просмотра ДЗ:** * Содержит полное описание задания. * Если работа не сдана, на странице присутствует форма для загрузки файла. * **FR-6 (P0): Отправка решения:** * Форма должна принимать один файл (поддержка различных форматов: ``.pdf``, ``.zip``, ``.docx``, и др.). * **FR-7 (P0): Просмотр результата:** * Если работа отправлена, отображается: дата отправки, оценка (если есть) и отзыв преподавателя (если есть). * **FR-8 (P0): Таблица с результатами:** * Отдельная страница "Мои оценки", где в виде таблицы сведены все задания по всем курсам и итоговые оценки. * **FR-9 (P0): История отправок:** * Страница "Мои работы" со списком всех отправленных работ. 3.3. Функционал для Преподавателя (веб-интерфейс) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * **FR-10 (P0): Управление Курсами (CRUD):** * Преподаватель через веб-интерфейс может создавать новые Курсы, указывая ``title``, ``description``. * Преподаватель может редактировать и удалять свои курсы. * Преподаватель может добавлять/удалять студентов на свой курс через отдельную страницу управления студентами. * **FR-11 (P0): Управление ДЗ (CRUD):** * Преподаватель через веб-интерфейс может создавать новые ДЗ в рамках своих курсов, указывая ``title``, ``description``, ``due_date``. * Преподаватель может редактировать и удалять свои домашние задания. * **FR-12 (P0): Проверка отправок:** * Преподаватель видит список всех отправок по каждому заданию через веб-интерфейс. * На странице проверки отправки он может: * Скачать файл решения. * Заполнить поле ``grade`` (оценка). * Заполнить поле ``feedback`` (отзыв). * Преподаватель может фильтровать работы: "Все" / "Непроверенные" / "Проверенные". * **FR-13 (P0): Статистика:** * На странице курса отображается количество заданий. * На странице задания отображается количество сданных работ. 3.4. Функционал для Администратора (админ-панель Django) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * **FR-14 (P0): Полное управление:** * Доступ к админ-панели Django (``/admin``). * Создание, редактирование, удаление пользователей. * Назначение ролей пользователям. * Управление всеми курсами, заданиями, отправками. 4. Нефункциональные требования ------------------------------- 4.1. Дизайн и юзабилити ~~~~~~~~~~~~~~~~~~~~~~~ * **NFR-1 (P0):** Простой и интуитивно понятный интерфейс для всех ролей. * **NFR-2 (P0):** Использование CSS-фреймворка Bootstrap 5 через CDN для быстрой стилизации. * **NFR-3 (P0):** Адаптивный дизайн (responsive design) - работа на всех устройствах (desktop, tablet, mobile). * **NFR-4 (P0):** Единый стиль для всех страниц. 4.2. Безопасность ~~~~~~~~~~~~~~~~~ * **NFR-5 (P0):** Доступ к страницам и данным ограничен в соответствии с ролями и принадлежностью к курсу (студент видит только свои курсы, преподаватель - только свои). * **NFR-6 (P0):** Доступ в ``/admin`` разрешен только пользователям с флагом ``is_staff`` и ``is_superuser`` (только Администраторам). * **NFR-7 (P0):** Защита от базовых веб-уязвимостей: * Использование Django ORM для предотвращения SQL-инъекций. * Автоматическое экранирование данных в Django Templates для защиты от XSS. * CSRF-токены для защиты от межсайтовой подделки запросов. * **NFR-8 (P1):** Безопасная загрузка файлов: ограничение по размеру файла. 4.3. Производительность ~~~~~~~~~~~~~~~~~~~~~~~~ * **NFR-9 (P0):** Время загрузки страницы не более 2 секунд при локальном запуске. * **NFR-10 (P1):** Оптимизация запросов к БД (использование ``select_related``, ``prefetch_related``). 4.4. Тестирование ~~~~~~~~~~~~~~~~~ * **NFR-11 (P0):** Наличие автоматических тестов для критических функций. * **NFR-12 (P0):** Тесты безопасности (разграничение доступа). * **NFR-13 (P0):** CI/CD pipeline с автоматическим запуском тестов. 4.5. Документация ~~~~~~~~~~~~~~~~~ * **NFR-14 (P0):** Наличие README с инструкциями по запуску. * **NFR-15 (P0):** Google Style docstrings для всех функций и классов. * **NFR-16 (P0):** Автоматическая генерация документации из docstrings (Sphinx). * **NFR-17 (P0):** Публикация документации на GitHub Pages. 4.6. Качество кода ~~~~~~~~~~~~~~~~~~ * **NFR-18 (P0):** Соблюдение PEP 8 (проверка через flake8). * **NFR-19 (P0):** Автоформатирование кода (black). * **NFR-20 (P0):** Сортировка импортов (isort). * **NFR-21 (P0):** Статический анализ кода (pylint). 4.7. Требования к тестированию безопасности ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * **T-SEC-1 (P0):** **Тест на контроль доступа по ролям.** Попытка доступа к ``/admin`` под учетной записью студента или преподавателя должна приводить к ошибке доступа или редиректу. * **T-SEC-2 (P0):** **Тест на изоляцию данных.** Попытка получить доступ к странице чужой сданной работы по прямому URL пользователем, не являющимся автором работы или преподавателем курса, должна быть заблокирована. * **T-SEC-3 (P0):** **Тест на доступ к курсам.** Студент А, записанный на Курс 1, не должен видеть информацию о Курсе 2, на который он не записан. * **T-SEC-4 (P0):** **Тест на изоляцию курсов преподавателей.** Преподаватель А не должен видеть и управлять курсами Преподавателя Б. 4.8. Технический стек ~~~~~~~~~~~~~~~~~~~~~ * **Backend:** Python 3.9+, Django 5.2.7 * **База данных:** SQLite (для разработки, легко мигрируется на PostgreSQL) * **Frontend:** Django Templates, HTML5, Bootstrap 5 (CDN), Bootstrap Icons * **Документация:** Sphinx, sphinx-rtd-theme * **Линтеры:** flake8, black, isort, pylint, pylint-django * **CI/CD:** GitHub Actions * **Хостинг документации:** GitHub Pages 5. Критерии приемки MVP ------------------------ Проект считается успешно завершенным, если выполнены следующие сквозные сценарии: 5.1. Сценарий "Полный цикл ДЗ" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. **Регистрация Преподавателя:** * Преподаватель регистрируется через веб-форму, выбирая роль "Преподаватель". 2. **Создание Курса:** * Преподаватель через веб-интерфейс создает Курс "Программирование на Python". 3. **Регистрация Студента:** * Студент регистрируется через веб-форму, выбирая роль "Студент". 4. **Запись Студента на Курс:** * Преподаватель через веб-интерфейс записывает студента на свой курс. 5. **Создание ДЗ:** * Преподаватель через веб-интерфейс создает ДЗ "Задание 1: Hello World" в рамках курса. 6. **Сдача работы Студентом:** * Студент входит, видит свой Курс, переходит к списку ДЗ и загружает решение (файл). 7. **Проверка работы Преподавателем:** * Преподаватель через веб-интерфейс находит отправку, скачивает файл, проверяет работу, ставит оценку "95" и оставляет отзыв "Отличная работа!". 8. **Просмотр результата Студентом:** * Студент на странице ДЗ видит свою оценку и отзыв. * Студент в разделе "Мои оценки" видит таблицу с оценкой. 5.2. Сценарий "Контроль доступа" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. **Изоляция работ:** * Студент А не может видеть отправку Студента Б, даже если они на одном курсе. 2. **Защита админки:** * Студент не может войти в ``/admin`` (получает ошибку 403 или редирект). * Преподаватель не может войти в ``/admin`` (получает ошибку 403 или редирект). * Только Администратор (superuser) имеет доступ к ``/admin``. 3. **Изоляция курсов:** * Преподаватель А не может управлять курсами и проверять задания Преподавателя Б (если он не добавлен в этот курс как второй преподаватель). 4. **Изоляция студентов:** * Студент видит только те курсы, на которые он записан. 5.3. Сценарий "CI/CD и качество кода" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. **Автоматические тесты:** * При каждом push в ``main`` или создании PR запускаются тесты. * Все тесты должны пройти успешно. 2. **Линтинг:** * При каждом push/PR запускается проверка кода (flake8, black, isort, pylint). * Код должен соответствовать всем правилам. 3. **Документация:** * При каждом push в ``main`` автоматически генерируется и публикуется документация на GitHub Pages. 4. **Code Review:** * Все изменения вносятся через pull requests. * Каждый PR проходит code review другим членом команды. 6. Реализованные улучшения сверх ТЗ v1.1 ----------------------------------------- 6.1. Веб-интерфейс для преподавателей ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Вместо** работы через админ-панель Django (как было в v1.1) **Реализовано** отдельный удобный веб-интерфейс для преподавателей. **Преимущества:** - ✅ Более интуитивный и user-friendly интерфейс - ✅ Лучшая безопасность (преподаватели не имеют доступа к системным функциям) - ✅ Специализированные страницы для каждой задачи - ✅ Фильтрация работ по статусу 6.2. Регистрация пользователей ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Добавлено** веб-форма регистрации с выбором роли. **Преимущества:** - ✅ Не нужно создавать пользователей через админку - ✅ Упрощает тестирование и использование - ✅ Пользователи могут самостоятельно зарегистрироваться 6.3. История отправок ~~~~~~~~~~~~~~~~~~~~~ **Добавлено** страница "Мои работы" для студентов. **Преимущества:** - ✅ Студент видит историю всех своих отправок - ✅ Удобный обзор прогресса 6.4. Фильтры для преподавателей ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Добавлено** фильтрация работ: все/непроверенные/проверенные. **Преимущества:** - ✅ Быстрый доступ к работам, требующим проверки - ✅ Удобная навигация 6.5. Статистика ~~~~~~~~~~~~~~~ **Добавлено** счетчики заданий и сданных работ. **Преимущества:** - ✅ Преподаватель видит прогресс курса - ✅ Быстрая оценка активности студентов 7. Известные ограничения MVP ----------------------------- Следующие функции **НЕ** реализованы в текущей версии (могут быть добавлены в будущих версиях): * ❌ Восстановление пароля по email * ❌ Email-уведомления о новых заданиях/оценках * ❌ Групповые работы (несколько студентов на одно задание) * ❌ Автоматическая проверка кода (автотесты) * ❌ Экспорт оценок в Excel/CSV * ❌ Расширенная статистика (графики, диаграммы) * ❌ Комментарии к конкретным строкам кода * ❌ Интеграция с внешними LMS (Moodle, Canvas) * ❌ Поддержка нескольких файлов в одной отправке * ❌ Версионирование отправок (история изменений) * ❌ Чат между студентом и преподавателем * ❌ Календарь с дедлайнами **Обоснование:** Данные функции выходят за рамки MVP и требуют значительно больше времени на разработку. Текущая версия сфокусирована на базовом, но полном цикле работы с домашними заданиями. 8. План развития (Post-MVP) ---------------------------- Версия 2.0 (следующие итерации) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 🔔 Email-уведомления - 📊 Расширенная статистика и аналитика - 📁 Поддержка нескольких файлов - 🔄 Версионирование отправок - 📝 Комментарии к коду Версия 3.0 (будущее) ~~~~~~~~~~~~~~~~~~~~ - 🤖 Автоматическая проверка кода - 🎓 Интеграция с LMS - 👥 Групповые работы - 📅 Календарь и напоминания - 💬 Встроенный чат 9. Соответствие Extreme Programming ------------------------------------ Проект полностью следует принципам XP: .. list-table:: :header-rows: 1 :widths: 30 70 * - Практика XP - Реализация в проекте * - **Парное программирование** - Pull requests с code review * - **Непрерывная интеграция** - GitHub Actions CI/CD * - **Частые релизы** - Итеративная разработка (4 итерации за 3 часа) * - **Простой дизайн** - Django + Bootstrap, SQLite, минимум зависимостей * - **Рефакторинг** - Постоянное улучшение кода (см. историю коммитов) * - **Коллективное владение** - Все участники работали над всеми частями * - **TDD** - Тесты добавлены на ранней стадии * - **Стандарты кодирования** - PEP 8, линтеры, Google Style docstrings * - **Устойчивый темп** - 3 часа, без овертаймов * - **Метафора системы** - "Виртуальная учебная аудитория" Заключение ---------- Данное техническое задание описывает **реализованную** систему Homework Checker. Все требования уровня P0 выполнены на 100%. Проект может служить базой для дальнейшего развития и масштабирования. | **Статус:** ✅ MVP готов и протестирован | **Версия ТЗ:** 1.2 (обновлено под фактическую реализацию) | **Дата:** Октябрь 2025 | **Методология:** Extreme Programming (XP)