Archibalt — AI Sana Challenge Hub: от бизнес-задачи к студенческой команде

Смотреть демо

Archibalt помогает бизнесу превратить описание проблемы в понятное задание, а студентам — найти реальный проект и предложить решение. AI уточняет потребность и собирает карточку; бизнес проверяет её, публикует и сам выбирает команду по откликам.

MVP для кейса «Рейтинг качества бизнес-задач и открытый выбор команд» (HackAlem AI, трек Education, задание 01). Официальное задание — TASK.md.

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

Запрос «нужно приложение для учёта заявок» ещё не объясняет, кто будет им пользоваться, какие данные есть и как проверить результат. Archibalt помогает уточнить эти сведения до начала работы со студенческой командой.

Рейтинг готовности 0–100 показывает, насколько подробно описана задача и чего не хватает. Бизнес дополняет карточку и подтверждает изменения — балл пересчитывается, позиция в каталоге обновляется. Даже на задачу с низким баллом можно откликнуться.

Как это работает

1. Бизнес описывает проблему в чате без входа и готового ТЗ. AI задаёт минимум три уточняющих вопроса и предлагает варианты первого результата.
2. Бизнес проверяет карточку из 10 полей: от контекста и данных до результата, критериев успеха и связи. Перед сборкой нужен демо-вход; текст можно исправить вручную.
3. Подтверждённая задача попадает в каталог. Рейтинг объясняет начисленные баллы и подсказывает, что дописать. По умолчанию выше стоят более готовые задачи.
4. Студенческая команда выбирает проект и отправляет идею, план, срок и ссылку на прототип. Бизнес сравнивает предложения и вручную выбирает одну, несколько или ни одной команды. За подтверждённый бизнесом этап команда получает 10 баллов.

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

Команда: Абылай (архитектура, бэкенд, AI, рейтинг), Ильяс (продукт, фронтенд, данные, демо). В работе использовались AI-инструменты разработки.

Быстрый запуск (для проверки экспертами)

Нужен Docker с Compose v2 (проверка: docker compose version). Раздел одинаков для macOS, Linux и Windows. Аккаунт OpenAI и API-ключ не нужны: без OPENAI_API_KEY AI работает в локальном mock-режиме с тем же форматом входа и выхода. Для действий бизнеса и команды используется демо-вход по email или телефону с кодом 000000; код никуда не отправляется.

git clone https://github.com/BAITC-Hacks/hack-fee6d244-archibalt.git
cd hack-fee6d244-archibalt
docker compose up --build

Откройте http://localhost:8080. Оба порта слушают только 127.0.0.1: 8080 (приложение) и 5432 (Postgres). Если 8080 занят: APP_PORT=8081 docker compose up --build. Проверка, что всё живо: http://localhost:8080/api/health → {"ok":true,"db":true,"ai_mode":"mock"}.

На пустой БД автоматически появятся 5 задач, 5 команд и 5 откликов. Начните с «Обсудить задачу» на главной или откройте каталог.

Живой AI через OpenAI (по желанию): скопируйте .env.example в .env, впишите OPENAI_API_KEY, перезапустите docker compose up --build. /api/health покажет ai_mode:"openai"; при сбое OpenAI система один раз повторяет запрос, откатывается на mock и показывает mock, не роняя сценарий.

Остановить контейнеры с сохранением данных: docker compose down. Удалить локальные данные и заново загрузить демо-набор: docker compose down -v, затем docker compose up --build.

Запуск без Docker (разработка)

Раздел для macOS/Linux; на Windows используйте Docker-запуск выше. Требуется Go 1.25+, Node 22+, PostgreSQL 16 (или make db, который поднимает только БД в Docker). Команды выполняются из корня репозитория.

Терминал 1 — база и API:

make db                          # postgres на localhost:5432, пароль hack
make run                         # Go API на :8080, seed загружается при пустой БД

Терминал 2 — фронтенд:

