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

Пять решений. Бюджет 100. Будущее пяти районов Астаны.

Учебный AI-симулятор городского управления для HackAlem. Команда LODZ POLSKA.

Пользователь выбирает городские инициативы, распределяет ограниченный бюджет и сравнивает последствия для транспорта, экологии, социальной инфраструктуры, безопасности и городских сервисов. Расчётный движок определяет Astana Quality of Life Score, а AI объясняет сильные стороны, риски и компромиссы выбранного плана.

Все исходные данные и эффекты мероприятий синтетические. Это учебная модель для сравнения сценариев, а не прогноз реального развития Астаны.

Возможности · Как работает · Технологии · Запуск · Проверка жюри · Данные · Архитектура · Публикация

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

На 23 сентября 2026 года модули опубликованы в отдельных ветках и ожидают объединения. В main пока находится общая документация. Команды ниже явно выбирают ветку с нужным кодом.

Часть	Что есть в коде	Ветка / pull request
Frontend	Главная, планирование, результаты, сравнение, адаптивный интерфейс и демонстрационный режим	feature/frontend · PR #2
Backend / simulation	FastAPI, проверка ограничений, детерминированный расчёт, вклады мероприятий и поиск одной замены	feature/simulation · PR #3
AI / report	Анализ рассчитанного сценария через LLM, структурированный ответ и краткий отчёт	feature/ai · PR #1
Сквозная интеграция	Форматы frontend/backend сверены; требуются объединение модулей и проверка с провайдером	См. подключение компонентов

Режимы различаются: демоверсия интерфейса показывает сохранённый контрольный пример; backend рассчитывает произвольные допустимые наборы; настоящий AI требует серверной настройки и завершённой интеграции. В репозитории есть отчёт о проверке интеграции, включая один успешный вызов AI с увеличенным таймаутом. Полный пользовательский сценарий на объединённой версии при штатных лимитах ещё требует проверки.

Для кого и зачем

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

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

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

• Планирование: пять районов, каталог из 14 мероприятий, поиск и фильтры, бюджет, пять слотов решений, районный и общегородской охват.
• Последствия: показатели до/после, оценка города и районов, критические значения, синергии, задержки и рассчитанные сервером вклады мероприятий.
• Объяснение: AI-модуль формирует сильные стороны, риски, компромиссы и рекомендации на основе рассчитанных фактов. Ошибка AI не должна блокировать числовой результат.
• Сравнение: интерфейс хранит до 12 сценариев в браузере, сравнивает два выбранных плана и выгружает результат в JSON.
• Поиск улучшения: backend проверяет допустимые варианты с заменой одного решения. Это поиск лучшей одной замены, а не доказательство глобально оптимального плана.
• Интерфейс: адаптивная компоновка, диаграммы, схема районов, анимации с поддержкой prefers-reduced-motion, управление диалогами и схемой с клавиатуры.

Подробные границы реализации: frontend README, общий API-контракт, AI README.

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

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

Это сценарий режима live. В mock используются локальные данные и сохранённый ответ контрольного примера; сетевой AI-вызов и расчёт произвольных планов не выполняются.

Технологии

Компонент	Подтверждённые технологии
Языки	TypeScript и JavaScript на frontend; Python на backend; CSS; JSON для данных и контрактов
Интерфейс	Next.js 16.3.6 (App Router), React 19.3.0, TypeScript 6.0.3, Tailwind CSS 4.3.3
Компоненты и графики	Radix UI, Recharts, Lucide; Zod для проверки ответов API
Сервер	FastAPI 0.141.1, Pydantic 2.13.5, Uvicorn 0.53.0, python-dotenv
AI	OpenAI Python SDK 3.19.0, Responses API, структурированные ответы по Pydantic-схеме
Проверки	Vitest, TypeScript, ESLint; pytest, Hypothesis, Ruff; workflow backend-проверок в GitHub Actions
Локальная инфраструктура	npm, Python venv; Dockerfile и Compose для расчётного API; localStorage для сохранённых планов

