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

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

Городскому управленцу нужно одновременно развивать транспорт, озеленение, социальную инфраструктуру, безопасность и сервисы — при ограниченных ресурсах. Наш симулятор помогает управленцам, аналитикам и участникам игры сравнить последствия решений: кому станет лучше, какие проблемы останутся и чем придётся пожертвовать.

Кейс и критерии хакатона · Датасет · Архитектура · Развёртывание

Что умеет

Требование кейса	Реализация
Одинаковые стартовые условия	Бюджет 100, пять районов, десять показателей, единый синтетический датасет
Пять управленческих решений	Каталог 14 инициатив по всем пяти направлениям; выбор района для адресных мер
Контроль бюджета	Проверки стоимости, количества и совместимости мер в интерфейсе и повторно на сервере
Итоговый Astana Quality of Life Score	Воспроизводимый расчёт, графики «до/после», вклад мер и критические показатели
AI-анализ и объяснение компромиссов	Главный вывод, сильные стороны, риски, рекомендации, основания расчёта и источники

Дополнительно: интерактивная карта, чат с советником, веб-поиск мировых практик, сохранение сценария вместе с итоговым AI-разбором и восстановление черновика.

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

Стек

Слой	Технологии
Приложение и API	Next.js 16 App Router, React 19, TypeScript, Route Handlers, Zod
Интерфейс	Tailwind CSS 4, Radix/shadcn-паттерн, Lucide, Recharts, SVG-карта
AI	OpenAI SDK, Responses API, gpt-6-astra, reasoning medium, веб-поиск
Данные	SQLite локально; адаптер Neon PostgreSQL для облака; localStorage для черновика
Облачный запуск	Подготовлены Netlify и фоновая функция для AI-задач
Проверки	Vitest, Playwright/Chromium, независимая проверка датасета на Python

Точные версии и команды — в package.json. Публичный деплой и подключение живой Neon пока не подтверждены в материалах репозитория; порядок проверки — в инструкции публикации.

Как это работает

1. Пользователь выбирает инициативы и районы. Интерфейс сразу показывает расход и предварительные изменения.
2. Сервер проверяет выбор и заново вычисляет результат единым TypeScript-движком — стоимость и Score из браузера не принимаются на доверии.
3. По запросу пользователя AI исследует внешний контекст и объясняет серверный отчёт. Числовые основания выводятся из расчёта; мировой опыт не меняет коэффициенты модели.
4. Сценарий и готовое объяснение сохраняются для повторного просмотра без новой генерации.

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

Эффект меры = полный эффект × (8 − срок реализации в кварталах) / 8
Score = 0.7 × средний индекс с учётом населения
      + 0.3 × индекс слабейшего района
      − число показателей ниже 40

Так итог учитывает и общий прогресс, и положение слабейшего района. Подробные правила — в датасете, реализация — src/engine. Движок отделён от AI: отказ модели не блокирует расчёт.

Локальный запуск

Нужны Node.js 22.20+ и npm; используемый менеджер — npm 11.20.0.

git clone https://github.com/BAITC-Hacks/hack-4078ad52-mama-papa-and-me.git
cd hack-4078ad52-mama-papa-and-me
npx --yes [email protected] ci
npm run dev

Откройте 127.0.0.1:3000. Без ключа работают симуляция, отчёт и SQLite; вместо AI показывается явно обозначенное шаблонное объяснение. Для production-режима остановите dev-сервер и выполните npm run build, затем npm start.

Чтобы включить настоящий AI: создайте .env по .env.example, если файла ещё нет, заполните OPENAI_API_KEY и перезапустите сервер. Локально оставьте DEPLOY_TARGET=local и пустой DATABASE_URL. Нужны интернет и доступ к указанной модели. AI_ENABLED=false отключает платные вызовы.

Ключ хранится только на сервере. AI запускается по вопросу или кнопке разбора; подбор мер не расходует API-баланс. На настроенном облачном сайте посетителю собственный ключ не нужен — используется серверный ключ команды. Настройка Netlify, Neon, фонового обработчика и квоты описана отдельно.

Проверка для жюри

1. Нажмите «Загрузить пример» → «Рассчитать результат»: расход 95, Score 56,54, прирост 3,99 относительно исходного 52,56.
2. Нажмите «Изменить решения» и перенесите «Школа + детский сад» из Нуры в Есиль. После пересчёта Score станет 55,30: место вложений влияет на результат.
3. При настроенном ключе нажмите «Разобрать сценарий с AI». Проверьте вывод, риски и раскрываемые основания расчёта.
4. Сохраните сценарий и откройте его через «Мои сценарии»: итоговый разбор доступен без нового запроса.

