EduTask

MVP образовательного трека хакатона AI Sana: от потребности преподавателя до понятной проектной задачи и предложения студенческой команды.

1. Какую проблему решает проект

Преподавателю бывает сложно превратить идею «хочу сделать урок интереснее» в задание, по которому команда сможет предложить решение: обозначить аудиторию, материалы, ограничения, ожидаемый результат и критерии успеха. Студенческой команде, в свою очередь, нужна понятная постановка задачи и способ предложить свою помощь.

EduTask объединяет этот процесс в одном веб-приложении. AI помогает уточнить и оформить задачу, преподаватель проверяет и подтверждает текст, а команды находят опубликованные задачи и отправляют предложения.

Целевая аудитория — преподаватели как заказчики образовательных решений и студенческие команды как исполнители. Текущая версия не проводит уроки: она помогает подготовить и согласовать задание на создание урока, набора упражнений, методических материалов или веб-приложения.

2. Что реализовано

• Мастер создания задачи из трёх шагов: исходное описание, уточнение деталей, редактирование и подтверждение карточки.
• AI-помощь: улучшение исходной формулировки, уточняющие вопросы с редактируемыми вариантами ответов, генерация карточки и замечания перед публикацией.
• Прозрачный рейтинг готовности от 0 до 100: предварительная оценка, разбивка баллов по полям и подсказки о недостающей информации. Рейтинг рассчитывает сервер по правилам, а не AI.
• Общий каталог: публикация, поиск, фильтр по уровню готовности, сортировка по рейтингу или новизне, просмотр и редактирование опубликованной карточки.
• Подбор задач команде: оценка соответствия указанным навыкам, интересам и сроку с пояснением; сортировка и фильтр «Только подходящие».
• Предложения команд: название команды, идея, план, срок и ссылка на прототип. Преподаватель вручную принимает или отклоняет каждое предложение; можно принять несколько команд.
• Сохранение на сервере: черновики, опубликованные задачи, отклики и решения остаются после перезапуска.
• Удобства интерфейса: быстрые примеры, светлая и тёмная темы, редактируемый локальный профиль, автосохранение исходного текста черновика в браузере.
• Демо-режим без API-ключа: основной сценарий можно пройти без платных запросов; предусмотрены локальные ответы при недоступности AI.

Роли «Преподаватель» и «Студенческая команда» переключаются для демонстрации. Это не авторизация и не разграничение прав доступа.

3. Как работает решение

1. Преподаватель вводит описание потребности длиной 15–500 символов, при желании использует пример или улучшение текста.
2. Сервер сохраняет черновик и возвращает уточняющие вопросы с предложенными ответами. Преподаватель проверяет ответы, указывает аудиторию, предмет, формат, срок, имеющиеся материалы и ограничения.
3. На основе этих данных формируется редактируемая карточка: название, контекст, ожидаемый результат и критерии успеха. Преподаватель дополняет её, включая контакт и формат обратной связи.
4. Интерфейс показывает замечания и предварительный рейтинг. После явного подтверждения преподавателем карточка публикуется в общем каталоге.
5. Команда находит задачу через каталог или подбор по навыкам, открывает её и отправляет предложение.
6. Преподаватель принимает или отклоняет предложение. Задача, отклики и принятые решения сохраняются в серверном JSON-хранилище.

AI не публикует задачи и не выбирает исполнителя самостоятельно. Предложенные ответы — варианты для проверки человеком, а не установленные факты.

Как устроен рейтинг и элемент геймификации

Заполнение карточки повышает её готовность и позицию в стандартной сортировке каталога. Это реализованный элемент геймификации MVP; баллов за обучение или наград студенческим командам пока нет.

Что проверяется	Условие начисления	Баллы
Контекст	Не менее 30 символов после удаления пробелов по краям	20
Материалы	Не менее 10 символов	20
Ожидаемый результат	Не менее 20 символов	15
Критерии успеха	Не менее двух непустых пунктов	15
Ограничения или срок	Хотя бы один непустой пункт либо указанный срок	10
Аудитория	Хотя бы один непустой пункт	10
Контакт и обратная связь	Контакт от пяти символов и непустой формат взаимодействия	10

Уровни: 0–39 — требует уточнения (draft), 40–69 — рабочая (working), 70–89 — готовая (ready), 90–100 — приоритетная (priority).

