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

Три варианта исполнения проекта

У проекта три варианта исполнения, размещённые в отдельных ветках:

Вариант	Назначение	Ссылка
1. Основная версия — main	Актуальный MVP: 3D-город на Three.js, выбор инициатив, расчёт Score и AI-анализ. Поддерживает локальный запуск и Cloudflare Worker.	Открыть ветку main
2. Концептуальная версия — concept/isometric-city-sim	Отдельная ветка концепции изометрического городского симулятора. Состояние и команды запуска смотрите в этой ветке.	Открыть концептуальную ветку
3. Альтернативная версия — feature/city-team-scenarios	Отдельный вариант проекта в ветке командных городских сценариев. Состояние реализации и команды запуска смотрите в этой ветке.	Открыть ветку city-team-scenarios

Инструкции ниже относятся к основной версии в ветке main.

Что решает

Симулятор городских решений: распределите ограниченный бюджет между инициативами для условных районов Астаны, получите рассчитанный Astana Quality of Life Score и объяснение компромиссов от AI.

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

• Общие для всех пользователей бюджет 100 и синтетические показатели пяти районов, 14 мероприятий (полные исходные данные — docs/data-set.md и docs/data-set.json, рабочие данные backend — apps/backend/db.json).
• Выбор ровно пяти мер, проверка районов, повторов, ограничений по направлениям, несовместимостей и бюджета.
• Детерминированный расчёт показателей и Score по сокращённому apps/backend/db.json, сверяемому с docs/data-set.json: лаги, синергии, слабейший район и штраф за значения ниже 40.
• Серверный вызов OpenAI для объяснения уже рассчитанного результата. Если ключа нет или API недоступен, Score остаётся доступен, а ошибка AI показана явно.
• Тёмный экран симулятора: процедурный 3D-город на Three.js с рекой, мостами, кварталами и деревьями; каталог мероприятий, план на пять мер и результат. Вращение — перетаскиванием, масштаб — колёсиком. Это иллюстративная модель, не географически точная карта Астаны. При недоступном WebGL остаются кнопки выбора районов.
• Выбранные инициативы сразу подсвечивают условные участки и здания: районные — в назначенном районе, городские — во всех пяти. Цвет показывает направление; открытая инициатива выделяется голубым. Нажмите на значок меры или «На карте» в каталоге, чтобы увидеть её название, стоимость и лаг. При смене района, удалении или сбросе отметки обновляются; мера без назначенного района не получает случайное место на карте. Подсветка обозначает выбор в плане, а не факт строительства или уже рассчитанный эффект.
• Предупреждающие тосты сообщают о неполном плане, превышении бюджета, выборе районной меры без района и ошибках API/AI. Сообщение можно закрыть вручную; оно исчезает через 8 секунд, таймер приостанавливается при наведении или фокусе. Ошибки расчёта также остаются в форме.

Архитектура

React SPA (apps/frontend/) запрашивает каталог через GET /api/simulator и отправляет пять объектов { "measureId": "M7", "district": "Нура" } в массиве decisions через POST /api/simulator. Локально HTTP обслуживает Express, на Cloudflare — apps/backend/cloudflare.ts. Оба используют общий валидатор, расчёт из features/simulator/service.ts и OpenAI-интеграцию. Данные apps/backend/db.json импортируются и включаются в сборку. LLM получает стоимость, остаток бюджета, эффекты и готовые выводы о районах; не рассчитывает Score. Сценарии не сохраняются. База данных и миграции не нужны.

React / Three.js → Express validator → deterministic Score → OpenAI → explanation
                                           ↑
                                   apps/backend/db.json

Технологии

React 19 + TypeScript + Webpack 5 — интерфейс; Express 5 + TypeScript — API и расчёт; OpenAI Responses API (gpt-4o-mini) — текстовое объяснение; Yarn Classic workspaces — зависимости и запуск.

Изображения инициатив

Подготовленные командой PNG находятся в apps/frontend/public/initiatives/. Карточки используют уменьшенные WebP-копии 256×256 из подпапки optimized/, а при их отсутствии загружают исходный PNG. Все 14 иллюстраций включаются в сборку локально, без зависимости от внешнего хостинга. SVG-рисунки в карточках заменены растровыми изображениями.

Портреты akim.png и advisor-social.png, advisor-transport.png, advisor-environment.png находятся в той же папке. Карточки используют WebP-копии 192×256 с резервной загрузкой исходного PNG. Стрелки и точки в карточке советника переключают портрет, подпись и подсказку вместе.

Шрифты

Основной шрифт — Outfit для латиницы и цифр; кириллицу, отсутствующую в Outfit, отображает Inter. Оба шрифта хранятся локально в WOFF2: внешнего подключения к Google Fonts при запуске нет. Обычный текст имеет вес 300, выделения — 400, основные заголовки и числовые акценты — максимум 500. Источники и лицензия SIL OFL находятся в apps/frontend/app/shared/assets/fonts/.

Требования

Рекомендуем Node.js 24 LTS и Yarn Classic 1.22.22 (проверенная среда: Node.js 24.19.0). Минимум по проекту — Node.js 22.18.0. Нужен современный браузер с WebGL2 для 3D-карты; при недоступном WebGL остаются выбор районов и расчёт.

Для AI нужен интернет и ключ OpenAI API с доступом к gpt-4o-mini и оплаченной API-квотой (подписка ChatGPT не заменяет API-квоту). Для расчёта Score ключ не требуется. Установка зависимостей требует доступа к реестру пакетов.

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

