Alem Practice

Платформа для подготовки бизнес-задач и совместной работы со студенческими командами. MVP по кейсу HackAlem: от краткого описания проблемы до понятной карточки, открытого каталога, откликов и подтверждённого результата.

Исходный код

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

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

Alem Practice помогает представителю бизнеса постепенно дополнить описание с помощью ИИ. Рейтинг показывает готовность карточки к работе и влияет на её позицию в каталоге. Студенческие команды самостоятельно выбирают задачи и предлагают решения, а бизнес вручную принимает решение о сотрудничестве.

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

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

Пользователи и доступ

• Бизнес: создание, редактирование и публикация своих задач, просмотр откликов, выбор команд, подтверждение результатов.
• Студенческая команда: просмотр каталога, отправка предложений и передача результата после выбора бизнесом. Размещать задачи нельзя.
• Тип не назначен: доступ к открытому каталогу; для рабочих действий администратор должен назначить тип.
• Проверки роли и владельца выполняются на сервере. Недоступные действия также скрыты в интерфейсе.
• Вход и выход через стандартную авторизацию Django; административная панель для управления данными.

Конструктор и AI-помощник

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

Каталог, предложения и результаты

• Каталог всех опубликованных задач, поиск по названию и потребности, фильтры по теме и уровню готовности.
• Сортировка по убыванию рейтинга, затем по времени изменения задачи.
• Отклик с идеей, планом, сроком и необязательной ссылкой на прототип.
• Ручное принятие и отклонение предложений без перезагрузки всей страницы. Статусы: серый — на рассмотрении, зелёный — выбрана, красный — отклонена.
• Возможность выбрать несколько команд. Автоматического назначения нет.
• Передача выбранной командой текстового результата этапа; подтверждение бизнесом даёт 25 баллов один раз за отклик.
• Кабинет бизнеса со своими задачами и кабинет команды с предложениями и баллами.

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

1. Представитель бизнеса входит и вводит краткое описание проблемы. Создаётся непубличный черновик; исходный текст переносится в поле контекста.
2. Пользователь заполняет очередной блок и нажимает «Далее · уточнить с ИИ». OpenAI анализирует текст и возвращает до трёх подсказок по текущему блоку. Если существенных уточнений нет, список может быть пустым.
3. Пользователь дополняет текст. Можно повторно проверить уточнения или нажать «Продолжить», в том числе без дополнений. Этот выбор учитывается при оценке качества.
4. После всех блоков система показывает карточку и предварительные баллы с причинами. «Подтвердить и сохранить» сохраняет изменения и пересчитывает рейтинг.
5. Бизнес отдельно нажимает «Опубликовать». Задача появляется в общем каталоге; низкий рейтинг не запрещает отклики.
6. Команда входит в свой аккаунт, находит задачу и отправляет предложение.
7. Бизнес принимает или отклоняет отклик. Выбранная команда передаёт результат этапа; бизнес подтверждает его, после чего команде начисляются баллы.

Промежуточные изменения конструктора и история уточнений хранятся в серверной сессии. До итогового подтверждения они не изменяют сохранённую карточку и её рейтинг. Перезагрузка страницы сама по себе не повторяет AI-запрос.

Как считается рейтинг

Суммарный максимум — 100 баллов. Веса разделов:

• Контекст и потребность — 20, по 10 за каждое поле.
• Данные и материалы — 20.
• Ожидаемый результат — 15.
• Критерии успеха — 15.
• Ограничения — 10.
• Пользователи — 10.
• Контакт и формат взаимодействия — 10, по 5 за каждое поле.

Название и тема входят в конструктор, но отдельных баллов не дают.

Для каждого оцениваемого поля:

• 0% веса: поле пустое, карточка ещё не подтверждена либо AI-проверка признала текст бессодержательным.
• 50% веса: поле заполнено, но актуальной AI-проверки нет, API недоступен или пользователь продолжил без устранения уточнений.
• Частичная оценка: после проверки доля рассчитывается как 50 + floor(50 × закрытые уточнения / все уточнения). Новые существенные пробелы также учитываются.
• 100% веса: AI-проверка подтвердила содержательность текста и отсутствие существенных пробелов либо закрытие всех уточнений.

Например, если закрыто одно из двух уточнений, поле получает 75% своего веса. Наличие изменённого текста само по себе не считается ответом: проверяется цитата из текущего поля и её соответствие уточнению. Для контакта, который не отправляется в API, проверяется только признак наличия.

Баллы суммируются внутри каждого раздела и округляются вниз. Поэтому полностью заполненная карточка без AI-проверок получает 49/100. Отсутствие подсказок после фильтрации не даёт максимум автоматически: полнота проверяется отдельно.