В AI-провайдере значение модели по умолчанию — gpt-6-astra. Его можно изменить через OPENAI_MODEL; для запуска требуется доступ к выбранной модели в API-проекте. Это значение из кода, а не обещание доступности модели любому аккаунту. Модель объясняет результат; математический движок не использует LLM для расчёта Score.

Версии взяты из frontend/package.json, backend/requirements.txt и backend/requirements-ai.txt. Frontend устанавливается по package-lock.json; Python-зависимости закреплены в requirements-файлах.

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

Репозиторий приватный: для клонирования нужен доступ к нему в GitHub. Зависимости устанавливаются из интернета. Для локальной демонстрации интерфейса и расчётов API-ключ не нужен.

1. Интерфейс — быстрый просмотр

Требуются Git, Node.js 22.20+ и npm. В новом терминале:

git clone --branch feature/frontend https://github.com/BAITC-Hacks/hack-921839cc-lodz-polska.git akim-ai-ui
cd akim-ai-ui/frontend
npm ci
npm run dev

Откройте http://127.0.0.1:3000. По умолчанию включён mock: нажмите «Попробовать пример», чтобы пройти полный интерфейсный сценарий.

В этом режиме только контрольный набор имеет сохранённый результат. Произвольные наборы не получают выдуманный Score; для них нужен backend. Текст объяснения отмечен «Шаблон · не AI».

Production-сборка, из той же папки frontend:

npm run build
npm start

Перед npm start остановите dev-сервер на порту 3000.

2. Backend — реальные расчёты модели

Требуются Git и Python 3.11+; для воспроизводимой проверки используется Python 3.12. Во втором терминале клонируйте расчётную ветку в отдельную папку:

git clone --branch feature/simulation https://github.com/BAITC-Hacks/hack-921839cc-lodz-polska.git akim-ai-api
cd akim-ai-api

Windows PowerShell:

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r backend/requirements-dev.txt
.\.venv\Scripts\python.exe -m uvicorn app.main:app --app-dir backend --host 127.0.0.1 --port 8000

Linux / macOS:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r backend/requirements-dev.txt
python -m uvicorn app.main:app --app-dir backend --host 127.0.0.1 --port 8000

Для запуска без инструментов тестирования достаточно backend/requirements.txt. Не отделяйте backend/ от shared/: сервер читает общий датасет из репозитория.

Проверьте health и откройте Swagger UI. В POST /api/scenario/finalize нажмите Try it out, вставьте контрольный запрос и выполните его. Ожидаемый итог — 56.54307 при расходе 95.

Подключение компонентов

Для проверки числового сценария UI и API могут работать из двух отдельных копий выше. В akim-ai-ui/frontend/.env.local создайте:

NEXT_PUBLIC_API_MODE=live
NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8000
NEXT_PUBLIC_ENABLE_RECOMMENDATIONS=false

Перезапустите npm run dev; для production нужна новая сборка. В URL указывается адрес сервера без /api. Backend по умолчанию разрешает оба origin: http://127.0.0.1:3000 и http://localhost:3000.

Полный локальный запуск с AI

Пока pull request не объединены, собрать существующие модули для проверки можно в новой отдельной папке. Команды ниже берут расчётную ветку за основу и добавляют из других веток только каталоги frontend, AI и отчёта:

git clone --branch feature/simulation https://github.com/BAITC-Hacks/hack-921839cc-lodz-polska.git akim-ai-full
cd akim-ai-full
git restore --source=origin/feature/frontend --worktree -- frontend
git restore --source=origin/feature/ai --worktree -- backend/app/ai backend/app/report

В этой новой копии выполните следующие шаги:

