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

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

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

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

• Карта города, выбор района и каталог из 14 мероприятий.
• Расчёт для пяти районов: Есиль, Алматы, Сарыарка, Байконур и Нура.
• Проверка бюджета, количества решений, ограничений по направлениям, повторов, допустимых районов и несовместимости мероприятий.
• Детерминированный расчёт на горизонте восьми кварталов с учётом задержек эффекта, синергий и диапазона показателей 0–100.
• Итоговый Score, изменения показателей, слабейший район и количество критических показателей.
• Распределение прироста Score между мероприятиями методом Шепли.
• AI-анализ: вывод, сильные стороны, риски, компромиссы и рекомендации.
• Локальное резервное объяснение при отсутствии ключа или ошибке OpenAI.
• Сохранение именованных сценариев в SQLite и просмотр истории результатов.
• REST API, Swagger и автоматические тесты.

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

1. Интерфейс получает исходные показатели, мероприятия и правила от backend.
2. Пользователь выбирает пять мероприятий, указывая район для районных мер.
3. Backend проверяет ограничения и рассчитывает результат.
4. Интерфейс показывает бюджет, изменения показателей и вклад выбранных мер.
5. Рассчитанный результат передаётся AI-модели для текстового объяснения.
6. Пользователь сохраняет сценарий и открывает его через историю /results.

Числа рассчитывает Python; OpenAI объясняет готовый результат. Для текущих правил:

Score = 0.7 × средний балл районов с учётом долей населения
      + 0.3 × балл слабейшего района
      − количество показателей ниже 40

Балл района — взвешенная сумма десяти показателей. Веса и ограничения заданы в rules.json, алгоритм — в scoring.py.

Технологии

Компонент	Технологии
Интерфейс	TypeScript, Angular 22, RxJS, NG-ZORRO, Tailwind CSS, SCSS
Карта	Leaflet, GeoJSON, OpenStreetMap
Backend	Python, FastAPI, Uvicorn, Pydantic, pydantic-settings
Хранение	JSON для исходных данных, SQLite для сценариев
AI	OpenAI Python SDK, Responses API, структурированный ответ Pydantic; модель по умолчанию gpt-4o-mini
Проверки	pytest, HTTPX, Angular Test Runner / Vitest

Версии зависимостей находятся в backend/requirements.txt, frontend/package.json и frontend/package-lock.json.

Архитектура

Браузер: Angular + Leaflet
             │ HTTP /api/v1
             ▼
         FastAPI
          ├── dataset_repository.py  → JSON районов, мероприятий и правил
          ├── scoring.py             → валидация и расчёт
          ├── scenario_repository.py → SQLite
          └── ai_adapter.py          → OpenAI / локальное объяснение

Путь	Назначение
backend/api.py	HTTP endpoints
backend/schemas.py	Модели запросов
backend/settings.py	Настройки окружения
backend/app/data/	Районы, мероприятия и правила
backend/tests/	Тесты backend
frontend/src/app/	Интерфейс сценария, история, API-клиент
frontend/public/config.js	Публичный адрес API
frontend/public/maps/	Границы районов и описание источников
frontend/proxy.conf.json	Прокси локального сервера разработки

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

Требования

• Git и доступ к репозиторию, если он приватный.
• Python 3.11 или новее.
• Node.js, совместимый с Angular из lock-файла: ^22.22.3, ^24.15.0 или >=26.0.0.
• npm; в package.json указан [email protected].
• Интернет для установки зависимостей, подложки карты и запросов OpenAI.
• Собственный OpenAI API-ключ с доступом к выбранной модели — для AI-анализа. Без ключа работают расчёты и резервное объяснение.

1. Получить проект

git clone https://github.com/BAITC-Hacks/hack-3154ac51-nomad-minds.git
cd hack-3154ac51-nomad-minds

Все команды backend выполняются из корня репозитория.

2. Подготовить backend

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r backend/requirements.txt
if (!(Test-Path .env)) { Copy-Item .env.example .env }

Если PowerShell запрещает активацию, используйте .\.venv\Scripts\python.exe вместо python в последующих командах.

Linux / macOS:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r backend/requirements.txt
test -f .env || cp .env.example .env

В .env задайте параметры. Для описанного запуска используется порт 8000:

HOST=127.0.0.1
PORT=8000
CORS_ORIGINS=http://localhost:4200,http://127.0.0.1:4200
DATABASE_PATH=backend/app.db
OPENAI_API_KEY=
OPENAI_MODEL=gpt-4o-mini
OPENAI_TIMEOUT_SECONDS=30

Для OpenAI заполните OPENAI_API_KEY своим ключом. .env не коммитьте; в .env.example оставляйте ключ пустым. Ключ не должен попадать в публичную конфигурацию frontend.

Запустите backend:

python backend/api.py

• Swagger: http://127.0.0.1:8000/docs
• Проверка сервиса: http://127.0.0.1:8000/api/v1/health