Путь /preview — отдельное демо интерфейса с браузерным архивом и без настоящего AI. Для проверки серверной реализации используйте главную страницу.

Тесты и воспроизводимость

npm test
npm run typecheck
npm run lint
npx playwright install chromium
npm run test:e2e
npm run build
npm run check:data
npm run check:docs

Последним двум командам нужен Python 3.9+. Vitest проверяет правила, серверные границы и жизненный цикл AI; SQL облачного адаптера тестируется через PGlite. Playwright проверяет основной пользовательский путь и демо. Автотесты подменяют AI и не расходуют API-баланс; E2E рассчитаны на локальный режим без облачных переменных окружения.

Примеры реальных AI-ответов и найденные исправления · Журнал проверок и текущий статус. Платные оценки запускаются отдельно: node scripts/evaluate-ai.mjs --live.

Границы MVP и развитие

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

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

Устройство модулей — в карте архитектуры, условия публикации и ограничения доступа — в руководстве деплоя.

Все документы · Этапы и результаты · История разработки.

Деплой

Публикация MVP: Netlify + Neon

Сайт: hackalem.netlify.app. Исходный репозиторий: BAITC-Hacks/hack-4078ad52-mama-papa-and-me. Подготовка основана на 3700ece, настройки деплоя — 4e217df, исправление инструкции Windows — 71f0c6e. Это общий демонстрационный сайт без регистрации игроков. Сохранённые сценарии видны всем посетителям; не вводите приватные данные. Ключ OpenAI находится только на сервере. Локальная SQLite продолжает работать при отсутствии DATABASE_URL.

Текущее состояние

По предоставленному владельцем выводу CLI подтверждены полная production-сборка Next.js, TypeScript, упаковка серверной функции и analysis-background, загрузка и сообщение Deploy is live!.

• Production: https://hackalem.netlify.app
• Опубликованный deploy: https://6ab3c9819a645066402dee47--hackalem.netlify.app
• Логи сборки
• Логи функций

При последней внешней проверке / и /api/status вернули HTTP 401 с перенаправлением на вход Netlify. Значит, публикация успешна, но доступ для внешнего судьи ещё не подтверждён. Живые операции PostgreSQL и платный AI на сайте пока не проверены.

Сайт уже создан: для следующего обновления используйте существующую привязку CLI, не создавайте второй проект.

Повторная публикация существующего сайта

Из рабочей папки:

cd "C:\Users\Елена\Documents\Codex\2026-09-23\new-chat-3\work\hackalem-public"
npm.cmd run netlify:status
npm.cmd run netlify:deploy

Перед deploy убедитесь, что status показывает именно проект hackalem. Если привязка отсутствует, выполните npm.cmd run netlify:login, затем npx.cmd --yes netlify-cli link и выберите существующий сайт. После изменения зависимостей сначала установите их командой из раздела 2. Остальные разделы описывают первоначальную настройку и проверку.

1. Создать базу Neon

В Neon создайте проект на Free, выберите регион рядом с регионом функций Netlify. В SQL Editor выполните содержимое файла src/storage/migrations/001-postgres.sql в репозитории. Повторный запуск безопасен для существующих строк. Это новая облачная база: локальные сценарии автоматически не копируются.

В Connect скопируйте PostgreSQL connection string в переменную DATABASE_URL в Netlify. Не отправляйте строку в чат и не сохраняйте её в Git. Альтернативный запуск миграции: npm run db:migrate после установки DATABASE_URL в локальное окружение или защищённый .env.

2. Создать сайт через CLI без подключения GitHub

Работа ведётся только в BAITC-Hacks/hack-4078ad52-mama-papa-and-me. Новый репозиторий, fork и установка GitHub App Netlify в организацию не нужны. CLI загружает собранное приложение из локальной рабочей копии. Код и история остаются в исходном репозитории. Сборка выполняется на вашем компьютере; после публикации он не нужен для работы сайта.

Откройте PowerShell в корне рабочей копии с package.json и netlify.toml. Для текущей подготовленной ветки это:

cd "C:\Users\Елена\Documents\Codex\2026-09-23\new-chat-3\work\hackalem-public"
node --version
npm.cmd --version

Нужен Node.js 22.20+ и npm. Установите зависимости и авторизуйтесь:

npx.cmd --yes [email protected] ci --ignore-scripts
npm.cmd run netlify:login
npm.cmd run netlify:create
npm.cmd run netlify:status

Для этой зафиксированной версии зависимостей установка на Windows проверена с --ignore-scripts: обычный npm ci пытался собирать better-sqlite3 через node-gyp и требовал Python. Готовый SQLite-модуль проверен отдельным запросом на Node 24.21.0. При обновлении зависимостей пригодность этого способа нужно проверить заново.

