Iskra

| POST /api/task-drafts/{draft_id}/answers | Оценка ответов и следующий шаг | | POST /api/task-drafts/{draft_id}/publish | Публикация готового черновика | | GET /api/tasks | Получение серверного каталога | | DELETE /api/tasks/{task_id} | Удаление серверной задачи |

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

Требования

• Git и доступ к репозиторию: на момент анализа репозиторий приватный.
• Node.js 22 и npm; Python 3.12 — версии, используемые в CI.
• Для полного AI-сценария — ключ Gemini API, доступ к указанным в коде моделям и интернет-соединение backend.

Ниже приведены команды для PowerShell. Файлов .env.example в проверенной версии нет, поэтому конфигурация создаётся вручную. Промпты уже находятся в backend/app/services/ai_service.py.

1. Получить проект

git clone https://github.com/BAITC-Hacks/hack-99d4c8fe-team.git
cd hack-99d4c8fe-team

2. Подготовить backend

cd backend
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip install google-genai

Создайте файл backend/.env со следующим содержимым, заменив значение ключа:

GEMINI_API_KEY=YOUR_GEMINI_API_KEY
FRONTEND_ORIGIN=http://localhost:3000

Ключ используется только backend. Не помещайте его в переменные NEXT_PUBLIC_*.

Запустите сервер из каталога backend:

.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload --port 8000

• Проверка процесса: http://localhost:8000/api/health.
• Интерактивная документация API: http://localhost:8000/docs.

Ожидаемый ответ проверки процесса — {"status":"ok"}. Он не проверяет ключ и доступность Gemini.

3. Запустить frontend

Откройте второй терминал в корне клонированного репозитория:

cd frontend
npm ci
Set-Content -Path .env.local -Value 'NEXT_PUBLIC_API_BASE_URL=http://localhost:8000' -Encoding utf8
npm run dev

Откройте http://localhost:3000. После изменения .env.local перезапустите frontend.

Для локального запуска production-сборки frontend вместо npm run dev:

npm run build
npm run start

Backend при этом запускается отдельно.

Режим демонстрации без AI

Для просмотра каталога достаточно запустить frontend. Три встроенные карточки доступны даже при недоступном backend; можно проверить поиск, фильтры и форму предложения команды. Создание новой задачи требует работающего backend и Gemini API.

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

Сценарий A: интерфейс без API-ключа

1. Запустите frontend и перейдите в «Каталог задач».
2. Найдите задачу «Снизить пищевые отходы в кампусе» через поиск или категорию «Экология».
3. Откройте карточку, проверьте описание, поля задачи и расшифровку рейтинга.
4. Нажмите «Предложить решение». Укажите команду «Тестовая команда», идею «Вести журнал остатков еды» и план «Собрать данные за неделю и подготовить прототип учёта».
5. Отправьте форму: число откликов у карточки должно увеличиться в текущем сеансе.

Это проверка локального интерфейса. Изменения демонстрационных карточек sample-* не сохраняются после перезагрузки страницы; отправка формы не означает доставку отклика другому пользователю.

Сценарий B: от описания до публикации

Требуется настроенный Gemini API с доступом к обеим моделям, указанным в исходном коде.

1. Запустите frontend и backend; убедитесь, что /api/health отвечает {"status":"ok"}.

2. Нажмите «Создать задачу», выберите «Экология» и введите название «Учёт пищевых остатков в столовой».

3. Вставьте тестовое описание:

   В столовой кампуса ежедневно остаётся еда, но объём списаний не фиксируется. Нужен веб-прототип для сотрудников столовой, чтобы записывать остатки по блюдам и видеть недельный отчёт. Для пилота предоставим обезличенную таблицу за неделю. Новое оборудование покупать нельзя. Ожидаемый результат — форма ввода и сводный отчёт. Критерий проверки — сотрудник может внести остатки и получить итоги за выбранную неделю. Контакт: [email protected]. Формат работы — еженедельная встреча с командой.

4. Ответьте на все вопросы каждого из трёх блоков. Формулировки зависят от модели. Если она запросит дополнительные сведения, дополните ответы в третьем блоке.

5. После получения ready: true проверьте итоговый текст и поля, внесите правку и нажмите «Подтвердить и опубликовать».

6. Проверьте появление карточки в каталоге и разделе «Мои задачи». В /api/tasks должна появиться серверная запись.

7. Удалите созданную тестовую задачу через её карточку и убедитесь, что она исчезла из /api/tasks.

