Аким на 5 часов

Хакатон-проект команды Datalicious — интерактивный симулятор управления городом на примере Астаны. Пользователь распределяет 100 условных единиц бюджета между пятью решениями и видит, как меняются качество жизни и положение районов. AI-агент может искать альтернативные наборы решений, проверяя каждый настоящим расчётным движком.

Текущая объединённая версия находится в ветке main. Расчёт и локальное объяснение работают без OpenAI и без API-ключа. Агент подключён к интерфейсу и проверен с подменённым провайдером; успешный запуск с реальной моделью пока не подтверждён.

Для кого и какую проблему решает

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

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

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

• Интерактивная 3D-карта с роботизированным указателем, выбором районов и демонстрацией выбранных работ. При недоступности WebGL остаётся выбор кнопками.
• Профили пяти расчётных районов, десять показателей, выделение значений ниже 40.
• Каталог M1–M14: направления, стоимость, районный/городской охват, лаг и эффекты.
• Пять слотов решений, бюджет и остаток, контроль повторов, конфликтов и лимита двух мер одного направления. Невалидный набор не получает Score.
• Детерминированный расчёт: итоговый Astana Quality of Life Score, изменение относительно базы, оценки районов и показатели до/после, критические значения, ухудшения, реализованные эффекты решений и сработавшие синергии.
• Сохранение и восстановление одного плана в localStorage текущего браузера.
• Два явных действия: «Получить локальное объяснение» и «Запустить AI-агента». Локальный ответ подписан «Локальное объяснение — без AI».
• Загрузка, ошибки и отсутствие настроек AI, блокировка повторной отправки, отмена и игнорирование устаревших ответов при смене сценария.
• Русскоязычный адаптивный интерфейс, клавиатурное управление и поддержка предпочтения уменьшенной анимации (prefers-reduced-motion).

Как работает решение

1. Пользователь изучает район и выбирает мероприятия. Для районной меры указывает район; городская применяется ко всем пяти расчётным районам.
2. Общий доменный модуль проверяет набор: ровно пять разных мер, стоимость не выше 100, максимум две одного направления, соблюдение несовместимостей. Покрывать все пять направлений не обязательно.
3. Кнопка «Запустить план» вызывает настоящий движок. После десятисекундной демонстрации, которую можно пропустить, открывается результат. Анимация не рассчитывает эффективность и не означает выполнение реальных работ.
4. По отдельной кнопке UI отправляет только решения и режим в POST /api/analyze. Сервер заново проверяет сценарий и вычисляет результат по исходному датасету: клиентские стоимость и Score не принимаются на веру.
5. В режиме local сервер формирует объяснение по правилам без обращения к модели. В режиме agent модель предлагает варианты, а сервер проверяет их движком. Ответ содержит объяснение, риски, последствия и рекомендации.

Агент использует инструменты get_city_context, evaluate_scenario и compare_scenarios. Он выбирает меры и районы, получает результаты проверок и может исправлять невалидные предложения. Итог ссылается только на лучший проверенный сценарий, включая исходный; если улучшение не найдено, это явно сообщается. Числа и текстовый отчёт формируются сервером из проверенных фактов, а не из свободных числовых утверждений модели.

Альтернатива не заменяет план автоматически: её можно перенести вручную и пересчитать. Открытие страницы, изменение полей и обычный расчёт AI не запускают.

Технологии

• Next.js 16, App Router, React 19, TypeScript — приложение и серверный маршрут.
• Tailwind CSS 4 и CSS — оформление; Three.js — 3D-карта, робот и анимация.
• Zod 4 — проверка входных данных, конфигурации и ответов.
• Официальный OpenAI SDK 6, Responses API — серверный агент с вызовом инструментов. Модель задаётся через OPENAI_MODEL; фиксированной модели и модели по умолчанию нет.
• Vitest, React Testing Library, Playwright, ESLint — проверки кода и интерфейса.
• npm и package-lock.json — воспроизводимая установка зависимостей.

Recharts установлен в проекте, но графики на нём в текущем интерфейсе не реализованы. Точные версии зависимостей зафиксированы в package-lock.json. Python и Shapely нужны только для отдельных скриптов обновления геоданных, не для запуска приложения.

Архитектура

