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

Учебный симулятор распределения городского бюджета Астаны с объяснением результатов через AI.

Открыть deployed-версию · Проверить состояние API

О проекте

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

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

Данные синтетические. Это демонстрационная модель, а не прогноз развития Астаны и не инструмент принятия реальных бюджетных решений. Числа рассчитывает детерминированный движок; языковая модель выбирает значимые факты для объяснения.

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

Модуль населения и «Пульс города»

Три уровня симуляции: агрегаты на 1 550 000 жителей, Canvas-рой из 1 550 потоков масштаба 1:1000 и 60 персонажей с фокус-группой из 30. Чистая математика считает стресс мостов, школ и теплосетей; сервер получает короткие мнения только затронутых жителей одним кешируемым LLM-запросом. Архитектура, код, JSON и запуск демо.

«Карта Астаны» — GIS-атлас

Новая вкладка /#/astana-map: реальная география OpenStreetMap / OpenFreeMap, улицы и здания в 2D/3D, переключаемые слои, 500 объектов образования и медицины, поиск и карточки объектов. Слои deck.gl показывают точки или плотность инфраструктуры; можно импортировать и экспортировать GeoJSON. Прежние режимы сохранены. Снимок инфраструктуры датирован 1 июня 2026 года; полнота OSM и оценочные высоты не заменяют официальный городской реестр. Возможности, источники и обновление.

Навигация и оформление

В классическом режиме рабочая область разделена на «Решения и бюджет», «Карты города», «Аналитику» и «Запросы районов». Аналитика объединяет показатели по пяти направлениям и показывает исходные значения, результат и изменение. В цифровом двойнике отдельно доступны город и проекты, бюджет и динамика, сценарии и события. Переключение разделов сохраняет выбранные меры и настройки.

Переключатель в верхней панели мгновенно меняет светлую и тёмную тему; предпочтение сохраняется в браузере. Язык интерфейса выбирается рядом. Географические 3D-сцены и транспортная мини-карта сохраняют ночную палитру для читаемости линий и маркеров.

При первом посещении короткое знакомство проводит через выбор района, проблемы, пяти мер и просмотр результата. Его можно пропустить; завершение и пропуск запоминаются в браузере. Кнопка «Как начать» открывает знакомство повторно, сохраняя текущий план. Графики показывают короткую подсказку при наведении, фокусе с клавиатуры или касании; Escape закрывает подсказку.

«Симулятор города» — цифровой двойник

Режимы связаны: выберите пять допустимых мер в «Акиме на 5 часов», перейдите в симулятор и нажмите «Принять пять решений в городе». Набор применяется один раз за городской сценарий, включая районные и общегородские последствия и синергии. Черновик можно редактировать независимо от уже принятого набора; для другого набора сохраните снимок города и начните новый сценарий.

Перенос использует явные учебные правила: стоимость умножается на 10 у.е. и списывается сразу, задержка в кварталах умножается на 3 месяца. При вводе среднее двух эффектов каждого направления изменяет состояние системы, включая отрицательные значения; синергия срабатывает после ввода обеих мер. Показатели ограничены диапазоном 0–100. Затем последствия развиваются через обычную модель износа, нагрузки и роста населения. Это другая формула, чем итоговый Score классического режима. Экспериментальные кризисы не переносятся. Сроки, принятый набор и защита от повторного списания сохраняются в черновике и снимках.

По адресу /#/digital-twin доступен симулятор на 60 месяцев: шесть районов, пять взаимосвязанных систем, строительство проектов, финансирование, сезонность и дефицит бюджета. Карта со слоями, графики и журнал показывают последствия решений относительно базового варианта. Есть автосохранение и отдельная библиотека снимков. Данные синтетические; реальная география и внешние источники не подключены. Модель, формулы и инструкция.

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

