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

StikerAI — учебный симулятор городских решений и демонстрация взаимодействия администрации с жителями. Пользователь собирает план из пяти инициатив в рамках общего виртуального бюджета; backend проверяет план, детерминированно считает показатели районов и итоговый Astana Quality of Life Score. AI может объяснить уже рассчитанный результат, но не принимает решение и не меняет числа.

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

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

• Akim workspace: портфель инициатив, общий бюджет 100 виртуальных единиц, выбор районов, проверка ограничений, предварительный расчёт и сохранённый результат.
• Детерминированная модель: пять синтетических районов, десять показателей, 14 инициатив, лаги, синергии и конфликты. При отправке требуется ровно пять разных инициатив; допускается не более двух инициатив одного направления.
• Citizen workspace: демонстрационные петиции, голоса, сообщения и проекты. Это вымышленные данные, хранящиеся локально в браузере; они не меняют государственный бюджет или Score.
• Карта: шесть community-mapped границ районов и отдельный слой объектов OpenStreetMap с тегом amenity=school. Улицы загружаются отдельным слоем карты. География является контекстом, а не официальным кадастром и не связана с синтетическими показателями по неподтверждённому совпадению названий.
• AI-объяснение: необязательный вызов OpenAI Responses API получает сохранённые результаты и отдельный явно вымышленный civic-снимок. AI не пересчитывает Score и не должен представлять вымышленные сигналы как мнение жителей.
• Сохранение сценариев: PostgreSQL, анонимная браузерная сессия, проверка ревизии при записи, отправка и копирование сценариев.

Симулятор встроен в Akim workspace: откройте пункт Simulator или адрес /simulator. Общая оболочка объединяет выбор пяти мер, бюджет, карту, предварительный расчёт, сравнение показателей и AI-анализ. Сессия и каталог общие с обзором города.

Технологии и архитектура

Слой	Технологии	Ответственность
Frontend	React 19, TypeScript, Vite 7, CSS, Lucide React	Рабочие пространства, локальная civic-демонстрация и отображение результатов
Карта	MapLibre GL, Leaflet, GeoJSON	OSM-границы районов, контекстные school POI и необязательная подложка улиц
API	Python 3.12, FastAPI, Pydantic, Uvicorn	Каталог, сессии, проверка и сохранение решений, расчёт, карта и объяснения
Хранение	PostgreSQL 16, SQLAlchemy 2, psycopg 3, Alembic	Версии набора, сценарии, расчёты, AI-объяснения и миграции
Запуск / CI	Docker Compose v2, GitHub Actions, pytest, Playwright	Повторяемый локальный запуск, проверки backend/frontend и сборка
AI	OpenAI Responses API; необязательный MiroFish gateway	Качественное объяснение рассчитанного backend результата

Поток расчёта:

React UI → FastAPI → проверка бюджета/правил → Python scoring → сохранённый результат
                                                        └→ AI explanation (optional)

Основные файлы: frontend/src/App.tsx и frontend/src/SimulatorWorkspace.tsx — интерфейс; backend/app/api/simulator.py — сценарии и API; backend/app/services/scenarios.py — правила плана; backend/app/services/scoring.py и backend/app/services/results.py — численный расчёт; backend/app/services/llm.py — AI; backend/app/models.py и backend/migrations/ — хранение и схема БД.

Формула модели astana-qol-v1 описана в datadoc.md:

применённый эффект = полный эффект × (8 − лаг кварталов) / 8
оценка района = Σ(вес показателя × значение показателя)
D_avg = Σ(доля населения района × оценка района)
Score = 0.7 × D_avg + 0.3 × min(оценки районов) − N_crit

N_crit — количество значений «район × показатель» ниже 40. Показатели ограничиваются диапазоном 0–100; итоговый Score формулой снизу не ограничивается и теоретически может быть отрицательным. AI получает рассчитанные числа, компромиссы и решения; вычисления остаются в Python.

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

Нужны Git, Docker Engine/Desktop и Docker Compose v2.

git clone https://github.com/BAITC-Hacks/hack-3f85346f-stikerai.git
cd hack-3f85346f-stikerai
cp .env.example .env
docker compose up --build -d --wait

На Windows PowerShell вместо cp используйте Copy-Item .env.example .env. Compose запускает PostgreSQL, миграции и seed синтетического датасета, затем API и Vite frontend.

• Приложение: http://localhost:5173
• Симулятор в Akim workspace: http://localhost:5173/simulator
• FastAPI / Swagger: http://localhost:8000/docs
• Health: http://localhost:8000/api/health

Для детерминированного расчёта ключи не нужны. Для AI-объяснения задайте OPENAI_API_KEY и OPENAI_MODEL в .env, затем пересоздайте backend:

docker compose up -d --force-recreate backend

OPENAI_BASE_URL и OPENAI_TIMEOUT_SECONDS настраивают API endpoint и timeout. VITE_MAP_STYLE_URL задаёт публичный стиль слоя улиц, VITE_MAP_TILE_URL — тайлы школьного контекста. Эти map-переменные видны браузеру; не размещайте в них секреты. MIROFISH_ENABLED по умолчанию false; для адаптера требуется отдельный защищённый gateway. Все параметры и локальные значения находятся в .env.example.