Модуль	Ответственность
src/data/dataset.ts	Типизированный датасет организаторов, каталог и параметры модели
src/domain	Чистые валидация и расчёт; публичный simulationEngine, единая реализация правил и Score
src/domain/types.ts	Общие контракты сценария, результата, объяснения и HTTP
src/components/city	3D-сцена, районные панели, выбор и сохранение плана
src/components/simulator	Результаты расчёта, таблицы и запрос объяснения
src/server	Локальный генератор, AI-агент, инструменты, проверка ответов и ограничения запуска
src/app/api/analyze/route.ts	POST /api/analyze: HTTP-оболочка, повторный серверный расчёт и выбранный режим анализа
tests/domain, e2e	Доменные и сквозные проверки; компонентные/серверные тесты расположены рядом с кодом

UI и сервер используют один расчётный модуль. Домен не зависит от React, Next.js, OpenAI или переменных окружения. SDK доступен только серверным модулям, защищённым server-only; секреты в браузер не передаются.

Контракт запроса — { scenario, mode?: "local" | "agent" }, успеха — { ok: true, result, analysis, source }. Если mode не указан, используется agent; для бесплатной проверки нужно явно выбрать local. Ошибки формы дают 400, нарушения правил — 422, отсутствие настроек агента — 503, сбой агента — 502, внутренняя ошибка — 500. Ошибки не подменяются локальным успехом. Полный контракт и точки подключения: AI_INTEGRATION.md.

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

Нужны Node.js ≥22.12.0, npm и Git. База данных и ключ картографического сервиса не требуются. В Windows PowerShell при запрете запуска .ps1 используйте npm.cmd и npx.cmd вместо npm и npx.

Запуск без OpenAI

git clone --branch main https://github.com/BAITC-Hacks/hack-497ca5e1-datalicious.git
cd hack-497ca5e1-datalicious
npm ci
npm run dev

Откройте http://localhost:3000. Для расчёта и локального объяснения .env.local создавать не нужно.

Если репозиторий уже клонирован, сначала сохраните свою работу, затем выполните git fetch origin, git switch main и git pull --ff-only origin main. Если локальная история разошлась с общей, сначала согласуйте её объединение с командой. Установка зависимостей остаётся той же: npm ci.

Необязательное подключение AI-агента

Если .env.local ещё нет, создайте его на основе .env.example. Заполните OPENAI_API_KEY своим ключом и OPENAI_MODEL точным идентификатором доступной вам модели. Код использует Responses API, вызов инструментов и структурированный финальный ответ; совместимость выбранной модели нужно проверить. Перезапустите сервер после настройки.

Не коммитьте .env.local, не присылайте ключ в чат и не используйте для него префикс NEXT_PUBLIC_. Текущий агент допускает только endpoint https://api.openai.com/v1; произвольный совместимый шлюз не поддержан.

Кнопка «Запустить AI-агента» может расходовать API-токены. Перед живой проверкой согласуйте модель, тариф и допустимые расходы. Обычный HTTP-маршрут ограничивает цикл шестью ответами модели, двенадцатью инструментальными вызовами и 45 секундами, но не задаёт денежного потолка. Отдельная серверная функция runLiveAgentCheck требует бюджетную политику; она не вызывается кнопкой UI и не является готовой CLI-командой. Подробности — в инструкции AI-интеграции.

Production-запуск локально

npm run build
npm start

Приложение использует серверный API-маршрут, поэтому для полного сценария нужен работающий Next.js-сервер, а не только статическая раздача HTML.

Сценарий проверки для жюри

Можно пройти полностью бесплатно, без настройки OpenAI.

1. Откройте приложение и выберите следующие пять мер через районные панели и фильтры направлений:

   Район / охват	Направление	Мера	Стоимость
   Нура	Соцсфера	M7 — школа + детсад	24
   Нура	Соцсфера	M8 — центр семейного здоровья / поликлиника	20
   Нура	Безопасность	M10 — освещение и камеры	12
   Весь город	Сервисы	M12 — единая цифровая платформа обращений	14
   Сарыарка	Экология	M5 — перевод частного сектора на чистое топливо	25

2. Проверьте бюджет: 95 из 100, остаток 5. Нажмите «Запустить план»; дождитесь демонстрации или нажмите «Пропустить анимацию».

3. В результате должны быть исходный Score 52,55768, итоговый 56,54307, изменение +3,98539. Критических показателей: 2 → 0. Самый слабый район — Нура с оценкой 52,9625; срабатывает синергия M10 + M12.

