hack-78afec8c-se-g-ys

Hackathon team repository for SE G_YS

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

QALA показывает исходные данные пяти районов и каталог 14 мероприятий, а затем позволяет собрать и проверить черновик сценария. Проверка не раскрывает Score.

Один раз установите зависимости:

uv sync --locked --project packages/draft-api
npm ci --prefix packages/draft-ui

npm start

Откройте http://127.0.0.1:5173. Скрипт запускает FastAPI на порту 8013 и Vite на порту 5173; Vite передаёт запросы /api в FastAPI.

Запуск в Docker

Для запуска полной текущей веб-версии достаточно Docker: образ содержит Node-сервер QALA и не требует установки зависимостей на хосте.

docker build --tag qala .
docker run --rm --name qala --publish 3000:3000 qala

Откройте http://127.0.0.1:3000. Чтобы использовать AI-разбор, передайте серверный ключ при запуске, например docker run --rm --publish 3000:3000 --env OPENAI_API_KEY qala. Не добавляйте ключ в образ или репозиторий.

Проверка:

npm test
uv run --project packages/draft-api pytest
npm test --prefix packages/draft-ui

Каталог доступен через GET /api/catalog, а проверка черновика — через POST /api/drafts/validate.

Принятие сценария выполняется через POST /api/scenarios/accept с JSON-полем decisions из пяти решений. Сервер возвращает причины отказа без результата для невалидного набора и детерминированный результат Q8 для принятого сценария.

После принятия браузер сохраняет неизменяемую попытку в localStorage. История доступна только в том же браузере: из неё можно открыть результат, создать редактируемую копию с тем же лимитом 100 или сравнить любые две попытки по решениям, расходам, Score и изменениям показателей районов.

Phase 2: карта, лаги и What If

После принятия сценария доступна проектная SVG-карта пяти синтетических районов. Район можно выбрать мышью или клавиатурой; рядом всегда есть текстовое описание исходных и, после принятия, Q8-показателей и решений. Цвет и геометрия не являются единственным источником данных. В черновике карта показывает только выбранные решения, их охват и стоимость — Score и значения Q8 не раскрываются.

Принятый сценарий также получает календарь лагов с пятью строками и Q1–Q8. Маркер обозначает начало действия мероприятия; это не поквартальная симуляция и не содержит промежуточных Score или показателей. Весь результат относится к концу Q8.

Кнопка What If: сравнить с глобальным максимумом появляется только у принятой попытки и запускается только по явному нажатию. Сервер перебирает все допустимые неупорядоченные сценарии активного каталога, используя тот же валидатор и калькулятор, затем показывает Score, разницу, пять решений и стоимость стабильного представителя. Равные максимумы выбираются по меньшей стоимости, затем по каноническому порядку идентификаторов и районов. Результат сохраняется с попыткой; он относится исключительно к синтетическому каталогу и формуле и не является рекомендацией реальной городской политики.

Измерение глобального поиска

Повторяемая команда для холодного измерения:

time node --test test/issue12-global-comparison.test.js

На текущем ноутбуке разработки (2026-09-23) сам холодный перебор 694 395 допустимых сценариев занял примерно 11.2 с. Сервер кеширует результат только пока его вычисленная версия модели совпадает с текущими данными и формулой; изменение каталога или модели создаёт другую версию и не использует старый ответ. Для демонстрационного ноутбука измерение следует повторить этой же командой.

AI-разбор OpenAI

После принятия браузер сразу сохраняет расчётный результат и базовый разбор, затем асинхронно вызывает POST /api/scenarios/analyze с теми же решениями. Сервер пересчитывает результат, отправляет только рассчитанные факты в OpenAI Responses API со строгой JSON-схемой и проверяет каждый факт, обоснование и точечную замену перед показом AI-разбора. Ошибка сети, тайм-аут или некорректный ответ оставляют доступным явно обозначенный базовый разбор; кнопка «Повторить AI-разбор» не создаёт новую попытку.

Для живого вызова задайте серверные переменные окружения перед запуском:

export OPENAI_API_KEY='...'
export OPENAI_MODEL='gpt-4o-mini' # необязательно
export OPENAI_TIMEOUT_MS=12000    # необязательно
npm start

Ключ не передаётся браузеру и не сохраняется в localStorage. Без OPENAI_API_KEY приложение продолжает работать с базовым разбором.

The cached API at POST /api/attempts/:attemptId/analysis returns one verified AI version per attempt and locale (ru or kk), deduplicating concurrent requests and falling back to the localized basic analysis on failure.