SQLite-файл и таблица сценариев создаются автоматически при обращении к хранилищу. Отдельный сервер БД не нужен. При изменении DATABASE_PATH родительская папка должна существовать.

3. Запустить frontend

В отдельном терминале из корня репозитория:

cd frontend
npm ci
npm start

Откройте http://localhost:4200. Оба терминала должны оставаться запущенными. Остановка — Ctrl+C.

Frontend проксирует /api/** на http://127.0.0.1:8000. Если backend нужен на 8085, измените PORT=8085 в .env и target в frontend/proxy.conf.json на http://127.0.0.1:8085, затем перезапустите обе части. Swagger тогда доступен на http://127.0.0.1:8085/docs.

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

Повторяемый сценарий для жюри

На странице /scenario выберите:

Мера	Район
M7 — школа и детсад	Нура
M8 — поликлиника	Нура
M10 — освещение и камеры	Нура
M12 — платформа обращений	Весь город
M5 — перевод частного сектора на чистое топливо	Сарыарка

Выполните расчёт, просмотрите объяснение, сохраните сценарий с именем и откройте его в истории /results.

Тот же расчёт проверяется через Swagger: POST /api/v1/scenarios/calculate → Try it out → передайте:

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

Для данных версии 1.0.0 ожидаются значения, закреплённые в тестах backend:

Поле	Результат
valid	true
budget.spent / budget.remaining	95 / 5
baselineScore	52.55768
score	56.54307
scoreDelta	примерно 3.98539
criticalCount	0 (в исходном состоянии — 2)
weakestDistrictId	nura

Незначительные хвосты десятичных дробей обусловлены арифметикой floating-point. Для проверки ошибочного сценария удалите одну меру: расчёт вернёт valid: false и описание нарушения.

Для отдельной проверки AI передайте полный ответ расчёта в POST /api/v1/scenarios/analyze как значение поля result. source: "openai" означает ответ модели; source: "fallback" — локальное объяснение. Поле aiProvider в health отражает наличие ключа, а не проверяет доступность OpenAI.

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

Из корня репозитория в Python-окружении проекта:

python -m pytest backend/tests -q
python -m pip check

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

Из папки frontend:

npm test -- --watch=false
npm run build

Результат сборки — frontend/dist/frontend/browser относительно корня проекта.

API

Метод и путь	Назначение
GET /api/v1/health	Состояние сервиса и настройка AI
GET /api/v1/dataset	Районы, мероприятия, правила, исходный Score
POST /api/v1/scenarios/validate	Проверка в том числе неполного набора решений
POST /api/v1/scenarios/calculate	Расчёт полного сценария
POST /api/v1/scenarios/analyze	Объяснение рассчитанного результата
POST /api/v1/scenarios	Сохранение: name и decisions; сервер пересчитывает результат
GET /api/v1/scenarios	История сохранённых сценариев

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

• Модель города: backend/app/data/districts.json, measures.json и rules.json. Это фиксированные входные данные симулятора, а не онлайн-статистика городских служб. Бюджет и цены выражены в условных единицах.
• География: локальный снимок границ OpenStreetMap в GeoJSON. Источники, идентификаторы отношений и лицензия ODbL описаны в документации карты.
• Подложка карты: тайлы https://tile.openstreetmap.org/{z}/{x}/{y}.png, загружаемые браузером; требуется интернет.
• OpenAI: backend отправляет JSON рассчитанного сценария во внешний API. Модель задаётся OPENAI_MODEL. Текст ответа может отличаться между запросами.
• SQLite: хранит имя, решения, результат, версию данных и дату создания сценария.

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

• Модель охватывает пять районов. Сарайшык отображается на карте, но не участвует в расчёте: в наборе данных нет его показателей и доли населения.
• Эффекты и веса заданы фиксированными правилами; модель не обучается на реальных городских данных и не подтверждает причинный эффект мероприятий в реальности.
• Автоматический поиск оптимального набора мероприятий не реализован.
• Страницы /comparison и /project-info пока являются заглушками.
• В API нет авторизации, разделения истории по пользователям и ограничения частоты запросов. Публичное использование требует дополнительной настройки защиты.
• AI может ошибаться; рекомендации нужно проверять. Резервный ответ проще, сформирован на английском и содержит пустой список рекомендаций.
• Endpoint анализа принимает готовый результат от клиента и не пересчитывает его; для проверки используйте результат /calculate.
• Для сохранности истории нужен постоянный SQLite-файл и резервное копирование. Удаление файла или временное хранилище сервера приводит к потере сценариев.

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

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

Для размещения frontend адрес backend задаётся в frontend/public/config.js (или config.js внутри готовой сборки) полем apiBaseUrl, включая /api/v1. Значение по умолчанию /api/v1 требует прокси на том же домене. При разных доменах настройте CORS_ORIGINS backend. Подробности — в frontend/README.md.