Money Graph — команда Xi

Фиксированный монорепозиторий: Next.js + NestJS + Python CLI. Главный приоритет — полное выполнение обязательного ТЗ, корректность, объяснимость, производительность и воспроизводимость.

Быстрый запуск приложения — одна команда

Нужен запущенный Docker Desktop / Docker Engine с Compose v2, поддерживающим --wait. Из корня клона выполните:

docker compose up --build --wait

Откройте http://localhost:3000. В интерфейсе выберите выданные организаторами nodes.parquet, edges.parquet, transactions.parquet и нажмите кнопку запуска расчёта. После завершения доступны граф, поиск по gid, карточки, топ приоритетов и три CSV. Данные получают отдельно: в репозитории их нет, для запуска пустого интерфейса они не нужны.

На хосте не нужно устанавливать Node.js, Python или Chromium и создавать .env: настройки портов 3000/3001 работают по умолчанию. При первой сборке нужен интернет для образов и зависимостей; расчёт выполняется локально. Браузерные тесты не входят в обычный запуск. Команда остаётся работать в фоне после готовности сервисов; остановка — docker compose down (сохранённые файлы в runs/ остаются). После перезапуска API для просмотра анализа загрузите файлы заново: серверные состояния запусков не восстанавливаются с диска.

Если репозитория ещё нет, сначала выполните git clone https://github.com/BAITC-Hacks/hack-18874c1c-xi.git и cd hack-18874c1c-xi. Командные скрипты, Git hooks и полный тестовый стенд — отдельные инструменты разработки, не предварительные шаги для запуска приложения.

Состояние решения

Frontend, backend и аналитический CLI объединены. NestJS принимает три Parquet, запускает Python, проверяет четыре артефакта и выдаёт результат. Python валидирует данные, считает метрики, шесть ролей, кластеры и приоритеты, создаёт три CSV и analysis.json. Next.js реализует загрузку, граф, поиск, карточку узла, топ и скачивание, навигацию по кластерам и восстановление анализа после F5. На 23.09.2026 после последнего слияния прошли 70 frontend-тестов, 103 backend-теста, 25 проверок скриптов, типы, Docker-сборка, независимая проверка CLI и HTTP-интеграция. Повторная браузерная приёмка ещё не завершена: реальная загрузка и расчёт прошли, затем старый тест таблицы остановился на изменённом оформлении; пять следующих сценариев не выполнены. Прежний полный успешный прогон из семи сценариев относится к версии до обновления UI. Отдельные прогоны Ерасыла на Windows и в Docker описаны в backend-отчёте; результаты и границы текущей проверки — в отчёте приёмки. Ручное объяснение трёх gid за минуту и воспроизведение итоговой ревизии другим участником ещё нужны. Инструкция аналитики · Правила и методология.

Команда и ветки

Участник	Зона	Ветка
Илья	apps/web/ — Next.js, TypeScript, Cytoscape.js	ilya-branch-front
Ерасыл	apps/api/ — единственный API NestJS	yerasyl-branch-back
Родион	analytics/ — пакетная аналитика Python	rodion-branch-analytics

У каждого участника — свой клон или worktree. При открытии новой задачи Codex читает AGENTS.md и проектный skill, спрашивает «Как тебя зовут?» и после ответа запускает безопасное переключение ветки. Если skill не появился в интерфейсе, открыть Codex в корне этого Git-репозитория и начать новую задачу; AGENTS.md также явно указывает путь к skill.

Ручной эквивалент из корня клона:

git fetch origin
npm run team:start
npm run team:check

team:start работает без npm install, но требует Node.js. Он переключает только на соответствующую существующую ветку и включает локальные hooks. Незакоммиченные изменения при переходе с другой ветки, detached HEAD и конфликт существующих hooks останавливают переключение; скрипт не делает stash, commit, reset или force. Имена поддерживаются на русском и латиницей.