1. Создайте .venv и установите backend/requirements-dev.txt командами из раздела запуска backend, пока не запускайте Uvicorn.
2. Установите AI-зависимости. В PowerShell из akim-ai-full: .\.venv\Scripts\python.exe -m pip install -r backend/requirements-ai.txt. В Linux/macOS после активации окружения: python -m pip install -r backend/requirements-ai.txt.
3. Создайте локальный файл backend/.env с собственным ключом и доступной моделью:

OPENAI_API_KEY=YOUR_API_KEY
OPENAI_MODEL=gpt-6-astra

4. Создайте frontend/.env.local с тремя NEXT_PUBLIC_* значениями из раздела «Подключение компонентов» выше.
5. Из akim-ai-full запустите Uvicorn той же командой, что в разделе backend. В другом терминале перейдите в akim-ai-full/frontend, выполните npm ci, затем npm run dev. Остановите предыдущие локальные серверы, если они уже занимают порты 8000 и 3000.
6. Откройте интерфейс, повторите контрольный сценарий и проверьте AI-панель. Для поиска одной замены после проверки /api/recommend включите NEXT_PUBLIC_ENABLE_RECOMMENDATIONS=true и перезапустите frontend.

Изменения git restore остаются локальными; это способ собрать проверяемые модули, а не публикация объединённого релиза. Для чисто расчётной демонстрации AI-зависимости и ключ не нужны.

Backend начиная с 280a2a2 принимает текущий frontend-запрос {scenario: ...} и возвращает выводы {text, evidence}. Старый вариант {simulation: ...} имеет другой формат ответа и сохранён для обратной совместимости. Используйте имеющийся адаптер интегратора: дополнительное подключение прямых AI-роутеров создаёт дублирующиеся маршруты и обходит серверный пересчёт. Подробности — в API-контракте.

Без AI-модуля, SDK или ключа анализ возвращает HTTP 503; расчётные маршруты продолжают работать. Поле aiConfigured в health отражает настройку адаптера, но не подтверждает успешный ответ внешнего провайдера. Переменные процесса имеют приоритет над backend/.env.

Переменные окружения

Переменная	Где задаётся	Назначение
NEXT_PUBLIC_API_MODE	frontend/.env.local	mock для примера, live для HTTP API
NEXT_PUBLIC_API_BASE_URL	frontend/.env.local	Origin backend; пустое значение — запросы на текущий origin при настроенном reverse proxy
NEXT_PUBLIC_ENABLE_RECOMMENDATIONS	frontend/.env.local	true после проверки endpoint поиска замены
CORS_ORIGINS	Окружение backend	Разрешённые origin через запятую; по умолчанию localhost и 127.0.0.1 на порту 3000
OPENAI_API_KEY	backend/.env или окружение backend	Собственный ключ провайдера для AI
OPENAI_MODEL	backend/.env или окружение backend	Доступная аккаунту модель, поддерживаемая AI-адаптером

Значения NEXT_PUBLIC_* доступны браузеру. Не помещайте туда секреты и не коммитьте настоящие ключи или локальные .env.

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

Демонстрация для жюри

1. Открыть главную и нажать «Начать управление».
2. Выбрать Нуру на схеме: изучить показатели, открыть детали мероприятия и его задержку эффекта.
3. Нажать «Попробовать пример»: пять решений, расход 95, остаток 5.
4. Нажать «Рассчитать результат»: показать Score 52.56 → 56.54, изменения по районам и исчезновение критических показателей.
5. Показать объяснение: в mock это явно обозначенный шаблон; настоящий AI демонстрируется после интеграции.
6. Сохранить сценарий, открыть сравнение и экспортировать JSON. Для сравнения разных рассчитанных планов использовать backend; одинаковые планы должны давать одинаковые результаты.

Контрольный запрос

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

Тело запроса к POST /api/scenario/finalize:

{
  "decisions": [
    { "measureId": "M7", "districtId": "nura" },
    { "measureId": "M8", "districtId": "nura" },
    { "measureId": "M10", "districtId": "nura" },
    { "measureId": "M12" },
    { "measureId": "M5", "districtId": "saryarka" }
  ]
}

