---

Что решает ASAR

Хорошая учебная практика начинается не с красивого интерфейса, а с понятной задачи.

На практике бизнес часто описывает запрос слишком общо: без данных, ограничений, критериев успеха или ожидаемого результата. Из-за этого студенческим командам сложно оценить объём работы и предложить реалистичное решение.

ASAR превращает такое описание в готовую к работе карточку:

• AI анализирует исходный текст;
• определяет, каких сведений не хватает;
• задаёт уточняющие вопросы;
• формирует структурированную карточку без выдумывания фактов;
• бизнес вручную проверяет и подтверждает информацию;
• backend рассчитывает рейтинг готовности 0–100;
• опубликованные задачи попадают в общий каталог;
• студенческие команды отправляют предложения;
• финальное решение по команде всегда остаётся за бизнесом.

AI помогает сформулировать задачу, но не принимает бизнес-решения за человека.

---

Сквозной сценарий

Слабое описание задачи
        ↓
AI-анализ
        ↓
Недостающие сведения + уточняющие вопросы
        ↓
Ответы бизнеса
        ↓
AI формирует карточку
        ↓
Ручное редактирование и подтверждение
        ↓
Прозрачный рейтинг готовности 0–100
        ↓
Публикация в общем каталоге
        ↓
Студенческая команда выбирает задачу
        ↓
Команда отправляет предложение
        ↓
Бизнес вручную принимает / отклоняет отклик

---

Интерфейс и сценарий работы

1. Старт: бизнес описывает задачу

Пользователь начинает с обычного свободного описания. На этом этапе не требуется заранее заполнять длинную форму: достаточно выбрать тему и объяснить задачу своими словами.

Что демонстрирует экран:

• низкий порог входа для бизнеса;
• один понятный CTA — «Уточнить задачу с AI»;
• переход от неструктурированного запроса к управляемому процессу;
• возможность быстро загрузить демонстрационный пример.

---

2. AI задаёт только недостающие вопросы

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

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

Принцип: модель не должна придумывать сведения за пользователя. Если факта нет во входных данных — он остаётся неизвестным.

---

3. AI собирает редактируемую карточку

После ответов система формирует структурированную карточку.

Бизнес видит все поля и может вручную изменить любое значение перед подтверждением. Это сохраняет human-in-the-loop: AI структурирует информацию, а человек отвечает за её корректность.

Карточка включает:

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

---

4. Прозрачный рейтинг готовности

После подтверждения backend рассчитывает рейтинг задачи от 0 до 100.

Рейтинг не генерируется моделью. Это детерминированная backend-функция: пользователь видит, за какие поля начислены баллы и что ещё можно улучшить.

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

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

Уровни готовности

Баллы	Уровень
0–39	Черновик
40–69	Рабочая
70–89	Готовая
90–100	Приоритетная

Низкий рейтинг не блокирует публикацию. Его задача — показать, каких сведений не хватает и где есть потенциал роста.

---

5. Публикация задачи

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

На экране сразу видны:

• итоговый рейтинг;
• уровень готовности;
• сохранённый task_id;
• переход к опубликованной задаче;
• переход в общий каталог.

После публикации карточка становится доступна студенческим командам.

---

6. Общий каталог задач

Каталог — единая точка входа для студенческих команд.

Поддерживаются:

• сортировка по рейтингу;
• фильтрация по теме;
• фильтрация по уровню готовности;
• просмотр количества недостающих полей;
• переход к полной карточке.

Рейтинг влияет на порядок отображения, но не скрывает задачи с низкой готовностью.

---

7. Полная карточка задачи

Перед отправкой предложения команда может изучить подробную карточку и увидеть:

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

Это позволяет принять решение осознанно, а не ориентироваться только на заголовок задачи.

---

8. Предложение студенческой команды

Студенческая команда самостоятельно выбирает задачу и отправляет предложение.

Предложение содержит:

• идею решения;
• план реализации;
• предполагаемый срок;
• ссылку на прототип — опционально.

Новое предложение получает статус pending.

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

---

Архитектура

flowchart LR
    FE["React + TypeScript<br/>Create / Catalog / Task"]
    API["FastAPI<br/>Task API · Proposal API<br/>Rating · Validation · AI Service"]
    DB[("PostgreSQL<br/>tasks · teams · proposals")]
    AI["OpenAI API<br/>Structured Outputs"]

    FE -->|HTTP / JSON| API
    API --> DB
    API --> AI

Ответственность компонентов

• AI — извлекает предоставленные сведения, определяет пробелы, задаёт вопросы и формирует структурированную карточку.
• Backend — валидирует данные, хранит сущности, рассчитывает рейтинг, публикует и сортирует задачи.
• Frontend — проводит пользователя через единый пошаговый сценарий.
• Человек — редактирует и подтверждает карточку, а также принимает решение по предложениям команд.

---

Технологии

Backend

• Python 3.12
• FastAPI
• Pydantic v2
• SQLAlchemy 2
• psycopg 3
• Alembic
• PostgreSQL
• OpenAI Python SDK
• pytest

Frontend

• React
• TypeScript
• Vite
• React Router
• Native Fetch
• Tailwind CSS

Infrastructure

• Docker Compose
• GitHub
• Codex

---

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

1. Переменные окружения

Создайте локальный .env на основе .env.example:

cp .env.example .env

Минимально необходимо настроить:

OPENAI_API_KEY=
DATABASE_URL=postgresql+psycopg://postgres:postgres@postgres:5432/hackalem
VITE_API_URL=http://localhost:5137/create

OPENAI_MODEL задаётся через .env / .env.example проекта.

