Техническое задание: Веб-приложение «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. Сценарий «Полный цикл ДЗ»

Регистрация Преподавателя:
- Преподаватель регистрируется через веб-форму, выбирая роль «Преподаватель».
Создание Курса:
- Преподаватель через веб-интерфейс создает Курс «Программирование на Python».
Регистрация Студента:
- Студент регистрируется через веб-форму, выбирая роль «Студент».
Запись Студента на Курс:
- Преподаватель через веб-интерфейс записывает студента на свой курс.
Создание ДЗ:
- Преподаватель через веб-интерфейс создает ДЗ «Задание 1: Hello World» в рамках курса.
Сдача работы Студентом:
- Студент входит, видит свой Курс, переходит к списку ДЗ и загружает решение (файл).
Проверка работы Преподавателем:
- Преподаватель через веб-интерфейс находит отправку, скачивает файл, проверяет работу, ставит оценку «95» и оставляет отзыв «Отличная работа!».
Просмотр результата Студентом:
- Студент на странице ДЗ видит свою оценку и отзыв.
- Студент в разделе «Мои оценки» видит таблицу с оценкой.

5.2. Сценарий «Контроль доступа»

Изоляция работ:
- Студент А не может видеть отправку Студента Б, даже если они на одном курсе.
Защита админки:
- Студент не может войти в /admin (получает ошибку 403 или редирект).
- Преподаватель не может войти в /admin (получает ошибку 403 или редирект).
- Только Администратор (superuser) имеет доступ к /admin.
Изоляция курсов:
- Преподаватель А не может управлять курсами и проверять задания Преподавателя Б (если он не добавлен в этот курс как второй преподаватель).
Изоляция студентов:
- Студент видит только те курсы, на которые он записан.

5.3. Сценарий «CI/CD и качество кода»

Автоматические тесты:
- При каждом push в main или создании PR запускаются тесты.
- Все тесты должны пройти успешно.
Линтинг:
- При каждом push/PR запускается проверка кода (flake8, black, isort, pylint).
- Код должен соответствовать всем правилам.
Документация:
- При каждом push в main автоматически генерируется и публикуется документация на GitHub Pages.
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:

Практика 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)