Проверяемая величина	До	После
Astana Quality of Life Score	52.55768	56.54307
Среднее по населению	56.8624	58.0776
Оценка слабейшего района — Нуры	49.18	52.9625
Количество индикаторов ниже 40	2	0

Изменение Score — +3.98539, бюджетный остаток — 5. UI округляет числа только для отображения. Запрос и ответы для автоматической проверки доступны в example-scenario.json и shared/fixtures.

Дополнительная проверка через Swagger: отправьте в POST /api/simulate набор M1/Есиль + M3/Нура. Эти меры несовместимы даже в разных районах; ожидается validation.status=invalid и after=null. Для проверки влияния выбора измените район M5 в полном контрольном плане и повторите финализацию: получите новый серверный расчёт вместо сохранённого mock-ответа.

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

Источник / интеграция	Что используется	Где подтверждено
Синтетический датасет организаторов	5 районов, доли населения и 10 исходных индикаторов	shared/districts.json
Каталог мероприятий	14 мер: стоимость, охват, задержки и эффекты	shared/measures.json
Правила симуляции	Бюджет, веса, пороги, синергии, несовместимости и версия модели	shared/model.json
Контрольные примеры	Входной план и воспроизводимые ответы расчётного движка	example-scenario.json, fixtures
Собственный HTTP API	Обмен frontend с FastAPI: JSON, схемы OpenAPI и описанный контракт	shared/api-contract.md
OpenAI Responses API	Только серверный AI-анализ: рассчитанный сценарий и необязательный вопрос; ответ в заданной схеме	openai_provider.py
Браузерное хранилище	Черновик и сохранённые сценарии на устройстве пользователя	frontend/lib/storage.ts

В проекте нет подключения к реестрам акимата, живой городской статистике, GIS-сервисам или картографическому API. Схема районов локальная. Данные модели хранятся в репозитории; для расчёта не требуется внешний сервис. AI-анализ отправляет рассчитанные данные сценария внешнему провайдеру и требует отдельного API-доступа.

Источник и трактовка исходного задания описаны в разборе требований. Fixtures — контрольные данные для проверки, а примеры ответов AI в его модуле не следует выдавать за новые живые ответы модели.

Расчётная модель

Данные и правила

Пять районов: Есиль, Алматы, Сарыарка, Байконур и Нура. Доли населения — 27%, 24%, 20%, 13% и 16% соответственно. В каждом районе десять индикаторов от 0 до 100; чем выше, тем лучше, включая транспорт и безопасность.

Направление	Индикаторы	Веса в оценке района
Транспорт	T1 — разгрузка дорог; T2 — общественный транспорт	0.10; 0.10
Экология	E1 — озеленение; E2 — качество воздуха	0.09; 0.11
Социальная инфраструктура	S1 — школы и детсады; S2 — первичная медицина	0.11; 0.11
Безопасность	B1 — улицы; B2 — дорожное движение	0.09; 0.09
Городские сервисы	C1 — надёжность ЖКХ; C2 — обращения жителей	0.10; 0.10

Официальный результат выдаётся только при соблюдении ограничений:

• бюджет не более 100, ровно 5 разных мероприятий;
• каждое мероприятие выбирается не более одного раза, даже для разных районов;
• не более 2 мероприятий одного направления;
• для районной меры указан район; общегородская применяется ко всем районам;
• нет несовместимых сочетаний: M1 + M3 в любых районах, M4 + M7 в одном районе, M5 + M13 в одном районе.

По подробному датасету не требуется выбирать ровно по одной мере из каждого направления: действует предел «не более двух». Краткое ТЗ формулирует пять направлений менее подробно; эта трактовка зафиксирована для согласования с организаторами. Остаток бюджета не добавляет баллов.