main — интеграционная ветка. Каждые 20 минут участники сохраняют проверенную работу, получают и объединяют ветки коллег в свою ветку и пушат только её; протокол и готовый промпт. Расписание настраивается отдельно в Codex каждого участника. Hooks запрещают commit на ветке, не соответствующей выбранному человеку, и push чужой ветки или main; npm run check:structure проверяет согласованную архитектуру. Hooks и skill — защита рабочего процесса, не система прав доступа GitHub; серверная защита веток отдельно не настраивалась.

Зафиксированная структура

apps/
  web/                  # только Next.js UI — Илья
  api/                  # единственный HTTP API NestJS — Ерасыл
analytics/
  src/money_graph/      # Python CLI и вычисления — Родион
  tests/
  pyproject.toml
  requirements.lock
packages/contracts/    # общие TypeScript-типы и analysis.schema.json
docker/Dockerfile      # цели web, api, analytics
compose.yaml
scripts/               # вход участника, проверки структуры и ветки
.githooks/             # локальные pre-commit/pre-push
.agents/skills/money-graph-team/
.github/workflows/verify.yml
docs/                  # план, контракты и промпты
data/                  # исходные Parquet, исключены из Git
runs/                  # результаты API, исключены из Git
artifacts/             # результаты прямого CLI, исключены из Git

Нельзя переносить компоненты, создавать параллельные frontend/backend/services или второй HTTP API. Допускаются необходимые модули внутри своей зоны. Изменение стека и верхнего уровня требует решения владельца проекта; общий контракт меняется согласованно с потребителями. Корневые зависимости, Docker, scripts, skill и contracts — общая зона, за интеграцию отвечает Ерасыл. Используем один npm lockfile, без дополнительных pnpm/yarn lockfiles.

Правила разработки: Ерасыл использует TDD: Red → Green → Refactor; Илья — утверждённую палитру XI по frontend-промпту. Эти требования также закреплены в AGENTS.md и командном skill. Это инструкции для дальнейшей реализации, не утверждение о том, что текущий UI уже оформлен по палитре.

Запуск в Docker одной командой

Нужны Git, работающий Docker Engine/Desktop и Docker Compose v2+ с поддержкой --wait. Node.js и Python для самих контейнеров устанавливаются образами; Node.js 24 LTS нужен на хосте для командных скриптов и git hooks. Первый build загружает базовые образы и зависимости из реестров. Работа собранного каркаса локальная, без внешних API, шрифтов и CDN.

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

docker compose up --build --wait

• Интерфейс: localhost:3000.
• Проверка API: localhost:3001/api/health, ответ { "status": "ok", "service": "api" }. Это доступность HTTP; успешный расчёт подтверждает статус completed отдельного запуска.
• API содержит Node.js 24 и Python 3.12 с аналитическим пакетом; NestJS вызывает PYTHON_BIN отдельным процессом без второго Python-сервиса.
• Chromium и приёмочные тесты не участвуют в этой сборке/запуске. В конечном API-образе удалены dev/optional npm-пакеты; сборка отдельно запрещает наличие Playwright, TypeScript и tsx. Frontend использует production standalone-сборку Next.js.
• Контейнеры слушают только loopback хоста. Каталог runs/ сохраняется между перезапусками.

Команды проверки и остановки:

docker compose ps
docker compose logs --tail=100 api web
docker compose exec api python -m money_graph --check-environment
docker compose --profile tools run --rm --build analytics --check-environment
docker compose down

Сервис analytics — отдельная CLI-цель по профилю tools, не постоянно работающий сервер. Для прямого пересчёта положить три файла в data/ и выполнить:

docker compose --profile tools run --rm --build analytics --input-dir /data --output-dir /artifacts/run-001

Команда создаёт nodes_roles.csv, clusters.csv, top_nodes.csv и внутренний analysis.json. Для повторного запуска используй новый каталог, например run-002: существующие результаты не перезаписываются. Данные организаторов нужно получить отдельно и положить в data/; каталог исключён из Git. Описание и starter сохранены в docs/references/organizers/. CLI, API и сквозной браузерный сценарий проверены на реальном наборе; границы автоматической и ручной приёмки — в отчёте, подготовка повторного показа — в DEMO.md.