• В «Аналитике» доступен план на три года: график Astana Quality of Life Score, расходы и остаток бюджета по годам, показатели районов и AI-анализ выбранного года. Правила годового расчёта.
• Каталог 14 мер по пяти направлениям с ценой, эффектами и задержкой реализации.
• Выбор районных и общегородских мер: 100 условных единиц бюджета, ровно пять решений, не более двух мер одного направления.
• Проверка бюджета, повторов, назначения района и несовместимых решений с объяснением ошибок.
• Модель пяти районов: Есиль, Алматы, Сарыарка, Байконур и Нура; десять показателей качества жизни.
• Расчёт Astana Quality of Life Score, прироста относительно исходного состояния, среднего результата города, оценки слабейшего района и критических показателей.
• Интерактивная схематическая карта районов и показатели до/после выбранных мер.
• Учёт задержек на горизонте восьми кварталов, отрицательных эффектов и трёх синергий между мерами.
• Серверный AI-анализ: резюме, сильные стороны, риски, последствия для районов, рекомендации и необязательный вопрос советнику.
• Явно обозначенный анализ по правилам при отсутствии ключа или сбое модели; числовой расчёт остаётся доступен.
• Пометка устаревшего анализа при изменении сценария и защита от подмены актуального ответа поздним ответом на старый запрос.
• Кнопка «Эталон ТЗ» для воспроизводимой демонстрации и сброс выбранных решений.
• Автосохранение незаконченного черновика и открытого района, личная библиотека именованных сценариев в браузере.
• Таблица результатов и подробное сравнение двух сохранённых вариантов: решения, бюджет, районные оценки и десять показателей выбранного района.

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

На первом экране пользователь выбирает район и одну из трёх его наиболее слабых исходных сторон. Каталог фильтруется по положительному влиянию на выбранный показатель; районные меры по умолчанию адресуются выбранному району. Фильтр можно снять, а район отдельной меры — изменить перед добавлением.

В карточках показаны названия показателей и вклад меры за восемь кварталов с учётом задержки, до синергий и ограничения диапазоном 0–100. После пяти допустимых решений блок пути показывает рассчитанные изменения выбранного района, оставшиеся критические показатели и переход к сохранению и сравнению вариантов. После сохранения можно вернуться к мерам и подготовить второй вариант, не меняя первый снимок.

1. Пользователь открывает приложение без регистрации. При первом посещении доступно 100 у.е., выбрано 0 из 5 решений; при повторном — восстанавливается последний черновик.
2. Выбирает меры из каталога. Для районной меры указывает район; общегородская применяется ко всем пяти районам.
3. Валидатор проверяет ограничения при добавлении. До полного допустимого набора интерфейс показывает исходные показатели, итоговый Score ещё не рассчитан.
4. После пяти допустимых решений движок рассчитывает последствия: обновляет показатели, районные оценки и общий Score.
5. Пользователь изучает карту и изменения показателей, затем нажимает «Получить AI-анализ», при необходимости указав вопрос.
6. Сервер повторно проверяет и рассчитывает сценарий, формирует доказанные факты и передаёт их модели. Модель выбирает и ранжирует идентификаторы фактов; сервер проверяет ответ и собирает текст из подготовленных утверждений.
7. Пользователь меняет решения, сравнивает новый результат с исходным и обновляет анализ.
8. В окне «Сценарии» сохраняет готовые варианты с названием, загружает их или выбирает пару A/B для подробного сравнения.

Черновик и библиотека сценариев

Текущие решения (в том числе неполный набор) и открытый район автоматически сохраняются в localStorage. После обновления страницы работа продолжается с того же места. AI-ответы, вопросы советнику, таймер и экспериментальные кризисы не сохраняются.

Чтобы сохранить отдельный вариант, выберите пять допустимых решений, откройте «Сценарии», введите название и нажмите «Сохранить сценарий». Каждое сохранение создаёт независимый снимок; одинаковые названия допустимы. Последующие изменения черновика не меняют этот снимок. При активных кризисах сохранение именованного варианта недоступно: сначала отключите события.

Загрузка сохранённого сценария или эталона заменяет текущий черновик и отключает кризисы. Сброс очищает черновик, сохраняя библиотеку; удаление записи из библиотеки не меняет открытый сценарий. Загрузка также помечает предыдущий AI-анализ устаревшим и отменяет незавершённый запрос.

В таблице сценарии упорядочены по точному Score, при равенстве сначала идут более новые. Для подробного сравнения выберите два разных варианта A и B. Разницы показывают B − A. Снижение числа критических показателей считается улучшением; разница расходов показана нейтрально, поскольку остаток бюджета не даёт бонуса к Score. Ниже доступны выбранные меры, оценки всех районов и показатели выбранного района.

