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

Интерактивный симулятор городских решений для HackAlem AI. Он помогает сравнить, как пять мер при ограниченном бюджете меняют показатели пяти районов Астаны. Проект рассчитан на участников хакатона, жюри и всех, кому нужно быстро увидеть последствия выбранного плана в рамках учебной модели.

Главная идея: расчётный движок проверяет решения и считает результат, советник перебирает допустимые замены одной меры, а AI расставляет по важности уже проверенные выводы. Числа и эффекты не рассчитываются языковой моделью.

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

• Выбор пяти разных городских и районных мер из каталога с бюджетом 100 единиц, проверкой ограничений и пояснением ошибок.
• Расчёт исходного и итогового Astana Quality of Life Score, показателей районов, критических значений и влияния выбранных мер.
• Контрфактический советник: перебор допустимых замен одной меры, сравнение планов и применение найденной замены.
• Объяснение результата по сильным сторонам, рискам, компромиссам и рекомендациям. При наличии API-ключа OpenAI выбирает приоритет проверенных фактов; без ключа доступен локальный детерминированный анализ.
• Интерфейс на русском, казахском и английском языках, светлая и тёмная темы, сохранение плана и настроек в localStorage браузера.
• Серверный POST /api/analyze, который самостоятельно пересчитывает переданные решения и не принимает клиентские Score или бюджет как достоверные данные.

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

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

Формула и полный контракт расчёта описаны в документации движка. Итог учитывает среднюю оценку с весами по населению, оценку самого слабого района и штраф за показатели ниже 40.

Технологии

Область	Используется
Приложение	TypeScript, React 19, Next.js 16 (App Router), CSS и Tailwind CSS 4
Расчёт	Локальный TypeScript-модуль src/domain/ и данные src/data/
AI	Официальный OpenAI SDK, Responses API и Structured Outputs; модель из OPENAI_MODEL, по умолчанию gpt-6-sol
Проверка данных	Zod на границе AI API
Тестирование	Vitest, Node.js test runner и Playwright
Хранение настроек	localStorage браузера

OpenAI API — единственный внешний сервис, используемый приложением, и он необязателен для запуска. База данных в репозитории не настроена.

Архитектура проекта

src/data/                 Районы, показатели, меры и правила учебной модели
        ↓
src/domain/               Валидация → расчёт сценария → поиск замены
        ↓                              ↓
src/app/page.tsx           Интерфейс   POST /api/analyze
src/components/                       ↓
                            Серверный пересчёт → проверенные факты
                                                     ↓
                                      OpenAI или локальный анализ

src/lib/ai/ содержит адаптер результатов движка, локальный анализ, вызов OpenAI и клиентский хук. Серверный маршрут расположен в src/app/api/analyze/route.ts. Числа в интерфейсе берутся из движка. Модель получает проверенные карточки, стоимость и лаги выбранных мер, реализованные эффекты, изменения районов и сравнение с заменой. Она возвращает только идентификаторы карточек в порядке важности; неизвестные идентификаторы и ошибки API приводят к локальному анализу.

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

Требуются Node.js 22.18 или новее и npm (версия Node указана в package.json). Выполняйте команды из корня репозитория:

npm ci
npm run dev

Откройте http://localhost:3000. Без дополнительной настройки доступны симуляция, советник и локальное объяснение.

Для необязательного OpenAI-анализа скопируйте .env.example в .env.local и добавьте действующий ключ OpenAI API:

cp .env.example .env.local

В PowerShell: Copy-Item .env.example .env.local. Содержимое файла:

OPENAI_API_KEY=ваш_ключ_OpenAI_API
OPENAI_MODEL=gpt-6-sol

Выберите в OPENAI_MODEL модель, доступную вашему API-аккаунту и поддерживающую нужный формат ответа. После изменения .env.local перезапустите сервер. Ключ используется только на сервере.

Для локального production-запуска:

npm run build
npm run start

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

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

1. Откройте главную страницу и нажмите «Загрузить пример». План содержит M7/Нура, M8/Нура, M10/Нура, M12/весь город и M5/Сарыарка.
2. Проверьте бюджет 95 из 100 и изменение Score 52,56 → 56,54. Значения до округления: 52.55768 → 56.54307.
3. Нажмите «Найти лучшую замену». Советник показывает замену M5/Сарыарка → M3/Нура: бюджет 100, новый Score 57.20556 (на экране 57,21).
4. Нажмите «Применить замену», затем «Рассчитать сценарий». Изменение плана вызывает новый расчёт; прежний результат не остаётся результатом нового плана.
5. Нажмите «Сбросить» и выберите меньше пяти мер. Интерфейс показывает ошибку выбора и блокирует расчёт.

На русском языке при настроенном ключе может появиться анализ с меткой OpenAI. Без ключа тот же сценарий сопровождается локальным анализом. Казахская и английская версии используют локализованный локальный анализ.

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

npm run check
npx playwright install chromium
npm run test:e2e

npm run check последовательно выполняет проверку типов, линтер, тесты приложения и движка, production-сборку и smoke-проверку собранного движка. Тесты Playwright проверяют пользовательский поток в браузере. Обычные тесты не делают платных запросов к OpenAI. Отдельные команды перечислены в package.json.

Повторная сверка с оригинальными PDF, независимый расчёт 10 010 планов, проверка AI и интерфейса описаны в полном отчёте аудита.

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

Исходные показатели пяти районов, десять индикаторов, четырнадцать мер, их эффекты и правила хранятся в src/data/. Это синтетический датасет для хакатона, а не актуальная городская статистика или прогноз. Пользователь выбирает меры из этого каталога; загрузки произвольного набора данных через интерфейс нет.

POST /api/analyze принимает { "decisions": [...] } и опционально полный массив replacementDecisions. Для обоих наборов сервер вызывает расчётный движок; неверный план возвращает HTTP 400. OpenAI Responses API используется только при наличии OPENAI_API_KEY. Ключ хранится в серверном окружении, а .env.local исключён из Git.

Лимит тела запроса — 16 КиБ (HTTP 413 при превышении). Тайм-аут OpenAI — 20 секунд, клиентского запроса — 25 секунд. Сбой или тайм-аут переключает объяснение на локальные проверенные факты; изменение плана отменяет устаревший запрос.

Развёрнутая версия

Публичная демо-версия: akim-na-5-chasov.daniiproger.chatgpt.site. Она доступна без API-ключа OpenAI и использует локальный анализ; расчёт сценариев и поиск замены работают на опубликованном сайте.