HackAlem AI — платформа бизнес-задач

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

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

2. Проблема

Сырые бизнес-запросы часто не содержат данных, критериев успеха или ожидаемого результата. Студенческой команде трудно оценить такую задачу и подготовить предложение. Платформа помогает превратить черновик в структурированную Task Card и показать, какой информации не хватает.

3. Решение

Business вводит черновик → AI анализирует его и задаёт вопросы → после ответов создаётся Task Card → backend рассчитывает рейтинг → Business проверяет и редактирует карточку → публикует задачу → Student Team находит её в каталоге и отправляет Proposal → Business вручную принимает или отклоняет предложение.

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

• Анализ черновика через OpenAI API, список недостающих полей и минимум три уточняющих вопроса.
• Генерация и редактирование Task Card с полями: title, topic, context, need, users, data_materials, constraints, expected_result, success_criteria, contact, interaction_format.
• Расчёт на backend: score, readiness, missing_fields и breakdown; сохранение и пересчёт после редактирования. Интерфейс показывает общий рейтинг, готовность и недостающие поля; breakdown доступен в ответе API, но отдельно в интерфейсе пока не выведен.
• Хранение задач и предложений в SQLite; ручная публикация задач.
• Каталог опубликованных задач с фильтрами по теме и готовности, сортировкой по рейтингу и просмотром карточки.
• Отправка нескольких предложений к одной задаче, просмотр и ручные действия Accept / Reject.
• Проверка входных данных и сообщения об ошибках API в интерфейсе.

5. Основной пользовательский сценарий

1. Business открывает создание задачи, вводит тему и свободное описание, нажимает Analyze.
2. AI возвращает недостающие поля и вопросы; Business отвечает на них и нажимает Generate Task Card.
3. Открывается редактор сохранённой задачи с рейтингом и недостающей информацией. Business дополняет карточку и нажимает Save & Recalculate.
4. Business проверяет результат, нажимает Publish и переходит в каталог.
5. Student Team открывает опубликованную задачу и отправляет Proposal.
6. Business возвращается к редактору той же задачи и нажимает View Proposals, затем вручную выбирает Accept или Reject. Адрес редактора имеет вид /business/tasks/<id>; его удобно сохранить до перехода к студенческому сценарию. Также можно вернуться через историю браузера.

6. AI

Backend использует OpenAI Responses API и типизированный Structured Output через Pydantic. Один запрос анализирует черновик и формирует вопросы, второй структурирует описание и ответы в Task Card. Инструкции модели требуют опираться только на сведения пользователя и оставлять неизвестные поля пустыми. AI-результат не публикуется автоматически: Business может проверить и отредактировать карточку. Для этих функций нужен настроенный OpenAI API key и доступный API.

7. Рейтинг и геймификация

Рейтинг определяет backend по заполненности полей, а не AI. Формула фиксирована:

Компонент	Баллы
Context + Need (context 10 + need 10)	20
Data and materials	20
Expected result	15
Success criteria	15
Constraints	10
Users	10
Business connection (contact 5 + interaction_format 5)	10
Всего	100

Уровни готовности: 0–39 Draft, 40–69 Working, 70–89 Ready, 90–100 Priority. Backend также возвращает breakdown и missing_fields. Низкий рейтинг не блокирует публикацию задачи и отправку предложения. Рейтинг измеряет заполненность указанных полей, а не гарантирует качество содержания.

8. Каталог

Каталог получает из backend только опубликованные задачи. По умолчанию они отсортированы по убыванию рейтинга; доступны сортировка по возрастанию, фильтр по topic и фильтр по readiness. Просмотр каталога не требует учётной записи.

9. Proposals

Student Team указывает название команды (team_name), идею (idea), план (plan), срок (deadline) и ссылку на прототип (prototype_url). К одной задаче можно отправить несколько предложений. Business вручную принимает или отклоняет каждое; автоматического назначения команды и автоматического отклонения остальных предложений нет.

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

• Frontend: React, Vite, JavaScript, CSS, fetch().
• Backend: Python, FastAPI, Pydantic.
• Хранение: SQLite.
• AI: OpenAI API, Responses API, Structured Outputs.

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