cd web
npm ci
npm run dev                      # http://localhost:5173, proxy /api → :8080

make run не загружает .env автоматически. Для живого AI экспортируйте переменные в терминале API перед запуском. Если вы уже заполнили собственный .env из примера:

set -a
. ./.env
set +a
make run

С другой БД задайте DATABASE_URL перед make run; make db в этом случае не нужен. Проверки описаны в разделе «Тестовые сценарии» ниже.

Параметры окружения

Переменная	По умолчанию	Назначение
PORT	8080	порт HTTP-сервера внутри контейнера; на хост Compose пробрасывает 127.0.0.1:${APP_PORT:-8080}
APP_PORT	8080	только для Compose: порт приложения на хосте
DATABASE_URL	postgres://postgres:hack@localhost:5432/hack?sslmode=disable	строка подключения Postgres; в Compose хост заменён на db
OPENAI_API_KEY	пусто → mock	ключ OpenAI; не коммитить, .env в .gitignore
OPENAI_MODEL	gpt-6-sol	модель для сборки карточки
OPENAI_MODEL_FAST	gpt-5.4-mini в Compose	модель для уточняющих вопросов; при прямом запуске незаданное или пустое значение — как OPENAI_MODEL
OPENAI_IMAGE_MODEL	gpt-image-1	модель визуального концепта (POST /api/tasks/{id}/visual)
OPENAI_IMAGE_QUALITY	low	качество визуального концепта
SEED_DIR	./seed	папка с демо-данными
STATIC_DIR	./web/dist	собранный фронт
REQUIRE_TEAM_LOGIN	true	false — отклик без входа по team_id из тела (страховка для демо)
DEMO_OTP	000000	общий демо-код входа бизнеса и команд; реальная отправка не реализована
WS_ORIGINS	localhost:*,127.0.0.1:*	разрешённые Origin для WebSocket-чата, через запятую
DEV_PROXY	пусто	адрес Vite (http://127.0.0.1:5173) для dev без сборки фронта
TEST_DATABASE_URL	пусто → тесты store пропускаются	БД для интеграционных тестов internal/store

Compose читает .env из корня сам; пустой OPENAI_MODEL_FAST там заменяется на gpt-5.4-mini. Чтобы использовать одну модель для всех текстовых вызовов, явно задайте одинаковые OPENAI_MODEL_FAST и OPENAI_MODEL.

Архитектура

web/  (Vite + React + TS)  ──fetch /api/*──▶  Go net/http  ──database/sql──▶  PostgreSQL 16
                                              ├─ internal/http    хендлеры, валидация, SPA-раздача
                                              ├─ internal/rating  формула рейтинга (чистая функция)
                                              ├─ internal/ai      OpenAI Responses API + mock + Guard
                                              ├─ internal/store   запросы, миграция db/schema.sql, seed
                                              └─ internal/model   типы = TS-типы фронта (API_CONTRACT.md)

• Один бинарник Go раздаёт и API (/api/*), и собранный фронт (/, SPA-fallback). Один docker compose up.
• Две роли: «Я бизнес / Я команда» переключаются на фронте; обе входят по email или телефону с демо-кодом 000000. Разговор с агентом начинается без входа (анонимный черновик); вход заявителя нужен, чтобы выбрать вариант результата или собрать карточку, править её, публиковать и решать по откликам — задача присваивается вошедшему. Команда входит перед откликом. Смотреть каталог можно без входа. Сессии хранятся в памяти API: после перезапуска нужен повторный вход.
• Контракт API с типами и всеми эндпоинтами: API_CONTRACT.md.
• Схема БД: db/schema.sql — teams, tasks (карточка в jsonb, рейтинг в jsonb + score), proposals, messages (чат по отклику), task_visuals (визуальный концепт).

Сквозной сценарий (ТЗ §2) → API

Шаг	Экран	API
1 Разговор без входа	чат с главной («Обсудить задачу»)	POST /api/tasks {draft_text, industry, mode:"dynamic"} без токена → анонимный черновик
2 Уточнение (3–10 вопросов, до 12 по запросу)	тот же чат	POST /api/tasks/{id}/next-question {answer}; варианты результата POST …/result-options
2а Вход и присвоение	модалка «Войти» при сборке карточки	POST /api/auth/business/verify → business_token; POST /api/tasks/{id}/owner {}; POST …/apply-result, POST …/answers {}
3 Карточка (редактируемая)	/task/:id/edit	PUT /api/tasks/{id}/fields
4 Рейтинг и подсказки	там же	score, breakdown, missing в каждом ответе
5 Публикация после подтверждения	кнопка «Подтвердить и опубликовать»	POST /api/tasks/{id}/confirm
6 Каталог, отклик команды	/catalog, /task/:id	GET /api/tasks?industry=&level=, POST /api/tasks/{id}/proposals
7 Ручной выбор бизнеса	/task/:id	POST /api/proposals/{id}/select / reject
8 Баллы команде за этап	/task/:id	POST /api/proposals/{id}/confirm-stage (+10 баллов команде)

Формула рейтинга готовности (ТЗ §4)

Рейтинг измеряет готовность конкретной задачи к работе со студентами, а не известность компании. Считается детерминированно в коде (internal/rating), AI на балл не влияет.

Семь показателей с весами из ТЗ, сумма 100:

Показатель	Вес	Поля карточки	Полный балл, если
Контекст и потребность	20	context, need	оба поля содержательно описаны: что происходит сейчас и что нужно изменить
Данные и материалы	20	data	назван материал (выгрузка, таблица, CRM, API, примеры, интервью) и способ или срок передачи
Ожидаемый результат	15	expected_result	назван конкретный артефакт (прототип, отчёт, сервис, дашборд, модель) с функцией
Критерии успеха	15	success_criteria	есть число с метрикой или единицей, либо описан способ проверки
Ограничения	10	constraints	указаны сроки, технологии, доступы или иные границы
Пользователи	10	users	названа роль или группа, для кого решение
Связь с бизнесом	10	contact, interaction_format	пригодный контакт (email, Telegram, телефон) и канал с ритмом встреч или сроком ответа

Начисление на показатель: 0 — пусто, заглушка (x, -, todo, «не знаю», в том числе внутри текста), текст без признаков короче трёх значимых слов, отказ без плана («данных не будет», «встреч не будет») или телефон из одинаковых цифр; половина веса (округление вниз) — заполнено, но признак полноты не найден (например, «передадим позже» без срока и способа); полный вес — условие из таблицы выполнено, причина называет найденный признак. У составных показателей половина, если закрыто одно поле из двух. Длина текста — вспомогательный сигнал, повтор фраз и пробелы балл не поднимают.

Известное ограничение: признаки — ключевые слова и регулярные выражения, а не понимание смысла. Осмысленный текст простыми словами без ключевых признаков получит половину веса, а длинная бессмыслица в полях «контекст» и «потребность» — полный. Список правил открыт в internal/rating/rating.go и на странице «Как работает AI».

score = Σ earned. Уровни: 0–39 черновик (виден в каталоге с пометкой), 40–69 рабочая (можно откликаться и рекомендовать), 70–89 готовая (повышенная позиция), 90–100 приоритетная (выделена). Низкий рейтинг задачу не скрывает и отклик не запрещает.

breakdown объясняет каждый показатель словами, missing перечисляет, что дописать и сколько это даст (gain = weight − earned), отсортировано по выгоде. Рейтинг пересчитывается при каждом сохранении.

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

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

• В каталоге только подтверждённые задачи. Все видны всем командам, ограничений на просмотр нет.
• По умолчанию: score по убыванию, при равенстве раньше опубликованная выше. В интерфейсе также есть «Сначала новые» и «Меньше откликов»; номер места на карточке остаётся местом по готовности во всём каталоге.
• Фильтры: отрасль (industry) и уровень готовности (level). В интерфейсе есть текстовый поиск; запрос, фильтры и выбранная сортировка сохраняются в URL.
• Отклики не лимитируются: любая команда может откликнуться на любую задачу, включая черновики.
• Автоназначения нет: только ручные select / reject по каждому отклику; можно выбрать 0, 1 или несколько команд.
• Начать черновик и ответить на вопросы можно без входа. После присвоения задачи вошедшему заявителю только он может менять карточку, публиковать её и принимать решения по откликам (select / reject / hold / confirm-stage). В текущем демо-наборе у всех пяти задач есть заявители; их контакты для проверки указаны ниже.
• Рекомендации (GET /api/teams/{id}/recommended) — дополнение: пересечение навыков и интересов команды со словами карточки, только задачи от уровня «рабочая»; общий каталог они не ограничивают.

AI-функция (ТЗ §5)

Вызовы OpenAI Responses API со строгой JSON-схемой (strict: true), без SDK. Промпты и схемы — в internal/ai/prompts.go, интерфейс с пояснениями — /ai, диагностика в JSON — GET /api/ai:

1. Вопросы: уточнить проблему, рабочий сценарий и ожидаемую пользу; минимум три вопроса. Пошаговый режим описан ниже, API также поддерживает получение списка вопросов сразу.
2. Карточка: собрать 10 полей только из черновика и ответов; для отсутствующих сведений вернуть пустую строку.

Визуальный концепт (необязательно): после выбора варианта первого результата агент сам рисует картинку через OpenAI GPT Image (gpt-image-1, quality=low) — ключевой экран, схему процесса или пример отчёта по полям карточки; подпись «Концепт для обсуждения, не обещание объёма». Без ключа — помеченная mock-заглушка; ошибка генерации не блокирует сборку карточки (internal/ai/image.go, internal/http/visual.go).

Пошаговый режим (mode: "dynamic", эндпоинт POST /api/tasks/{id}/next-question): агент задаёт по одному вопросу с учётом всего разговора. Промпт направляет его сначала разобраться в проблеме, пользователях и рабочем процессе, затем предложить подходящий первый результат и способ проверки. Частичный ответ можно уточнить; исправления и отказ от предложенного решения учитываются в следующих вопросах. Варианты ответов служат подсказками, можно написать свой текст. Контакт разрешено дописать в редакторе.

Минимум — 3 вопроса; 10 — предохранитель от бесконечного разговора, а не обязательная длина беседы. Кнопка «Спросить ещё» позволяет продолжить до 12 вопросов всего. Код ограничивает повтор одной темы двумя вопросами и учитывает явный пропуск; ответ «данных нет» считается сведением для диалога, но не даёт баллов за готовность данных. В чате можно раскрыть предварительную карточку и её балл. Итоговую карточку собирает вызов с Guard, затем её проверяет человек. Mock использует заготовленные вопросы и правила вместо смыслового анализа моделью.

Защита от выдуманных фактов (internal/ai/guard.go, работает и для OpenAI, и для mock): каждое непустое поле, включая название, проверяется на пересечение слов с исходным текстом пользователя, а любое число должно встречаться в исходнике рядом с тем же словом («2 недели» нельзя превратить в «2 оператора»); иначе поле очищается. Последний реальный вызов с сырым ответом модели и списком вырезанных полей виден в GET /api/ai → last_call. Ограничение: для полей «контекст» и «потребность» смена смысла через отрицание словами из исходника не ловится (для остальных полей полярность проверяется), поэтому карточку подтверждает человек. Человек редактирует и подтверждает карточку до публикации.

Обработка ошибок текстового AI: таймаут 10 с на попытку, при ошибке сети, статуса или невалидного JSON один повтор, затем локальный mock с тем же форматом; текст последней ошибки виден в GET /api/ai → last_error. Mock детерминирован: вопросы по таблице ключевых слов и приоритету весов, карточка из ответов. У генерации изображения отдельный таймаут 60 с; ошибка показывается без подмены картинки mock-заглушкой.

Пример живого вызова OpenAI на слабом черновике (вопросы, собранная карточка, что вырезал Guard): docs/ai-live-sample.json; текущее состояние — GET /api/ai → last_call.

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

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

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

make test                      # формула, AI, хендлеры; без внешнего AI и БД
npm --prefix web ci
npm --prefix web run build     # проверка TypeScript и сборка фронтенда

Тесты хранилища без TEST_DATABASE_URL пропускаются. Они создают и удаляют собственную временную схему, не затрагивая таблицы приложения. После make db запустите:

TEST_DATABASE_URL='postgres://postgres:hack@localhost:5432/hack?sslmode=disable' go test ./internal/store/

Go-тесты проверяют формулу (включая заглушки), AI (mock, Guard, откат при 500), хендлеры (сквозной путь и ошибки 400/404), а с тестовой БД — миграцию, seed, внешние ключи и баллы за этап.

Ручная проверка основного сценария (5 минут, всё в интерфейсе):

1. Открыть /catalog на свежей БД: видны 5 демо-задач со всеми четырьмя уровнями от «черновик» до «приоритетная», сортировка по баллу, фильтры работают.
2. «Обсудить задачу» на главной открывает чат сразу, без входа. Ожидаемо: агент задаёт не меньше 3 вопросов с кнопками-подсказками (в mock — по ключевым словам черновика). Агент спрашивает, чем занимается бизнес и что мешает; первое сообщение становится черновиком, например: «Нужно приложение для учёта заявок, сейчас всё в Excel и теряется». Дальше — по одному вопросу с подсказками-кнопками. Проверить, что вопросы уточняют проблему и ожидаемый результат; при непонятном ответе агент помогает уточнить тему, при явном пропуске идёт дальше. Минимум 3 вопроса, предел 10; «Спросить ещё» после завершения — до 12.
3. После вопросов агент предлагает 2–3 варианта первого проверяемого результата (результат / как проверим / что нужно / ~недель · оценка AI). «Выбрать» → появляется модалка входа заявителя (например, [email protected], код 000000, демо-режим) — беседа сохраняется, задача присваивается вошедшему. После выбора агент сам рисует визуальный концепт (GPT Image; без ключа — помеченная заглушка), «Собрать карточку» его не ждёт. Заявители пяти стартовых задач (чтобы показать решение бизнеса по откликам на seed-данных): [email protected], [email protected], [email protected], [email protected], [email protected] — задачи 1–5 соответственно, код 000000.
4. «Собрать карточку» → редактор: проверить соответствие текста черновику, ответам и выбранному результату. Исправить неточности, проверить незаполненные поля. Балл, разбивка по 7 показателям, список «что дописать» с +N.
5. Дописать критерии успеха с числом («снизить время обработки на 30%») и контакт с email и ритмом созвонов → сохранить → балл вырос, уровень изменился.
6. «Подтвердить и опубликовать» → задача в каталоге на позиции по баллу.
7. Переключиться в режим «Я команда» → открыть задачу → отправить отклик (идея, план, срок, ссылка). Вход команды: «Я команда» → любой email или телефон (например, [email protected]) → код 000000 (демо-режим, код не отправляется, подсказка на экране); новый контакт создаёт новую команду. Второй отклик: выйти, войти как [email protected], отправить отклик на ту же задачу.
8. Режим «Я бизнес» → вход тем же контактом, что на шаге 3 ([email protected]; для seed-задачи 1 — [email protected]) → «Мои задачи»: кто откликнулся и статусы → выбрать один отклик, отклонить другой. Можно выбрать несколько или отклонить все.
9. (Дополнительно) «Подтвердить этап» у выбранного отклика → команде начислены баллы.

В интерфейсе и через API (см. API_CONTRACT.md): «Мои отклики» (GET /api/me); «Мои задачи» заявителя (/api/business/me: отклики с командой, статусом и датами); принятие проекта командой (accept/decline); чат команды и заявителя по отклику (REST + WebSocket). Проверки серверной логики — в internal/http/*_test.go, сценарий через curl — в контракте.

Проверка ошибок: пустой черновик → сообщение, отклик без ссылки → сообщение, /api/tasks/999 → 404.

Тот же сценарий через curl — в API_CONTRACT.md; демо-набор — в seed/. Сервер загружает tasks.json, teams.json и proposals.json; drafts.json содержит 5 исходных описаний для ручной проверки и не создаёт дополнительных задач в БД.

Служебные файлы репозитория

Код продукта: cmd/, internal/, db/, web/, seed/, Dockerfile, docker-compose.yml. Остальные Markdown-файлы в корне (кроме TASK.md с заданием и API_CONTRACT.md с контрактом API) и папка research/ — рабочие заметки команды, на запуск не влияют.

Границы MVP и ограничения

• Есть две роли и демо-вход. Полноценная регистрация, восстановление доступа и реальная отправка email/SMS не реализованы; общий код 000000 предназначен для демонстрации.
• Рейтинг и проверка текста AI основаны на правилах и могут ошибаться. Карточку перед публикацией проверяет человек.
• Неопубликованную задачу можно прочитать по числовому ID; анонимный черновик до присвоения не защищён отдельным секретом.
• Правка опубликованной карточки убирает задачу из каталога до повторного подтверждения.
• Нет уведомлений, файлового хранилища, платежей, полного трекера проекта и инфраструктуры для промышленной эксплуатации.

Подробности и известные дефекты — в KNOWN_ISSUES.md. Текущее состояние командной приёмки — в STATUS.md.

Дальнейшее развитие

• Куратор AI Sana как эскроу. Третья роль (модератор платформы) держит грант или оплату на холде и выпускает после того, как обе стороны подтвердили этап. Механика статусов selected → accepted → этап подтверждён уже в API, статус on_hold заложен; остаётся роль куратора и интеграция с платёжным или грантовым контуром.
• Реальная отправка одноразовых кодов на email/SMS вместо демо-кода 000000.
• Версия-снимок опубликованной карточки при правке, чтобы задача не пропадала из каталога.
• Рекомендации командам по смыслу, а не по пересечению слов.

Сторонние компоненты

Компонент	Лицензия	Назначение
Go stdlib (net/http, database/sql, encoding/json)	BSD-3	сервер, БД, JSON
github.com/jackc/pgx/v5	MIT	драйвер PostgreSQL
jackc/pgpassfile, jackc/pgservicefile, jackc/puddle/v2	MIT	косвенные зависимости pgx
golang.org/x/sync, golang.org/x/text	BSD-3	косвенные зависимости pgx
github.com/coder/websocket	ISC	WebSocket-чат отклика
PostgreSQL 16 (Docker image postgres:16-alpine)	PostgreSQL License	база данных
React 18, react-dom, react-router-dom 6, @types/react, @types/react-dom	MIT	фронтенд
Vite 6, @vitejs/plugin-react, TypeScript 5	MIT / Apache-2.0	сборка фронта
OpenAI API (Responses)	по условиям OpenAI	AI-вопросы и карточка; опционально
Docker-образы golang:1.26-alpine, node:22-alpine, alpine:3.22	BSD-3 / MIT / смешанная (musl MIT, busybox GPL-2.0)	сборка и рантайм

Транзитивные npm-зависимости — в web/package-lock.json. Демо-данные в seed/ синтетические, созданы командой. Код продукта (cmd/, internal/, db/, web/, seed/, Docker-файлы) написан во время соревновательной части 23.09.2026 13:00–18:00; до старта в репозитории были только правила хакатона, документы для AI-агентов и заметки исследования рынка (research/).