Формулы

Горизонт — 8 кварталов, L — задержка мероприятия в кварталах:

Учтённый эффект = полный эффект × (8 − L) / 8
Показатель после = clip(исходный + сумма эффектов + синергии, 0, 100)
Оценка района D = сумма(вес индикатора × его значение)
Среднее Davg = сумма(доля населения района × D)
Score = 0.7 × Davg + 0.3 × min(D) − Ncrit

Ncrit — количество пар «район / индикатор» со значением строго ниже 40. Значение 40 не штрафуется. Эффекты сначала суммируются, затем ограничиваются диапазоном; промежуточного округления нет. Порядок решений не меняет результат.

Фиксированные синергии добавляются без коэффициента задержки: M1 + M2 → T1 +2 в районе M1; M10 + M12 → B1 +2 в районе M10; M5 + M6 → E2 +2 в районе M5.

Движок использует точные рациональные числа Fraction, а в JSON отдаёт обычные числа. Вклады мероприятий рассчитываются методом Шепли: усреднением вклада по порядкам добавления. Их сумма соответствует изменению Score, включая синергии и нелинейный штраф.

Единые данные: districts.json, measures.json, model.json. Версия модели и контрольная сумма данных позволяют отличать результаты разных редакций. При невалидном плане официальный Score отсутствует (null), а ответ содержит причины отказа.

Архитектура

flowchart LR
    UI["Next.js / React: интерфейс"] --> API["FastAPI: валидация запросов"]
    API --> Engine["Simulation engine: расчёт"]
    Data["shared: данные и правила"] --> Engine
    Engine --> Result["Проверенный результат"]
    Result --> UI
    Result --> Bridge["Серверный AI-адаптер"]
    Bridge --> LLM["LLM: объяснение"]
    LLM --> Analysis["Анализ и краткий отчёт"]
    Analysis --> UI
    UI --> Storage["localStorage: сохранённые планы"]

Схема показывает устройство объединённого приложения; состояние интеграции указано выше. Числа рассчитывает backend. AI объясняет уже проверенные факты. Браузер не является источником стоимости, эффектов или официального Score.

Структура модулей после объединения веток:

frontend/                   страницы, компоненты, HTTP-адаптер, типы, тесты
backend/app/main.py          сборка приложения FastAPI и CORS
backend/app/api/simulation/  HTTP-маршруты и проверяющий AI-адаптер
backend/app/models/          схемы запросов и ответов
backend/app/simulation/      данные, ограничения, расчёт, поиск улучшения
backend/app/ai/              AI-схемы, prompts, service и провайдер
backend/app/report/          краткий структурированный отчёт
backend/tests/              проверки модели и API
backend/docs/               разбор требований и принятые решения
shared/                     датасет, модель, контракт, OpenAPI, fixtures

API

Расчётные запросы и ответы используют camelCase; текущий AI-запрос содержит scenario с полями snake_case. Полная схема — API-контракт; при работающем сервере доступны /docs и /openapi.json.

Метод	Маршрут	Назначение
GET	/api/health	Состояние приложения, версия и контрольная сумма модели
GET	/api/districts, /api/measures, /api/bootstrap	Данные районов, каталог и стартовые параметры
POST	/api/simulate	Предварительный расчёт для 0–5 решений
POST	/api/scenario/finalize	Повторная проверка и официальный результат пяти решений
POST	/api/recommend	Проверенная замена одного решения
POST	/api/ai/analyze	Анализ после серверного пересчёта решений из scenario; выводы с evidence
POST	/api/explain	Анализ по компактному запросу {decisions, question?}
POST	/api/report/executive-brief	Структурированный отчёт по проверенному сценарию

Preview не является официальной финализацией. Бизнес-ошибка simulate/finalize возвращается как HTTP 200 с validation.status=invalid и after=null; неверный формат запроса — HTTP 422; недоступный AI — HTTP 503. Клиент должен проверять содержимое ответа, а не только HTTP-статус.

