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

Симулятор управления Астаной для спецтрека Astana Innovations: пять решений, бюджет 100, пять районов. Соберите план и узнайте, как он меняет качество жизни и положение самого слабого района.

Открыть демо · Swagger демо · Контракт API · Сторонние компоненты

Быстрый старт: после клонирования репозитория запустите docker compose up --build и откройте localhost:3000. По умолчанию используется mock: ключ OpenAI не нужен. Настройки и подробные команды — в разделах 4–7.

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

1. Описание и назначение

Пользователь выбирает ровно пять из 14 мероприятий на горизонте восьми кварталов. Все начинают с одного синтетического датасета организаторов: пять районов, доли населения и десять показателей по шкале 0–100. Большее значение всегда лучше.

Маршрут приложения:

1. Обзор (/): исходные показатели, бюджет, правила и модель города.
2. Решения (/decisions): каталог, выбор районов, стоимость и причины недоступности мер.
3. Результат (/results): Score до/после, районные баллы, изменения показателей, расходы, сильные стороны и риски. Здесь же доступны альтернативные планы и сравнение двух последних успешных попыток.

Интерфейс доступен на русском, казахском и английском, с темами «День», «Ночь», «Бумага» и поддержкой уменьшенного движения. Трёхмерная сцена включает Байтерек, EXPO, Хан Шатыр, мечеть, монумент и мосты. Геометрия и размещение условные: это иллюстрация, а не географическая карта или источник числовых показателей.

На узком экране район выбирается через карточки и схему, колонка 3D скрыта. На широком экране при экономии трафика или недоступном WebGL показывается подписанный снимок модели. Черновик плана сохраняется в текущей вкладке. После полной перезагрузки результат нужно рассчитать снова — серверной истории и базы данных в MVP нет.

2. Архитектура и расчёт

Браузер: Next.js / React
  ├─ GET  /api/scenario
  ├─ POST /api/simulations/evaluate
  └─ POST /api/simulations/alternatives
           ↓
C# Minimal API: проверка → расчёт → объяснение
  ├─ единый датасет и детерминированная модель
  └─ mock или OpenAI Responses API с резервным mock

Браузер обращается к API через NEXT_PUBLIC_API_URL. Локально это прямые запросы на порт 8080 с CORS; на Brev nginx объединяет сайт и API под одним HTTPS-адресом. Next.js rewrites и отдельный API_INTERNAL_URL не нужны.

Только C# рассчитывает итоговые числа. Интерфейс предварительно считает стоимость и количество выбранных мер, а также вычитает полученные «после − до» для показа изменений.

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

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

1. Применить эффекты мер с долей реализации (8 − лаг) / 8, затем фиксированные бонусы синергии.
2. Ограничить показатели диапазоном 0–100.
3. Рассчитать районные баллы по весам десяти показателей и средний городской балл по долям населения.
4. Рассчитать Score = 0,7 × средний балл + 0,3 × балл худшего района − количество значений показателей ниже 40 по всем районам.

Промежуточные значения не округляются; API округляет числа ответа до двух знаков. Исходные данные находятся в ScenarioData.cs, алгоритм — в ScoreCalculator.cs.

Роль AI. В режиме live сервер отправляет проверенные утверждения в OpenAI Responses API. Модель определяет их приоритет; итоговые тексты, переводы и рекомендации формирует сервер. Модель не рассчитывает Score и не сочиняет показатели. В режиме mock, а также при ошибке или некорректном ответе модели, сервер возвращает шаблонное объяснение с теми же рассчитанными числами. UI различает «AI-анализ» и «Шаблонное объяснение». Свободный чат и поиск глобально оптимального плана в MVP не реализованы.

Язык объяснения задаётся Accept-Language: ru-RU / kk-KZ / en-US; фактический язык возвращается в explanationLocale и Content-Language. Смена языка интерфейса не вызывает платный запрос автоматически: объяснение обновляется отдельной кнопкой.

На результате кнопка поиска вызывает POST /api/simulations/alternatives: сервер перебирает замены одной меры по целям Score, помощь слабейшему району и экономия, проверяет допустимость и рассчитывает последствия. AI может выбрать вариант и аргументы из проверенного набора. Это ограниченный поиск, а не глобальная оптимизация. Совпавшие стратегии не выдаются за разные планы; отсутствие улучшения показывается явно. «Применить» переносит пять мер в конструктор, а повторная оценка выполняется отдельным нажатием. История двух успешных планов хранится в памяти вкладки и очищается при перезагрузке или сбросе.

backend/                .NET API, датасет, расчёт и серверные проверки
frontend/app/           страницы /, /decisions, /results
frontend/features/      обзор и 3D, конструктор, результат, альтернативы, состояние
frontend/components/    общие компоненты интерфейса
frontend/lib/           API-клиент, контракты, форматирование и локализация
frontend/public/        логотип, favicon, снимки модели
frontend/tests/         frontend-тесты
frontend/docs/reports/  отчёты UI, интеграции и готовности релиза
docs/api.md             сетевой контракт и примеры
docs/reference/         исходные материалы задания