Конкретный рейтинг и готовность после определённого числа ответов не гарантированы: это результат модели. Если AI-запрос завершается ошибкой, проверьте ключ, доступность моделей и логи backend. Локальной замены AI-ответов в приложении нет.

Автоматические проверки

В каталоге frontend:

npm run format:check
npm run lint
npm run typecheck
npm run build

В каталоге backend, после установки зависимостей выше:

.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe -m ruff format --check app tests
.\.venv\Scripts\python.exe -m ruff check app tests
.\.venv\Scripts\python.exe -m pytest -q

Backend-тесты проверяют три раунда, публикацию, каталог, удаление, обработку смоделированной ошибки ключа OpenAI и разбор JSON. AI-вызовы в тестах подменяются; успешный тест не подтверждает работу реального Gemini API. В существующем CI отдельная установка google-genai отсутствует.

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

• Пользовательский ввод: описание задачи, категория, ответы на уточнения, правки карточки и предложения команд.
• Демонстрационные данные: три карточки в frontend/src/features/tasks/data.ts — пищевые отходы, стажировки и полив клумб. Указанные в них показатели являются содержанием примеров, а не измеренными результатами проекта.
• Gemini API: получает описание, категорию, историю ответов и данные текущего раунда; возвращает JSON с вопросами либо готовой карточкой и рейтингом. Названия моделей заданы непосредственно в ai_service.py.
• Память backend: черновики и опубликованные задачи находятся в словарях drafts и tasks; перезапуск процесса очищает их.
• Браузер: локальные карточки и отклики хранятся под ключом iskra-tasks-v2. Данные демонстрационных карточек исключаются из сохранения.

Загрузка датасетов, подключение CRM, внешних каталогов задач или системы уведомлений в текущем коде не реализованы. Поле «Данные и материалы» содержит текст; автоматическое получение указанных материалов отсутствует.

Ограничения текущей версии

• Незавершён переход на Gemini. SDK отсутствует в requirements, обработка ошибок backend всё ещё ориентирована на OpenAI. Поэтому ошибки Gemini, включая отсутствие GEMINI_API_KEY, могут отображаться как общая ошибка HTTP 500. Код допускает резервное чтение OPENAI_API_KEY, но передаёт это значение клиенту Gemini — ключ OpenAI не заменяет ключ Gemini.
• Доступность AI-моделей требует проверки. Репозиторий подтверждает названия gemini-1.5-flash и gemini-2.5-flash, но не их доступность для конкретного ключа. Переключения модели через .env нет.
• Нет постоянного хранилища. После перезапуска backend серверные данные теряются; локальные копии могут оставаться в браузере и расходиться с сервером. Хранилище в памяти также не общее для нескольких процессов backend.
• Нет регистрации, входа и проверки прав. Интерфейс определяет собственную задачу по локальному значению автора «Вы». API удаления не проверяет владельца.
• Отклики и правки не синхронизируются. Для редактирования карточек, отправки предложений и смены их статуса серверных маршрутов нет. Полный сценарий сотрудничества между разными пользователями ещё не реализован.
• Рейтинг имеет два источника. Сервер сохраняет оценку модели, а браузер рассчитывает заполненность полей по фиксированным весам. Эти значения могут различаться; заполненность не доказывает качество или реализуемость задачи.
• Нет ограничения публикации по рейтингу 40/100. Такое условие упомянуто в прежней документации frontend, но в текущем конструкторе и API публикации оно не проверяется. Backend проверяет флаг ready.
• Три раунда — логика обычного интерфейсного сценария. Сервер принимает номер раунда от клиента и не проверяет всю последовательность; дополнительные уточнения отправляются с номером 3.
• Нет подтверждённых результатов эксплуатации. В репозитории не приведены измерения точности AI, нагрузки, числа реальных пользователей или эффективности сотрудничества.

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

Подтверждённая ссылка на опубликованное приложение в проверенных файлах репозитория не найдена. Для демонстрации используйте локальный запуск по инструкции выше.

Основание документации

README составлен по исходному коду BAITC-Hacks/hack-99d4c8fe-team, снимок ветки main: 3c650b5.

Ключевые источники: frontend/src/app/page.tsx, компоненты и библиотеки frontend/src/features/tasks/, backend/app/main.py, backend/app/schemas.py, backend/app/services/ai_service.py, файлы зависимостей, тесты и .github/workflows/ci.yml. Инструкции сверены с кодом; запуск приложения и запросы к реальному Gemini API при подготовке README не выполнялись.