KazAST-AI

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

Работает сквозной сценарий: черновик → AI-вопросы → ответы → предложение карточки → ручная проверка → подтверждение и рейтинг → публикация → отклик → выбор команды.

Реализованы API и интерфейсы конструктора, каталога с пагинацией по 12 задач, публичной карточки, «Моих задач» бизнеса и «Моих откликов» студента. AI работает через OpenAI либо явно обозначенную локальную заглушку. Подтверждение этапов работы и начисление баллов командам пока представлены только в БД.

Технический стек

Слой	Технологии	Назначение
Frontend	JavaScript, Vue 3.5, Vue Router 4, Vuex 4	Страницы, навигация, состояние и API-запросы
Сборка frontend	Vite 6, @vitejs/plugin-vue 5	Dev-сервер и production-сборка
Оформление	HTML, CSS, собственный стайл-кит	Токены, кнопки, формы и общие стили без сторонней UI-библиотеки
Backend	Node.js 22 в Docker, Express 5, ES modules	HTTP API, валидация, бизнес-операции
Доступ к БД	pg 8, параметризованный SQL	Пул соединений и транзакции; ORM не используется
База данных	PostgreSQL 16	Данные, ограничения, снимки карточек, вычисление рейтинга
Миграции	SQL-файлы и Node.js-скрипт	Транзакционное применение, контрольные суммы и блокировка запуска
Тестирование	Встроенный node:test, assert, реальный PostgreSQL	API, ограничения БД, Vuex-модули
Окружение	Docker, Docker Compose	Сервисы frontend, backend, db, постоянные volumes
AI	openai SDK 5, Responses API, Structured Outputs	Уточняющие вопросы и подготовка карточки; локальный демо-режим

Диапазоны версий указаны в frontend/package.json и backend/package.json, точные версии зависимостей зафиксированы в соответствующих package-lock.json.

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

Нужны Docker и Docker Compose. Выполняйте команды из корня проекта.

Если .env ещё нет, создайте его из шаблона; существующий файл с настройками не перезаписывайте:

cp .env.example .env

Запустите сервисы и загрузите тестовые данные:

docker compose up --build -d
docker compose exec backend npm run db:seed
docker compose exec backend npm run db:seed:catalog

• Приложение: localhost:5173.
• Каталог: localhost:5173/tasks.
• Конструктор: localhost:5173/tasks/new.
• Мои задачи бизнеса: localhost:5173/tasks/mine.
• Проверка API и соединения с БД: localhost:3000/api/health.
• PostgreSQL с хоста: 127.0.0.1:5433; внутри Compose: db:5432.

Compose ждёт готовности PostgreSQL, затем backend применяет миграции и запускает сервер. Frontend стартует после успешной проверки backend. Изменения исходников подхватываются в режиме разработки. Новые миграции применяются при запуске backend; для уже работающего контейнера выполните docker compose exec backend npm run db:migrate. Текущие миграции: 001_initial.sql (основная схема), 002_task_version.sql (версия задачи), 003_clarification_sessions.sql (раунды уточнения).

Если в существующих volumes остались старые зависимости, обновите их и пересоздайте сервисы:

docker compose run --rm --no-deps backend npm ci
docker compose run --rm --no-deps frontend npm ci
docker compose up --build -d

Обычная остановка: docker compose down. Данные БД остаются в volume postgres_data. Команда docker compose down -v удаляет volumes вместе с данными.

Настройки окружения

Переменная	Назначение
POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD	Настройки PostgreSQL в Compose; локальные значения приведены в .env.example
DATABASE_URL	Подключение Node.js к БД. Compose собирает URL с хостом db; для запуска Node на хосте нужен адрес localhost:5433
DEMO_AUTH_ENABLED	Локальный демо-доступ к операциям владельца; по умолчанию включён в Compose
VITE_API_URL	Адрес backend для браузера; в Compose — http://localhost:3000
VITE_DEMO_USER_ID	Необязательный UUID демо-пользователя фронтенда; по умолчанию первый бизнес-пользователь seed
OPENAI_API_KEY	Ключ реального AI-режима, только на backend
AI_MODE	openai или local; пустое — выбор по наличию ключа
OPENAI_MODEL	Модель Structured Outputs; по умолчанию gpt-4o-mini

