TaskLab — задачи бизнеса для студенческих команд

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

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

Текущее состояние: каталог, конструктор с AI-уточнением, команды, отклики, решения бизнеса, вознаграждение, смена роли и AI-чат-помощник работают через SQLite. Локально AI по умолчанию работает в режиме заглушки и не требует ключа; развёрнутая версия использует OpenAI gpt-4.1.

Развёрнутая версия для проверки: https://hackalem-kilc-project-production.up.railway.app — без установки и go run .. Роль хранится в браузере; переключиться между бизнесом и командой можно кнопкой «Сменить роль» в верхней панели (или откройте второе окно инкогнито). Подробнее — в разделе «Развёрнутая версия».

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

• Открытый каталог: все опубликованные задачи видны всем командам независимо от рейтинга. Порядок — по рейтингу с бонусом за подтверждённое вознаграждение (0/+5/+10), затем по рейтингу. Рейтинг 0–100 и уровень от вознаграждения не зависят. Фильтры по категории, отрасли и уровню (диапазон баллов).
• Карточка задачи с исходным описанием, контекстом, потребностью, пользователями, данными, ограничениями, ожидаемым результатом, критериями успеха, контактом и форматом взаимодействия.
• Создание, чтение, обновление и публикация задач через JSON API. Исходный черновик после сохранения изменить нельзя.
• Браузерный конструктор: черновик → 3–5 уточняющих вопросов → карточка от AI (поля приходят неподтверждёнными) → ручная правка и подтверждение каждого поля → сохранение → публикация. Рейтинг пересчитывается на сервере, есть подсказки и локальная резервная копия новой задачи.
• Рейтинг 0–100 с разбивкой, потенциальным баллом и подсказками. При изменении поля его подтверждение снимается; это проверяется и на сервере (store/tasks.go).
• Просмотр, поиск, создание и выбор команды; профиль содержит название, интересы, навыки и технологии.
• Предложения команд: идея, план, дата завершения и ссылка на прототип. Новое предложение получает статус pending.
• Вознаграждение команде (тип и описание) хранится в задаче; после подтверждения даёт бонус к позиции в каталоге, но не к рейтингу.
• Кабинет бизнеса: задачи своей компании, сравнение откликов, ручное принятие или отклонение. Можно принять несколько предложений.
• Однократное подтверждение этапа принятого предложения с начислением 1–100 баллов. Баллы команды вычисляются как сумма начислений.
• Рекомендации: до пяти опубликованных задач по совпадению категории с интересами команды, с рейтингом от 40. Это алгоритм по правилам, без AI; остальные опубликованные задачи остаются в общем каталоге.
• Смена роли без второго браузера: кнопка «Сменить роль» в верхней панели (DELETE /api/session); задачи, команды и отклики сохраняются.
• AI-чат-помощник (кнопка «Помощник»): объясняет рейтинг открытой задачи и подсказывает, как улучшить описание или отклик. Только советует, ничего не меняет в данных.
• Автоматическое заполнение демонстрационной базы и endpoint проверки состояния /health.

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

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

Компонент	Максимум
Контекст и потребность	20
Данные и материалы	20
Ожидаемый результат	15
Критерии успеха	15
Ограничения	10
Пользователи	10
Связь с бизнесом	10
Всего	100

Контекст и потребность дают до 10 баллов каждый; контакт и формат взаимодействия — до 5. Для обычных текстовых полей описание короче пяти слов получает половину максимума с округлением вниз. Для полного балла критерии успеха должны содержать число, контакт — символ @ или хотя бы семь цифр.

Уровни: 0–39 — черновик, 40–69 — рабочая, 70–89 — готовая, 90–100 — приоритетная. Уровень вычисляется из балла. Категория на него не влияет. Низкий рейтинг не запрещает публикацию и отправку предложения; для публикации нужны название и подтверждение заполненных полей рейтинга. Статус публикации и уровень «черновик» — разные свойства.

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