Пользователь
    ↓
React Frontend
    ↓ HTTP/JSON
FastAPI REST API
    ├── SQLite: Task и Proposal
    └── OpenAI API: анализ и генерация Task Card

Frontend обращается к backend через frontend/src/services/api.js. Только backend работает с ключом OpenAI; рейтинг рассчитывается на backend, а данные задач и предложений сохраняются в SQLite.

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

backend/          FastAPI, схемы, сервисы, SQLite, requirements.txt
frontend/         React/Vite, страницы, компоненты, API-клиент
PROJECT_PLAN.md   план и API contract
README.md         инструкция и описание MVP
.env.example      шаблон переменных окружения

13. Требования

Нужны Python, Node.js/npm и OpenAI API key. Версии инструментов в репозитории не закреплены; зависимости backend перечислены в backend/requirements.txt, frontend — в frontend/package.json.

14. Установка backend

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

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp ../.env.example .env

Заполните backend/.env собственными значениями:

OPENAI_API_KEY=your_api_key
OPENAI_MODEL=<configured model>

Укажите модель, доступную вашему OpenAI API key. Не добавляйте настоящий ключ в README или Git.

15. Запуск backend

В каталоге backend/ с активированным окружением:

uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Адрес: http://localhost:8000. Проверка: откройте http://localhost:8000/api/health или выполните curl http://localhost:8000/api/health; ответ — {"status":"ok"}.

16. Установка frontend

В другом терминале из корня репозитория:

cd frontend
npm install

17. Запуск frontend

В каталоге frontend/:

npm run dev

Откройте http://localhost:5173. Frontend ожидает backend на http://localhost:8000/api.

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

1. Откройте Create task на http://localhost:5173/business/new.
2. Введите тему Customer Service и описание Хотим автоматизировать обработку обращений клиентов.
3. Нажмите Analyze и ответьте на полученные AI-вопросы. Их формулировки могут отличаться между запусками.
4. Нажмите Generate Task Card. Сохраните адрес открывшегося редактора.
5. Покажите рейтинг и недостающие поля, дополните их и нажмите Save & Recalculate. Если заполнены ранее пустые оцениваемые поля, рейтинг увеличится.
6. Нажмите Publish, откройте задачу в Catalog и отправьте Submit Proposal.
7. Вернитесь на сохранённый адрес редактора задачи, нажмите View Proposals и вручную выполните Accept или Reject.

19. API

GET    /api/health
POST   /api/tasks/analyze
POST   /api/tasks
PUT    /api/tasks/{task_id}
POST   /api/tasks/{task_id}/publish
GET    /api/tasks
GET    /api/tasks/{task_id}
POST   /api/tasks/{task_id}/proposals
GET    /api/tasks/{task_id}/proposals
PATCH  /api/proposals/{proposal_id}/status

20. Данные и внешние сервисы

SQLite хранит созданные через UI/API задачи и предложения в локальном файле backend/tasks.db. AI-функции обращаются к OpenAI API. Автоматической загрузки синтетических seed-данных в текущем коде нет; для демонстрации создайте задачу и предложение через интерфейс.

21. Валидация и ошибки

Backend отклоняет пустое описание и тему при анализе, пустой черновик при создании задачи, некорректные тела запросов, неизвестные задачи и предложения, неверные значения готовности, сортировки и статуса предложения. Ошибки конфигурации, недоступности OpenAI API и некорректного AI-ответа возвращаются как HTTP-ошибки. Frontend показывает сообщение backend, а при недоступности сервера сообщает об ошибке соединения.

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

Нет полноценной аутентификации, чата, уведомлений и публичного production-развёртывания. Роли Business и Student представлены отдельными страницами без разграничения прав. SQLite используется как локальное хранилище MVP. AI-функции зависят от настроенного ключа и доступности OpenAI API. Детализация breakdown есть в API, но пока не показана в интерфейсе отдельным списком.

23. Безопасность

Ключ OpenAI хранится в локальном backend/.env; этот файл исключён через .gitignore. Не публикуйте ключ и не передавайте его во frontend.

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

Развёрнутая публичная версия отсутствует; MVP запускается локально по инструкции выше.