Оценки, причины, уточнения, подтверждающие цитаты и хеши проверенных текстов сохраняются в Task.quality_reviews. Изменение текста делает прежнюю оценку этого поля неприменимой. Старые карточки без истории AI-проверок пересчитываются на базовый уровень.

Уровни готовности:

• 0–39: черновик.
• 40–69: рабочая.
• 70–89: готовая.
• 90–100: приоритетная.

Уровень «черновик» в рейтинге не равен статусу публикации: подтверждённую задачу с низким баллом можно опубликовать.

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

• Python, Django 5.2.17 — серверная логика, формы, ORM, миграции, сессии, авторизация и административная панель.
• SQLite — локальная база db.sqlite3.
• Django Templates, HTML, CSS — серверный интерфейс с адаптивными стилями.
• JavaScript и Fetch API — асинхронные действия с откликами и индикация ожидания в конструкторе.
• OpenAI Python SDK 3.19.0, Responses API, Structured Outputs — генерация уточнений, проверка их смысла и оценка дополнений.
• Pydantic 2.13.5 — схемы структурированных ответов модели.
• python-dotenv 1.2.3 — загрузка настроек из .env.

Модель по умолчанию — gpt-5.4-mini. Она указана в .env.example и используется кодом, если OPENAI_MODEL пуст. Другую доступную модель можно задать через переменную окружения; она должна поддерживать используемый API и структурированные ответы.

Версии прямых зависимостей закреплены в requirements.txt. Отдельная сборка фронтенда и Node.js для запуска не нужны.

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

Это Django-монолит: браузер получает HTML со страницами, отправляет формы на сервер, а сервер работает с SQLite и при необходимости вызывает OpenAI. Для решений по откликам тот же сервер возвращает JSON, которым JavaScript обновляет статус на странице.

Браузер: формы и JavaScript
          |
          v
Django: маршруты → проверка роли/владельца → представления
          |                         |
          v                         v
SQLite: пользователи,        OpenAI Responses API:
задачи, отклики, сессии      подсказки и проверка качества
          |
          v
Карточка, рейтинг, каталог, решение по отклику

Основные компоненты:

• config/ — настройки приложения, корневые маршруты и WSGI.
• projects/models.py — Account (тип пользователя), Task (карточка и рейтинг), Team (профиль команды), Proposal (отклик и результат этапа). Учётные записи — стандартная модель пользователя Django.
• projects/views.py, projects/urls.py, projects/forms.py — пользовательские действия, маршрутизация и проверка ввода.
• projects/roles.py — ограничения по типу пользователя и данные для отображения роли в интерфейсе.
• projects/wizard.py — порядок блоков конструктора и пояснения к полям.
• projects/ai.py, projects/question_scopes.py — генерация подсказок, границы блоков, проверка смысла и локальный резервный режим.
• projects/quality.py — AI-проверка дополнений, проверка цитат и оценка отдельных полей; projects/services.py — суммирование рейтинга по разделам.
• templates/, static/ — шаблоны страниц, стили, скрипты конструктора и действий с откликами.
• projects/migrations/ — схема БД и миграции существующих ролей и рейтингов.
• projects/management/commands/ — демонстрационные данные и проверки подключения AI.
• projects/tests.py, projects/test_*.py — автоматические тесты.

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

Подготовка

Для воспроизведения локального запуска используйте Python 3.12, pip и Git. Для AI-функций нужны интернет, API-ключ OpenAI и доступ к выбранной модели. Без ключа приложение запускается с локальными подсказками и базовым рейтингом.

git clone https://github.com/BAITC-Hacks/hack-6fec9f63-andreysolo.git
cd hack-6fec9f63-andreysolo

Если проект уже скачан, достаточно перейти в его корневую папку, где находится manage.py.

Windows PowerShell

Создайте окружение, установите зависимости и подготовьте файл настроек:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
Copy-Item .env.example .env
.\.venv\Scripts\python.exe -c "import secrets; print(secrets.token_urlsafe(48))"

Скопируйте выведенный случайный секрет в DJANGO_SECRET_KEY внутри .env. Если .env уже существует, не копируйте шаблон поверх него.

Linux / macOS

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
cp .env.example .env
.venv/bin/python -c "import secrets; print(secrets.token_urlsafe(48))"

Аналогично перенесите сгенерированный секрет в .env; сохраните существующий файл, если он уже настроен.

Настройки .env

DJANGO_DEBUG=1
DJANGO_SECRET_KEY=вставьте_сгенерированный_секрет
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1,[::1]
OPENAI_API_KEY=
OPENAI_MODEL=gpt-5.4-mini

