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

AI-симулятор управления городом (кодовое имя пакетов в репозитории: backend astana-innovation, frontend hackalem).

1. Название проекта

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

2. Краткое описание

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

Решение: интерактивный симулятор на синтетических, но внутренне непротиворечивых данных Астаны. Пользователь получает единый стартовый город, 100 условных единиц бюджета и должен принять ровно пять решений (мер) для пяти районов. Детерминированный движок пересчитывает Astana Quality of Life Score, а AI на основе уже посчитанных фактов объясняет сильные стороны, риски и компромиссы выбранного сценария.

Аудитория: жюри и участники хакатона, преподаватели/студенты, интересующиеся основами городского планирования и объяснимого AI-анализа (LLM, который не считает сам, а комментирует готовый расчёт).

Явная оговорка авторов (см. README.md/frontend/README.md в репозитории): данные, границы районов и индекс — синтетические. Это учебная модель для сравнения сценариев, а не официальная статистика и не прогноз реального развития Астаны.

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

• Каталог из 5 районов и 14 инициатив (мер) с ценой, направлением, лагом и эффектом на конкретные показатели (app/data/, GET /api/bootstrap).
• Интерактивная SVG/Leaflet-карта районов с профилем, ключевыми проблемами и 10 показателями каждого района (frontend widgets/city-map, widgets/district-panel).
• Выбор ровно пяти решений с проверкой бюджета, лимита мер на направление, дублей, несовместимых пар мер и обязательности района для районных мер (app/domain/engine.py, frontend/src/features/manage-scenario).
• Отдельный режим «Весь город»: меры городского охвата (например, «Единая цифровая платформа обращений») можно выбрать без клика по конкретному району — карта при этом подсвечивает сразу все пять районов.
• Детерминированный расчёт Astana Quality of Life Score «до/после» с разбивкой по районам, критическими показателями (значение < 40) и сработавшими синергиями/несовместимостями мер (POST /api/simulate).
• AI-объяснение готового расчёта через OpenAI: сильные стороны, риски, компромиссы и рекомендации — без права пересчитывать Score или выдумывать меры/эффекты, которых нет в расчёте (POST /api/analysis, app/modules/analysis/).
• Автоматическая проверка каждого числа в ответе AI против данных расчёта (app/modules/analysis/numeric_check.py): при несовпадении запрос к OpenAI повторяется один раз с уточнением, иначе пользователю возвращается явная ошибка, а не непроверенный текст.
• Готовый эталонный сценарий («Эталонный план») для быстрой проверки жюри.
• Backend- и frontend-тесты, покрывающие расчёт, валидацию сценария, контракт API и ключевые пользовательские сценарии интерфейса.

4. Как работает решение

1. Пользователь открывает карту Астаны и выбирает район (или переключается на вкладку «Весь город» для городских мер) — справа отображается профиль района: QoL-балл, ключевые проблемы, 10 показателей по 5 направлениям.
2. По кнопке «Принять решение» открывается каталог из 14 инициатив, отфильтрованный по направлению; для района уже недоступны меры, которые не проходят по бюджету, лимиту направления или конфликтуют с уже выбранными.
3. Так собираются ровно 5 решений; бюджет и прогресс видны в реальном времени.
4. По кнопке «Запустить симуляцию» решения (scenarioVersion + decisions) уходят на backend. Единственный источник истины — детерминированный Python-движок (app/domain/engine.py): он валидирует набор, применяет эффекты с учётом лага, синергий и штрафов и считает Score «до/после».
5. Backend пересчитывает те же самые проверенные факты («evidence») и передаёт их в OpenAI со строгим system-промптом: LLM может только объяснять готовые цифры, не имеет права их менять или придумывать новые. Ответ проверяется на совпадение каждого числа с evidence.
6. Пользователь видит итоговый Score, карту «до/после», сравнение по районам и панель AI-анализа (сильные стороны, риски, компромиссы, рекомендации). Если AI недоступен (нет ключа, сеть, таймаут) — числовой результат расчёта всё равно сохраняется и показывается.

5. Технологии

Backend (pyproject.toml, requirements.txt, Python >=3.12,<4.0): FastAPI 0.141.1, Pydantic 2.13.5, pydantic-settings 2.15.0, Starlette 1.7.0, Uvicorn 0.53.0. Вызов OpenAI Chat Completions API (Structured Outputs, response_format: json_schema) реализован через стандартную библиотеку urllib — без отдельного OpenAI SDK. Модель по умолчанию — gpt-4o-mini (настраивается через APP_OPENAI_MODEL).