netlify:login открывает браузер для входа в ваш Netlify. netlify:create создаёт пустой сайт в выбранном личном пространстве и привязывает его к папке, не подключая GitHub. Выполняйте create только один раз. Если сайт уже существует, вместо create используйте npx.cmd --yes netlify-cli link и выберите его. Локальная привязка в .netlify/ исключена из Git.

Команды npm используют Netlify CLI через npx; при первом запуске нужен интернет для загрузки. Настройки сборки берутся из netlify.toml: Node 22, npm 11.20.0, команда npm run build, каталог .next, функции netlify/functions. Next.js требует адаптер Netlify OpenNext и серверные функции. Не используйте Netlify Drop, static export или загрузку папки исходников через Проводник.

Сохраните адрес созданного сайта. До публикации выполните миграцию Neon и задайте переменные из следующего раздела.

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

Задайте через Netlify UI. Они должны быть доступны функциям во время выполнения; переменные из раздела build.environment в netlify.toml для этого недостаточны. Если доступны scopes, выберите Builds и Functions. Изменение переменных требует нового деплоя.

Имя	Значение
DEPLOY_TARGET	netlify
DATABASE_URL	Строка подключения из Neon, секрет
APP_ORIGIN	Точный адрес https://hackalem.netlify.app, без / в конце
WORKER_SECRET	Случайный секрет не менее 32 символов
OPENAI_API_KEY	Ваш собственный ключ OpenAI, секрет
OPENAI_MODEL	gpt-6-astra, проектный default сохранён
AI_ENABLED	Сначала false, после проверки расчёта и БД — true
AI_MAX_ANALYSIS_MINUTES	12
AI_DAILY_ANALYSIS_LIMIT	Сначала 10, затем нужное число; default кода 50

WORKER_SECRET можно сгенерировать локально: node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))". Не публикуйте его. Не используйте префикс NEXT_PUBLIC_ для секретов. Используйте свой ключ OpenAI, чтобы запросы расходовались из вашего API-проекта, а не через неявную интеграцию платформы.

Квота — число допущенных анализов за сутки UTC для всего сайта, не денежный лимит. Каждый анализ может содержать два платных этапа и веб-поиск. Неудачная или одновременная повторная заявка может израсходовать одно место в квоте; автоматического возврата нет. В актуальном интерфейсе анализ вызывается по запросу пользователя; каждый запуск учитывается в квоте. Симуляция остаётся доступной при исчерпании квоты.

Не включайте production-секреты для непроверенных preview-веток. Эта версия нацелена на один основной адрес; preview не должен вызывать worker production-сайта.

4. Собрать и опубликовать

После настройки окружения и базы, из той же папки:

npm.cmd run netlify:build

Продолжайте только при успешной сборке. В окружении агента запуск дочерних процессов ограничивался ошибкой spawn EPERM. В обычном PowerShell владельца полная сборка и публикация уже прошли; проверка типов не отключалась.

Для публикации на основной адрес:

npm.cmd run netlify:deploy

Эта команда повторно собирает приложение с production-окружением и загружает страницы, API и фоновую функцию. Не добавляйте --no-build: важны выходные файлы адаптера Next.js. При успехе CLI напечатает адрес сайта. Обычная draft-публикация здесь не настроена: APP_ORIGIN и worker рассчитаны на один основной адрес.

После изменений кода повторяется deploy из той же папки. Git push сам по себе не обновляет сайт, поскольку интеграция GitHub не подключена. Изменения окружения Netlify также требуют нового deploy.

5. Открыть production для судьи

В Netlify откройте проект hackalem → Project configuration → General → Visitor access → Project visibility. Для production выберите Public. Если включена Team login protection, исключите production из её области действия. Preview можно оставить закрытым.

Проверьте главную страницу в инкогнито: вход в Netlify не должен требоваться. Это настройка доступа к опубликованному приложению, а не изменение приватности репозитория GitHub. Защиту служебного API через WORKER_SECRET оставьте включённой.

Защита входом Netlify может блокировать и серверные обращения worker к сайту: одного успешного открытия страницы под аккаунтом владельца недостаточно.

Документация доступа.

6. Проверить публикацию

Для бесплатной проверки расчёта и HTTP-защиты без вызова AI:

node scripts/judge-smoke.mjs https://hackalem.netlify.app

Скрипт проверяет статус, контрольный Score, бюджет, отклонение подмены Score и чужого Origin. Он не проверяет базу или генерацию AI. При 401 сначала исправьте доступ из раздела 5.