3. Технологии и команда

Часть	Технологии
Frontend	Next.js 16.3.6, React 19.2.8, TypeScript, CSS Modules
Визуализация	Three.js 0.186, собственные процедурные модели и SVG
Backend	.NET 8 / ASP.NET Core Minimal API, Swashbuckle / Swagger
Объяснение	OpenAI Responses API через HttpClient; необязательный внешний сервис
Запуск	Docker Compose, Node.js 22 и .NET 8 контейнеры
Публикация	NVIDIA Brev, nginx, HTTPS Secure Link

Фронтенд и интеграция — Hizeshi; C# API — Тамерлан (TamerlanWebd); сервер и DevOps — Кирилл. Зависимости, лицензии и назначение компонентов раскрыты в THIRD_PARTY.md.

4. Требования

Для запуска достаточно Docker Engine / Docker Desktop и Docker Compose v2, доступа к интернету при первой сборке и свободных портов 3000 и 8080. На Windows используйте WSL Ubuntu с включённой интеграцией Docker Desktop. Команды ниже предназначены для Bash в WSL/Linux.

Установка Node.js и .NET на хост не требуется для Docker. Для разработки и тестов без контейнеров нужны Node.js 22, npm и .NET 8 SDK. Для серверного compose-файла требуется Compose 2.24.4+, поддерживающий !override.

5. Установка

git clone https://github.com/BAITC-Hacks/hack-4c816c70-team.git
cd hack-4c816c70-team
cp .env.example .env

Настройки из примера запускают mock без ключей. Файл .env не добавляется в Git. Не копируйте в него чужой ключ и не передавайте секреты через NEXT_PUBLIC_*: эти переменные доступны браузеру.

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

Переменная	Значение по умолчанию / назначение
API_PORT	8080, порт API на хосте
FRONTEND_PORT	3000, порт сайта на хосте
GATEWAY_PORT	8000, только для серверного nginx
FRONTEND_ORIGIN	Пусто: http://localhost:<FRONTEND_PORT>; разрешённые CORS origins через запятую
NEXT_PUBLIC_API_URL	http://localhost:8080; адрес API для браузера, встраивается при сборке
ASPNETCORE_ENVIRONMENT	Production
LLM_MODE	mock без внешних запросов; live для OpenAI
OPENAI_API_KEY	Пусто; нужен только для live, только на сервере
OPENAI_MODEL	Пусто; для live укажите доступную модель, команда использует gpt-4o-mini
OPENAI_BASE_URL	Пусто: стандартный OpenAI API; можно задать совместимый адрес для тестирования

При изменении API_PORT обновите и NEXT_PUBLIC_API_URL. После изменения адреса API необходима пересборка frontend. Для включения модели заполните серверные LLM_MODE=live, OPENAI_API_KEY, OPENAI_MODEL и пересоздайте API: docker compose up -d api.

7. Запуск и публикация

Из корня репозитория:

docker compose up --build

После сборки откройте сайт, Swagger и health. Обе службы должны стать healthy:

docker compose ps
curl --fail http://localhost:8080/health
docker compose logs --tail=100 api frontend

Команды проверки выполняйте во втором терминале. Для фонового запуска: docker compose up --build -d --wait. Остановка: docker compose down. Базы данных и тома с результатами нет.

На сервере Brev из согласованной рабочей копии запускайте:

docker compose -f docker-compose.yml -f docker-compose.brev.yml up --build -d --wait

В Secure Link укажите HTTP-порт 8000. nginx направляет /api/, /health, /swagger в C# API, остальные запросы — во frontend. Серверный compose задаёт относительный NEXT_PUBLIC_API_URL=/; временный Cloudflare-туннель для такого запуска не нужен. Порты 3000 и 8080 привязаны к loopback, HTTPS обслуживает Brev.

docker compose -f docker-compose.yml -f docker-compose.brev.yml ps
curl --fail http://127.0.0.1:8000/health

Обновляйте только чистую согласованную копию: git fetch origin, проверка изменений, git pull --ff-only, затем сборка. Записывайте SHA исходников и фактически запущенных образов обоих сервисов; git push сам по себе сайт не обновляет. Сохраняйте действующую серверную конфигурацию и права доступа. На текущем стенде API и frontend запускались из разных каталогов — не выполняйте обновление из случайного старого checkout с тем же Compose project. Точное состояние и оставшиеся шаги — в отчёте готовности.

После обновления проверьте, что Swagger содержит /api/simulations/alternatives. Если там есть только scenario и evaluate, работает старая версия API; обновление только frontend не включит альтернативы.

Если запуск не удался:

