that day

AI-симулятор городского управления «Аким на 5 часов». Проект помогает оценить, как решения при ограниченном бюджете влияют на районы Астаны и качество жизни жителей.

Открыть работающий сайт · Документация · Ветки и PR

Проблема и пользователи

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

Симулятор предназначен для городских управленцев, аналитиков и участников хакатона. Он позволяет сравнить варианты на синтетических данных и обосновать выбор. Игровая эстетика используется в интерфейсе; логика решений определяется датасетом.

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

Возможность	Как работает
Единый стартовый бюджет	Каждому участнику доступны собственные 100 виртуальных единиц. Расходы участников независимы
Решения по пяти направлениям	Каталог из 14 мероприятий: транспорт, экология, соцсфера, безопасность и сервисы. Можно выбрать район или городское мероприятие, изменить и удалить решение
Контроль допустимости	Проверяются бюджет, количество и уникальность мер, ограничения направлений и несовместимости. Сервер повторно проверяет отправленный сценарий
Интерактивная карта	Пять районов, достопримечательности, перемещение и масштаб. Выбор района приближает и выделяет его; «Весь город» возвращает общий вид
Изменения показателей	Справа от карты показаны 10 показателей района и его индекс до/после решений. Изменения сопровождаются короткими анимациями; в аналитике доступны диаграммы районов
Astana Quality of Life Score	Расчёт учитывает эффекты мер, задержки, синергии, доли населения и критические значения. AI не назначает баллы
AI-анализ	Структурированное объяснение сильных сторон, рисков и последствий со ссылками на факты расчёта
Рекомендации	До трёх допустимых вариантов замены одного мероприятия с приростом Score, расходами и AI-обоснованием. Вариант можно применить к плану
События на карте	Осадки, жара, сбой сервисов и ремонт улиц размещаются на районе или всём городе перетаскиванием либо кликом. До трёх событий одновременно; резерв уменьшает доступный бюджет, удаление возвращает средства
Перераспределение бюджета	Отдельный редактор сценария события позволяет заменить мероприятия и пересчитать план с учётом резерва. Есть случайный выбор события
Сравнение участников	Общий рейтинг через Redis: явная публикация с именем, личный лучший результат, равные места, выделение своей записи и страницы результатов
Краткая презентация	Просмотр и скачивание Markdown: 9 слайдов с AI, 6 расчётных/служебных слайдов при его недоступности
Сохранение и доступность	Черновик и последние отчёты сохраняются в браузере. Есть мобильная компоновка, управление картой/событиями с клавиатуры и поддержка уменьшенного движения

Правила исходного датасета: ровно пять разных мероприятий, максимум два из одного направления, сумма не более 100. Покрытие всех пяти направлений не обязательно. Доступны пять районов и горизонт моделирования восемь кварталов.

Также реализован экспериментальный API анализа отзывов: сигналы с цитатами и ограниченный пересчёт показателей. Он не имеет отдельного экрана и исключён из рейтинга.

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

1. Приложение загружает районы, показатели, мероприятия и правила из синтетического JSON.
2. На экране «Карта и решения» пользователь выбирает район и составляет план. Слева видны мероприятия и бюджет, в центре — карта, справа — показатели до/после.
3. По желанию пользователь размещает учебные события и исследует их влияние. События карты учитываются в отдельном предварительном расчёте.
4. «Рассчитать сценарий» открывает аналитику: сервер проверяет данные, пересчитывает основной план и передаёт готовые факты AI.
5. Пользователь получает Score и объяснение, сравнивает районы, применяет рекомендацию, публикует результат или формирует презентацию.

События карты не включаются в AI-анализ и рейтинг основного плана. Это отдельный эксперимент; различие обозначено в интерфейсе.

Технологии

Область	Используется в проекте
Приложение	TypeScript, Next.js 16, React 19, Node.js 22
Интерфейс	CSS, Tailwind CSS 4, SVG-карта, Lucide React, шрифт Manrope
Контракты и валидация	Zod 4, общие схемы для клиента и сервера
AI	OpenAI SDK 6, Responses API, Structured Outputs. Модель по умолчанию — gpt-5.4-mini-2026-03-17; переопределяется через OPENAI_MODEL
Хранение	JSON в репозитории, браузерный localStorage, Upstash-совместимый Redis REST для рейтинга
Проверки	Vitest, Playwright, TypeScript, ESLint
Подготовка данных и карты	Скрипты Python, сохранённая география OpenStreetMap
Размещение	Vercel; публикация через CLI

NVIDIA API в текущей реализации не используется.

Архитектура

JSON-датасет → общая расчётная модель → показатели, бюджет и Score
                     ↑                           ↓
Карта и план → API Next.js + проверка Zod → OpenAI → объяснение
                     ↓
               Redis → общий рейтинг

Клиент передаёт идентификаторы мер и районов, а не готовые цены или Score. Сервер проверяет версию каталога и рассчитывает результат самостоятельно. Для быстрого предварительного отображения интерфейс использует тот же расчётный модуль. Ключи OpenAI и Redis остаются на сервере.