Compose передаёт сервисам только переменные, перечисленные в их environment. Для переопределения VITE_DEMO_USER_ID добавьте его в frontend.environment или задайте в окружении локального Vite. Node-скрипты самостоятельно .env не загружают. Пароли со специальными символами URI нужно кодировать в DATABASE_URL.

.env исключён из Git. Ключ AI передаётся только backend, не в переменных VITE_* или исходниках.

Архитектура бэкенда

Vue-компонент → Vuex action → API-клиент → Express route
                                            ↓
                                      бизнес-сервис
                                            ↓
                                  pg Pool → PostgreSQL

• src/server.js запускает HTTP-сервер, src/app.js собирает Express-приложение, CORS, JSON-парсер и обработку ошибок.
• src/routes/ связывает HTTP-методы с сервисами и проверкой демо-пользователя.
• src/services/tasks.js валидирует поля и выполняет создание, чтение владельцем, редактирование, подтверждение и публикацию.
• src/services/proposals.js проверяет членство в команде, сохраняет отклики и решения бизнеса; src/routes/proposals.js предоставляет методы откликов и списка своих команд.
• src/services/catalog.js возвращает открытый каталог и отдельную опубликованную карточку; my-tasks.js — список собственных черновиков и публикаций.
• src/services/clarifications.js управляет раундами уточнения, сохранением ответов и предложений карточки; clarification-state.js читает последний раунд.
• src/services/clarification-ai.js содержит промпт, JSON Schema, проверку результата, OpenAI-адаптер и локальную заглушку. Внешний вызов выполняется без удержания блокировки БД; перед записью версия проверяется повторно.
• src/db/pool.js предоставляет пул PostgreSQL. Все значения в SQL передаются параметрами.
• src/middleware/demo-auth.js проверяет существование пользователя и требуемую маршрутом роль business или student. Сервисы дополнительно проверяют владельца задачи.

Редактирование, подтверждение и публикация используют транзакции и блокировку строки задачи. Клиент передаёт expected_version: устаревшая версия приводит к 409 VERSION_CONFLICT. Сохранение карточки, изменение опубликованного снимка и успешные операции уточнения увеличивают task.version. Повторное подтверждение неизменившейся карточки не создаёт новый снимок; повторная публикация текущего снимка с актуальной версией не меняет дату и версию задачи.

Доступные API

Все пути начинаются с /api. Полные тела запросов, ответы и ошибки — в backend/API.md.

Метод	Путь	Доступ и действие
GET	/health	Проверка сервера и БД
GET	/tasks	Открытый каталог: page, industry, readiness_level, по 12 задач
GET	/tasks/:id/published	Открытая опубликованная карточка
GET	/tasks/mine	Бизнес: свои задачи, фильтр status=draft/published, по 12 на странице
POST	/tasks	Бизнес-пользователь: создание черновика
GET	/tasks/:id	Владелец: рабочая копия, последнее подтверждение и последний раунд уточнения
PATCH	/tasks/:id	Владелец: частичное редактирование
POST	/tasks/:id/confirm	Владелец: подтверждение и расчёт рейтинга
POST	/tasks/:id/publish	Владелец: публикация или обновление опубликованной версии
POST	/tasks/:id/clarification/questions	Владелец: генерация и сохранение 3–8 вопросов
PATCH	/tasks/:id/clarification/answers	Владелец: сохранение ответов текущего раунда
POST	/tasks/:id/clarification/card	Владелец: подготовка предложения карточки
GET	/teams/mine	Студент: команды, в которых он состоит
POST	/tasks/:id/proposals	Студент: отправка отклика от своей команды
GET	/proposals/mine	Студент: отклики своих команд
GET	/tasks/:id/proposals	Владелец: предложения по задаче
PATCH	/proposals/:id/status	Владелец: принять или отклонить отклик

Демо-личность выбирается заголовком X-User-Id. После seed доступен UUID 00000000-0000-4000-8000-010000000001. Это не аутентификация для публичного сервера: знающий UUID может выбрать пользователя. В NODE_ENV=production демо-доступ отключается. Открытые каталог и карточки не требуют заголовка.