1. При AI_ENABLED=false открыть сайт с двух устройств, рассчитать пример: Score 56,54.
2. Сохранить сценарий, перезагрузить страницу и открыть его. После повторного деплоя сценарий должен сохраниться в Neon.
3. Включить AI и повторно опубликовать. Запустить один анализ, закрыть вкладку. Через несколько минут проверить статус и ответ в таблице analyses в Neon. Закрытие вкладки может удалить sessionStorage: автоматическое восстановление панели AI в новой вкладке этой версией не гарантируется. При простой перезагрузке той же вкладки сохранённый ID обычно остаётся.
4. Убедиться, что в Netlify видны Next.js server function и analysis-background. Проверить логи без вывода секретов.
5. Проверить отмену и повторную доставку одной задачи: уже завершённая задача не должна создавать новые AI-запросы.
6. Проверить запрос к внутреннему маршруту без WORKER_SECRET: HTTP 403. Проверить межсайтовую запись: HTTP 403.

Успешная публикация файлов уже подтверждена; до этих проверок нельзя считать приложение полностью готовым для судьи. Локальные тесты используют имитацию AI и PostgreSQL в PGlite; реальная доступность модели и связь с Neon требуют отдельной проверки.

Выполнение и ограничения

POST /api/analyses создаёт запись и запускает исследование OpenAI, затем получает подтверждение приёма фоновой функции Netlify. Worker каждые четыре секунды вызывает защищённый внутренний API. API проверяет статус провайдера, запускает второй этап и сохраняет ответ. GET из браузера только читает состояние. Закрытие вкладки не останавливает worker; сознательная отмена или новый ход останавливают старую задачу.

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

Общий срок анализа — до 12 минут; цикл worker ограничен 14 минутами при лимите Netlify 15 минут. Отдельный вызов API остаётся коротким относительно полного анализа. При недоступности базы или платформы задача может завершиться ошибкой; бесплатный тариф не даёт гарантии бесперебойности. Долгое ожидание в worker, опросы, сборки и трафик расходуют кредиты Netlify; AI оплачивается отдельно.

Источники: Next.js на Netlify, Background Functions, переменные функций, тарифы.

Сохранение кода в исходный репозиторий

GitHub и Netlify обновляются отдельно. Git push сохраняет код; CLI deploy обновляет сайт. Работа ведётся только в исходном репозитории, без fork. Для сохранения уже созданного локального коммита в main, как согласовано владельцем:

$gitExe = Join-Path $env:USERPROFILE ".cache\codex-runtimes\codex-primary-runtime\dependencies\native\git\cmd\git.exe"
$env:GIT_SSH = "C:\Windows\System32\OpenSSH\ssh.exe"
& $gitExe --no-pager log -1 --oneline
& $gitExe push origin HEAD:main

Команды выполняются из рабочей копии с нужным коммитом. Push обычный, без --force: при новых изменениях команды или защите main Git должен отказать, после чего нужно обновить код и разрешить расхождения. Команды здесь являются инструкцией, а не подтверждением выполненного push.

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

• Локально прошли 78 тестов, TypeScript, ESLint, проверки данных и документации.
• PostgreSQL SQL проверен через PGlite: миграция, сохранение, квоты и блокировки. Настоящий Neon требует проверки из раздела 6.
• В тестах AI заменён провайдером-имитацией; реальные AI-запросы после деплоя ещё не подтверждены.
• Полная сборка, упаковка двух функций и публикация успешно прошли в PowerShell владельца по предоставленному логу.
• Браузерные Playwright-тесты в окружении агента остановились на spawn EPERM; их прохождение на этой версии не подтверждено.
• Последняя внешняя HTTP-проверка остановилась на защите Netlify (401). После открытия доступа повторите judge-smoke и ручные проверки базы и AI.

Ошибки установки на Windows

node-gyp / Python при установке better-sqlite3. Для текущего package-lock проверена установка npx.cmd --yes [email protected] ci --ignore-scripts; готовый SQLite-модуль работает на Node 24.21.0. Этот драйвер нужен локальному режиму, а в облаке используется PostgreSQL. При обновлении зависимостей повторите проверку пригодности установки без скриптов.

git не найден / переменная gitExe пуста. Сначала выполните две строки определения gitExe и GIT_SSH из раздела сохранения кода. Переменная действует только в текущем PowerShell.

cannot spawn less. Это ошибка просмотра истории, не скачивания репозитория. Используйте & $gitExe --no-pager log -1 --oneline.

spawn EPERM в окружении агента. Повторите команду сборки из обычного PowerShell пользователя; не отключайте TypeScript. Именно там уже получен успешный production deploy.