Tulgalyq

Исходный код: GitHub · BAITC-Hacks/hack-5f8abe41-tulgalyq, готовые ветки — main и Moldiyar. Для оценки работы участника используйте Moldiyar.

Рабочий прототип платформы бизнес-задач для HackAlem AI. Бизнес вводит свободное описание, отвечает на уточняющие вопросы, редактирует и подтверждает карточку. После подтверждения она попадает в каталог, где команды могут предложить решения. Сайт адаптирован для компьютера и телефона.

Идея: сильным студентам нужна не «популярная компания», а задача, с которой реально можно начать работу. Tulgalyq показывает готовность конкретной задачи: AI помогает задать правильные вопросы, бизнес подтверждает факты, а рейтинг 0–100 объясняет, чего ещё не хватает. Неидеальная задача остаётся в открытом каталоге и может получить отклик.

Отличия: прозрачный путь к 100 баллам без автопубликации AI-текста; открытый выбор нескольких команд самим бизнесом; скачиваемый «паспорт миссии» с подтверждёнными сведениями и пробелами для обсуждения. Описание для жюри · Демо за 3 минуты · Сверка с кейсом.

Пакет сдачи

1. Исходный код: ссылка на репозиторий выше; архив не нужен. Если GitHub показывает 404, проверьте доступ к приватному командному репозиторию.
2. Работающий MVP: запускается локально одной командой по инструкции ниже; Python 3.9+, внешние пакеты не нужны. Публичный адрес не требуется для проверки кода.
3. Документация: этот README содержит архитектуру, формулу рейтинга, правила каталога и тестовые сценарии. Описание для жюри, демо до 5 минут и сверка с кейсом дополняют его.
4. AI: для этого приватного хакатонного репозитория команда временно включила файл .env с Gemini-ключом по своему решению. После клонирования дополнительная настройка ключа не нужна. После оценки ключ необходимо отозвать; база данных в репозиторий не входит.

Запуск с нуля

Нужен Python 3.9 или новее. Внешние пакеты не требуются. Если репозиторий уже скачан, перейдите в его папку и пропустите первые две команды.

git clone --branch Moldiyar https://github.com/BAITC-Hacks/hack-5f8abe41-tulgalyq.git
cd hack-5f8abe41-tulgalyq
python3 app.py

Откройте http://127.0.0.1:8000/. Сервер должен оставаться запущенным в терминале; остановка — Ctrl+C. Если порт 8000 занят, остановите прежний процесс или задайте другой порт, например PORT=8001 python3 app.py, и откройте http://127.0.0.1:8001/.

При первом запуске каталог пуст — это нормально. Данные хранятся только локально в data/tulgalyq-demo.sqlite3, папка data/ исключена из Git. Для готового примера откройте «Каталог задач» и нажмите «Добавить демо-данные»: появятся 5 опубликованных карточек с разными рейтингами, 5 черновиков, 5 команд и 7 откликов. Повторное нажатие не создаёт дубликаты. Все ссылки на прототипы в синтетических откликах — примеры формата, а не работающие прототипы.

На машине разработки прежняя база data/mission100.sqlite3 сохранена и не удалена. Чтобы снова открыть её, запустите сервер с MISSION100_DB_PATH=data/mission100.sqlite3; для проверки свежего клона это не нужно.

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

Тестовые сценарии

1. В «Конструкторе» введите слабое описание задачи и ответьте на три уточняющих вопроса.
2. Заполните название и потребность, откройте карточку: справа видны предварительный рейтинг и баллы за каждое поле. Добавьте сведения, затем сохраните и подтвердите карточку. В отдельном разделе «Рейтинг задач» проверьте подтверждённый балл, разбивку и недостающие сведения.
3. В «Каталоге» найдите опубликованную задачу. По умолчанию карточки упорядочены по рейтингу; проверьте фильтры темы и четырёх уровней готовности. Даже подтверждённая задача с низким баллом принимает отклики.
4. Создайте команду с интересами, навыками и технологиями, отправьте идею, план, срок и ссылку на прототип.
5. В «Выборе команд» отфильтруйте задачу, сравните предложения рядом, выберите одну, несколько или ни одной команды. Для выбранной команды отправьте этап работы и подтвердите его: после этого в рейтинге прогресса команд появятся 10 баллов.

