BesSheshim

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

Демо за 60 секунд · Docker · Локальная разработка · Формула · Статус

BesSheshim за 20 секунд

Вы делаете	Город показывает	Вы понимаете
Выбираете ровно 5 из 14 инициатив в пределах 100 единиц бюджета	Карту районов, показатели качества жизни и итоговый Score	Какие районы выиграли, какие проблемы остались и за что пришлось заплатить

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

Главная страница

_{Первый экран: задача и правила понятны до начала игры.}

_{Ниже на главной: как продукт помогает увидеть эффект и объяснить результат.}

Экран симулятора

_{Рабочий экран: слева — каталог из 14 инициатив по категориям, в центре — карта районов с индексом качества жизни, справа — выбранный район и план из пяти решений в пределах бюджета 100 единиц.}

Демо за 60 секунд

1. Откройте http://localhost:3000 и нажмите «Начать игру». На старте у города 2 критических показателя в Нуре; базовый Score по проверенной модели — 52,57.
2. Добавьте пять мер в указанном порядке: M7 «Школа + детсад» → Нура, M8 «Поликлиника» → Нура, M10 «Освещение и камеры» → Нура, M12 «Платформа обращений» → весь город, M5 «Чистое топливо» → Сарыарка.
3. В панели «Ваш план» проверьте бюджет: 95 / 100. Нажмите «Посмотреть результат».
4. Проверенный сценарий даёт 56,49 (+3,92). Оба критических показателя Нуры выходят из красной зоны; сочетание M10 + M12 дополнительно улучшает безопасность Нуры. Разбор объясняет и оставшиеся слабые места: транспорт и экологию Нуры.

Это эталонный сценарий из контракта. Числа независимо воспроизводит scripts/verify.py и проверяют golden-фикстуры.

Как запустить

Для запуска без Docker нужны Go 1.26+ и Node.js 20.9+. Ключ LLM для демонстрации не нужен.

git clone https://github.com/BAITC-Hacks/hack-2e79658e-nosleep-dev.git
cd hack-2e79658e-nosleep-dev
cp .env.example .env
npm --prefix apps/web ci
make dev

Затем откройте http://localhost:3000. API доступен на http://localhost:8000/api/v1; проверка работоспособности — /health.

