Задачник

1. Название проекта

«Задачник» — рейтинг готовности бизнес-задач и открытый выбор студенческих команд. Решение кейса AI Sana «Рейтинг качества бизнес задач и открытый выбор команд» (HackAlem AI).

2. Краткое описание

Бизнес часто приходит к студентам с задачей в одну строку: «курьеры опаздывают, нужна какая-то система». Команде с такой задачей не с чем работать, а бизнес не понимает, чего не хватает.

«Задачник» помогает представителю бизнеса превратить черновик в полноценную карточку задачи: ИИ задаёт уточняющие вопросы, формула считает рейтинг готовности от 0 до 100 и показывает, какие сведения его повысят. Опубликованная задача встаёт в открытый каталог на место по своему рейтингу. Любая студенческая команда откликается идеей, планом, сроком и ссылкой на прототип, а бизнес сам решает, с кем работать.

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

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

Бизнес

• Ввод черновика задачи свободным текстом и выбор отрасли.
• ИИ разбирает черновик по полям карточки и задаёт от 3 до 6 уточняющих вопросов по недостающим пунктам.
• Ответы редактируются и сохраняются сами. Табло пересчитывает предварительный рейтинг, уровень и место в таблице, мини-таблица показывает, как задача поднимается выше.
• ИИ собирает карточку из черновика и ответов. Карточка редактируется: все 9 полей, название, тема.
• Баллы засчитываются только после ручного подтверждения. До подтверждения видно, сколько добавят правки и какое место займёт задача.
• Рейтинг с расшифровкой: каждый из 7 пунктов формулы разбит на проверки, пустые отрезки подсказывают, что добавить («+5 · Указан срок»).
• История рейтинга: каждое подтверждение пишет запись (было → стало, причина).
• Публикация подтверждённой версии в каталог.
• Кабинет: профиль компании (редактируется), список своих задач с баллами, уровнем, местом и числом заявок.
• Заявки команд по каждой задаче: идея, план, срок, ссылка на прототип. Действия «Выбрать команду», «Отклонить», «Отменить выбор». Можно выбрать одну, несколько или ни одной команды — автоматического назначения нет.

Студенческая команда

• Профиль команды: название, число участников, интересы, навыки, технологии.
• Таблица задач: все опубликованные задачи по рейтингу, зоны уровней готовности, фильтры по уровню и теме, сортировка «по очкам» и «сначала новые». Задачи с низким рейтингом остаются в таблице с пометкой «Мало сведений».
• Страница задачи со всеми полями, рейтингом и разбором по пунктам.
• Форма заявки (идея, план, срок, ссылка) с валидацией. Число заявок не ограничено.
• Список своих заявок с решением бизнеса.
• Подсказка «Подходит команде»: совпадения интересов, навыков и технологий с текстом задачи. Работает на правилах, без ИИ, предлагает только задачи от 40 баллов и не сужает таблицу.

Прозрачность ИИ

• Страница «Как работает ИИ» (/ai): системные промпты, пример входа, JSON-схемы ответа, обработка некорректного ответа.

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

1. Черновик. Бизнес пишет, например: «Курьеры часто опаздывают, клиенты жалуются. Нужна какая-то система, чтобы это исправить.»
2. Разбор. POST /api/tasks отправляет черновик в OpenAI. Модель раскладывает сказанное по полям карточки и задаёт 3–6 вопросов о пустых пунктах. Контакт подставляется из профиля компании. Проверка фактов отменяет всё, чего нет в черновике.
3. Уточнение. Бизнес отвечает. Каждый ответ сохраняется (PUT /api/tasks/:id/answers), сервер считает предварительный рейтинг и место. На демо-черновике рейтинг растёт примерно с 19 до 85–95.
4. Карточка. POST /api/tasks/:id/structure: модель собирает карточку из черновика и ответов. Результат ждёт подтверждения человеком.
5. Рейтинг. Бизнес правит поля и нажимает «Подтвердить». PATCH /api/tasks/:id сохраняет поля, пересчитывает рейтинг формулой и пишет запись в историю.
6. Каталог. POST /api/tasks/:id/publish: задача появляется в таблице на месте, соответствующем рейтингу.
7. Выбор студентов. Команда находит задачу в таблице и отправляет заявку (POST /api/tasks/:id/proposals).
8. Выбор бизнеса. Бизнес видит заявку в кабинете и вручную выбирает или отклоняет команду (PUT /api/tasks/:id/selections/:teamId).

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

Чистая функция evaluate() в backend/src/scoring/scoring.ts, без ИИ и без обращения к БД. Покрыта тестами. Баллы начисляются только за подтверждённые поля; неподтверждённые правки показываются отдельно.

