TaskUp

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

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

Проект предназначен для двух demo-ролей:

• Business — создаёт, улучшает, публикует задачи и рассматривает отклики;
• Student — выбирает опубликованную задачу и отправляет proposal от команды.

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

• создание бизнес-задачи из свободного текста;
• AI-анализ недостающей информации;
• динамические уточняющие вопросы по найденным пробелам;
• генерация структурированной TaskCard;
• inline-редактирование всех полей карточки;
• детерминированный рейтинг качества от 0 до 100;
• уровни готовности Draft, Working, Ready, Priority;
• разбивка рейтинга по семи категориям;
• рекомендации, показывающие, сколько баллов и за какое улучшение можно получить;
• явная публикация карточки бизнесом;
• общий каталог опубликованных задач;
• сортировка каталога по score;
• фильтры по теме и уровню готовности;
• полная страница задачи для студента;
• отправка отклика с названием команды, идеей, планом, сроком и необязательной ссылкой;
• просмотр всех откликов бизнесом;
• ручные действия Принять и Отклонить;
• редактирование опубликованной задачи с автоматическим пересчётом score и уровня;
• demo-переключатель ролей Business / Student.

Для одной задачи можно принять только одну команду. После Accept задача получает статус in_progress, исчезает из каталога и больше не принимает отклики. Другие pending-отклики автоматически не отклоняются, но принять ещё одну команду нельзя.

XP и milestones в текущей версии не реализованы.

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

Бизнес описывает проблему
        ↓
AI находит пробелы
        ↓
AI задаёт уточняющие вопросы
        ↓
AI формирует структурированную TaskCard
        ↓
Бизнес редактирует карточку
        ↓
Детерминированный код рассчитывает score, уровень и hints
        ↓
Бизнес подтверждает публикацию
        ↓
Задача появляется в каталоге
        ↓
Студенческая команда отправляет proposal
        ↓
Бизнес вручную выбирает Accept или Reject
        ↓
После Accept задача переходит в статус «В работе»

AI отвечает только за анализ текста, вопросы и содержимое карточки. Score, уровень, статусы, правила публикации, сортировка каталога и решения по откликам выполняются обычным кодом.

Основные маршруты

Маршрут	Назначение
/	Главная страница и вход в сценарии Business / Student
/create	Описание задачи, AI-анализ, вопросы, карточка и публикация
/catalog	Каталог опубликованных задач с фильтрами
/tasks/[id]	Карточка задачи, score и форма отклика команды
/business	Все задачи бизнеса и количество ожидающих откликов
/business/[id]	Редактирование, публикация и ручной Accept / Reject

Технологии

• Next.js 16 и App Router;
• React 19;
• TypeScript;
• Tailwind CSS 4;
• shadcn/ui и Base UI для UI-компонентов;
• Zustand для клиентского состояния MVP;
• Zod для проверки запросов и структурированных AI-ответов;
• OpenAI JavaScript SDK и Responses API;
• Framer Motion для интерфейсных анимаций;
• Lucide React для иконок;
• ESLint для статического анализа.

Конкретная AI-модель в репозитории не зафиксирована. Сервер читает её идентификатор из переменной OPENAI_MODEL.

Архитектура

Frontend UI
    ↓ fetch
Next.js API Routes: /api/analyze и /api/card
    ↓
OpenAI Responses API
    ↓
Zod validation
    ↓
структурированный TaskCard
    ↓
Zustand Store
    ↓
calculateScore / Catalog / Proposals / Business actions

Основные части:

• components/create-task/ управляет flow Describe → Clarify → Review;
• app/api/analyze принимает исходный текст и возвращает пробелы с вопросами;
• app/api/card принимает текст и ответы, валидирует результат AI и возвращает карточку;
• lib/ai.ts содержит AI-инструкции и Zod-схемы;
• lib/openai.ts создаёт серверный OpenAI-клиент и выполняет запрос через Responses API;
• lib/store.ts хранит задачи и реализует публикацию, редактирование и решения по откликам;
• lib/score.ts независимо от AI рассчитывает рейтинг, уровень и рекомендации;
• components/tasks/ отображает каталог, карточки, score и Business / Student actions.

Состояние MVP хранится в памяти Zustand на клиенте. Серверной базы данных нет.

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

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

   git clone https://github.com/BAITC-Hacks/hack-b2e7006f-meynya-craft.git
   cd hack-b2e7006f-meynya-craft
   

2. Установите зависимости из lock-файла.

   npm ci
   

3. Создайте .env.local рядом с package.json.

   OPENAI_API_KEY=ваш_основной_ключ
   OPENAI_MODEL=идентификатор_доступной_модели
   
   # Необязательно: используется только при исчерпании квоты основного ключа
   OPENAI_API_KEY_BACKUP=ваш_резервный_ключ
   

   Не используйте префикс NEXT_PUBLIC_: ключи нужны только серверной части. Реальные ключи нельзя добавлять в Git.

4. Запустите development-сервер.

   npm run dev
   

5. Откройте http://localhost:3000.

Для production-сборки:

npm run build
npm run start

Как проверить решение за несколько минут

Все действия выполняйте в одной вкладке, не обновляя страницу: состояние MVP хранится клиентски.

1. Откройте /create.

2. Введите намеренно неполное описание:

   У нас небольшая кофейня. Администратор записывает заказы на доставку в блокнот, иногда заказы теряются. Хотим уменьшить количество ручной работы.