1. Пользователь выбирает роль. Бизнес указывает компанию и нажимает «Создать задачу».
2. В конструкторе он вводит исходное описание и нажимает «Получить уточняющие вопросы» — появляются 3–5 вопросов. Неизвестный ответ можно оставить пустым.
3. «Сформировать карточку» заполняет название, категорию и поля описания. Все они приходят неподтверждёнными, рейтинг за них — 0. Пользователь правит и подтверждает каждое поле: название, категорию, 9 полей рейтинга и вознаграждение. Изменение поля снимает его подтверждение — это обеспечивает сервер в store/tasks.go. Затем задача сохраняется и публикуется отдельным действием; для публикации нужны название и подтверждение всех заполненных полей.
4. Команда выбирает задачу в каталоге и отправляет идею, план, срок и ссылку на прототип.
5. Бизнес сравнивает отклики и вручную принимает или отклоняет каждый.
6. После выполнения этапа бизнес подтверждает его и назначает баллы. Они отображаются в профиле команды.

Выбор роли и команды — серверная сессия браузера, а не вход в защищённый аккаунт.

Технологии и AI

Область	Реализация
Сервер	Go 1.25.0 по go.mod, стандартный net/http
HTML	html/template для каталога; отдельные HTML-страницы для остальных сценариев
Клиент	HTML, CSS, обычный JavaScript и Fetch API; без Node.js и сборки
Хранилище	SQLite, database/sql, modernc.org/sqlite v1.59.0 — драйвер без CGO
Встраивание ресурсов	embed.FS: шаблоны, статика, схема и JSON-данные
Тесты	Go testing, HTTP-тесты и тесты хранилища
AI	Совместимый Chat Completions API: в развёрнутой версии OpenAI gpt-4.1; по умолчанию в коде — DeepSeek deepseek-chat; без ключа — локальная заглушка

Единственная прямая сторонняя Go-зависимость — SQLite-драйвер; его транзитивные зависимости перечислены в go.mod. Веб-фреймворка, ORM и JS-зависимостей нет.

Пакет ai/ подключён к серверу: клиент создаётся в main.go через ai.New() и ai.NewChat(). Маршруты:

1. POST /api/ai/questions — {"draft_text": "..."} → {"questions": [{"field", "question"}], "source"}, 3–5 вопросов.
2. POST /api/ai/card — {"draft_text", "qa": [{"field", "question", "answer"}]} → {"card": {...}, "source"}.
3. POST /api/chat (api/chat.go, дополнительно к ТЗ) — {"message", "history": [{"role", "content"}], "context": {"page", "task_id"}} → {"reply": "..."}. Системный промпт задаёт сервер; роль, компания и команда — из серверной сессии; задача из context проверяется на доступ. В режиме заглушки — 503: помощник не выдумывает ответы без модели.

• Режим. Без ключа или при STUB, отличном от 0, работает заглушка — это режим по умолчанию. source в ответе показывает model или stub.
• Промпты — ai/prompts.go (QuestionsPrompt, CardPrompt): только факты из черновика и ответов, ничего не придумывать, строгий JSON.
• Формат входа и выхода — типы Question, QA, Card в ai/ai.go. Карточка: title, category, context, need, users, data, constraints, expected_result, success_criteria, contact, interaction_format.
• Проверка ответа — ai/validate.go: неизвестные ключи отбрасываются; текстовое поле принимается, только если это целые предложения или строки из черновика и ответов; категория — только код из фиксированного списка; превышение длины отбрасывает поле.
• Некорректный ответ — ai/fallback.go: при ошибке модели или невалидном JSON запрос переходит на заглушку, в лог пишется ai: переход на заглушку: ...; отброшенные поля тоже логируются. Успешный результат не выдумывается.
• Сохранение и публикация остаются ручными: AI только заполняет форму.

Подробности, пример .env и проверка — в ai/README.md.

Архитектура

Браузер
  ├─ GET / → HTML-каталог из templates/
  └─ static/task-builder/ → JavaScript → JSON API (сессия в HttpOnly cookie)
                                      ├─ api/ai.go, api/chat.go → ai/ → модель или заглушка
                                      ├─ rating/ → оценка без БД и HTTP
                                      └─ store/ → SQLite

main.go → .env → открытие БД → схема → демонстрационные данные → ai.New(), ai.NewChat() → HTTP-сервер