• DJANGO_DEBUG=1 включает режим локальной разработки; 0 отключает его.
• DJANGO_SECRET_KEY — секрет Django, отдельный от API-ключа.
• DJANGO_ALLOWED_HOSTS — разрешённые имена хостов через запятую.
• OPENAI_API_KEY — ключ для настоящих AI-запросов. Оставьте пустым для резервного режима.
• OPENAI_MODEL — идентификатор модели.

.env автоматически читается при запуске и исключён из Git. Уже заданные системные переменные окружения имеют приоритет. После изменения настроек перезапустите сервер. Не публикуйте ключи в README или репозитории.

База данных и сервер

Windows:

.\.venv\Scripts\python.exe manage.py migrate
.\.venv\Scripts\python.exe manage.py seed_demo
.\.venv\Scripts\python.exe manage.py runserver 127.0.0.1:8000

Linux / macOS:

.venv/bin/python manage.py migrate
.venv/bin/python manage.py seed_demo
.venv/bin/python manage.py runserver 127.0.0.1:8000

Откройте локальное приложение. Остановка сервера — Ctrl+C.

Демоаккаунты

После seed_demo доступны:

• business — представитель бизнеса.
• team1 — Steppe Coders.
• team2 — Data Nomads.
• team3 — Qadam.
• team4 — Green Stack.
• team5 — Jas AI.

Пароль всех созданных демоаккаунтов: AlemDemo2026!. Это общедоступные демонстрационные реквизиты для локального показа.

При первом запуске на пустой БД команда создаёт пять опубликованных задач с исходными описаниями, пять команд и пять откликов. Повторный запуск не сбрасывает существующие пароли и не заменяет созданные карточки; для пары «задача–команда» новый демоотклик создаётся только при отсутствии отклика.

Администрирование

.\.venv\Scripts\python.exe manage.py createsuperuser

В Linux/macOS используйте .venv/bin/python. Вход в административную панель — под созданным суперпользователем.

Для нового рабочего аккаунта создайте пользователя и профиль Account с типом business или student. Для студенческого аккаунта также создайте Team. Сам по себе статус суперпользователя не назначает бизнес-роль в пользовательском интерфейсе.

7. Как проверить решение жюри

Сквозной сценарий

1. Войдите как business. Нажмите «Разместить задачу». Укажите название «Учёт заказов кофейни», тему «Ритейл» и исходное описание: «Заказы на торты приходят в два мессенджера и иногда теряются».
2. Пройдите конструктор. На каждом блоке нажмите «Далее · уточнить с ИИ», прочитайте подсказки и дополните описание либо продолжите без дополнений. При работающем API источник подсказок — OpenAI; при ошибке явно отображается резервный режим.
3. Для демонстрационной карточки можно использовать следующие сведения:
   • Контекст: администратор вручную переносит заказы из двух мессенджеров в тетрадь, часть обращений пропускается.
   • Потребность: собирать заявки в единый список и отслеживать их выполнение.
   • Пользователи: администратор оформляет заказ, кондитер видит состав и отмечает готовность.
   • Данные: 30 синтетических примеров заявок в CSV; никаких реальных контактов клиентов.
   • Ограничения: прототип за две недели без платных внешних сервисов.
   • Результат: веб-прототип со списком, поиском и сменой статуса заказа, инструкция запуска.
   • Критерии успеха: все 30 примеров отображаются; заказ находится по номеру; смена статуса сохраняется после обновления страницы.
   • Связь: [email protected], одна встреча в неделю, результат принимает администратор кофейни.
4. На итоговом экране рассмотрите рейтинг и причины. Подтвердите сведения, сохраните карточку и нажмите «Опубликовать». Убедитесь, что задача видна в каталоге и находится через поиск.
5. Выйдите и войдите как team1. Кнопки создания задачи быть не должно. Откройте задачу и отправьте предложение: идея «Единый журнал заказов», план «Макет → реализация → проверка на CSV», срок «2 недели». Ссылку на прототип можно оставить пустой.
6. Под business откройте отклик. Нажмите «Принять»: статус должен стать зелёным без перезагрузки страницы. Можно проверить отклонение: статус станет красным; затем снова принять предложение до подтверждения этапа.
7. Под team1 в кабинете нажмите «Передать результат этапа» и опишите выполненную демонстрационную работу. Под business подтвердите этап. В кабинете команды счёт увеличится на 25; повторное подтверждение не должно добавлять баллы ещё раз.

Для демонстрации качества рейтинга сначала продолжите один блок без ответа на уточнение, затем повторно отредактируйте карточку и добавьте недостающие сведения. Посмотрите, изменились ли оценка и причины. Конкретные подсказки и итоговый балл не фиксированы: они зависят от текста и ответа модели; рост до 100 не гарантируется.