Для автоматической проверки запустите python3 -m unittest -v test_app.py; тесты используют временную базу и не меняют данные сайта.

Что работает сейчас

• Создание черновика из свободного текста.
• Три уточняющих вопроса о недостающих данных. При подключённом API AI проверяет уместность ответов; без него действуют локальные проверки очевидных заглушек. Найденные проблемы показаны рядом с полем. Перед публикацией сервер повторно проверяет все непустые поля карточки.
• Редактируемая карточка с полями из кейса.
• Предварительный рейтинг по шкале 0–100 и подсказки о недостающих полях. Сервер не засчитывает очевидные заглушки, повторы символов/слов и контакт без способа связи; редактор объясняет причину.
• Ручное подтверждение карточки; только после него баллы считаются начисленными.
• После публикации конструктор очищается, а подтверждённая задача показывается в «Задачах бизнеса» с кнопкой перехода в каталог. Редактировать и повторно подтвердить её можно позже.
• Сохранение карточки между перезагрузками браузера. При правке опубликованной задачи последняя подтверждённая версия остаётся в каталоге и на странице откликов; новые поля становятся публичными только после повторного подтверждения.
• Демо-кабинет бизнеса со всеми черновиками и опубликованными карточками: можно продолжить уточнение, открыть редактор или перейти к задаче в каталоге. Пока нет авторизации, это общий список записей демо-базы, а не персональные «мои задачи».
• Подробная разбивка баллов по каждому полю: видно, какие баллы уже подтверждены, какие возможны после подтверждения и что ещё пусто.
• Отдельный раздел «Рейтинг задач» со всеми опубликованными задачами, фильтром по уровню готовности, расшифровкой начисления и списком недостающих полей; из него можно открыть карточку в редакторе или каталоге.
• Общий каталог только подтверждённых задач: по умолчанию задачи идут по убыванию рейтинга; доступны поиск, фильтры по теме и уровню готовности, а также сброс фильтров. Низкий рейтинг не блокирует отклики.
• Необязательный подбор до трёх задач по совпадению слов в интересах/навыках команды и описании миссии. Он объясняет совпадения и предлагает задачи от 40 баллов; остальные задачи по-прежнему видны в общем каталоге. Это локальное правило, не AI и не автоматический выбор исполнителя.
• Профили команд с интересами, навыками и технологиями; неограниченные предложения с идеей, планом, сроком и обязательной ссылкой на прототип.
• Экран ручного выбора: отклики показаны рядом для сравнения идей, планов, сроков и прототипов; есть фильтр по задаче и статусу, числа ожидающих/выбранных/отклонённых и переход из кабинета бизнеса к конкретной миссии.
• Ручное решение бизнеса: выбрать одну или несколько команд, отклонить или не принимать решения.
• Подтверждение выполненного этапа даёт команде 10 прогресс-баллов; повторно подтвердить тот же этап нельзя. Баллы видны в таблице прогресса команд.
• Кнопка демо-данных добавляет 5 синтетических карточек с разными рейтингами, 5 черновиков разной полноты, 5 команд и 7 предложений; по первой задаче можно сравнить три подхода. Для старой демо-базы повторное нажатие добавит только два недостающих альтернативных отклика, не дублируя остальное. Ссылки в демо-записях служат образцом формата, а не действующими прототипами. Уже созданные записи не переписываются обновлением приложения.
• После создания черновика AI автоматически предложит три уточняющих вопроса. При наличии GEMINI_API_KEY используется Gemini; если его нет, но есть OPENAI_API_KEY, используется OpenAI; иначе — локальные правила. Кнопка позволяет запросить вопросы повторно. AI не заполняет карточку и не начисляет баллы без ответа бизнеса.
• Из опубликованной задачи скачивается Markdown-«паспорт миссии»: исходный запрос, подтверждённые поля, рейтинг и вопросы к ещё неясным пунктам. Несогласованные правки редактора в экспорт не попадают.