Проверки

Команды ниже выполняются в соответствующих копиях репозитория. Они проверяют код; сквозной запуск с реальным AI проверяется отдельно после интеграции.

Frontend, из akim-ai-ui/frontend или akim-ai-full/frontend:

npm run test
npm run typecheck
npm run lint
npm run build

Backend, из корня akim-ai-api или akim-ai-full, в отдельном терминале. Активация окружения:

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# Linux / macOS
source .venv/bin/activate

Затем:

cd backend
python -m pytest --cov=app --cov-report=term-missing
python -m ruff check app/api/simulation app/models app/simulation app/main.py tests scripts
python -m ruff format --check app/api/simulation app/models app/simulation app/main.py tests scripts
cd ..
python backend/scripts/export_fixtures.py

Если PowerShell запрещает активацию, используйте путь к .venv\Scripts\python.exe вместо python, учитывая текущий каталог. Последняя команда заново формирует контрольные ответы в shared/fixtures/.

После локальной сборки модулей или объединения веток и установки зависимостей, из корня проекта:

node backend/scripts/check_frontend_contract.mjs
python backend/scripts/check_ai_contract.py

До объединения Node-скрипт принимает путь к внешней папке frontend первым аргументом; Python-скрипт — --ai-root с путём к внешней папке backend/app. Эти проверки используют контрольные ответы и не обращаются к внешнему LLM.

Проверка форматов frontend 2412b1e и backend 280a2a2 подтвердила совместимость шести серверных fixtures, AI-запроса и примера структурированного AI-ответа. Она не обращалась к внешнему провайдеру.

В отчёте интегратора отдельно зафиксированы 77 прошедших тестов, проверка настоящего HTTP-клиента frontend и успешный вызов gpt-6-astra через FastAPI с настоящим AI-провайдером. Успешный диагностический вызов использовал таймаут 60 секунд; первый запрос при штатных 15 секундах завершился таймаутом. Эти результаты взяты из отчёта в репозитории и не являются заявлением о повторном прогоне всех проверок при редактировании README.

Расчётный backend также содержит Docker-конфигурацию: docker compose up --build из корня его копии. Она поднимает только API на 127.0.0.1:8000; frontend и AI SDK в этот образ не включены. Сборка Docker в рамках этой проверки README не запускалась.

Backend-тесты покрывают контрольные числа, бюджет, количество и повторы мер, несовместимости, отрицательные эффекты, задержки, синергии, границы 0/40/100, независимость от порядка и поиск одной замены. Frontend-тесты проверяют формат и ошибки API, таймауты, отсутствие поддельного результата для произвольного mock-набора и восстановление локальных сохранений.

Сквозная проверка перед сдачей

• На чистом checkout зависимости устанавливаются по указанным командам.
• Сервер отдаёт 5 районов и 14 мероприятий; базовый Score равен 52.55768.
• Контрольный запрос даёт 56.54307, расход 95, остаток 5, ноль критических показателей.
• Изменённый допустимый набор пересчитывается сервером; проверяются превышение бюджета, повторы, несовместимости и финализация неполного плана.
• AI-запрос соответствует контракту, вывод объясняет рассчитанные факты; при HTTP 503 числовой результат остаётся доступным.
• Два разных плана сохраняются и сравниваются; JSON-экспорт содержит результат выбранного плана.
• Интерфейс проверен на мобильном экране и с клавиатуры, ошибки сети видимы пользователю.

Если что-то не запускается

Симптом	Что проверить
Нет папки frontend или backend	В main пока только документация; выберите нужную ветку из инструкции
UI работает, но свой план не рассчитывается	Включён mock; подключите расчётный API и перезапустите frontend
Ошибка сети / CORS	Backend запущен на 8000; base URL без /api; origin фронтенда разрешён
AI возвращает 422	Согласованы ли запрос и ответ AI-адаптера с текущим общим контрактом
AI возвращает 503	Подключён ли AI-модуль, установлен ли SDK, задан ли ключ в процессе backend и доступна ли выбранная модель
Порт 3000 занят	Остановите предыдущий dev/production-сервер либо согласуйте новый порт и CORS