Секреты не должны попадать в Git.

---

2. Запуск Docker Compose

docker compose up --build

После запуска доступны:

• frontend;
• backend;
• PostgreSQL.

Проверка backend:

GET /health

Ожидаемый ответ:

{
  "status": "ok"
}

Остановка:

docker compose down

---

AI-функциональность

В MVP используются две содержательные AI-операции.

Анализ черновика

POST /api/ai/analyze-draft

AI:

1. извлекает только известные сведения;
2. определяет недостающие поля;
3. формирует минимум три уточняющих вопроса;
4. возвращает структурированный результат.

Формирование карточки

POST /api/ai/build-card

AI получает первоначальный draft и ответы пользователя и формирует карточку задачи.

Все поля остаются доступными для ручного редактирования.

---

Grounding: AI не выдумывает бизнес-факты

Ключевое правило AI-модуля:

Использовать только информацию, явно предоставленную пользователем.

Модель не должна самостоятельно придумывать:

• данные и датасеты;
• пользователей;
• сроки;
• технологии;
• ограничения;
• контакты;
• числовые показатели;
• ожидаемые результаты;
• критерии успеха.

Если сведений недостаточно, поле остаётся null.

Перед публикацией карточка всегда проходит ручную проверку и подтверждение человеком.

---

Structured Outputs

AI-модуль использует официальный OpenAI Python SDK и Structured Outputs.

Обработка ответа:

OpenAI
  ↓
Structured Output
  ↓
Pydantic validation
  ↓
Grounding validation
  ↓
API response

Сырой ответ модели не передаётся напрямую во frontend.

При невалидном structured output выполняется не более одного повторного запроса.

---

AI fallback

Для анализа черновика предусмотрен локальный fallback.

Если OpenAI API временно недоступен, система может вернуть шаблонные вопросы по незаполненным полям, не пытаясь придумывать новые бизнес-факты.

Режим можно определить по header:

X-AI-Fallback: true

Реальный ответ модели:

X-AI-Fallback: false

Fallback — режим деградации и не считается успешным live-тестом AI.

---

Каталог и предложения

Все опубликованные задачи доступны всем студенческим командам.

Команда может:

1. открыть каталог;
2. применить фильтры;
3. изучить карточку;
4. самостоятельно выбрать задачу;
5. отправить предложение.

Бизнес видит поступившие предложения и вручную выполняет одно из действий:

accepted
rejected

Можно принять одну, несколько или ни одной команды.

---

API

Ключевые endpoints:

GET  /health

POST /api/ai/analyze-draft
POST /api/ai/build-card

GET  /api/meta
GET  /api/teams

POST /api/tasks
GET  /api/tasks/{task_id}
PUT  /api/tasks/{task_id}/confirm

POST /api/rating/preview

Расширенный контракт и примеры запросов находятся в:

docs/api-contract.md
docs/api-examples.md

---

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

Тесты backend можно запускать без реального OpenAI API:

python -m pytest -c backend/pytest.ini backend/tests -q

Live AI tests запускаются отдельно и используют API-квоту.

Проверяются в том числе:

• слабое описание → вопросы → карточка;
• отсутствие выдуманных фактов;
• сохранение отрицаний вроде «данных нет»;
• отсутствие повторных вопросов по уже предоставленной информации;
• null для отсутствующих значений;
• Structured Outputs через реальные FastAPI endpoints.

---

Демонстрационный сценарий

Для защиты достаточно пройти один целостный сценарий:

1. Бизнес вводит слабое описание задачи.
2. AI возвращает минимум 3 уточняющих вопроса.
3. Бизнес отвечает.
4. AI формирует структурированную карточку.
5. Бизнес вручную редактирует поле.
6. Карточка подтверждается.
7. Backend рассчитывает рейтинг.
8. Показывается breakdown и потенциал роста.
9. Задача публикуется.
10. Она появляется в каталоге.
11. Роль переключается на студенческую команду.
12. Команда открывает задачу.
13. Команда отправляет предложение.
14. Роль переключается обратно на бизнес.
15. Бизнес вручную принимает или отклоняет предложение.

---

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

В рамках хакатона намеренно не реализуются избыточные production-функции:

• полноценная регистрация и восстановление пароля;
• сложный RBAC;
• realtime chat;
• уведомления;
• календарь;
• файловое хранилище;
• RAG / vector database;
• обучение собственной ML-модели;
• multi-agent framework;
• полноценная LMS;
• production infrastructure;
• полный project tracker.

Основной фокус — один законченный сквозной сценарий.

---

Использование Codex

Codex использовался как обязательный инструмент разработки.

Работа разбивалась на небольшие изолированные задачи, в частности:

• AI schemas;
• Structured Outputs;
• grounding validation;
• fallback-механизм;
• unit и live AI tests;
• обработка edge cases;
• анализ интеграционных ошибок;
• улучшение системного prompt;
• проверка структуры и качества кода.

Сгенерированные изменения проверялись разработчиками и автоматическими тестами.

---

Definition of Done

После:

docker compose up --build

без изменения исходного кода должен выполняться полный сценарий:

✓ открыть frontend
✓ создать черновик
✓ получить AI-вопросы
✓ ответить на вопросы
✓ получить карточку
✓ отредактировать карточку
✓ подтвердить сведения
✓ получить рейтинг 0–100
✓ опубликовать задачу
✓ увидеть её в каталоге
✓ открыть задачу от лица студенческой команды
✓ отправить предложение
✓ принять или отклонить предложение от лица бизнеса
✓ сохранить данные после перезапуска

---