У неподтверждённой карточки сохранённая оценка равна нулю; предварительный расчёт показывает оценку, которую она получит после подтверждения. Для публикации нужны название, контекст и подтверждение, но минимальный порог баллов не установлен. Опубликованные задачи с низким рейтингом доступны для откликов.

Рейтинг оценивает заполненность, а не достоверность материалов, педагогическое качество или знания ученика. Процент соответствия навыкам команды — отдельная оценка, не заменяющая рейтинг готовности. Уровень draft также не равнозначен статусу неопубликованного черновика.

4. Технологии

Часть	Реализация
Интерфейс	HTML, CSS, JavaScript без фронтенд-фреймворка; DOM, Fetch API, localStorage
Сервер	Node.js, CommonJS, встроенные http, fs, path, crypto и fetch; без Express
AI	OpenAI Chat Completions API; модель по умолчанию в коде — gpt-4o-mini, настраивается через OPENAI_MODEL
Формат AI-ответов	Structured Outputs через response_format: json_schema, затем серверная проверка структуры JSON
Хранение	JSON-файл на диске сервера; локальные настройки интерфейса — в браузере
Проверки	Встроенные node:test и node:assert; отдельный браузерный сценарий через Chrome DevTools Protocol и WebSocket
Шрифты	Manrope и Playfair Display через Google Fonts, с запасными системными шрифтами

В package.json нет сторонних npm-зависимостей. OpenAI вызывается серверным HTTP-запросом, без отдельного SDK. NVIDIA API в текущем коде не подключён.

5. Архитектура проекта

Браузер получает интерфейс и обращается к API на одном адресе. Один процесс Node.js обслуживает сайт, работу с задачами и обращения к AI.

