SciMesh/docs/ui-admin-worker-plan.md

План: Coordinator Admin UI и Worker Setup UI

Статус: план. Текущий /ui — демонстрационный control room (джобы, ворклоады, docs). Два новых UI решают две разные задачи и живут в разных бинарниках: админка кластера — в coordinator, визард установки воркера — в worker-agent (для тех, кто ставит ТОЛЬКО воркер и не имеет координатора на своей машине).

1. Цель

1. Coordinator Admin UI (/ui/admin) — полноценная консоль админа распределённого кластера: система, джобы, воркеры, юзеры/роли, ворклоады, настройки, метрики. Живёт в бинарнике coordinator.
2. Worker Setup UI — локальный визард в бинарнике worker-agent (worker-agent setup → браузер на 127.0.0.1): пошаговое подключение машины к координатору — URL/токен/ключ, рабочий каталог, проверка соединения, запуск и статус воркера. Не требует установки координатора и работает на машине, где есть только воркер.

2. Принципы

• Coordinator UI (админка кластера): /ui/admin/* — только admin, bounded read model, браузер не касается БД, оба движка (sqlite/postgres) одинаково, секреты (worker.token) только админу с подтверждением.
• Worker UI (локальный визард в worker-agent): слушает только 127.0.0.1, без аутентификации (локальная машина), не требует никаких внешних сервисов; конфигурация сохраняется в JSON-файле рядом с рабочим каталогом воркера; запуск воркера — отдельным процессом (worker-agent --config <path>), который визард же может остановить.
• Никаких секретов в логах и в самом UI после сохранения.

3. Coordinator Admin UI (/ui/admin)

3.1 Экран «Обзор системы» — /ui/admin

• движок БД (sqlite/postgres), версия бинарника, data dir, uptime;
• занятое место blob-хранилища (байты по артефактам) и число артефактов;
• чипы: джобы/воркеры/таски по статусам (из существующих business metrics);
• токен воркера: кнопка «Показать worker token» (admin only, подтверждение).

3.2 Экран «Джобы» — /ui/admin/jobs

• таблица: id, ворклоад, статус, владелец, создан, завершён, результат;
• фильтры: статус, ворклоад, владелец; поиск по id (частичное совпадение);
• пагинация (limit/offset), переход в существующий detail-просмотр;
• действие: cancel (существующий usecase).

3.3 Экран «Воркеры» — /ui/admin/workers

• таблица: имя, id, статус (online/busy/offline), capabilities, trust, владелец, последний heartbeat;
• переключение trust (trusted/untrusted) для воркеров — новый usecase;
• индикация «какие ворклоады умеет» (capabilities из реестра).

3.4 Экран «Юзеры и ключи» — /ui/admin/users

• список юзеров через userservice (существующий прокси callUserserviceAuthed);
• verify/unverify, promote/demote (существующие действия);
• worker-ключи юзера: просмотр (без секрета), revoke.

3.5 Экран «Ворклоады» — /ui/admin/workloads

• каталог из embedded workloads.json (уже есть read view);
• enable/disable: новая таблица workload_settings (workload TEXT PK, enabled BOOLEAN), миграции sqlite + postgres; каталог читается с учётом оверрайдов;
• параметры: схема, reduction, upload_ready, ui_elements (read-only).

3.6 Экран «Настройки» — /ui/admin/settings

• read-only конфигурация без секретов: addr, storage dir, docs dir, лимиты (max upload, attempts, quorum), lease/reaper интервалы, engine;
• подсказки: где лежат миграции, как сделать бэкап sqlite (скопировать файл).

3.7 API (все — admin, JSON)

Метод	Путь	Назначение
GET	/ui/admin/api/system	движок, версия, storage usage, counts, worker token (admin)
GET	/ui/admin/api/jobs	пагинированный список с фильтрами
GET	/ui/admin/api/workers	список воркеров
POST	/ui/admin/api/workers/{id}/trust	переключить trust
GET	/ui/admin/api/users	список юзеров (userservice)
GET	/ui/admin/api/workloads	каталог + enabled
POST	/ui/admin/api/workloads/{name}/enabled	enable/disable
GET	/ui/admin/api/settings	конфигурация (без секретов)

4. Worker Setup UI (в бинарнике worker-agent)

4.1 Как это выглядит

curl -fsSL .../install.sh | bash -s worker
worker-agent setup          # печатает URL и открывает браузер
# → http://127.0.0.1:12700 — локальный визард, ничего устанавливать не нужно

4.2 Визард (шаги)

1. Координатор: URL (например http://192.168.1.10:8080) + способ аутентификации: токен (serve) или worker key (кластер);
2. Рабочий каталог: путь + имя машины (WORKER_NAME);
3. Проверка: кнопка «Проверить соединение» — GET /health координатора (+ обмен ключа, если key), версии; чек-лист зависимостей (Python 3, scimesh) с командой установки;
4. Запуск: «Запустить воркер» — визард сохраняет config.json и запускает worker-agent --config <path> отдельным процессом.

4.3 Статусная страница (та же вкладка после запуска)

• состояние: не запущен / запущен, worker id, зарегистрирован ли;
• статистика: забрано задач, выполнено, ошибок, последний heartbeat;
• runtime: python, scimesh, capabilities (из каталога);
• кнопки: Остановить / Запустить / Открыть лог (хвост).

4.4 API визарда (локальный HTTP, 127.0.0.1)

Метод	Путь	Назначение
GET	/api/status	конфиг (без секрета), состояние, статистика
POST	/api/config	сохранить конфигурацию в config.json
POST	/api/test	проверка соединения с координатором
POST	/api/start	запустить воркера (self --config)
POST	/api/stop	остановить
GET	/api/logs	хвост лога воркера

4.5 Изменения в агенте

• worker-agent setup [--port 12700] [--no-open] — локальный сервер визарда;
• worker-agent --config <path> — запуск демона из JSON-конфига (URL, токен или ключ, work dir, имя, task runner); env-переменные имеют приоритет;
• worker-agent --check [--coordinator-url URL] — пинг /health + версии, exit 0/1 (используется визардом на шаге 3);
• config.json по умолчанию: ~/.scimesh-worker/config.json (переопределяется через WORKER_CONFIG); секрет хранится с правами 0600.

5. Компоненты и структура кода

# Coordinator Admin UI (бинарник coordinator)
coordinator/internal/transport/http/
  ui_admin.go            # admin-хендлеры + admin.html
  server.go              # роуты /ui/admin/* (requireAdmin)

coordinator/internal/usecase/
  admin.go               # AdminSystem/ListJobsAdmin/ListWorkersAdmin/WorkloadSettings
  ports.go               # + PaginatedJobs(ctx, filter, limit, offset)

coordinator/internal/storage/{sqlite,postgres}/
  ui_read_repo.go        # + ListJobsPaginated, StorageStats
  migrations/*.sql       # + workload_settings

# Worker Setup UI (бинарник worker-agent)
coordinator/internal/agent/
  setup/                 # локальный визард: сервер, шаблоны, API, config.json
  setup_ui.go            # worker-agent setup (сервер 127.0.0.1:12700)
  configfile.go          # --config <path>: JSON-конфиг демона
  check.go               # --check: пинг /health + версии

6. Милестоуны

• M1. Admin-фундамент: экран «Система» + таблица джобов (фильтры, пагинация) + storage usage. API + шаблоны + тесты.
• M2. Admin-управление: воркеры (trust), юзеры/ключи (userservice), ворклоады enable/disable (таблица workload_settings + миграции обоих движков), настройки (read-only).
• M3. Worker Setup (в worker-agent): setup-сервер с визардом (config/test/start/stop/logs), --config, --check; E2E: визард запускает реального воркера, тот регистрируется и берёт джоб.
• M4. Полировка и верификация: пустые состояния, mobile, копирование, E2E в браузере (admin-флоу и setup-флоу с реальным worker-agent), обновление mkdocs/standalone.md, CI зелёный.

7. Тестирование

• Go (unit): usecase admin (memstore + sqlite), permission-тесты (admin vs user → 403), фильтры/пагинация, enable/disable ворклоадов; агент: визард API (config persist 0600, test без/с координатором, start/stop), --config, --check (с/без координатора).
• Go (integration, postgres): пагинация и storage-метрики на реальной БД.
• E2E (браузер): вход админом → /ui/admin показывает реальную систему; на «голой» машине: worker-agent setup → визард → запуск → воркер регистрируется в координаторе и берёт джоб.
• CI: существующие джобы + новые тесты в общем go test -race; sqlite и postgres пути одинаково зелёные.

8. Открытые решения

• enable/disable ворклоадов: хранить в workload_settings (миграции обоих движков); решение принято — таблица добавляется в M2.
• Токен в UI: только админ, с подтверждением; в командах визарда — плейсхолдер, чтобы не светить секрет в логах истории.
• worker-agent --check: без регистрации, только health + версии.
• Локальный визард без аутентификации: сервер слушает только 127.0.0.1; любой локальный процесс может управлять воркером — это сознательное упрощение для одной машины.
• Скоуп v1: без редактирования конфигурации координатора и без управления миграциями из UI (это задача setup/CLI).