[!IMPORTANT] Фронтенд по умолчанию обращается к Go API через /api/v1/*. Для локальной разработки запустите API вместе с Next.js через make dev. Локальные демоданные включаются только при NEXT_PUBLIC_USE_MOCKS=true.

Docker: один контейнер

Docker-образ собирает Go API и production-сборку Next.js. Внутри контейнера работают оба процесса; наружу открыт только порт веб-приложения 3000. Запросы браузера к /api/v1/* Next.js перенаправляет на API внутри контейнера. Поэтому один и тот же образ работает на localhost, IP-адресе сервера или за обратным прокси без пересборки с новым адресом API.

Быстрый запуск

Установите Docker с плагином Compose и запустите из корня репозитория:

docker compose up -d --build --wait
docker compose ps
curl -f http://localhost:3000/api/v1/health

Откройте http://localhost:3000 и перейдите в симулятор. Ответ проверки API — {"status":"ok"}. --wait дожидается статуса healthy; запуск API может занять около полуминуты. Compose поднимает один сервис app; файл .env и ключ LLM для этого демо не требуются. При первом запуске Docker загрузит базовые образы, установит Go и npm-зависимости и соберёт оба приложения.

Без Compose

docker build -t bessheshim:local .
docker run --name bessheshim -d --restart unless-stopped -p 3000:3000 bessheshim:local
docker ps --filter name=bessheshim
curl -f http://localhost:3000/api/v1/health

Если проверка сразу после docker run ещё не отвечает, подождите, пока docker ps покажет (healthy), и повторите curl. Для остановки и удаления контейнера: docker rm -f bessheshim. Контейнер не использует базу данных или постоянный том; данные приложения и контрактные примеры входят в образ.

Порт и размещение на сервере

В Compose APP_PORT меняет порт хоста, а APP_BIND — адрес привязки. Например, если HTTPS завершает обратный прокси на том же сервере:

APP_BIND=127.0.0.1 APP_PORT=8080 docker compose up -d --build --wait
curl -f http://127.0.0.1:8080/api/v1/health

Направьте обратный прокси на http://127.0.0.1:8080 и передавайте через него все пути, включая /api/v1/* и /_next/*. Для прямого доступа с другой машины оставьте APP_BIND=0.0.0.0 (значение по умолчанию), откройте выбранный APP_PORT в сетевом экране и перейдите на http://IP_СЕРВЕРА:APP_PORT. Для публичного сайта настройте домен и HTTPS на обратном прокси. В варианте docker run порт меняется флагом -p 8080:3000.

Не меняйте внутренний API_PORT=8000 или PORT=3000: собранный Next.js направляет API-запросы на 127.0.0.1:8000, а Docker публикует порт 3000.

Обновление и диагностика

git pull
docker compose up -d --build --wait
docker compose logs -f app
docker compose ps
docker compose down

docker compose up -d --build --wait пересобирает образ из текущего кода, заменяет контейнер и дожидается его здоровья. В docker compose ps статус должен быть healthy: встроенная проверка обращается к /api/v1/health через Next.js и тем самым проверяет оба процесса. Если порт занят, задайте APP_PORT=8080. Если проверка не проходит, посмотрите docker compose logs app и убедитесь, что оба процесса запустились. При завершении одного из процессов контейнер останавливает второй, после чего Compose перезапускает сервис.

Образ собирается с NEXT_PUBLIC_USE_MOCKS=false и относительным адресом API /api/v1; эти значения в браузерном коде фиксируются во время сборки. Без ключа LLM API возвращает разбор с пометкой cached; при настроенном OPENAI_API_KEY он может вернуть живой AI-разбор.

Настройка AI-разбора (необязательно)

Для живого AI-разбора скопируйте .env.example в .env, заполните OPENAI_API_KEY, затем запустите docker compose up -d --build --wait. Compose передаёт в контейнер LLM_BASE_URL, OPENAI_API_KEY, LLM_MODEL, LLM_TIMEOUT_SECONDS и DEMO_MODE; .env не включается в образ и игнорируется Git. При DEMO_MODE=true, пустом ключе или ошибке провайдера API отдаёт разбор с пометкой cached. Для docker run добавьте --env-file .env перед именем образа. Внутренние API_PORT и PORT оставьте как в образе.

Как считается результат

Результат рассчитывается по открытой спецификации, на одинаковых исходных данных для каждого игрока:

$$ \text{Score} = 0.7 \cdot D_{avg} + 0.3 \cdot \min_d(D_d) - N_{crit} $$

Здесь D_avg — средний балл районов с учётом населения, min D_d — балл самого уязвимого района, N_crit — число показателей ниже 40. Формула учитывает не только общий рост, но и состояние самого слабого района. Эффекты инициатив учитывают задержку, а некоторые сочетания дают синергию.

Проверенный пример	До	После
Итоговый Score	52,57	56,49
Критические показатели	2	0
Бюджет	0 / 100	95 / 100

Данные и правила лежат в data/, а независимая реализация формулы — в scripts/verify.py. Реализованный AI-клиент получает готовые результаты для объяснения; он не рассчитывает Score.

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

Часть	Текущий статус
Главная и интерфейс симулятора	Запускаются локально; выбор инициатив, районов, бюджет и результат доступны в UI
Детерминированный движок Score	Реализован на Go в internal/scoring и покрыт golden-тестами
HTTP API	Маршруты подключены к движку Score; каждый набор решений рассчитывается по данным модели
AI-разбор	Go-клиент подключён к HTTP API; без ключа или при сбое LLM возвращается разбор с пометкой cached
Оптимум, сравнение, городские события	Optimizer и события подключены к API; сохранение и сравнение сценариев доступны в UI, события остаются в API

Это hackathon demo build. Для точной проверки модели используйте тесты и эталонный сценарий выше.

Архитектура

flowchart LR
    Player[Игрок] --> Web[Next.js интерфейс]
    Web --> API[Go + Gin API]
    API --> Engine[Движок Score на Go]
    API --> LLM[Go AI-клиент и cached fallback]
    Data[data/*.json] --> Engine
    Engine --> Tests[Golden-тесты и независимая проверка]

Контракт API — в contracts/api.md. Основные маршруты: GET /catalog, POST /simulate, POST /explain, GET /optimum, POST /compare, POST /events/draw.

Проверка

python3 scripts/verify.py
cd apps/api && go test ./...

Ожидаемые опорные значения: BASE Score=52.5650, EX Score=56.4851. Go-тесты проверяют scoring, HTTP, LLM-клиент, optimizer и события. Проверены npm run lint и npm run build для веб-приложения.

Команда

NoSleep.dev · BAITC Hackathon 2026 · Астана, Казахстан

BesSheshim — «Аким на 5 часов». Пять решений. Один город.