3. Нажмите «Проанализировать задачу». Проверьте найденные пробелы и перейдите к вопросам.

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

5. Сформируйте карточку. На Review-экране проверьте score, уровень, категории и рекомендации.

6. Отредактируйте слабые поля, например:

   • пользователи: «Два администратора кофейни, которые принимают и распределяют заказы»;
   • критерий успеха: «Сократить среднее время оформления заказа до 2 минут»;
   • данные: «Таблица из 500 обезличенных заказов за последние три месяца».

7. Убедитесь, что score пересчитался, затем нажмите «Подтвердить задачу».

8. Перейдите по ссылке в /catalog, найдите опубликованную карточку и откройте /tasks/[id].

9. Отправьте proposal от первой команды. Через каталог снова откройте ту же задачу и отправьте второй proposal от другой команды.

10. Переключитесь в Business, откройте /business/[id], отклоните один отклик и примите другой.

11. Проверьте, что принятый отклик получил статус «Принят», задача перешла в состояние «В работе», закрылась для новых откликов и исчезла из /catalog.

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

OpenAI API

• используются два POST-маршрута: /api/analyze и /api/card;
• запросы выполняются через OpenAI Responses API с store: false;
• ответы AI проходят Zod-валидацию;
• frontend дополнительно проверяет структуру ответа перед обновлением состояния;
• основной и необязательный резервный API-ключи остаются на сервере;
• резервный ключ используется только при ошибке исчерпания квоты основного ключа;
• конкретная модель задаётся через OPENAI_MODEL и в репозитории не указана.

Synthetic seed data

В lib/seed.ts находятся вымышленные demo-данные:

• 8 задач: 6 опубликованных, 1 черновик и 1 задача в работе;
• 5 студенческих команд;
• 8 откликов: 6 pending, 1 accepted и 1 rejected.

Контакты используют адреса example.com и не относятся к реальным организациям.

На экране создания также есть три готовых demo-описания: Ритейл, Поддержка клиентов и Логистика.

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

calculateScore() находится в lib/score.ts. Максимальный score — 100 баллов.

Перед расчётом пробелы и повторяющиеся пробелы нормализуются. Пустая строка и значение «Не указано» дают 0 баллов. Короткое заполненное значение получает половину максимума с округлением вниз. Полный балл начисляется при достижении порога длины.

Категория	Максимум	Фактическое правило
Context + Need	20	context и need по 10; каждое поле получает максимум от 40 символов
Data	20	data: максимум от 40 символов
Expected Result	15	expectedResult: максимум от 40 символов
Success Criteria	15	до 8 баллов за длину и ещё 7 за измеримый числовой показатель
Constraints	10	constraints: максимум от 40 символов
Users	10	users: максимум от 40 символов
Business Contact	10	contact: максимум от 10 символов

interactionFormat отображается в карточке, но не влияет на score.

Для дополнительных 7 баллов в successCriteria должны одновременно присутствовать:

• хотя бы одна цифра;
• русская или латинская буква;
• не менее четырёх слов.

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

Score	Уровень
0–39	Draft
40–69	Working
70–89	Ready
90–100	Priority

Hints формируются детерминированно только для недостающих баллов. Каждая рекомендация показывает потенциальную прибавку; сумма всех прибавок равна 100 − score.

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

• в каталог попадают только задачи со статусом published;
• черновики и задачи in_progress не показываются;
• задачи сортируются по score по убыванию;
• при одинаковом score используется сортировка по id;
• доступны совместимые фильтры по теме и уровню готовности;
• минимального score для публикации и отклика нет;
• низкий score влияет только на позицию в каталоге и не запрещает отправить proposal;
• после Accept задача переходит в in_progress, исчезает из каталога и закрывается для новых откликов.

Ограничения MVP

• полноценной авторизации нет;
• Business / Student — интерфейсный demo-переключатель, а не система прав доступа;
• данные Zustand существуют только в памяти текущей вкладки;
• после reload пользовательские задачи, изменения и отклики сбрасываются к seed-данным;
• вкладки и устройства не синхронизируются;
• общей серверной базы данных нет;
• проект демонстрирует продуктовый сценарий и не является production-инфраструктурой.

Структура проекта

app/                  страницы App Router: landing, create, catalog, tasks, business
app/api/              серверные POST-маршруты AI-анализа и генерации карточки
components/           create-flow, task UI, landing и переиспользуемые UI-компоненты
lib/                  AI, OpenAI client, типы, store, scoring, seed и frontend API adapter
scripts/              автономная проверка backend-контрактов и бизнес-правил

Проверки

# ESLint
npm run lint

# TypeScript без генерации файлов
npx tsc --noEmit

# Production build
npm run build -- --webpack

# Проверка пробельных ошибок в diff
git diff --check

# Backend-контракты без реальных AI-запросов и без расхода кредитов
node scripts/check-backend.mjs

# Дополнительная live-проверка двух запросов к OpenAI; расходует API-кредиты
node --env-file=.env.local scripts/check-backend.mjs --live

Offline backend-check использует реальные Zod-схемы, Zustand-store, scoring, seed, API handlers и AI parsing; транспорт OpenAI в нём подменён. Live-режим требует OPENAI_API_KEY и OPENAI_MODEL.