diff --git a/PLAN.md b/PLAN.md index e92a32a..bee0cc0 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1056,6 +1056,37 @@ no PostgreSQL, no Docker, no Python setup. --- +### CTX-19 — Coordinator Admin UI + +**Goal:** Replace the demo-level operator pages with a real admin console +(`/ui/admin`): system overview, job management with filters and pagination, +worker management (trust, capabilities), users/roles and worker keys, +workload enable/disable, settings (read-only), and storage metrics. + +**Depends on:** CTX-11 (UI patterns, session/roles), CTX-15 (userservice +proxy), the sqlite/postgres storage pair. + +**Acceptance criteria:** full plan in +[`docs/ui-admin-worker-plan.md`](docs/ui-admin-worker-plan.md) (section 3); +all `/ui/admin/*` routes are admin-only, bounded read model, both engines +supported, unit + permission + integration tests green. + +### CTX-20 — Worker Setup UI + +**Goal:** A four-step wizard (`/ui/workers/setup`) that turns any machine into +a worker: platform detection, auth choice (serve token or worker key), a +ready-to-run command, and a `worker-agent --check` verification step. + +**Depends on:** CTX-19 (admin API for token reveal), the existing worker-key +API, the agent. + +**Acceptance criteria:** full plan in +[`docs/ui-admin-worker-plan.md`](docs/ui-admin-worker-plan.md) (section 4); +end-to-end in the browser: generated command starts a real worker that +registers and completes a job. + +--- + ## 10. Suggested assignment bundles These bundles minimize overlap. Do not run tasks from the same bundle in diff --git a/docs/ui-admin-worker-plan.md b/docs/ui-admin-worker-plan.md new file mode 100644 index 0000000..e6a24d1 --- /dev/null +++ b/docs/ui-admin-worker-plan.md @@ -0,0 +1,167 @@ +# План: Coordinator Admin UI и Worker Setup UI + +> Статус: план. Текущий `/ui` — демонстрационный control room (джобы, ворклоады, docs). +> Два новых UI решают две разные задачи: **управление платформой** (админка +> координатора) и **подключение машин как воркеров** (установочный визард). + +## 1. Цель + +1. **Coordinator Admin UI** (`/ui/admin`) — полноценная консоль оператора: + система, джобы, воркеры, юзеры/роли, ворклоады, настройки, метрики. +2. **Worker Setup UI** (`/ui/workers/setup`) — пошаговый визард, который + превращает любую машину (Linux/macOS/Windows, amd64/arm64) в воркера + без чтения документации: выбрать платформу → получить готовую команду → + запустить → убедиться, что машина появилась в «My machines». + +Оба UI живут в бинарнике координатора (single-binary philosophy), защищены +той же сессией (JWT через userservice), браузер по-прежнему не касается БД — +только bounded read model от координатора. + +## 2. Принципы + +- **Не демо**: каждый экран работает от реального состояния (репозитории + + metrics), без симуляции; пустые состояния информативны. +- **Роли**: всё в `/ui/admin` — только `admin`; `/ui/workers/setup` — любой + аутентифицированный пользователь (ключи привязаны к аккаунту). +- **Секреты**: `worker.token` показывается только админу, с явным + подтверждением и предупреждением; в командах setup-визарда по умолчанию + плейсхолдер `$(coordinator token)`. +- **Новые API** — `/ui/admin/api/*` (JSON), те же middleware + (`withUISession`, `requireAdmin`), тот же паттерн bounded read model. +- **Оба движка БД** (sqlite и postgres) поддерживаются одинаково; новые + таблицы — миграции в обоих наборах. + +## 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 (`/ui/workers/setup`) + +### 4.1 Визард (4 шага) + +1. **Платформа**: автоопределение (navigator/platform + архитектура), ручной + выбор (linux/darwin/windows × amd64/arm64) → показ установочной команды + (`install.sh | bash -s worker`, `install.ps1` с `SCIMESH_COMPONENT=worker`). +2. **Способ аутентификации**: + - a) токен serve-инстанса: поле ввода + (для admin) кнопка «вставить токен» + — забирает из `/ui/admin/api/system` (показывается только админу); + - b) worker key: форма создания ключа (существующий + `POST /ui/api/worker-keys`) — для кластерного режима; +3. **Готовая команда**: полный блок `export ...` + `worker-agent` + (COORDINATOR_URL, токен/ключ, WORK_DIR, WORKER_NAME) + кнопка Copy; + чек-лист зависимостей: Python 3, scimesh (`pip install scimesh` или + `SCIMESH_PIP_PACKAGE`). +4. **Проверка**: `worker-agent --check` (новый флаг: `GET /health` + + `--version`, без регистрации) + инструкция «появится в My machines». + +### 4.2 Дополнительно +- сайдбар «My machines» (существующий список ключей с revoke); +- ссылка на этот же флоу из дашборда и из `install.sh worker` (печать URL). + +### 4.3 Изменения в агенте +- `worker-agent --check [--coordinator-url URL]`: пингует координатор, + печатает версии и пригодность (python3/scimesh видимость), exit 0/1. + +## 5. Компоненты и структура кода + +``` +coordinator/internal/transport/http/ + ui_admin.go # новые admin-хендлеры + шаблоны admin/*.html + ui_worker_setup.go # setup-визард + worker-setup.html + templates/admin.html # (заменяет текущий минимальный) + templates/worker-setup.html + server.go # роуты /ui/admin/* (requireAdmin), /ui/workers/setup + +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 + +coordinator/internal/agent/ + main.go / daemon # + --check mode + +coordinator/cmd/coordinator/main.go # (serve уже отдаёт UI; правки не нужны) +``` + +## 6. Милестоуны + +- **M1. Admin-фундамент**: экран «Система» + таблица джобов (фильтры, + пагинация) + storage usage. API + шаблоны + тесты. +- **M2. Admin-управление**: воркеры (trust), юзеры/ключи (userservice), + ворклоады enable/disable (таблица `workload_settings` + миграции обоих + движков), настройки (read-only). +- **M3. Worker Setup**: визард 4 шага + `worker-agent --check` + admin-кнопка + «вставить токен» + ключевой флоу (токен/ключ). +- **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 ворклоадов + (схема учитывается), `--check` (с/без координатора). +- **Go (integration, postgres)**: пагинация и storage-метрики на реальной БД. +- **E2E (браузер)**: вход админом → `/ui/admin` показывает реальную систему; + `/ui/workers/setup` → сгенерированная команда запускает `worker-agent` на + той же машине → воркер появляется в «My machines» и берёт джоб. +- **CI**: существующие джобы + новые тесты в общем `go test -race`; sqlite и + postgres пути одинаково зелёные. + +## 8. Открытые решения + +- **enable/disable ворклоадов**: хранить в `workload_settings` (миграции + обоих движков); решение принято — таблица добавляется в M2. +- **Токен в UI**: только админ, с подтверждением; в командах визарда — + плейсхолдер, чтобы не светить секрет в логах истории. +- **`worker-agent --check`**: без регистрации, только health + версии. +- Скоуп v1: без редактирования конфигурации и без управления миграциями + из UI (это задача `setup`/CLI).