Критерии хакатона

Таблица связывает критерии из ТЗ с материалами и проверками проекта. Баллы — максимумы организаторов, а не заявленная оценка команды.

Критерий	Максимум	Что демонстрировать и проверять
Соответствие задаче и работоспособность	25	Единый бюджет и датасет, пять решений, ограничения, пересчёт Score и AI-объяснение; контрольный сценарий и сквозной прогон
Техническая реализация	25	Разделение UI / engine / AI, серверная валидация, типизированный контракт, точная математика и обработка ошибок
README и воспроизводимость	25	Требования к окружению, команды запуска, режимы, конфигурация, контрольный JSON с ожидаемыми числами, тесты и устранение ошибок
Ценность и применимость решения	15	Сравнение бюджетных компромиссов, улучшение слабейшего района, работа с критическими показателями и понятные объяснения
Потенциал развития и оригинальность подхода	10	Объяснимые вклады мер, проверенная замена одного решения, учёт синергий и задержек, план развития
Всего	100	Финальная оценка зависит от работающей объединённой версии

Ограничения и развитие

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

В текущий MVP не входят авторизация, серверное хранение, межкомандный рейтинг, неожиданные городские события и готовый экспорт PDF/PPT. Модуль Executive Brief формирует структурированные данные и Markdown; это ещё не генератор презентаций.

Штатный таймаут backend для AI — 15 секунд, frontend — 20 секунд. В репозитории подтверждён один успешный запрос с увеличенным диагностическим лимитом; стабильное прохождение AI-анализа при штатных настройках ещё не подтверждено. При недоступности провайдера интерфейс должен сохранить расчётный результат и показать ошибку анализа.

Ближайший приоритет — закончить объединение веток и повторить полный пользовательский сценарий с AI при штатных настройках. Дальнейшее развитие: общие сессии команд и рейтинг, наборы городских событий, экспорт презентации, анализ чувствительности сценариев и подключение проверенных открытых данных с отдельной калибровкой модели.

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

Подтверждённая ссылка на развёрнутое приложение в репозитории не указана. На момент проверки поле Website пустое, GitHub Pages не включён, имеющийся workflow запускает проверки backend и не публикует сайт. Поэтому внешняя demo-ссылка здесь не приводится.

Для проверки жюри доступен локальный запуск. Адреса 127.0.0.1:3000 и 127.0.0.1:8000 работают на компьютере, где запущены компоненты, и не являются deployed-версией.

Работа команды и источники

Зона ответственности	Файлы
Nurali №1 — FRONTEND	frontend/**
Alibek №2 — BACKEND / SIMULATION / INTEGRATOR	Расчётный backend, shared/**, сборка приложения и общий контракт
Abylay №3 — AI / REPORT	backend/app/ai/**, backend/app/report/**

Общий API-контракт согласуется до изменения форматов. Frontend не дублирует расчётный движок; AI не меняет формулу и исходные данные. Изменения общего контракта сопровождаются обновлением адаптеров и контрольных ответов, после чего повторяется сквозная проверка.

Проект опирается на четыре предоставленных документа:

1. «HackAlem AI: “Аким на 5 часов”» — задача, обязательные возможности и критерии оценки.
2. «Датасет районов» — синтетические исходные значения, мероприятия, ограничения и формулы.
3. «План проекта» — пользовательский сценарий и план реализации.
4. «Чёткое разделение участников» — границы ответственности и правила интеграции.

Разбор требований сохранён в документации frontend и документации backend. Ссылки на код ниже ведут в рабочие ветки, поскольку они ещё не объединены с main.