Если Yarn отсутствует, после установки Node.js выполните npm install --global [email protected]. Все команды ниже выполняются из корня репозитория; не запускайте отдельный yarn install внутри apps.

git clone https://github.com/BAITC-Hacks/hack-30aab437-skynomads.git
cd hack-30aab437-skynomads
yarn install --frozen-lockfile

Создайте конфигурацию:

PowerShell (Windows):

Copy-Item apps/backend/.env.example apps/backend/.env

macOS/Linux:

cp apps/backend/.env.example apps/backend/.env

Откройте apps/backend/.env в редакторе, замените значение OPENAI_API_KEY собственным ключом. Не отправляйте его в чат или Git. Для проверки без AI оставьте значение пустым. Затем из корня:

yarn start

Откройте http://localhost:3000; backend работает на http://localhost:7000. Webpack проксирует /api в Express. Остановить оба сервера — Ctrl+C.

Запуск готовой сборки (рекомендуется для демо)

yarn verify
yarn serve

Откройте http://localhost:7000 — Express раздаёт и собранный интерфейс, и API с одного адреса. Предварительная сборка обязательна. Это локальный запуск, не развёртывание на внешний хостинг. yarn start — режим разработки на 3000, yarn serve — запуск собранного проекта на 7000.

Конфигурация

Переменная (apps/backend/.env)	Назначение	Пример в .env.example
OPENAI_API_KEY	Реальный вызов AI; без неё Score считается, AI возвращает явную ошибку	replace-with-your-openai-api-key
PORT	Порт backend	7000
NODE_ENV	Режим backend	development

.env игнорируется Git. Шаблонные auth/blog/media-маршруты отключены: JWT, SMTP и отдельные учётные записи для симулятора не нужны. Если меняете PORT, для разработки потребуется согласовать target прокси в apps/frontend/webpack.config.cjs; в режиме yarn serve достаточно открыть новый порт.

Проверка основного сценария

1. Откройте «Решения» в боковой навигации и нажмите «Загрузить демо-набор» в панели «План города». Выбраны M7/Нура, M8/Нура, M10/Нура, M12/весь город, M5/Сарыарка. Альтернативно нажимайте на район на условной карте и добавляйте меры из каталога справа, затем при необходимости уточняйте район в плане. Можно закрыть панель, чтобы увидеть подсветку: три районные меры в Нуре, одну в Сарыарке и пять отметок городской M12. Для расчёта снова откройте «Решения» или нажмите кнопку ▶ вверху. Стоимость M12 учитывается один раз.
2. Нажмите «Рассчитать результат». Стоимость 95, остаток 5, исходный Score 52.56, новый Score 56.54 (до округления 56.5431), срабатывает синергия M10 + M12. Откроется AI-отчёт; его можно закрыть крестиком или Escape. Показатели направлений внизу — средние арифметические значений направления по районам, отдельно от взвешенного итогового Score.
3. При корректном OPENAI_API_KEY дождитесь AI-объяснения сильных сторон и рисков. Без него интерфейс покажет сообщение об отсутствии конфигурации рядом с рассчитанными числами.
4. Уберите одну меру из плана и повторите расчёт: получите сообщение «Выберите ровно 5 мероприятий» без нового Score. Если сумма выбранных мер превысит 100, отправка будет заблокирована; сервер также отклоняет такие запросы.

Проверки кода:

yarn verify

Команда последовательно запускает backend-тесты (включая HTTP-проверки), TypeScript и production build. Отдельно доступны yarn test, yarn typecheck, yarn build. Автотесты OpenAI подменяют HTTP только внутри тестов и не расходуют квоту; приложение использует настоящий API. Сценарий демонстрации и чек-лист сдачи — docs/submission.md.

После сборки можно автоматически проверить запущенное приложение:

yarn smoke
yarn smoke --live

Первая команда запускает встроенный сервер на свободном порту, проверяет UI/ресурсы, API и обработку отсутствующего ключа, не обращаясь к OpenAI. --live делает один реальный платный API-вызов с ключом из backend .env и проверяет наличие объяснения. Обе команды сами останавливают свой проверочный сервер.

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

• Порт занят: остановите предыдущий экземпляр проекта; не запускайте yarn start и yarn serve одновременно на одном backend-порту.
• Не удалось загрузить каталог: убедитесь, что Express работает на 7000. В production открывайте 7000, а не отдельный статический сервер фронтенда на 5000.
• Ошибка AI / ключ отклонён: проверьте apps/backend/.env, доступ к модели и API-баланс, затем перезапустите backend. Результат Score не теряется; готового ответа вместо AI нет.
• Установка отклонена из-за Node: используйте Node 24 LTS и Yarn 1.22.22; не смешивайте npm install и yarn install.
• 3D недоступно: разрешите аппаратное ускорение/попробуйте современный браузер; резервные кнопки выбора работают без WebGL.

Ограничения

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

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

Шаблонные auth/blog/media-файлы сохранены, но их маршруты не подключены. Backend использует apps/backend/db.json; при изменении полного набора в docs/data-set.json синхронизируйте рабочую копию — это проверяет тест. Webpack предупреждает о размере Three.js и исходных PNG; миниатюры в UI загружаются из оптимизированных WebP. Конфиги Vercel унаследованы от шаблона; актуальная конфигурация Cloudflare — wrangler.jsonc. Статус фактической публикации смотрите в журнале релиза, наличие конфига не означает успешный deploy.