PostgreSQL и бизнес-данные

Таблица / представление	Содержимое и назначение
users	Пользователи с ролями business / student, без паролей
teams, team_members	Команды, интересы, навыки, технологии и участники
tasks	Исходное описание, редактируемые поля, владелец, версия и ссылка на публикацию
clarification_questions	Вопросы и ответы раундов уточнения
clarification_sessions	Раунды уточнения и предложенные карточки
task_revisions	Неизменяемые подтверждённые снимки card в JSONB, автор подтверждения и вычисляемый рейтинг
proposals	Предложения команд и статусы pending, accepted, rejected; подключены к API
progress_milestones	Подтверждённые этапы и баллы; пока только слой БД
schema_migrations	Применённые миграции, контрольные суммы и время применения
task_catalog	Представление опубликованных снимков, рейтинга, уровней и недостающих сведений
team_progress	Представление суммы баллов за подтверждённые этапы команд

Основные связи: пользователь владеет задачами; задача содержит вопросы и подтверждённые версии; отклик связывает задачу с командой; этап прогресса относится к отклику. Участники связаны с командами через team_members. Внешние ключи защищают связи; каскадного удаления нет.

Жизненный цикл карточки

1. Сохранение меняет рабочую копию в tasks.
2. Подтверждение создаёт снимок task_revisions и рассчитывает его рейтинг.
3. Публикация записывает ссылку на подтверждённый снимок в tasks.published_revision_id и дату published_at.
4. Обновление требует сохранить и подтвердить правки, затем снова опубликовать. До этого каталог показывает прежний снимок.

БД запрещает изменение подтверждённых снимков и публикацию версии другой задачи. API публикации требует совпадения текущей карточки с последним подтверждением. Нулевой рейтинг публикации не мешает. Статус публикации независим от уровня готовности draft.

Рейтинг и каталог

Рейтинг считается в PostgreSQL функциями readiness_breakdown и readiness_score, хранится вычисляемым столбцом снимка и не принимается от клиента.

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

Группа получает полный вес за непустые подтверждённые поля, иначе 0. Это проверка полноты, а не смыслового качества текста. Уровни: draft 0–39, working 40–69, ready 70–89, priority 90–100.

Каталог показывает только опубликованные версии. Порядок: рейтинг по убыванию, дата публикации по убыванию, UUID по возрастанию. Фильтры применяются до подсчёта и пагинации. Размер страницы фиксирован — 12. Слишком большой номер страницы приводит к последней доступной странице; пустой результат имеет page=1, total_pages=0.

Подробности схемы, миграций и ограничений — backend/db/README.md.

Frontend

Маршрут	Экран
/	Главная
/tasks	Каталог с фильтрами и пагинацией
/tasks/new	Создание черновика
/tasks/:id/edit	Редактор с AI-уточнением, подтверждение и публикация
/tasks/:id	Публичная карточка и форма отклика студента
/tasks/mine	Свои задачи бизнеса, статусы и счётчики откликов
/proposals	Отклики команд текущего студента
/tasks/:id/proposals	Предложения команд и решения владельца

Vuex-модули tasks, catalog, published_task, proposals, my_tasks, app_status хранят данные и состояние запросов. HTTP-запросы выполняются в actions через src/services/api.js, изменения состояния — в mutations. Постоянное хранение обеспечивает PostgreSQL; после перезагрузки данные восстанавливаются через API. Несохранённый текст формы остаётся только в памяти.

Страница редактора использует переиспользуемые поля, секции, уведомления, рейтинг, панель публикации и clarification_panel. Состояние уточнения и ответы хранятся в модуле tasks. Каталог — карточки и пагинацию; публичная страница — секции сведений. Компонентная логика находится в JS-файлах, оформление — в frontend/style/: tokens.css, controls.css, global.css. Правила разработки: FRONTEND_GUIDE.md.

Отклики и выбор команды