Логи и остановка:

docker compose logs backend frontend db migrate seed
docker compose down

PostgreSQL хранится в volume postgres_data; docker compose down сохраняет его. Для чистой локальной демонстрационной БД можно выполнить docker compose down -v — эта команда удаляет volume с данными.

Пример проверки

Проверьте доступность API:

curl -fsS http://localhost:8000/api/health

Ожидаемый ответ:

{"status":"ok","service":"stikerai-backend"}

В интерфейсе нажмите Enter Command Center и соберите контрольный план из набора astana-synthetic-v1:

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

Backend должен принять план стоимостью 95 из 100 и показать контрольный расчёт: базовый Score 52.55768, итоговый 56.54307, критические показатели — с 2 до 0. Это тестовый результат синтетической формулы, не оценка реального воздействия.

Backend-проверки на запущенном Compose:

docker compose exec backend python -m pytest -q

Для browser E2E на хосте нужны Python 3.12, Node.js 22.12+ и Chromium. Команда запускает изолированный тестовый API и frontend; AI-запросы не требуются.

cd backend
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
cd ../frontend
npm ci
npx playwright install chromium
PATH="../backend/.venv/bin:$PATH" npm run test:e2e

Сборка frontend:

cd frontend
npm ci
npm run build

npm run build сначала запускает prebuild: скрипт получает историю веток с Git remotes и блокирует сборку, если текущий checkout отстаёт от какой-либо удалённой ветки. Для этого шага требуется Git remote и сеть. CI дополнительно проверяет генерацию типов, backend-тесты на SQLite/PostgreSQL, frontend build и Docker Compose.

Данные и внешние сервисы

Источник	Где используется	Статус и границы
backend/data/astana-v1.json, datadoc.md	Бюджет, районы, индикаторы, меры, эффекты и Score	Синтетический учебный набор; не официальная статистика и не прогноз
OpenStreetMap relations	Геометрия шести районов на карте	Снимок от 2026-09-23; community mapping, не кадастровая или официально подтверждённая граница. Лицензия ODbL и attribution показаны в UI
OpenStreetMap через Overpass	171 точка в снимке объектов, помеченных amenity=school	На 2026-09-22; могут быть неполные, устаревшие или неверно размеченные записи, включая колледжи/дошкольные объекты. Только поиск кандидатов; не официальный реестр
OpenFreeMap и OSM tile service	Необязательные веб-подложки улиц	Загружаются браузером; требуют сети и зависят от условий/доступности поставщика. Границы и интерактивные списки остаются полезны без подложки
OpenAI Responses API	Необязательное текстовое объяснение	Реальный внешний запрос только с серверными OPENAI_API_KEY и OPENAI_MODEL; численная модель остаётся в backend
MiroFish gateway	Необязательный адаптер	Выключен по умолчанию; не собирает посты или сообщения из соцсетей
Citizen fixtures / localStorage	Петиции, сигналы, community activity	Вымышленные локальные данные, не реальные голоса или финансирование
Open-Meteo fixture в backend/data/enrichment/	Исследовательская фикстура	Снимок прогноза хранится с provenance; текущий интерфейс не использует его для показателей или Score
YouTube livestream	Видеоконтекст	Загружается только по нажатию; видео не анализируется

Геоданные, происхождение карты и crosswalk описаны в docs/interactive-map.md, исследование источников — в sources.md и плане обогащения. Официальные источники по транспорту, школам, безопасности, воздуху и городским активам пока не подключены как проверенные слои показателей.

Известные ограничения

• Реальные городские результаты нельзя выводить из синтетических метрик, условных цен и модельных эффектов.
• Пять синтетических профилей не имеют подтверждённого crosswalk к шести картографическим районам; совпадение названий не используется для окрашивания районов по Score.
• OSM не заменяет официальный перечень школ, полевую проверку или инженерный аудит. В текущем продукте нет дорожных замеров, аварийных точек, вместимости школ, локальных показателей воздуха или реальных данных обращений.
• Civic workspace демонстрационный: действия жителей хранятся в браузере, не синхронизируются между людьми, петиции не имеют юридического эффекта, платежи не проводятся.
• AI может быть не настроен; без ключа недоступно только внешнее текстовое объяснение. AI не подтверждает факты и не доказывает причинность.
• Стандартные OSM/OpenFreeMap подложки зависят от внешней сети и политики поставщика; для production требуется выбранный провайдер или собственный tile-сервис. Публичный deployment в репозитории не указан.
• Compose настроен для разработки: используются Vite dev server и auto-reload. Production-конфигурация, HTTPS, аутентификация пользователей и эксплуатационная поддержка не входят в этот прототип.

Развёрнутая версия и документация

Публичная развёрнутая версия в репозитории не указана. Чтобы воспроизвести проект, используйте Docker Compose выше.

• PRD хакатона и DataDoc модели
• Архитектура и использование карты
• AI-объяснения
• Интеграционные API и сценарии
• Источники данных
• Исследование обогащения