• Порт занят — измените порты в .env, согласуйте адрес API и повторите сборку.
• Failed to fetch / CORS — проверьте API из браузера и точный FRONTEND_ORIGIN, включая схему и порт; localhost и 127.0.0.1 различаются.
• Сайт показывает старую версию — проверьте SHA контейнера и пересборку, затем обновите страницу.
• Вместо 3D виден снимок — прочитайте подпись и попробуйте «Запустить 3D»; ограничения WebGL не мешают оценке плана.
• Модель недоступна — числовой результат сохраняется, источник объяснения меняется на mock.

8. Проверка и демонстрация

Контрольный план: M7 → Нура, M8 → Нура, M10 → Нура, M12 → город, M5 → Сарыарка. Ожидаемый результат: 52,56 → 56,54, расходы 95, остаток 5.

curl --fail-with-body http://localhost:8080/api/simulations/evaluate \
  -H 'Content-Type: application/json' \
  -H 'Accept-Language: ru-RU' \
  --data '{"choices":[{"measureId":"M7","districtId":"nura"},{"measureId":"M8","districtId":"nura"},{"measureId":"M10","districtId":"nura"},{"measureId":"M12"},{"measureId":"M5","districtId":"saryarka"}]}'

Повторите с kk-KZ и en-US: числа должны совпасть, язык объяснения — измениться. Невалидный набор:

curl -i http://localhost:8080/api/simulations/evaluate \
  -H 'Content-Type: application/json' --data '{"choices":[]}'

Ожидается HTTP 400 с code: WRONG_CHOICE_COUNT, без Score. Остальные коды, схемы и примеры — в контракте API.

Для короткого демо откройте обзор, соберите контрольный план, покажите результат и изменения Нуры. Затем измените район M5 на Алматы и оцените заново: Score меняется на 56,58 при тех же расходах 95. Покажите переключение языка и честное обозначение источника объяснения.

Для демонстрации альтернатив вернитесь к исходному контрольному плану и выберите цель Score: лучшая найденная замена M5 Сарыарка → M3 Нура даёт 57,21 при расходах 100. Цель экономии предлагает M5 Сарыарка → M11 Нура: 56,69 при расходах 80, с потерями для Сарыарки. Примените вариант, явно оцените его и покажите сравнение попыток. Эти значения проверены на API из репозитория; доступность нового экрана на публичном демо зависит от версии деплоя.

План	Расходы	Остаток	Score
Контрольный: M7, M8, M10 в Нуре; M12 город; M5 Сарыарка	95	5	56,54
В контрольном плане заменить M5 Сарыарка на M3 Нура	100	0	57,21
В контрольном плане заменить M5 Сарыарка на M11 Нура	80	20	56,69

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

cd frontend
npm ci
npm run lint
npm test
npm run build
npm run typecheck
cd ..

Проверки backend:

dotnet run --project backend/CitySimulator.RegressionTests -c Release
node backend/tests/api-regression.mjs http://localhost:8080

HTTP regression требует отдельный запущенный тестовый API в режиме mock и делает более 500 запросов; не направляйте его на публичное демо с платной моделью. Подробности — в инструкции тестов.

Проверка	Подтверждённый результат
Frontend на коде 7073164	74/74 теста, lint, production build и typecheck
Клавиатура на 7073164, локально, 390 px	Добавление/удаление сохраняют фокус; первая, последняя и единственная строки; Escape возвращает фокус на корзину. Повторно проверено Claude 2 без POST
Новый backend, Docker	45/45 C# и 45/45 HTTP-проверок, 400 наборов и 120 перестановок; альтернативы включены
Чистый Compose на Brev	6929bf4, оба контейнера healthy, без ключей; этот прогон предшествовал последнему UI альтернатив
Полный сценарий из чистого клона, отчёт Тамерлана	88a0c8c: 110/110 браузерных проверок; план → результат → альтернативы → применение → отдельная оценка → сравнение; mock без ключа
Последующая приёмка, отчёт Тамерлана	7c0570e: 31/31 проверка пустого HTTP 503, повторов и мобильного обзора; на 7073164 повторно прошла production-сборка Docker
Настоящий AI, отчёт Тамерлана	Один запрос альтернатив: HTTP 200, recommendation.source=llm, исходный план 56,54 / 95 → совет 57,21 / 100
Firefox 156 / Intel Arc	Живая 3D-сцена, выбор районов и возврат со страницы решений; публичный frontend 631efbb

Подробности и границы проверки — в независимом отчёте, приёмке отчётов и финальной интеграции Тамерлана, включая машинные отчёты и скриншоты. Интегратор проверял Docker на Brev, Тамерлан — отдельный локальный Docker-стек; это разные стенды. Физические мобильные устройства и скринридер не проверены. Локальная приёмка не подменяет проверку нового публичного деплоя.

Готовность релиза и ограничения проверок · Отчёт по 3D · Отчёт по сценарию · Серверная регрессия