HackAlem AI

HackAlem AI превращает неструктурированную бизнес-проблему в проверяемую задачу для студенческих команд.

Проблема

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

Решение

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

Основной сценарий

1. Бизнес создаёт черновик с кратким описанием.
2. AI задаёт уточняющие вопросы.
3. AI формирует редактируемую карточку задачи.
4. Backend рассчитывает рейтинг готовности.
5. Бизнес дополняет карточку и сохраняет изменения.
6. Бизнес подтверждает и публикует задачу.
7. Студент видит задачу в каталоге.
8. Студент отправляет предложение.
9. Бизнес вручную принимает или отклоняет предложение.

Реализовано

• REST API на Go и стандартном net/http.
• SQLite через database/sql и modernc.org/sqlite.
• Инициализация схемы и опциональные идемпотентные demo-данные.
• Создание, редактирование, подтверждение и публикация задач.
• Каталог опубликованных задач с фильтрами по теме, уровню и рейтингу.
• AI endpoints для вопросов и карточки задачи.
• Создание и просмотр предложений команд.
• Независимое принятие или отклонение каждого предложения.
• Русский пользовательский интерфейс на React.

Геймификация

Рейтинг готовности рассчитывается backend по шкале 0–100:

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

Уровни: 0–39 — черновик, 40–69 — рабочая, 70–89 — готовая, 90–100 — приоритетная. Низкий рейтинг не скрывает опубликованную задачу из каталога.

AI

• POST /api/ai/questions возвращает 3–5 уточняющих вопросов.
• POST /api/ai/card возвращает карточку из 11 строковых полей задачи.
• AI не придумывает неподтверждённые факты и не рассчитывает рейтинг.
• Карточка остаётся редактируемой человеком.
• X-AI-Mode: live или X-AI-Mode: fallback показывает фактический режим ответа.
• При отсутствии ключа или недоступности провайдера используется явный fallback без внешнего API-вызова.

Архитектура

React frontend
      |
      v
Go backend + SQLite
      |
      +-- tasks / rating / catalog / proposals
      |
      +-- AI module
             |
             v
         OpenAI provider

backend/ и ai/ — отдельные Go-модули. При запуске backend/cmd/server AI-модуль подключается к общему net/http серверу.

Технологии

• Go 1.25+
• net/http
• database/sql
• SQLite через modernc.org/sqlite
• React 19
• Vite 7
• стандартный fetch API

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

backend/   Go API, SQLite, rating, catalog and proposals
ai/        Go AI service, validation and fallback provider flow
frontend/  React/Vite client
docs/      jury demo scenario

Быстрый запуск

В PowerShell из корня проекта:

Set-Location .\backend
$env:AI_FORCE_FALLBACK = 'true'
$env:SEED_DEMO_DATA = 'true'
go run ./cmd/server

Backend слушает http://localhost:8080. В отдельном PowerShell:

Set-Location .\frontend
npm install
Copy-Item .env.example .env -ErrorAction SilentlyContinue
npm run dev

Frontend будет доступен по адресу http://localhost:5173. Полный сценарий для жюри находится в docs/demo-script.md.

Environment variables

Backend читает переменные процесса; dotenv-файлы автоматически не загружаются:

Переменная	Обязательность	Назначение
DATABASE_PATH	необязательно	путь к SQLite, по умолчанию ./data/app.db
FRONTEND_ORIGIN	необязательно	разрешённый origin, по умолчанию http://localhost:5173
SEED_DEMO_DATA	необязательно	true включает идемпотентные demo-данные
OPENAI_API_KEY	необязательно	серверный ключ провайдера; без него используется fallback
OPENAI_MODEL	необязательно	модель провайдера; без неё используется fallback
AI_TIMEOUT_SECONDS	необязательно	timeout AI, по умолчанию 15
AI_MAX_ATTEMPTS	необязательно	число попыток AI, по умолчанию 2
AI_FORCE_FALLBACK	необязательно	true запрещает обращения к провайдеру

Frontend использует переменные сборки VITE_API_URL (по умолчанию http://localhost:8080), VITE_USE_MOCK (явный локальный режим без backend) и VITE_DEMO_TEAM_ID (по умолчанию 1).

Demo mode

Для демонстрации без API-ключа используйте:

$env:SEED_DEMO_DATA = 'true'
$env:AI_FORCE_FALLBACK = 'true'

Повторный запуск seed не дублирует задачи, команды и предложения.

Проверка

Введите Хотим автоматизировать работу склада, ответьте на вопросы AI, сохраните карточку, дополните поля, подтвердите и опубликуйте задачу. Затем откройте её в режиме студента, отправьте предложение и обработайте его в режиме бизнеса.

Тесты

Set-Location .\backend
go vet ./...
go test -count=1 ./...

Set-Location ..\ai
go vet ./...
go test -count=1 ./...

Set-Location ..\frontend
npm run build

В frontend нет отдельных lint- или test-скриптов.

API

• GET /api/health
• POST /api/tasks
• GET /api/tasks
• GET /api/tasks/{id}
• PUT /api/tasks/{id}
• GET /api/tasks/{id}/rating
• POST /api/tasks/{id}/confirm
• POST /api/tasks/{id}/publish
• POST /api/tasks/{id}/proposals
• GET /api/tasks/{id}/proposals
• PATCH /api/proposals/{id}/status
• POST /api/ai/questions
• POST /api/ai/card

Ограничения

Это MVP без аутентификации, JWT, real-time чата, уведомлений, календаря, файлового хранилища и автоматического назначения команд. Идентификатор команды вводится в форме; отдельного team-list endpoint нет. Fallback AI задаёт вопросы и сохраняет исходное описание, а неизвестные поля карточки заполняются человеком.

Команда

Состав команды и роли не указаны в текущем репозитории.