Пункт	Вес	Проверки
Контекст и потребность	20	описана текущая ситуация (8) · есть подробности: где, когда, как часто (6) · понятно, что нужно изменить (6)
Данные и материалы	20	перечислены доступные данные (10) · указан объём, формат или источник (10)
Ожидаемый результат	15	описан результат работы команды (10) · назван формат: прототип, отчёт, модель (5)
Критерии успеха	15	есть признак приёмки (8) · признак измерим: число, доля или срок (7)
Ограничения	10	указан срок (5) · названы технологии, доступы или иные границы (5)
Пользователи	10	понятно, для кого решение (10)
Связь с бизнесом	10	есть контактное лицо (5) · описан формат консультаций и обратной связи (5)

Уровни: 0–39 черновик (виден в каталоге с пометкой «требует уточнения») · 40–69 рабочая · 70–89 готовая · 90–100 приоритетная (строка выделена в таблице).

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

• В таблице все опубликованные задачи. Низкий рейтинг задачу не скрывает и отклик не запрещает.
• Место — порядок по рейтингу; при равенстве выше та, что опубликована раньше. Фильтры не меняют место задачи.
• Таблица разбита на зоны уровней; приоритетные задачи выделены цветом.
• Подсказки для команды предлагают только задачи от 40 баллов («Рабочая» и выше) и не фильтруют таблицу.
• Число заявок не ограничено. Решение по команде принимает только бизнес.

ИИ: промпты, вход и выход, обработка ошибок

• Промпты: backend/src/ai/prompts.ts. Их же отдаёт GET /api/ai/info, и они показаны на странице /ai.
• Вход: отрасль, компания и черновик; на втором шаге — ещё текущие поля и пары «вопрос — ответ».
• Выход: Structured Outputs через OpenAI Responses API. Схемы описаны на zod в backend/src/ai/schemas.ts: шаг 1 — { title, fields{9 полей}, questions[{criterion, field, question, why}] }, шаг 2 — { title, fields }.
• Обработка некорректного ответа (backend/src/ai/openai.ts, service.ts):
  1. ответ дополнительно проверяется zod; при ошибке — один повтор с описанием проблемы;
  2. ошибка сети, таймаут, отказ модели или повторная ошибка схемы — срабатывают локальные правила (backend/src/ai/fallback.ts), интерфейс показывает, кто составил вопросы;
  3. если модель задала меньше трёх вопросов, недостающие добавляются из шаблонов по самым весомым пустым пунктам;
  4. проверка фактов (backend/src/ai/guard.ts): число или латинское название, которого нет в словах бизнеса, отменяет поле — остаётся текст самого бизнеса;
  5. если сжатая моделью формулировка теряет баллы, остаётся формулировка бизнеса.
• Без ключа OpenAI приложение работает целиком на локальных правилах.

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

• Языки: TypeScript, SQL (миграции Prisma).
• Фронтенд: Next.js 16.3 (App Router), React 19.2, собственные CSS-стили, шрифты Sofia Sans и Sofia Sans Extra Condensed через next/font.
• Бэкенд: Node.js, Express 5, zod 4, cors, запуск через tsx.
• База данных: PostgreSQL 17 (Docker), Prisma ORM 7 с адаптером @prisma/adapter-pg.
• ИИ: OpenAI API через официальный SDK openai, Responses API со Structured Outputs. Модель задаётся в .env (OPENAI_MODEL, по умолчанию gpt-5.6-terra, уровень рассуждений low).
• Тесты: встроенный node:test через tsx --test.
• Пакетный менеджер: pnpm.

6. Архитектура

./
├── docker-compose.yml   # один сервис: postgres
├── .env.example         # все переменные окружения
├── backend/             # Express REST API + Prisma
│   ├── prisma/          # schema.prisma, миграции, seed.ts, data/*.json
│   └── src/
│       ├── scoring/     # формула рейтинга и тесты
│       ├── ai/          # промпты, схемы, OpenAI, проверка фактов, локальные правила
│       ├── routes/      # tasks, catalog, businesses, teams, meta
│       └── lib/         # DTO задач, место в каталоге, подсказки для команд
└── frontend/            # Next.js
    ├── app/             # страницы: /, /catalog, /catalog/[id], /team, /business, /business/new, /business/tasks/[id], /business/tasks/[id]/clarify, /ai
    ├── components/      # табло, разбор очков, формы, кабинет
    └── lib/             # API-клиент, типы, выбор компании или команды

Взаимодействие: браузер ↔ Next.js (серверные компоненты загружают данные, клиентские — формы и живой пересчёт) ↔ Express REST API ↔ PostgreSQL через Prisma. Express обращается к OpenAI только на двух шагах: разбор черновика и сборка карточки. Рейтинг всегда считает формула на сервере.

Модель данных (backend/prisma/schema.prisma): Business, Task (поля карточки, score, readinessLevel, status, JSON с вопросами и ответами), ScoreEvent (история рейтинга), TeamProfile, Proposal, Selection (решение бизнеса: выбрана или отклонена; нет записи — на рассмотрении).