Перед выходом из аккаунта подтвердите карточку: незавершённые изменения конструктора привязаны к текущей сессии.

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

.\.venv\Scripts\python.exe manage.py check
.\.venv\Scripts\python.exe manage.py test
.\.venv\Scripts\python.exe manage.py makemigrations --check --dry-run

В Linux/macOS замените путь интерпретатора на .venv/bin/python.

Тесты покрывают сквозной сценарий, публикацию после подтверждения, ограничения ролей и владельцев, рейтинг и подтверждающие цитаты, резервные AI-ответы, шаги конструктора, JSON-действия с откликами, CSRF и защиту от повторного начисления баллов. В автоматических тестах AI-вызовы подменяются или используется режим без ключа.

Для отдельной проверки настоящего API предусмотрены команды на синтетических данных, не создающие карточки в БД:

.\.venv\Scripts\python.exe -X utf8 manage.py check_openai --field context --cattle
.\.venv\Scripts\python.exe -X utf8 manage.py check_quality

Первая проверяет уточнения по блоку, вторая сравнивает оценку до и после дополнения. Нужен действующий API-ключ; команды отправляют реальные, потенциально платные запросы. Результаты модели могут различаться, а диагностическая команда может завершиться ошибкой, если проверка не пройдена.

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

Источники данных: текст, введённый бизнесом; профили и предложения команд; результаты этапов; синтетический набор из seed_demo. Демозадачи относятся к кофейне, велопрокату, стажировкам, теплице и мастерской. Ссылки example.com/demo в демооткликах — заглушки, не готовые прототипы.

Внешняя интеграция: OpenAI Responses API на https://api.openai.com/v1. Приложение вызывает его только с сервера. Модель помогает уточнять постановку и оценивать полноту; она не выполняет саму бизнес-задачу, не строит прогнозы по файлам и не назначает команды.

При генерации отправляются текстовые поля карточки, включая исходное описание. В оценке используются поля карточки и история уточнений, а при проверке цитат — уточнения и цитаты. Отдельное поле contact заменяется признаком наличия контакта. Данные, вписанные в другие поля, автоматически не обезличиваются. Контакт из опубликованной карточки виден её посетителям.

В запросах указано store=False; это параметр API-запроса, а не гарантия отсутствия обработки данных у внешнего провайдера. Ключ берётся из окружения. У клиента установлен таймаут 30 секунд на запрос, автоматические повторы отключены. Генерация с проверкой смысла может использовать два запроса; оценка дополнений с проверкой цитат — ещё до двух.

Для генерации ограничен размер входного JSON до 24 000 символов; для оценки качества — до 30 000. При превышении лимита либо сбое используется базовый режим. Импорт CSV/JSON, загрузка файлов и интеграции с системами бизнеса не реализованы: упоминания CSV в карточках — описания доступных материалов.

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

• Это демонстрационный MVP, а не готовая производственная платформа. Используются SQLite и стандартный сервер разработки Django; готовой конфигурации публичного размещения нет.
• Нет самостоятельной регистрации, интерфейса восстановления пароля и управления участниками команды. Один профиль команды связан с одним аккаунтом.
• Нет чата, уведомлений, календаря, загрузки файлов, персональных рекомендаций задач или автоматического подбора команд.
• Один подтверждаемый этап на отклик. Отдельного проектного трекера нет; подтверждённый этап нельзя отклонить.
• Незавершённый конструктор хранится в сессии. Выход из аккаунта завершает её; одновременное редактирование одной задачи в нескольких вкладках не поддерживается, устаревшие шаги отклоняются.
• AI-оценка вероятностная: возможны лишние уточнения, пропуски, неточная оценка полноты. Проверяется качество описания, а не истинность фактов и не реализуемость решения. Максимальный рейтинг не является гарантией результата проекта.
• Без доступного API заполненные поля получают только базовые баллы; смысловая проверка не имитируется как успешная.
• AI-запросы синхронные и могут занимать заметное время. Пользовательских лимитов частоты и бюджета запросов, фоновой очереди и кэширования ответов нет.
• Нет отдельного журнала аудита решений и механизма скрытия контактов опубликованных задач.
• DEBUG включён по умолчанию, демопароли общедоступны. Для публичного запуска нужны отдельные секреты, HTTPS, настройки cookies, обслуживание статики, производственный сервер и дополнительные эксплуатационные настройки. Демоданные не следует выдавать за реальные заявки бизнеса.

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

Подтверждённая ссылка на публично развёрнутую версию в репозитории отсутствует.

Для демонстрации предусмотрен локальный адрес http://127.0.0.1:8000/ после запуска по инструкции. Он доступен на компьютере, где запущен сервер, и не является публичным деплоем.