Браузер: index.html + styles.css + JavaScript
  ├─ localStorage: тема, локальный профиль, исходный текст
  └─ HTTP /api/* → server.js
                    ├─ AI-обработчики → OpenAI API
                    │                  или локальный демо-ответ
                    └─ api/tasks.js
                         ├─ api/scoring.js → рейтинг по правилам
                         └─ data/runtime/tasks.json → задачи и отклики

Файл	Назначение
server.js	Точка запуска, загрузка .env, выдача сайта, обработка HTTP, AI и демо-ответы
api/tasks.js	Черновики, публикация, редактирование, каталог, предложения команд и запись данных
api/scoring.js	Формула рейтинга и список недостающих сведений
app.js	Мастер создания, AI-проверка, каталог и подбор задач
tasks-ui.js	Подтверждение, разбивка рейтинга, демонстрационные роли, формы отклика и редактирования
ui-preferences.js	Тема, профиль, быстрые примеры и восстановление исходного текста
data/tasks.json	Стартовая демонстрационная задача для первого запуска
api/task-schema.json	Описание структуры карточки
docs/api-contract.md	Маршруты API, входные поля, ответы и правила переходов
api/server.js	Совместимый прежний вход в тот же сервер, не отдельный сервис

При первом запуске стартовые данные копируются в рабочий файл, если он отсутствует. Запись выполняется через временный файл и переименование. Это файловое хранилище для одного процесса, а не многопользовательская производственная СУБД.

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

Требования и получение проекта

Для повторения всех проверок используйте Node.js 24, npm и современный браузер. Для клонирования нужен Git. Команды ниже предназначены для PowerShell на Windows; в других оболочках команды npm.cmd заменяются на npm.

git clone https://github.com/BAITC-Hacks/hack-0e4a4153-bulduck.git
cd hack-0e4a4153-bulduck
node -v
npm.cmd -v

Если репозиторий уже открыт локально, выполняйте следующие команды из его корня — повторное клонирование не нужно. Устанавливать npm-зависимости не требуется.

Настройка окружения

Создайте .env по примеру, не перезаписывая существующий файл:

if (-not (Test-Path .env)) { Copy-Item .env.example .env }
notepad .env

Для демонстрации без платных запросов используйте:

OPENAI_API_KEY=
OPENAI_MODEL=gpt-4o-mini
PORT=3000
AI_MODE=demo

Для реального AI укажите собственный ключ в OPENAI_API_KEY и удалите строку AI_MODE=demo. При необходимости измените OPENAI_MODEL: выбранная модель должна быть доступна вашему API-проекту и поддерживать используемый формат структурированных ответов.

Переменная	Назначение	Если не задана
OPENAI_API_KEY	Серверный ключ OpenAI	Локальный демо-режим
OPENAI_MODEL	Имя модели для AI-запросов	gpt-4o-mini
PORT	Порт HTTP-сервера	3000
AI_MODE	Значение demo принудительно отключает обращения к OpenAI	Использование AI при наличии ключа
EDUTASK_DATA_FILE	Другой путь к рабочему JSON-хранилищу	data/runtime/tasks.json

.env исключён из Git и не выдаётся HTTP-сервером. Не вставляйте ключ в клиентские файлы и не публикуйте его в репозитории.

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

npm.cmd start

• Приложение: http://localhost:3000.
• Проверка сервера: http://localhost:3000/api/health.
• Каталог в формате JSON: http://localhost:3000/api/tasks.

При изменении PORT используйте соответствующий порт в адресах. Открывать index.html напрямую через file:// нельзя для полноценной работы с API.

Оставьте терминал работающим на время демонстрации. Остановка — Ctrl+C; после изменения .env сервер нужно перезапустить. Для разработки с автоматическим перезапуском при изменении кода есть команда npm.cmd run dev.

На Windows npm.cmd также позволяет запускать проект, если PowerShell блокирует скрипт npm.ps1, без изменения политики выполнения скриптов. Если не находится и npm.cmd, проверьте установку Node.js и откройте новый терминал после установки.

Как отличить настоящий AI от демо

В демо-режиме уточнения и рекомендации формируются локальными правилами. При генерации карточки поля результата и критериев остаются пустыми — их заполняет преподаватель. Подбор задач использует совпадения слов, а не модель.

При отсутствии ключа либо ошибке провайдера API возвращает demo: true; при ошибке также возвращается warning. Интерфейс сообщает о демо при уточнении, создании карточки и подборе задач. Тайм-аут обращения к OpenAI — 20 секунд.

Поле ai: true в /api/health означает только, что сервер настроен использовать ключ, а не что запрос к OpenAI успешно выполнен. Для проверки интеграции выполните действие с AI и убедитесь, что в ответе соответствующего запроса во вкладке Network инструментов разработчика нет demo: true и предупреждения о замене ответа.

7. Как проверить решение: сценарий для жюри

Сценарий воспроизводится в демо-режиме без API-ключа. Входные данные ниже — учебный пример, а не результат реального внедрения.

1. Откройте приложение и введите:

   Мне нужен интерактивный урок истории Казахстана для 8 класса, чтобы ученики лучше поняли тему «Алаш Орда» и не просто заучивали даты.

2. Нажмите «Продолжить с AI». Проверьте три вопроса и исправьте предложенные ответы при необходимости. Выберите аудиторию «Ученики 8 класса», предмет «История Казахстана», формат «Интерактивный урок» и срок «До 2 недель». В материалах укажите «Учебная программа и материалы урока», в ограничениях — «Урок должен длиться 45 минут и работать онлайн».

3. Нажмите «Продолжить». Проверьте название и контекст; заполните или исправьте остальные поля:

   Поле	Пример значения
   Название	Интерактивный урок об Алаш Орде
   Ожидаемый результат	Готовый сценарий урока с заданиями и итоговой проверкой понимания темы
   Критерии успеха	Два отдельных пункта с новой строки: «Минимум 3 практических задания» и «Итоговый тест из 10 вопросов»
   Контакт преподавателя	[email protected] — демонстрационный адрес
   Формат обратной связи	Консультация по почте

4. При заполнении всех перечисленных полей и сохранении подробного контекста предварительный рейтинг составит 100/100. Посмотрите разбивку баллов, при желании нажмите «Проверить ещё раз», подтвердите карточку галочкой и нажмите «Опубликовать задачу».

5. Найдите задачу в каталоге. Переключите роль на «Студенческая команда», откройте карточку и отправьте предложение: команда History Lab, идея «Интерактивный квест», план «Сценарий, прототип, проверка», срок «10 дней». Для проверки поля ссылки можно использовать https://example.com/demo — это заглушка из тестового сценария, не размещённый прототип.

6. Закройте карточку, переключитесь на «Преподаватель», откройте её снова и нажмите «Принять» у предложения. Проверьте отметку «Принято». Решение по одному отклику не отклоняет остальные автоматически.

7. Нажмите «Редактировать задачу», очистите поле материалов, подтвердите изменения и сохраните. Рейтинг снизится до 80/100, а предложение и решение сохранятся.

8. Перезагрузите страницу или перезапустите сервер с тем же файлом данных. Задача, отклик и принятие должны сохраниться. Для получения изменений из другого браузера используйте «Обновить каталог».

Дополнительно можно ввести в подборе навыки «история, дизайн, интерактивные уроки», нажать «Подобрать задачи» и посмотреть отдельную оценку соответствия с пояснением.

Автоматические проверки

npm.cmd test

Тесты бэкенда проверяют выдачу сайта, API, подтверждение публикации, расчёт рейтинга, отклики, независимый выбор нескольких команд, сохранение после перезапуска и некорректные запросы. Тесты AI используют подменённые ответы провайдера и проверяют структурированный вывод и переход в демо при ошибках. Платные запросы не выполняются, реальный ключ этими тестами не проверяется.

Отдельный сквозной сценарий в браузере:

npm.cmd run test:browser

Нужны Node.js 22+ со встроенным WebSocket и Chrome/Edge: скрипт ищет стандартные Windows-пути к браузеру. Если браузер установлен иначе, перед запуском задайте путь к Chromium-совместимому исполняемому файлу через переменную окружения EDUTASK_BROWSER в терминале. Эту переменную браузерный тест читает до загрузки .env.

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

8. Данные и интеграции

• Данные преподавателя: текст потребности, ответы на уточнения, описания материалов, аудитории, результата и ограничений. Поле материалов текстовое — загрузка и разбор файлов не реализованы.
• Данные команд: введённые вручную навыки и интересы для подбора, а также предложения со ссылками на прототипы. Ссылки сохраняются; содержимое внешних прототипов сервер не анализирует.
• Стартовый набор: в data/tasks.json есть одна демонстрационная задача по истории Казахстана. Её рейтинг пересчитывается сервером по текущей формуле, а не берётся как неизменное число из примера.
• Рабочее хранилище: data/runtime/tasks.json создаётся автоматически и исключён из Git. Это источник общего каталога, в отличие от локальных настроек браузера. На хостинге для сохранения данных нужен постоянный диск.
• Браузерное хранилище: тема, локальный профиль и исходный текст черновика сохраняются в localStorage. После успешной публикации сохранённый исходный текст очищается. Полное восстановление всех шагов мастера не реализовано.
• OpenAI: при включённом AI сервер отправляет на https://api.openai.com/v1/chat/completions данные, необходимые для конкретного действия: описание, уточнения, текст карточки либо навыки команды и поля задач для подбора. Не используйте реальные персональные данные в демонстрации.
• Google Fonts: браузер обращается к сервису для загрузки шрифтов; при недоступности используются системные варианты.

Интеграций с электронными журналами, LMS, видеосервисами и внешними образовательными базами в репозитории нет. Собственное обучение модели, RAG и поиск по загруженным учебным материалам не реализованы.

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

• Нет серверной авторизации и проверки прав. Любой клиент с доступом к API может менять задачи и принимать решения. Локальный профиль не является аккаунтом. MVP предназначен для контролируемой демонстрации с синтетическими данными; открытый запуск требует защиты доступа.
• Однопроцессное файловое хранение. Нет производственной БД, многосерверной синхронизации и автоматического резервного копирования. Каталог обновляется запросом, без уведомлений в реальном времени.
• AI может ошибаться. JSON-схема проверяет форму ответа, не фактическую точность. Преподаватель должен проверить содержание; демо-ответ нельзя считать результатом модели.
• Рейтинг ограничен проверками заполнения. Высокие баллы не доказывают качество урока. Измерений влияния на успеваемость или экономию времени в репозитории нет.
• Есть технические лимиты. Исходный текст — 15–500 символов, JSON-тело запроса — до 100 000 байт, AI-подбор обрабатывает не более 50 переданных задач за запрос.
• Нет проведения и анализа занятий. Не реализованы видеозвонки, загрузка аудио/видео, распознавание речи и отчёты о знаниях ученика.
• Нет полного цикла исполнения проекта. После выбора команды отсутствуют общий трекер выполнения, сдача работы через отдельный процесс, награды за завершение, оплата и подписки.

10. Развёрнутая версия

Ссылка на публичную deployed-версию в текущем репозитории не указана. Проверяемый способ запуска — локальный сервер по инструкции выше: открыть EduTask локально.

Репозиторий: BAITC-Hacks / hack-0e4a4153-bulduck.