Основные маршруты API (префикс /api): GET /meta, POST /score/preview, GET /ai/info, POST /tasks, GET /tasks/:id, POST /tasks/:id/analyze, PUT /tasks/:id/answers, POST /tasks/:id/structure, PATCH /tasks/:id, POST /tasks/:id/publish, GET|POST /tasks/:id/proposals, PUT /tasks/:id/selections/:teamId, GET /catalog, GET /catalog/:id, GET|PATCH /businesses/:id, GET /businesses/:id/tasks, GET|PATCH /teams/:id, GET /teams/:id/recommendations, GET /teams/:id/proposals.

Регистрации нет (вне рамок кейса): компания или команда выбирается в шапке, выбор хранится в cookie.

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

Нужны Node.js 22+ (проверено на 24.12), pnpm 10+ (проверено на 11.18) и Docker.

git clone https://github.com/BAITC-Hacks/hack-5bd8445b-talgat.git
cd hack-5bd8445b-talgat

# 1. Переменные окружения: вставьте свой OPENAI_API_KEY (без ключа сработают локальные правила)
cp .env.example .env

# 2. PostgreSQL в Docker (порт 5433 на хосте, чтобы не мешать локальному PostgreSQL)
docker compose up -d

# 3. Бэкенд: зависимости, миграции, демо-данные, запуск API на http://localhost:4000
cd backend
pnpm install
pnpm db:deploy
pnpm db:seed
pnpm dev

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

cd frontend
pnpm install
pnpm dev

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

Полезные команды бэкенда: pnpm test — тесты формулы и ИИ-защиты, pnpm db:seed — перезалить демо-данные (очищает таблицы), pnpm db:migrate — миграции в режиме разработки, pnpm build && pnpm start — сборка и запуск без watch.

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

Сценарий на сидовом черновике компании «Жетісу Логистик»:

1. Откройте http://localhost:3000 и нажмите «Выставить задачу». В шапке выбрана компания «Жетісу Логистик».
2. Нажмите «демо: вставить слабый черновик» — появится текст «Курьеры часто опаздывают, клиенты жалуются. Нужна какая-то система, чтобы это исправить.» — и «Разобрать черновик». Тот же черновик лежит в кабинете как «Курьеры часто опаздывают, клиенты жалуются».
3. На экране «Разбор черновика» будет от 3 до 6 вопросов и рейтинг около 19 («Черновик»). Отвечайте своими словами или кнопками «демо: подставить ответ». После каждого ответа растут очки, меняется уровень, задача поднимается в мини-таблице справа.
4. Нажмите «Собрать карточку». Проверьте поля, при желании допишите, например, формат встреч. Табло покажет, сколько добавят неподтверждённые правки.
5. Нажмите «Подтвердить и опубликовать». Уведомление покажет место в таблице; в «Истории рейтинга» появятся записи.
6. Переключитесь на «Команда» (выбрана Byte Batyrs), откройте «Таблицу задач»: задача стоит на месте по рейтингу. Попробуйте фильтры «Уровень» и «Тема».
7. Откройте задачу, отправьте пустую форму заявки — появятся подсказки по полям. Заполните идею, план, срок, ссылку и отправьте.
8. Вернитесь в «Бизнес» → «Кабинет»: заявка видна в блоке «Заявки на …». Нажмите «Выбрать команду» или «Отклонить».

Дополнительно: cd backend && pnpm test — 14 тестов формулы и защиты ИИ; страница http://localhost:3000/ai — промпты и схемы.

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

• Синтетические данные — в backend/prisma/data/*.json, загружаются одной командой pnpm db:seed:
  • 10 компаний;
  • 5 черновиков разной полноты с отраслью (drafts.json);
  • 7 опубликованных карточек со всеми полями, текущим рейтингом от 18 до 95 и историей (cards.json);
  • 5 профилей команд (teams.json);
  • 8 заявок, в том числе с решениями «выбрана» и «отклонена» (proposals.json).
• OpenAI API — разбор черновика и сборка карточки. Ключ берётся из OPENAI_API_KEY в .env. В репозиторий ключ не попадает: .env в .gitignore.
• PostgreSQL — основное хранилище, поднимается через docker-compose.yml.
• Google Fonts — шрифты загружаются при сборке через next/font.
• Других внешних сервисов нет.

10. Ограничения

• Нет регистрации, авторизации и ролей: компания и команда выбираются в шапке (по условиям кейса это вне рамок MVP).
• Нет чата, уведомлений, календаря и файлового хранилища; прототип передаётся ссылкой.
• Этап «Результат» из кейса (баллы выбранной команде за фактический прогресс) не реализован — MVP заканчивается решением бизнеса по заявке.
• Подсказки для команд работают на совпадении ключевых слов, без ИИ.
• Проверки формулы оценивают наличие и конкретность сведений (длина, числа, ключевые слова), а не смысл текста.
• Проверка фактов ловит новые числа и латинские названия; перефразирование без новых чисел и названий она не отличит.
• Интерфейс рассчитан на десктоп; мобильная адаптация по кейсу вне рамок.
• Продакшн-сборки и деплоя нет.

11. Ссылка на deployed-версию

Развёрнутой версии нет — проект запускается локально по инструкции выше.