В шапке приложения выберите демо-роль. «Студент» использует первого студента seed и его команды, «Бизнес» — бизнес-пользователя редактора. Выбор сохраняется в sessionStorage текущей вкладки; это только демо-доступ, не полноценная авторизация. Открытие редактора задачи переключает кабинет в режим бизнеса.

В режиме студента откройте публичную карточку и заполните форму «Предложить решение»: команда, идея, план, срок и необязательная ссылка. На /proposals доступны «Мои отклики» и текущие статусы. В режиме бизнеса ссылка «Посмотреть отклики» открывает /tasks/:id/proposals; сервер разрешает просмотр и решение только владельцу задачи. Ссылка на предложения также есть в редакторе.

Кнопки «Выбрать команду» и «Отклонить» требуют подтверждения окончательного решения. Можно выбрать несколько команд; принятие не закрывает задачу. Модуль Vuex proposals хранит формы, списки, ошибки и состояния запросов. Неотправленные формы сохраняются при переходах в пределах работающего приложения, но не после перезагрузки. При неопределённом сетевом результате повторная отправка блокируется до обновления списка, чтобы пользователь мог проверить, не сохранился ли отклик.

Мои задачи бизнеса

На /tasks/mine бизнес видит собственные черновики и публикации: по 12 карточек, фильтр по статусу, рейтинги подтверждённой и опубликованной версий, отметки о неопубликованных изменениях и счётчики откликов. Из карточки можно открыть редактор, отклики или публичную страницу. Данные поступают из PostgreSQL через GET /api/tasks/mine и Vuex-модуль my_tasks; доступ использует текущий демо-механизм X-User-Id.

AI-уточнение: настройка и проверка

Режим работы

Для реального AI задайте в .env:

AI_MODE=openai
OPENAI_API_KEY=your_api_key_here
OPENAI_MODEL=gpt-4o-mini

Для локальной демонстрации без внешних запросов задайте AI_MODE=local. В этом режиме стандартные вопросы выбираются прежде всего по незаполненным полям, а ответы копируются дословно; смыслового анализа описания нет. Интерфейс показывает «Локальный демо-режим» после получения вопросов.

При пустом AI_MODE backend выбирает OpenAI, если ключ задан, иначе local. Ошибка OpenAI не переключает приложение на заглушку автоматически. После изменения .env пересоздайте backend:

docker compose up -d --force-recreate backend

В OpenAI отправляются сохранённое описание, поля карточки и ответы. Ключ остаётся на сервере. Промпт запрещает выдумывать факты, неизвестные сведения должны оставаться пустыми. Сервер проверяет структуру ответа; фактическую точность проверяет пользователь. Промпт и схемы — в clarification-ai.js, контракты — в API.md.

Ручная проверка

1. Откройте /tasks/new и введите: «Заявки клиентов теряются в переписке. Хотим собирать их в одном месте и отслеживать обработку».
2. Нажмите «Создать черновик», затем «Получить вопросы». Ожидается 3–8 уточняющих вопросов.
3. Ответьте на известные вопросы и нажмите «Сохранить ответы». Перезагрузите страницу: ответы должны восстановиться. Для подготовки карточки достаточно одного непустого ответа.
4. Нажмите «Подготовить карточку». Должен появиться предпросмотр; рабочие поля, рейтинг и публикация ещё не меняются. Проверьте, что неизвестные контакты, сроки и материалы не выдуманы.
5. Нажмите «Перенести в форму», при необходимости исправьте текст. Он остаётся несохранённым до нажатия «Сохранить изменения».
6. Нажмите «Подтвердить карточку»: рейтинг рассчитывается по заполненным подтверждённым полям. После этого отдельно нажмите «Опубликовать» и проверьте карточку в каталоге.
7. Для продолжения сквозного сценария перейдите в каталог, переключите демо-роль на «Студент» и отправьте отклик. Вернитесь в «Бизнес», откройте «Мои задачи» → «Отклики» и выберите либо отклоните команду.

Сохранённые ответы и предложение хранятся в PostgreSQL. Новые вопросы создают новый раунд, прежние записи остаются в БД; интерфейс показывает последний раунд. Изменение рабочей карточки делает прежний раунд устаревшим: для следующего уточнения получите новые вопросы. Правки ответов сбрасывают ранее подготовленное предложение. AI не подтверждает и не публикует задачу автоматически.