Порты и адреса имеют рабочие значения по умолчанию. При необходимости создать локальный .env по .env.example. При смене WEB_PORT согласовать WEB_ORIGIN, при смене API_PORT — NEXT_PUBLIC_API_URL. Последний встраивается в Next.js при сборке: после изменения повторить docker compose up --build --wait. В браузере использовать localhost, а не внутреннее Docker-имя api.

Локальная разработка с перезапуском при изменении кода

Рекомендуются Node.js 24 LTS, npm 11 и Python 3.12. Версии Node/Python записаны в .node-version и .python-version. Базовые Docker-образы закреплены проверенными multi-platform digests для воспроизводимости на amd64 и arm64; npm-зависимости фиксирует package-lock.json, Python-зависимости — requirements.lock. Обновление зависимостей и образов выполняется явно, с повторной проверкой сборки.

npm ci
npm run build:contracts
python3 -m venv .venv
.venv/bin/python -m pip install -r analytics/requirements.lock
.venv/bin/python -m pip install --no-deps -e ./analytics
.venv/bin/python -m money_graph --check-environment

Затем в двух терминалах:

npm run dev:api

npm run dev:web

Перед npm run dev:api задать PYTHON_BIN абсолютным путём: export PYTHON_BIN="$PWD/.venv/bin/python". Локальный API читает переменные окружения процесса; корневой .env автоматически использует только Docker Compose.

В Windows PowerShell из корня (Python 3.12 рекомендуется; 3.13 также поддерживается пакетом):

py -3.13 -m venv .venv
.venv/Scripts/python.exe -m pip install -r analytics/requirements.lock
.venv/Scripts/python.exe -m pip install --no-deps -e ./analytics
.venv/Scripts/python.exe -m money_graph --check-environment
$env:PYTHON_BIN = (Resolve-Path .venv/Scripts/python.exe).Path
npm run dev:api

Если установлен Python 3.12, заменить py -3.13 на py -3.12. PYTHON_BIN — путь к исполняемому файлу, без аргументов и shell-команд. В Docker он уже задан как /opt/venv/bin/python.

После изменения общего пакета повторить npm run build:contracts. Не устанавливать зависимости отдельно в apps; запускать npm из корня с --workspace и сохранять общий lockfile.

При ошибке Next.js EXDEV при записи nextjs-nodejs/Config/config.json на Windows отключить телеметрию в текущем терминале: $env:NEXT_TELEMETRY_DISABLED = '1', затем повторить npm run build. В Docker эта настройка уже задана.

Проверки

npm run team:check
npm run check:structure
npm test
npm run build
npm run typecheck
.venv/bin/python -m unittest discover -s analytics/tests -v
.venv/bin/python -m money_graph --check-environment
docker compose config --quiet

npm test проверяет выбор ветки, HTTP-контракт, загрузки, изоляцию запусков, управление процессом, целостность JSON/CSV, dev-запуск и остановку API. Синтетические артефакты находятся только в apps/api/test/fixtures/ и не используются продуктом. Python-тесты проверяют входы, правила ролей, кластеризацию, точность денег/ID, выходные контракты, CLI и сохранность результатов. CI выполняет сборку, проверки структуры, типов и синтетические тесты; без локального датасета он не заменяет приёмку на выданных данных.

Дополнительная проверка настоящего установленного CLI через HTTP (с заданным PYTHON_BIN):

npm run test:python --workspace @money-graph/api

Она проверяет окружение Python и два неуспешных запуска с намеренно некорректными файлами: failed, недоступность результатов и освобождение слота. Успешный расчёт проверяется отдельной командой test:dataset, описанной ниже.

Backend: загрузка и результаты

Контракт v1 сохранён; дополнительные endpoints не добавлены. При работающем API отправить три настоящих файла:

curl -i -F "nodes=@data/nodes.parquet" -F "edges=@data/edges.parquet" -F "transactions=@data/transactions.parquet" http://localhost:3001/api/runs

В PowerShell использовать curl.exe. Ответ 202 содержит {run_id, status:"running"}. Подставить полученный идентификатор вместо RUN_ID:

curl http://localhost:3001/api/runs/RUN_ID
curl http://localhost:3001/api/runs/RUN_ID/result
curl -OJ http://localhost:3001/api/runs/RUN_ID/exports/nodes_roles.csv
curl -OJ http://localhost:3001/api/runs/RUN_ID/exports/clusters.csv
curl -OJ http://localhost:3001/api/runs/RUN_ID/exports/top_nodes.csv

• Слот резервируется до начала записи загрузки. Второй POST при занятом слоте получает 409; очереди нет. Неполные, пустые, повторные, лишние поля, повреждённый multipart и превышение лимитов получают 400.
• Имена назначает сервер: runs/<uuid>/input/{nodes,edges,transactions}.parquet; выходы — в отдельном output/. Оригинальное имя, расширение и MIME не определяют корректность Parquet: содержимое должен проверять Python.
• Python запускается с фиксированным -m money_graph, массивом аргументов, shell: false. API ждёт закрытия процесса и потоков, затем проверяет все четыре файла. Код выхода 0 сам по себе недостаточен для completed.
• Проверяются общая JSON Schema, int64-диапазон, строковые деньги, UTF-8, точные заголовки и содержимое CSV, уникальность, ссылки, размеры/seed-состав кластеров и порядок топа. Формулы ролей и оборотов в NestJS не пересчитываются. Покрытие исходных Parquet отдельно проверяет приёмка ниже.
• result и CSV доступны только после completed; до этого — 409, включая failed. Неизвестный запуск и недопустимое имя выгрузки — 404. Статус содержит error:null либо {code,message}; подробности процесса и валидации остаются в локальном логе.
• Основные коды: UPLOAD_INVALID, RUN_ACTIVE, RUN_NOT_FOUND, RUN_NOT_COMPLETED, EXPORT_NOT_FOUND, PYTHON_START_FAILED, PYTHON_FAILED, PYTHON_TIMEOUT, PYTHON_CANCELLED, ARTIFACTS_INVALID. При ошибке слот освобождается. Сбой нового запуска не подменяется предыдущим результатом.
• JSON и исходные байты проверенных CSV сохраняются в памяти каждого завершённого запуска: скачивание не пересчитывает и не переписывает суммы. Изменение выходного файла на диске после проверки не меняет опубликованный снимок.

Настройки API:

Переменная	По умолчанию	Значение
PYTHON_BIN	python на Windows, python3 на остальных ОС	Установленный Python; рекомендуется абсолютный путь к venv
RUNS_DIR	runs/ в корне репозитория	Серверный каталог запусков
UPLOAD_MAX_BYTES	134217728	Максимум 128 MiB для каждого из трёх файлов; запись потоковая
UPLOAD_TIMEOUT_MS	300000	Максимальное время загрузки; обрыв/таймаут удаляет частичные входы
PYTHON_TIMEOUT_MS	330000	Технический таймаут процесса; TERM, через 2 секунды KILL, ожидание закрытия

Технический таймаут не отменяет приёмочное требование менее 300 секунд. elapsed_ms статуса начинается после загрузки и включает запуск Python и проверку артефактов; после завершения не растёт. metadata.elapsed_ms приходит из Python и имеет отдельную границу измерения по контракту.

Один экземпляр API держит состояния в памяти. При штатной остановке активный процесс завершается, незаконченная загрузка очищается, соединения закрываются. После перезапуска API старые run_id получают 404; каталоги на диске сохраняются для диагностики, автоматического восстановления нет. Удалять старые каталоги следует после остановки API. Для длительной работы потребуется политика хранения; текущий полный JSON и снимки в памяти не предназначены для ~1 млн узлов. Такое масштабирование потребует согласованного изменения формата выдачи, ограничений памяти и интерфейса; сейчас дополнительные endpoints не вводятся.

Приёмка реального датасета

Полный изолированный стенд проверяет production Next.js → NestJS → Python, независимый пересчёт метрик, роли/кластеры/топ, поиск на карте и скачанные CSV. Из корня клона, при наличии трёх исходных Parquet в data/, Node.js 24 LTS и Docker Compose:

Это необязательный тестовый запуск команды. Для использования решения жюри достаточно обычного запуска Docker или прямого CLI выше: Chromium и приёмочный стенд им не нужны.

node scripts/acceptance/run.mjs --no-cache

Установка npm/Python/Chromium на хосте для этой команды не нужна. Стенд не занимает порты 3000/3001 и не трогает рабочие runs/; отчёты сохраняются в отдельном artifacts/acceptance-…/. Отсутствие исходных данных — ошибка, не повод подставить fixture. Подробные предварительные условия, матрица пяти must-have, границы тайминга и критерии оценки — в инструкции приёмки. Успех автоматизации не заменяет объяснение трёх произвольных gid человеком за минуту или независимый запуск другим участником.

Для отдельной проверки только API/CLI:

После получения данных и установки аналитики задать REAL_DATA_DIR абсолютным путём к каталогу трёх исходных Parquet и PYTHON_BIN, затем выполнить:

npm run build:contracts
npm run test:dataset --workspace @money-graph/api

PowerShell: $env:REAL_DATA_DIR = (Resolve-Path data).Path; macOS/Linux: export REAL_DATA_DIR="$PWD/data".

Команда запускает временный API с настоящим CLI, сравнивает полный набор строковых gid с реально прочитанным через PyArrow nodes.parquet, проверяет выдачу всех CSV и их исходные байты. Замеряется процесс снаружи от spawn до close, а также процесс вместе с backend-валидацией; оба должны быть <300000 ms. Установка, HTTP-загрузка и чтение gid для приёмки в этот интервал не входят. Отчёт содержит размеры файлов, metadata, CPU, ОС, версии Node/Python и длительность. Отсутствующие данные, неготовый CLI или ошибки приводят к падению теста, без подстановки fixture. Временные каталоги этой проверки удаляются.

Приёмка API/CLI и полный браузерный сценарий прошли: все 2 248 исходных gid сохранены, три CSV доступны и совпадают с прямым расчётом. В изолированном стенде Родиона на Apple M4 / Docker Linux arm64 полный CLI занял около 0.60 с, UI от нажатия запуска до готового графа — 2.62 с; окружение и границы измерений — в отчёте приёмки.

Отдельно Ерасыл повторил приёмку 23.09.2026 на Windows x64 и в Docker Linux x64. По его backend-отчёту, последний замер Windows (процесс + backend-валидация) — 2 289 ms, браузерный запуск через Docker — 2 384 ms по состоянию API. Проверены все узлы и направленные рёбра, 19 изолятов, карточки обычного узла, изолята и depth=4, топ и скачанные CSV. Это разные прогоны и границы тайминга, а не сравнение производительности машин. Данные и результаты исключены из Git; для повторения набор получают отдельно. Health обновлён и сообщает только доступность HTTP, не готовность аналитического результата.

Фактические результаты TDD, сборки и интеграционных проверок backend: BACKEND_VERIFICATION.md.

Документы для разработки и сдачи

• План команды, требования, веса оценки и приёмка.
• Запуск, схема решения и пятиминутная демонстрация.
• Контракты CLI, API, CSV и интерфейса.
• Приёмочный стенд, must-have и матрица критериев оценки.
• Ерасыл: backend-промпт.
• Илья: frontend-промпт.
• Родион: аналитический промпт.
• Исходное ТЗ.

Правила шести ролей, пороги, формулы, ограничения и масштабирование до ~1 млн узлов описаны в методологии. Health обновлён, схема и пятиминутный сценарий доступны в DEMO.md. К сдаче остаются адаптация браузерных тестов к новому UI и полный повторный прогон, командная репетиция с объяснением трёх произвольных gid за минуту, воспроизведение итоговой ревизии другим участником и комплект разрешённых выгрузок отдельно от Git. Автоматические тесты не присваивают баллы жюри; текущие измерения не доказывают производительность на миллионе узлов. LLM-судьи не подключены и для обязательного расчёта не нужны.