Формула рейтинга

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

Показатель	Поля в карточке	Баллы
Контекст и потребность	context — 10, need — 10	20
Данные и материалы	data	20
Ожидаемый результат	expected_result	15
Критерии успеха	success_criteria	15
Ограничения	constraints	10
Пользователи	users	10
Связь с бизнесом	contact — 5, interaction_format — 5	10
Итого		100

Каждое поле даёт либо весь свой вес, либо 0: пустое поле, очевидная заглушка, повтор символов/слов и несколько расплывчатых ответов баллов не дают. Для критериев успеха нужен измеримый признак; для контакта — email, @ник, ссылка или телефон минимум из 7 цифр. Сервер возвращает причины в quality_issues; локальная проверка не доказывает смысл и достоверность текста. При изменении подтверждённой карточки предварительный балл виден сразу, но начисление и публикация новых сведений происходят только после повторного ручного подтверждения. До этого каталог показывает последнюю подтверждённую версию и её прежний балл. Ранее подтверждённые баллы локальной базы не пересчитываются задним числом.

Правила каталога

• Уровни готовности: 0–39 — «черновик / требует уточнения»; 40–69 — рабочая; 70–89 — готовая; 90–100 — приоритетная. «Черновик» как уровень рейтинга не равен неопубликованному черновику: после подтверждения даже задача с 0 баллами видна в каталоге и принимает отклики.
• Только подтверждённая человеком версия публикуется в общем каталоге. Несогласованные правки не видны студентам; после повторного подтверждения балл и позиция обновляются.
• По умолчанию опубликованные задачи сортируются по убыванию рейтинга; при равном балле выше более новая задача. Есть поиск, фильтры по теме и уровню готовности, а также сортировка по новизне.
• Для неполной карточки вместо отсутствующего или некорректного названия показывается исходное описание бизнеса. Низкий балл не скрывает задачу и не запрещает отклик.
• Необязательные рекомендации показывают до трёх задач от 40 баллов по совпадению слов с интересами и навыками команды. Это локальное правило; общий каталог остаётся доступным всем, AI не назначает исполнителей.

Мобильный интерфейс

Это тот же сайт: на широком экране пять разделов расположены по центру шапки. На узком экране карточки перестраиваются в одну колонку, крупные кнопки подходят для касания, а разделы открываются боковым меню через кнопку ☰. Кнопка ☾ переключает светлую и тёмную темы; выбор сохраняется в этом браузере. В редакторе краткий рейтинг виден перед полями, а расшифровка раскрывается по нажатию. Подбор задач на телефоне тоже можно раскрыть при необходимости, не прокручивая его перед каталогом. Для просмотра на этом ноутбуке откройте http://localhost:8000. Адрес localhost на телефоне указывает на сам телефон, поэтому для проверки на другом устройстве понадобится отдельный доступ к серверу по локальной сети или хостинг.

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

AI-вопросы и локальный режим

Для демонстрации команда по своему решению включила в приватный репозиторий временный .env с GEMINI_API_KEY и GEMINI_MODEL. После клонирования ничего вставлять не нужно: запустите python3 app.py. Откройте http://127.0.0.1:8000/api/health: ai_enabled: true и ai_provider: "gemini" означают, что ключ найден, но не доказывают, что API ответит. Для окончательной проверки создайте тестовый черновик: под тремя вопросами должно быть написано «Вопросы предложены Gemini». Если написано о локальных вопросах, проверьте действительность ключа, доступность API и лимит.

Важная граница: ключ доступен каждому, кому доступен репозиторий, и остаётся в истории Git даже после удаления файла. Он предназначен только для демонстрации; владелец должен отозвать или заменить его после оценки. Не копируйте этот ключ в README, браузерный JavaScript или другие проекты. Переменная GEMINI_API_KEY из окружения процесса имеет приоритет над .env. По умолчанию используется gemini-3.5-flash-lite; имя модели можно изменить через GEMINI_MODEL. Если Gemini-ключа нет, но задан OPENAI_API_KEY, используется OpenAI Responses API с моделью gpt-4o-mini (можно изменить через OPENAI_MODEL). При создании черновика или повторном нажатии кнопки исходное описание, сохранённые поля и уже набранные ответы отправляются выбранной модели. Набранные ответы не сохраняются в карточку автоматически. Если API не ответил или вернул некорректный результат, сервер возвращает три локальных вопроса; введённые ответы остаются на месте. Интерфейс отдельно показывает отказ в доступе к API и достижение лимита, не раскрывая ключ.