4. Раскройте Нуру в «Районы и показатели до / после»: S1 меняется 38 → 48, S2 — 35 → 43,75. Эти числа рассчитаны доменом, не моделью AI.

5. Нажмите «Получить локальное объяснение». Должны появиться заголовок «Локальное объяснение — без AI», итог, сильные стороны, риски, последствия и рекомендации.

6. Нажмите «Вернуться к городу», сохраните план, перезагрузите страницу и нажмите «Восстановить». Удалите одну меру: запуск неполного плана должен стать недоступен.

Это исходный пример из датасета организаторов. Отрицательные эффекты тоже учитываются: отсутствие ухудшений именно в этом примере не означает, что все мероприятия всегда улучшают каждый показатель.

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

npm test
npm run lint
npm run typecheck
npm run build
npx playwright install chromium
npm run test:smoke

typecheck генерирует типы Next.js перед проверкой TypeScript. Smoke требует предварительной сборки; Playwright сам поднимает production-сервер на 127.0.0.1:3100. Этот порт должен быть свободен. Установка Chromium нужна один раз для окружения.

Подтверждённая проверка интеграционной версии от 23 сентября 2026: 244 теста Vitest в 17 файлах, 5 тестов Playwright, lint, typecheck и build прошли успешно. Проверяются правила и контрольные числа, компонентные состояния, серверная валидация, агентный протокол, ошибки, сохранение плана, мобильная вёрстка и работа без WebGL.

Успешный Playwright-сценарий использует настоящий сервер, движок и локальный генератор — без подмены успешного ответа. Отдельный UI-тест ошибки подменяет HTTP 500. В тестах агента провайдер подменён; платные запросы не выполняются. Эти проверки не подтверждают работу с реальным OpenAI.

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

Симуляция: материалы организаторов — Описание кейса.txt и Датасет районов.txt. В src/data/dataset.ts находится версия organizers-v1: пять районов, десять показателей и четырнадцать мер. Данные синтетические, без персональной информации. Бюджет, веса населения, эффекты, лаги, конфликты и синергии заданы этим датасетом. Горизонт расчёта — восемь кварталов; Score учитывает средний результат, самый слабый район и критические значения строго ниже 40. Подробная формула и правила — в DATASET.md, реализация — в домене.

Карта: локальный снимок OpenStreetMap от 23.09.2026 в src/components/city/geodata/astana.json. Атрибуция: © OpenStreetMap contributors, ODbL 1.0. Во время работы интерфейса картографические API не вызываются. На карте шесть контуров, но в расчёте остаются пять районов организаторов: для Сарайшыка нет выдуманных показателей и выбора мер. Байконыр на карте соответствует Байконуру (baikonur) в датасете.

AI: единственная внешняя интеграция анализа — OpenAI, используемый только сервером в режиме agent. В режиме local приложение использует собственный генератор объяснений без модели. Сценарии сохраняются в браузере, не в базе данных.

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

• Реальный OpenAI ещё не проверен; качество поиска и расходы живой модели не подтверждены. Агент не гарантирует улучшение или глобально оптимальный набор.
• Локальное объяснение не является AI-агентом и не выполняет поиск альтернатив.
• Альтернатива передаётся текстом; структурированного применения одной кнопкой нет.
• Нет пользовательского сравнения двух сохранённых сценариев, PDF-экспорта, рейтинга команд и графиков Recharts. Сохранение ограничено одним планом в браузере.
• 3D-дома, робот и демонстрационные действия условные. Геометрия OSM не является подтверждённым официальным кадастровым слоем, а анимация — планом строительства.
• Приложение — хакатон-прототип: в текущем API нет аутентификации и ограничения частоты запросов между пользователями. Перед публичным доступом к платному AI нужны дополнительные меры защиты и контроля расходов.

Публичная демоверсия

Подтверждённая ссылка на deployed-версию в репозитории не указана. Воспроизводимый способ проверки сейчас — локальный запуск по инструкции выше.

Документация проекта

• Кейс и критерии оценки.
• Датасет, правила, формула и контрольный пример.
• Актуальная интеграция UI, движка и AI; HTTP и проверки.
• Происхождение геоданных и устройство 3D-демонстрации.
• Архитектурные границы, план команды, правила разработки.

В ранних документах сохранились исторические отметки «каркас», HTTP 501 и «API ещё не подключён». Для текущего состояния интеграции ориентируйтесь на этот README, docs/AI_INTEGRATION.md и код; требования организаторов и исходный датасет остаются обязательными.