Диагностика

В DevTools → Network смотрите ответ запроса clarification/questions, clarification/answers или clarification/card.

Ошибка	Что делать
AI_NOT_CONFIGURED	Проверить AI_MODE и наличие ключа на backend, пересоздать контейнер
AI_UNAVAILABLE	Проверить доступ к API, ключ, модель и лимиты; повторить позже
AI_INVALID_RESPONSE	Модель вернула неправильный, незавершённый ответ или отказ; повторить запрос
VERSION_CONFLICT	Сохранить копию несохранённого текста и загрузить актуальную задачу
CLARIFICATION_STALE	Получить новый раунд вопросов для текущей карточки
ANSWERS_REQUIRED	Сохранить хотя бы один непустой ответ
NETWORK_ERROR	Проверить доступность backend; перед повтором проверить сохранённую задачу

Вызов модели ограничен 45 секундами без автоматических повторов; frontend ждёт до 60 секунд. Ошибка генерации не меняет сохранённые ответы или карточку. /api/health проверяет сервер и БД, но не соединение с OpenAI. Состояние сервисов и журналы доступны командами:

docker compose ps
docker compose logs --tail=100 backend

Демо-данные и проверки

• db:seed создаёт 5 бизнес-пользователей, 5 студентов, 5 команд, 6 исходных описаний, 5 опубликованных карточек, 15 вопросов и 5 откликов.
• db:seed:catalog добавляет 24 опубликованные синтетические задачи с разными темами и рейтингами. Вместе с базовым seed это 29 карточек: страницы 12 / 12 / 5. Пользовательские и ручные тестовые задачи увеличивают это количество.
• Seed-скрипты используют фиксированные UUID и допускают повторный запуск без дубликатов. Расширенный seed не изменяет существующие задачи.

docker compose exec backend npm run test:db
docker compose exec backend npm run test:api
docker compose exec frontend npm test
docker compose exec frontend npm run build

Проверки БД выполняются с откатом тестовой транзакции. API-тесты создают отдельные схемы PostgreSQL и удаляют их после выполнения; пользователю БД нужно право создания схем. Проверяются права владельца, конфликты версий, публикация и обновление снимков, каталог, фильтры и пагинация. Дополнительно проверяются AI-контракты, ошибки модели, сохранение ответов, устаревшие раунды и отсутствие автоматической публикации. Frontend-тесты проверяют Vuex-сценарии, ручное применение предложения и обработку устаревших ответов. Автотесты AI используют локальный адаптер и подменённые ответы, не требуют ключа и не обращаются к платной модели; реальное соединение проверяйте ручным сценарием выше.

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

backend/
  src/
    app.js, server.js
    routes/                 HTTP-маршруты
    services/               Бизнес-операции и каталог
    middleware/             Демо-доступ
    db/                     Пул PostgreSQL
  db/migrations/            SQL-миграции
  db/README.md              Схема и правила хранения
  scripts/                  Миграции и seed-данные
  test/                     Проверки API и БД
  API.md                    Контракт API
frontend/
  src/
    pages/, components/     Экраны и переиспользуемые элементы
    router/                 Маршруты
    store/modules/          Vuex
    services/               HTTP-клиент
    domain/                 Описание полей и критериев
  style/                    Общий CSS-пакет
  test/                     Проверки Vuex
compose.yaml                Локальное окружение
.env.example                Шаблон настроек

Что осталось

• Прогресс команд: API и интерфейс добавления результата этапа, подтверждения бизнесом и начисления баллов. Таблицы progress_milestones и представление team_progress уже есть; пользовательский сценарий ещё не подключён.
• Подготовка сдачи: выбрать один демонстрационный пример и отрепетировать сквозной сценарий до 5 минут.

Полноценная регистрация, восстановление пароля, чат, уведомления, файловое хранилище и производственная инфраструктура не входят в обязательный объём хакатонного MVP. Текущий X-User-Id предназначен для локальной демонстрации; перед публичным запуском потребуется настоящая аутентификация.