Основные компоненты: src/components и src/features — интерфейс и состояние; src/app/api — серверные обработчики; src/lib — расчёты, AI и рейтинг; src/shared — контракты; dataset — входные данные.

Формула: Score = 0.7 × средний индекс города + 0.3 × минимальный индекс района − число критических значений. Средний индекс взвешен по населению; критическими считаются показатели строго ниже 40. Подробнее — модель расчёта.

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

Нужны Node.js 22 и npm. Репозиторий приватный: для клонирования требуется доступ к GitHub команды.

git clone https://github.com/BAITC-Hacks/hack-e54d9694-that-day-in.git
cd hack-e54d9694-that-day-in
git switch main
npm ci
npm run dev

Приложение откроется на http://localhost:3000. Карта, бюджет, Score и события работают без внешних ключей.

Для AI и общего рейтинга скопируйте .env.example в .env.local, если такого файла ещё нет, и заполните серверные переменные:

Переменная	Для чего нужна
OPENAI_API_KEY	AI-анализ, объяснения рекомендаций и презентации
OPENAI_MODEL	Необязательный выбор модели
UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN	Общее хранилище рейтинга
PARTICIPANT_SECRET	Подпись cookie участника; не менее 32 случайных символов

Вместо Upstash-пары поддерживается пара KV_REST_API_URL / KV_REST_API_TOKEN от Vercel Marketplace. Пары нельзя смешивать. Секреты не добавляются в Git и не используют префикс NEXT_PUBLIC_. После настройки перезапустите сервер.

Production-сборка: npm run build, затем npm run start.

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

Сценарий для жюри

1. Откройте сайт без активных событий карты.
2. Нажмите значок помощи в шапке → «Загрузить контрольный пример · 95 ед.».
3. В плане появятся M7, M8, M10 в Нуре, M12 для всего города и M5 в Сарыарке. Посмотрите показатели выбранного района до/после.
4. Нажмите «Рассчитать сценарий» и проверьте результат:

Показатель	Ожидаемое значение
Расходы / остаток	95 / 5
Исходный Score	52,55768
Итоговый Score	56,54307 — в интерфейсе 56,54
Критических значений после мер	0

5. При доступном OpenAI появится объяснение сильных сторон, рисков и последствий. Затем можно открыть рекомендации, сформировать презентацию или явно опубликовать результат в рейтинге.
6. Для проверки карты очистите план и удалите активные события. Разместите «Сильные осадки» на Нуре: резерв составит 10, показатель «Разгрузка дорог» изменится 55 → 51. Удалите событие — бюджет и показатели восстановятся.

Расширенный сценарий, включая перераспределение бюджета, — в инструкции демо.

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

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

На интегрированной версии от 23.09.2026 проходят 143 unit/API-теста и 16 браузерных сценариев. Автотесты не расходуют AI-токены: платные AI-вызовы и внешний Redis подменяются в тестах; симуляция и события проверяются отдельно. Результаты настоящих проверок внешних сервисов зафиксированы в журнале публикации.

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

• dataset/dataset.json — заранее подготовленные синтетические данные без реальных персональных данных. Районы, показатели, цены, задержки, синергии и ограничения описаны в датасете.
• OpenStreetMap — сохранённая география для карты. Внешний картографический API при использовании сайта не требуется. Источники и атрибуция ODbL — в документации карты.
• OpenAI — текстовое объяснение рассчитанных фактов через структурированные ответы. Версия датасета и ссылки на факты проверяются сервером.
• Redis — общее хранилище лучших результатов. Участник определяется подписанной cookie браузера.
• Vercel — размещение приложения и серверного API.

Ограничения

• Данные и эффекты событий синтетические; пять зон карты условные и не являются официальными административными границами. Результат не является прогнозом реального развития Астаны.
• Недоступность AI сохраняет численный результат, но текстовое объяснение отсутствует. Проверка структуры и ссылок на факты не гарантирует корректность каждой формулировки модели.
• Рекомендации ищут улучшения заменой одной меры и не гарантируют глобально лучший сценарий.
• События карты хранятся только в текущем сеансе страницы и исключены из стандартного AI-отчёта и рейтинга. Мероприятия считаются запланированными: частично выполненные проекты не моделируются.
• Полноценной авторизации нет. Другой браузер или очистка cookie создают нового участника; локальные черновики и отчёты не синхронизируются между устройствами. Без настроенного Redis общий рейтинг недоступен.
• Презентация экспортируется в Markdown; PPTX/PDF не реализованы. Для экспериментального API отзывов нет отдельного экрана.

Опубликованная версия и ветки

Демо: akim-five-hours.vercel.app. Код опубликованной сборки и выполненные проверки указаны в docs/deployment.md. Автодеплой GitHub → Vercel пока не подключён: push сам по себе сайт не обновляет.

main — основная версия для запуска и оценки. codex/ui и codex/map-studio — ветки интерфейса и карты; остальные codex/* сохраняют этапы backend и публикации. Названия и история сохранены. Точный статус включения каждой ветки и соответствующие PR — в карте репозитория.