Ссылка на страницу OpenAI Platform или промоакцию — не API-ключ. Если вместо ключа в OPENAI_API_KEY указана веб-ссылка, приложение не отправляет её в API, сообщает о неверной настройке и использует локальные вопросы. Создайте секретный ключ в разделе API keys и введите его только в окружение процесса сервера; не вставляйте ключ в чат, браузерный JavaScript или Git.

Промпт просит ровно три разных вопроса на русском, каждый привязан к недостающему или расплывчатому полю, без выдумывания фактов и повторения известных сведений. Его точный текст хранится в AI_INSTRUCTIONS в app.py. Вход модели — JSON с description и fields; выход — JSON-объект с массивом questions, где каждый элемент содержит field (например, users) и text (например, «Кто будет пользоваться решением?»). Для ответа Gemini используется структурированный JSON; для OpenAI — Structured Outputs. Сервер проверяет завершённость ответа, количество, разные поля, разные формулировки и длину вопросов; некорректный ответ не меняет карточку и включает локальный резервный режим. API браузера POST /api/tasks/{id}/ai-questions принимает необязательный JSON {"answers":{"need":"..."}} и отвечает {"questions":[{"field":"data","text":"..."}],"source":"gemini"} либо "source":"openai" или "source":"local" с причиной перехода.

Для проверки ответов служит отдельный промпт REVIEW_INSTRUCTIONS. Вход — исходное описание, тема, текущие поля без контактного и массив answers вида {"field":"need","question":"Что нужно изменить?","answer":"Сократить ожидание"}. Модель возвращает структурированный JSON {"items":[{"field":"need","ok":true,"feedback":""}]}; для ответа не по теме — ok=false и конкретное объяснение. Сервер требует ровно по одному валидному вердикту на каждое поле. POST /api/tasks/{id}/review возвращает source, issues и checked, не сохраняя ответы. POST /api/tasks/{id}/confirm повторяет проверку на сервере; при проблемах возвращает HTTP 422 с issues, не меняя опубликованную версию. Пустые поля разрешены, поэтому низкорейтинговые задачи остаются возможными. Контактное поле проверяется только локально и не включается в отправляемый модели JSON.

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

Архитектура

• Сервер: app.py на стандартной библиотеке Python (http.server, sqlite3, urllib). Он отдаёт API, статические файлы, считает рейтинг, валидирует ввод и обращается к Gemini/OpenAI только со стороны сервера.
• Хранение: SQLite в data/tulgalyq-demo.sqlite3. Таблицы tasks, teams, proposals, progress; для опубликованной задачи хранятся отдельно рабочая версия и последняя подтверждённая версия карточки. При запуске прежние демо-базы дополняются новыми полями без удаления записей.
• Интерфейс: static/index.html, static/app.js, static/*.css и SVG-логотип. Пять разделов: конструктор, задачи бизнеса, рейтинг, каталог и выбор команд. Сайт адаптивный, со светлой и тёмной темами.
• AI: промпты AI_INSTRUCTIONS и REVIEW_INSTRUCTIONS находятся в app.py; модель возвращает структурированный JSON, а сервер проверяет ответ до использования. При недоступности внешнего API действуют локальные вопросы и проверки.
• Проверка: test_app.py запускает HTTP-сервер с временной базой и проверяет сквозной сценарий, рейтинг, AI-контракты, ошибки и изоляцию опубликованных правок. Команда: python3 -m unittest -v test_app.py.

Локальная база data/ не хранится в репозитории. Исключение по решению команды — временный демонстрационный Gemini-ключ в .env; после оценки его необходимо отозвать.

Ограничения прототипа

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