В хранилище записываются только решения и метаданные, а все показатели пересчитываются текущим движком. Повреждённые записи пропускаются с уведомлением. Если браузер запрещает хранение или место исчерпано, приложение продолжает работать в памяти и предупреждает, что изменения могут не сохраниться после перезагрузки.

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

Правила и формула

Каждую меру можно выбрать только один раз, даже для разных районов. Необязательно брать по одной мере из каждого направления. Остаток бюджета не даёт бонуса и не штрафуется.

Несовместимости:

Пара мер	Ограничение
M1 — автобусные полосы и M3 — ЛРТ	Нельзя сочетать независимо от района
M4 — парк и M7 — школа/детсад	Нельзя сочетать в одном районе
M5 — чистое топливо и M13 — модернизация сетей	Нельзя сочетать в одном районе

Расчёт основной версии без экспериментальных событий:

I'[d,k] = clip(I[d,k] + Σ(effect[m,k] × (8 − lag[m]) / 8) + synergy[d,k], 0, 100)
D[d]    = Σ(weight[k] × I'[d,k])
D_avg   = Σ(populationShare[d] × D[d])
Score   = 0.7 × D_avg + 0.3 × min(D[d]) − N_crit

Здесь d — район, k — показатель, m — применимая к району выбранная мера; lag — задержка в кварталах. clip ограничивает показатель диапазоном 0–100. Чем больше показатель, тем лучше. N_crit — количество пар «район × показатель» со значением строго ниже 40. Промежуточные значения не округляются.

Синергии добавляются без уменьшения на лаг: M1+M2 даёт +2 к T1 в районе M1; M10+M12 — +2 к B1 в районе M10; M5+M6 — +2 к E2 в районе M5.

Технологии

Слой	Используется в репозитории
Язык	TypeScript, HTML, CSS
Интерфейс	React 19, React DOM, собственные CSS-стили и SVG, Lucide React, clsx
Разработка и сборка	Vite 6, TypeScript 5, esbuild, tsx, concurrently, npm
Сервер	Node.js 22.12+, Express 5, dotenv
AI	Официальный пакет openai; модель по умолчанию gpt-4o-mini
API модели	OpenAI Responses API со Structured Outputs; при заданном baseURL — совместимый Chat Completions API в JSON-режиме
Тесты	Vitest, Testing Library, jsdom, Supertest
Развёртывание	Docker, Docker Compose, конфигурация Render в render.yaml
Шрифты	Google Fonts: Plus Jakarta Sans и JetBrains Mono

Версии зависимостей задаются в package.json, точные версии установки — в package-lock.json. Собственное обучение модели в проекте не реализовано.

Архитектура

Браузер: React
  ├─ каталог и исходные данные (src/data)
  ├─ общий валидатор и симулятор (src/engine) → карта, показатели, Score
  └─ POST /api/analyze: решения + необязательный вопрос
       ↓
Express API
  ├─ повторная валидация и расчёт тем же движком
  ├─ подготовка контекста, фактов и проверенных вариантов одной замены
  ├─ вызов LLM → проверка выбранных идентификаторов → сборка объяснения
  └─ резервный анализ по правилам при недоступности LLM
       ↓
Ответ: simulation + analysis + source + необязательный answer

Путь	Назначение
src/App.tsx, src/components/	Состояние сценария и пользовательский интерфейс
src/data/	Районы, показатели, меры, синергии, несовместимости и экспериментальные события
src/engine/validator.ts	Общие ограничения входных данных и решений
src/engine/simulator.ts	Расчёт показателей и Score
src/engine/optimizer.ts	Поиск вариантов замены мер для улучшения сценария
src/scenarios/	Проверка и локальное сохранение черновика и библиотеки сценариев
src/ai/	HTTP-клиент, актуальность запросов и анализ по правилам
server/app.ts, server/index.ts	HTTP-маршруты, запуск сервера и раздача production-сборки
server/context.ts, server/facts.ts, server/analysis.ts	Контекст, проверенные факты, вызов и проверка ответа модели
tests/	Тесты расчётов, валидации, фактов, API и UI
Dockerfile, docker-compose.yml, render.yaml	Контейнеризация и конфигурация размещения

В разработке Vite проксирует /api на Express. В production один Express-сервер обслуживает API и статические файлы из dist/; серверная сборка находится в dist-server/. Серверная база данных не используется: черновик и библиотека находятся в состоянии React и сохраняются в отдельных версионированных записях localStorage.

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

Локальная разработка

Требуются Node.js 22.12 или новее и npm. Скачайте репозиторий и откройте терминал в его корневой папке.

1. Установите зависимости:

   npm ci
   

2. Создайте файл окружения, если его ещё нет. Для PowerShell:

   Copy-Item .env.example .env
   

   Для Linux/macOS:

   cp .env.example .env
   

   Существующий .env не перезаписывайте. Для первого запуска ключ не нужен: симулятор и анализ по правилам работают без него.

3. Запустите интерфейс и API одной командой:

   npm run dev
   

4. Откройте интерфейс. API доступен на порту 3001. Для остановки нажмите Ctrl+C.

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

Переменная	Значение по умолчанию	Назначение
OPENAI_API_KEY	Пусто	Серверный ключ для вызова модели
OPENAI_MODEL	gpt-4o-mini	Имя модели
OPENAI_BASE_URL	Не задано	Альтернативный совместимый endpoint; включает ветку Chat Completions
HOST	127.0.0.1	Адрес привязки API; в контейнере — 0.0.0.0
PORT	3001	Порт API; также используется Vite для проксирования
VITE_ENABLE_EXPERIMENTS	false в примере окружения	Показ экспериментальных функций; учитывается при запуске Vite или сборке

Для OpenAI заполните OPENAI_API_KEY в .env и перезапустите сервер. Ключ остаётся на сервере: не помещайте его в переменные VITE_* и не коммитьте .env.

В сервере также предусмотрены NVIDIA_API_KEY, NVIDIA_BASE_URL, NVIDIA_MODEL, а для ключа и адреса — BREV_API_KEY, BREV_BASE_URL. В .env.example есть пример NVIDIA endpoint и модели meta/llama-3.1-70b-instruct. Это настройка совместимого провайдера, а не подтверждение его доступности или подключения на деплое.

При использовании этих альтернатив удалите неиспользуемые OPENAI_API_KEY и OPENAI_BASE_URL: даже пустые значения этих переменных имеют приоритет перед альтернативами. Для NVIDIA_MODEL также уберите заданный в примере OPENAI_MODEL=gpt-4o-mini или явно укажите нужную модель в OPENAI_MODEL.

Лимит ожидания модели — 20 секунд, автоматические повторы SDK отключены. В ветке Responses API передаётся store: false. При ошибке, таймауте или непрошедшем проверку ответе сервер возвращает анализ по правилам с причиной переключения. Реальное использование LLM подтверждается полем source: "llm"; llmConfigured: true в health-check означает только наличие настроенного провайдера.

Production-сборка

npm run build
npm start

После сборки интерфейс и API доступны на http://127.0.0.1:3001. Команда npm run preview запускает только просмотр фронтенд-сборки без API; для полного приложения используйте npm start.

Docker

При установленном Docker с Compose:

docker compose up --build

Откройте http://localhost:3001. Compose допускает запуск без .env; для AI укажите серверные переменные окружения.

Альтернативный запуск образа вручную, при наличии .env:

docker build -t akim-astana-simulator .
docker run --rm -p 3001:3001 --env-file .env akim-astana-simulator

Render

Опубликованная версия: fiveh-akim.onrender.com — адрес предоставлен автором проекта.

В render.yaml описан Docker Web Service с планом free, HOST=0.0.0.0, PORT=10000 и проверкой /api/health. Для развёртывания своего экземпляра подключите репозиторий как Blueprint в Render. При необходимости задайте OPENAI_API_KEY, OPENAI_MODEL и OPENAI_BASE_URL в окружении сервиса. Ключ не нужен для работы расчётного движка и резервного анализа.

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

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

1. Откройте демо или локальный экземпляр.

2. Нажмите «Эталон ТЗ». Загрузится следующий набор:

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

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

   Проверка	Ожидаемое значение
   Выбрано решений	5
   Потрачено / остаток	95 / 5 у.е.
   Исходный Score	52.56
   Итоговый Score	56.54 (до округления: 56.54307)
   Прирост Score	+3.99
   Критических показателей после мер	0
   Активная синергия	M10 + M12

4. Выберите Нуру на карте: S1 должен измениться с 38 до 48, S2 — с 35 до 43.75. Эти изменения выводят оба показателя из критической зоны.

5. Введите вопрос «Какие компромиссы есть у этого сценария?» и нажмите «Получить AI-анализ». Проверьте метку источника: «Анализ LLM» либо «Анализ по правилам» с объяснением причины. Во втором случае индивидуальный ответ модели недоступен, но расчёт и сводка работают.

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

7. Для проверки ограничений сбросьте сценарий, добавьте M1 в одном районе и попробуйте выбрать M3: несовместимая комбинация не должна добавиться.

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

npm test
npm run typecheck
npm run build

Существующие тесты проверяют контрольный Score, бюджет, лаги, синергии, отрицательные эффекты, границы 0–100, критический порог 40, недопустимые входные данные, серверные факты, резервные режимы API и актуальность анализа в UI. Дополнительно проверяются восстановление черновика, независимость сохранённых сценариев, ошибки хранилища, сравнение пары и загрузка во время AI-запроса. API-тесты используют подставной провайдер и не подтверждают доступность реальной модели.

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

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

Источник	Содержание
src/data/districts.ts	Пять районов, доли населения, профили и исходные показатели
src/data/indicators.ts	Десять показателей, описания и веса
src/data/measures.ts	Каталог из 14 мер, стоимость, лаги, эффекты, синергии и несовместимости
src/data/events.ts	События для экспериментального режима
OpenAI / совместимый API	Необязательный внешний анализ рассчитанного сценария и вопроса
Google Fonts	Загрузка шрифтов интерфейса
Render	Размещение опубликованного приложения; конфигурация включена в репозиторий

Названия Safe City, «Сергек» и iKomek 109 встречаются в описаниях учебных мер. Реальных интеграций с этими городскими системами в коде нет.

HTTP API приложения

• GET /api/health → { "status": "ok", "llmConfigured": false } (флаг зависит от конфигурации).
• POST /api/analyze принимает решения и необязательный непустой вопрос до 2000 символов. Пример тела:

{
  "decisions": [
    { "measureId": "M7", "districtId": "nura" },
    { "measureId": "M8", "districtId": "nura" },
    { "measureId": "M10", "districtId": "nura" },
    { "measureId": "M12" },
    { "measureId": "M5", "districtId": "saryarka" }
  ],
  "question": "Какие компромиссы есть у этого сценария?"
}

Ответ содержит simulation, analysis, source, необязательные answer и reason. Источник — llm или rules; причины резервного режима: missing_key, timeout, provider_error, invalid_response.

Сервер не принимает готовый Score от клиента. Ошибки формата дают HTTP 400, недопустимый сценарий — 422, тело больше 16 КБ — 413. Невалидный сценарий не передаётся модели.

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

• Синтетические данные, фиксированный каталог и упрощённые эффекты. Пять районов — состав учебного датасета, карта является условной схемой.
• Нет регистрации и серверной базы данных; черновик и библиотека сохраняются только в текущем браузере для текущего адреса сайта.
• AI ограничен набором подготовленных сервером фактов. Он не рассчитывает Score и не отвечает на произвольные вопросы, для которых нет фактов в сценарии.
• Рекомендации проверяют варианты одной замены, не доказывают глобальный оптимум. Несколько рекомендаций нельзя считать совместно проверенным набором без нового расчёта.
• Внешний AI требует ключа, сетевого доступа и совместимости выбранного endpoint. Доступность модели на опубликованном экземпляре определяется его серверной конфигурацией.
• Кризисы, отдельная карточка оптимизатора и презентация существуют как экспериментальные прототипы и по умолчанию скрыты. Библиотека и сравнение сценариев входят в основную версию; AI-анализ и сохранение именованного сценария отключаются при активных экспериментальных событиях.
• VITE_ENABLE_EXPERIMENTS — настройка фронтенда на этапе сборки. Передача её только запущенному production-контейнеру не включает скрытые элементы; текущий Dockerfile не предусматривает отдельного build-аргумента для этого флага.
• Таймер пятичасовой смены — элемент интерфейса: по истечении времени решения не блокируются.

Интерактивный транспортный двойник · 3D

Маршрут /#/transport (вкладка «Транспорт · 3D»): Three.js-сцена Астаны с рекой, тремя мостами, 420 агентами и интерактивной голографической развязкой. Два сценария, двухсекундная трансформация, автобусная полоса, анимированная телеметрия, камера, слои и пауза. Готовый React-компонент: src/transport/TransportTwin.tsx. Запуск, интеграция и допущения модели.