Frontend (frontend/package.json): Next.js 16.3.6 (App Router, Turbopack), React 19.2.8, TypeScript 5, Tailwind CSS 4, Leaflet 1.9.4 + React-Leaflet 5 (карта и тайлы OpenStreetMap), Vitest 3 + Testing Library (юнит- и интеграционные тесты).

Инфраструктура: Docker + Docker Compose (два сервиса — backend и frontend, плюс профиль tests), pytest + pytest-cov на backend.

6. Архитектура проекта

app/domain/engine.py          чистый Python: правила, валидация, детерминированный расчёт
app/data/                     5 районов и 14 мероприятий в JSON (источник каталога)
app/modules/simulations/      HTTP-схемы, адаптер движка, публичные маршруты (/api/*)
app/modules/analysis/         system prompt, вызов OpenAI, проверка чисел ответа (/api/analysis)
app/modules/districts/        каталог районов (legacy /api/v1/districts)
app/modules/initiatives/      каталог мер (legacy /api/v1/initiatives)
app/modules/ai_analysis/      сохранённый legacy-модуль (/api/v1/ai-analysis), не связан с /api/analysis
app/main.py                   сборка FastAPI-приложения, статика web/, регистрация роутеров
web/                           минимальный HTML/CSS/ES-модули UI, который backend отдаёт сам по "/"
frontend/                     основной UI: Next.js 16 / React 19, Feature-Sliced Design
frontend/src/app|views|widgets|features|entities|shared   FSD-слои (app → views → widgets → features → entities → shared)
frontend/src/features/run-simulation/api/backendMapping.ts  перевод доменных типов фронтенда в контракт backend и обратно
tests/                        pytest: движок, HTTP API, доставка интерфейса
frontend/src/**/*.test.ts(x)  vitest: доменная логика, карта, сценарий HomePage
examples/                     эталонный запрос и рассчитанный контекст для AI
docs/                         контракт AI-интеграции, инструкции по Docker

Поток данных: браузер → frontend (Next.js, порт 3000) → HTTP fetch к backend (FastAPI, порт 8000) по адресу из NEXT_PUBLIC_API_URL → единственный Python-движок расчёта → (для AI-анализа) OpenAI Chat Completions → ответ проверяется и возвращается фронтенду. Движок не хранит пользовательское состояние и не мутирует исходные данные; повторный расчёт одного и того же набора решений детерминирован и не зависит от их порядка.

Ключевые HTTP-маршруты (полностью в app/modules/simulations/public_router.py и app/modules/analysis/):

Метод	Маршрут	Назначение
GET	/api/bootstrap	Датасет, правила, каталог и базовый результат
POST	/api/validate	Проверка черновика сценария
POST	/api/simulate	Полный детерминированный расчёт Score
GET	/api/config	Публичные настройки frontend (без секретов)
GET	/api/health	Работоспособность backend без зависимости от AI
POST	/api/analysis	AI-объяснение расчёта через OpenAI; 404, если не настроено

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

Вариант A — всё через Docker Compose (backend + frontend)

Требования: Docker Engine/Desktop и Docker Compose v2.

docker compose up --build -d

• Frontend (основной UI, Next.js): localhost:3000
• Backend API + встроенный минимальный UI: localhost:8000
• Swagger: localhost:8000/docs
• Health: localhost:8000/api/health

Ключ OpenAI для запуска не обязателен — без него /api/analysis отвечает 404, а расчёт сценария (Score, карта, показатели) работает полностью. Чтобы включить реальный AI-анализ, задайте переменную окружения перед запуском:

OPENAI_API_KEY=sk-... docker compose up --build -d

Остановить и посмотреть логи:

docker compose logs --tail=100 backend frontend
docker compose down

Вариант B — локально без Docker

Backend (Python 3.12):

python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
.venv/bin/python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

На Windows используйте .venv\Scripts\python.exe вместо .venv/bin/python. Backend уже отдаёт минимальный встроенный UI на http://localhost:8000/.

Frontend (Node.js 20.9+; frontend/README.md):

cd frontend
npm install
cp .env.example .env.local   # на Windows: copy .env.example .env.local
npm run dev

Откройте http://localhost:3000. По умолчанию .env.example включает NEXT_PUBLIC_API_MODE=mock (детерминированное демо без обращения к backend); чтобы работать с живым backend, поставьте в .env.local NEXT_PUBLIC_API_MODE=live и убедитесь, что NEXT_PUBLIC_API_URL указывает на адрес запущенного backend (по умолчанию http://localhost:8000).

8. Как проверить решение

Есть готовый эталонный сценарий (examples/reference-scenario.json):

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

Ожидаемый результат: стоимость 95, остаток 5, Score 52.55768 → 56.54307 (прирост +3.98539, на экране округляется до 52,56 → 56,54 (+3,99)), критических показателей после мер — 0, активна синергия M10 + M12 в Нуре.

Через интерфейс: в интерфейсе frontend есть кнопка «Эталонный план» — она заменяет текущий план на этот сценарий одним кликом (с подтверждением, если план уже не пуст). Дальше нажмите «Запустить симуляцию» и сравните цифры с таблицей выше; в панели AI-анализа должны появиться сильные стороны, риски, компромиссы и рекомендации, построенные на этих же цифрах.

Через API, в обход интерфейса:

curl --fail http://localhost:8000/api/bootstrap
curl --fail http://localhost:8000/api/simulate \
  -H 'Content-Type: application/json' \
  --data-binary @examples/reference-scenario.json

Готовый рассчитанный контекст для сверки — examples/reference-analysis.json.

Автотесты (подтверждают ту же арифметику и контракт API):

.venv/bin/python -m pytest              # backend: движок, HTTP API, доставка интерфейса
cd frontend && npm run typecheck && npm run lint && npm run test && npm run build

9. Данные и интеграции

• Каталог районов и мер — статичные JSON-файлы в app/data/ (5 районов, 14 инициатив с ценой/лагом/эффектами). Данные синтетические, придуманы для проекта, не выгружены из внешнего источника.
• OpenAI API — единственная внешняя интеграция. Backend делает POST-запрос к Chat Completions (https://api.openai.com/v1/chat/completions, app/modules/analysis/client.py) со Structured Outputs и системным промптом, который запрещает модели пересчитывать Score или упоминать меры/районы, которых нет в переданных данных. Ключ (OPENAI_API_KEY) передаётся только backend-контейнеру в рантайме и никогда не попадает во frontend, публичный /api/config или образ.
• OpenStreetMap — источник тайлов карты для Leaflet во frontend (frontend/src/widgets/city-map); используется только как подложка, границы районов на карте упрощённые и не являются кадастровыми данными.
• Внешней базы данных, кэша или очередей проект не использует — весь расчёт идёт в памяти процесса backend и не хранит состояние между запросами.

10. Ограничения

• Данные и индекс качества жизни синтетические: это не официальная статистика и не прогноз реального развития Астаны (явно подтверждается и во frontend, и в system-промпте AI).
• Без OPENAI_API_KEY (или при APP_ANALYSIS_MODE отличном от remote) маршрут /api/analysis отвечает 404 — AI-объяснение недоступно, хотя сам расчёт сценария работает в полном объёме.
• В репозитории сохранён старый модуль app/modules/ai_analysis/ (/api/v1/ai-analysis) — он не переписан под новый контракт и намеренно возвращает управляемую ошибку миграции (legacy_request), а не считает по старой формуле.
• Backend отдаёт также собственный минимальный статический UI (web/) на http://localhost:8000/ — это отдельный, более простой интерфейс, не синхронизированный автоматически с основным Next.js-фронтендом в frontend/.
• Нет пользовательской аутентификации, нет сохранения сценариев на сервере между сессиями (только черновик в localStorage браузера) и нет базы данных.
• Карта в UI — стилизованная схема с упрощёнными границами районов, не точная GIS/кадастровая модель (отмечено прямо на карте: «Упрощённые границы · не кадастровая карта»).
• Проверка чисел в ответе AI (numeric_check.py) — эвристика на основе регулярных выражений и округления, а не формальное доказательство; она снижает, но не исключает риск галлюцинации, которая случайно совпадёт с числом из данных.

11. Deployed-версия

Публичного развёрнутого URL у проекта нет — решение запускается локально или через Docker Compose по инструкции из раздела 7.