Путь	Назначение
main.go, env.go	Чтение .env, встраивание ресурсов, запуск БД, регистрация маршрутов, health-check
api/	Каталог, задачи, рейтинг, AI-маршруты, сессии, команды, предложения, действия бизнеса, рекомендации
rating/	Чистые функции оценки, уровни и расчёт бонуса вознаграждения
store/	SQL-запросы, валидация, сохранение и загрузка демонстрационных данных
ai/	Интерфейс из двух операций, промпты, заглушка, HTTP-клиент, проверка ответов и fallback; ai/chat.go — текстовый чат-помощник
templates/	Серверные HTML-шаблоны
static/	CSS, JavaScript и страницы конструктора, команд и кабинета бизнеса
schema.sql	Схема таблиц задач, команд, предложений и сессий браузера
data/*.json	Демонстрационные задачи, команды и предложения

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

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

Потребуются Git, Go 1.25+ и браузер. При первой загрузке зависимостей нужен интернет. API-ключ, отдельный сервер БД и C-компилятор не требуются.

1. Клонируйте репозиторий и перейдите в него:

   git clone https://github.com/BAITC-Hacks/hack-7c4211c3-kilc.git
   cd hack-7c4211c3-kilc
   

2. Проверьте Go и загрузите зависимости:

   go version
   go mod download
   

3. Запустите сервер:

   go run .
   

4. Откройте каталог или выбор роли.

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

HTML следует открывать через Go-сервер: рабочие операции требуют его API. После изменения встроенных HTML/CSS/JS сервер нужно перезапустить.

Настройки

При старте сервер автоматически читает .env из рабочей директории (env.go); файл необязателен. Переменные окружения процесса имеют приоритет над .env. Шаблон — .env.example; подробности формата — в ai/README.md.

Переменная	Значение по умолчанию	Назначение
PORT	8080	Порт HTTP-сервера
DB_PATH	data.db	Путь к SQLite относительно рабочей директории
STUB	Режим заглушки	Модель используется только при STUB=0 и непустом ключе
AI_API_KEY	Пусто	Ключ AI-провайдера
AI_BASE_URL	https://api.deepseek.com	Базовый адрес; клиент добавляет /chat/completions
AI_MODEL	deepseek-chat	Имя модели

Отдельная демонстрационная база:

DB_PATH=demo.db go run .

Используйте новое имя базы, если нужно повторно получить исходные примеры, сохранив предыдущие результаты.

Как проверить решение

Техническая проверка

Из корня репозитория:

go test ./rating/...
go run .

Во втором терминале:

curl -f http://localhost:8080/health

Ожидаемый ответ — HTTP 200 и {"status":"ok"}. В Windows PowerShell можно вызвать curl.exe -f http://localhost:8080/health.

Для проверки всех пакетов:

go test ./...

Сценарий для жюри (5 минут)

1. Запустите сервер с новой базой: DB_PATH=demo.db go run .
2. Откройте два окна браузера: обычное — бизнес, инкогнито — студент. Можно работать и в одном окне: кнопка «Сменить роль» в верхней панели сбрасывает сессию без потери данных.
3. Бизнес: на выборе роли выберите бизнес, укажите компанию «Демо Кофейня» и нажмите «Создать задачу».
4. Черновик: «Нужен бот для предзаказа кофе, очереди утром слишком длинные». Нажмите «Получить уточняющие вопросы» и ответьте:
   • данные — «Выгрузка CSV из кассы за 3 месяца.»
   • контекст — «У нас 3 кофейни в Астане.»
   • потребность — «Утром очередь занимает 15 минут.»
   • ожидаемый результат — «Нужен Telegram-бот для предзаказа кофе.» (не короче 5 слов, иначе поле даст половину балла)
   • критерии успеха — «Ожидание не более 3 минут и 20% заказов через бота.»
5. Нажмите «Сформировать карточку»: поля заполнены, рейтинг — 0, потому что ничего не подтверждено.
6. Проверьте название, выберите категорию ai_assistant («Чат-бот / AI-ассистент»), укажите контакт [email скрыт] и подтвердите поля: рейтинг — 75, уровень «Готовая». Сохраните и опубликуйте.
7. Студент: в инкогнито (или после «Сменить роль» в том же окне) выберите роль студента и команду «Байт Батыры». Откройте задачу в каталоге и отправьте предложение: срок в формате YYYY-MM-DD, ссылка — https://....
8. Бизнес: «Мои задачи» → «Сравнить отклики» → «Выбрать команду» → подтвердите этап с 10 баллами. Сумма баллов команды увеличится на 10; повторное начисление за тот же этап недоступно.
9. Дополнительно: на странице задачи нажмите «Помощник» и спросите «Как рассчитан рейтинг этой задачи?» — ответ опирается на поля и подсказки рейтинга этой задачи (нужен режим модели).

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

• Источник начальных данных — data/tasks.json, data/teams.json и data/proposals.json. Это демонстрационные примеры, а не подтверждённые реальные заказчики или результаты проектов.
• Пользовательские задачи, профили команд и предложения сохраняются в SQLite. Файлы и прототипы не загружаются: предложение хранит только URL.
• Профили команд содержат общие навыки и технологии, без личных данных об отдельных участниках.
• Роль, компания и команда — серверная сессия: таблица browser_sessions, HttpOnly cookie tasklab-session, логика в api/session.go. Роль хранится в браузере до нажатия «Сменить роль» (DELETE /api/session удаляет сессию и cookie; задачи, команды и отклики сохраняются). Резервная копия новой задачи хранится в localStorage.
• Внешний AI API вызывается только при STUB=0 и заданном ключе; иначе работает заглушка. Интеграций с CRM, мессенджерами и внешними источниками бизнес-данных нет.
• Ссылки example.com в начальных предложениях — демонстрационные адреса.
• В демонстрационных данных одно предложение уже принято и по нему подтверждён этап (+10 баллов), ещё одно отклонено. Это заранее записанная история ручных решений бизнеса для наглядности кабинета; новые отклики всегда создаются в статусе pending, и принять их может только представитель бизнеса кнопкой «Выбрать команду».
• Дополнительно, вне рамок ТЗ: чат-помощник (кнопка «Помощник» на всех страницах). POST /api/chat (api/chat.go) отвечает через ту же модель; роль, компания и команда берутся только из серверной сессии, задача из контекста проверяется на доступ (студенту — только опубликованные, бизнесу — только своей компании), история ограничена 12 сообщениями без роли system, не чаще одного запроса в 2 секунды. Помощник только советует и ничего не меняет в данных. В режиме заглушки чат сообщает, что недоступен. Подробности — CHATBOT_INTEGRATION.md.

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

• Нет полноценной аутентификации: сессия браузера закрепляет роль, но это не вход по паролю.
• Оценка использует простые текстовые правила; она не проверяет достоверность данных, реализуемость задания и качество решения.
• Проверка AI-ответа допускает только дословные предложения из источника, поэтому часть полей может остаться пустой и заполняется вручную.
• Нет уведомлений, загрузки файлов, управления участниками команды и полноценного трекера проекта.
• Лимит частоты чата хранится в памяти процесса и сбрасывается при перезапуске; история чата — только в текущей вкладке (sessionStorage).
• Клиент модели передаёт temperature, поэтому модели семейства gpt-5, принимающие только значение по умолчанию, не поддерживаются: при их выборе вопросы и карточка переходят на заглушку, а чат возвращает понятную ошибку. Проверены gpt-4.1-mini и gpt-4.1.
• Подтверждается один этап на предложение; повторное начисление и пересмотр уже принятого решения не предусмотрены.
• Репозиторий не содержит конфигурации промышленного развёртывания. Текущая версия предназначена для демонстрации MVP.

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

Публичная версия: https://hackalem-kilc-project-production.up.railway.app. Проверка состояния: /health возвращает {"status":"ok"}.

• Развёрнута на Railway из этого репозитория тем же бинарником, что и go run .: шаблоны, статика, схема и демонстрационные данные встроены через embed.FS.
• AI работает на OpenAI gpt-4.1 (STUB=0, ключ хранится в переменных окружения Railway, а не в репозитории). Если модель недоступна или ответ некорректен, сервер записывает причину в лог и использует локальную заглушку — сценарий при этом не прерывается.
• Роль (бизнес или студенческая команда) хранится в cookie сессии. Переключиться можно кнопкой «Сменить роль» в верхней панели; для одновременной проверки обеих сторон удобно обычное окно для бизнеса и окно инкогнито для команды.
• База — SQLite внутри сервиса, с теми же демонстрационными данными (5 черновиков, 5 карточек, 5 команд, 5 предложений). Данные, созданные при проверке, видны всем проверяющим.

Локальный запуск описан в разделе «Установка и запуск»; адрес после запуска: http://localhost:8080/.