213 lines
10 KiB
Markdown
213 lines
10 KiB
Markdown
# Dashboard Service - Full Chat Context For Next Agent
|
||
|
||
Updated: 2026-04-16
|
||
Owner: naeel
|
||
|
||
## 1. Что это за сервис
|
||
|
||
Cloud Dashboard - отдельный веб-сервис (backend + frontend), который показывает инстансы облака, фильтрацию, детали, историю операций и граф зависимостей.
|
||
|
||
Текущая реализация:
|
||
- Backend: Python + FastAPI
|
||
- Frontend: статический SPA (HTML/CSS/vanilla JS)
|
||
- Граф: Cytoscape
|
||
- Runtime: контейнер в Kubernetes
|
||
|
||
## 2. Бизнес-цель
|
||
|
||
Сделать рабочий дашборд для повседневной эксплуатации:
|
||
- быстрый вход по API token
|
||
- фильтрация по статусам
|
||
- понятная таблица и карточки статистики
|
||
- просмотр параметров/зависимостей инстанса
|
||
- визуализация зависимостей
|
||
- стабильная работа в PROD
|
||
|
||
## 3. Ключевые сделанные фичи
|
||
|
||
### 3.1 Аутентификация и сессия
|
||
- Логин по API token.
|
||
- Токен сохраняется в localStorage.
|
||
- Logout очищает токен.
|
||
|
||
### 3.2 Выбор стенда (ВАЖНО)
|
||
Сделано переключение окружений на экране логина:
|
||
- PROD -> https://deck-api.ngcloud.ru/api/v1
|
||
- DEV -> https://deck-api-dev.ngcloud.ru/api/v1
|
||
- TEST -> https://deck-api-test.ngcloud.ru/api/v1
|
||
|
||
Как работает:
|
||
- выбранный стенд сохраняется в localStorage как deck_env
|
||
- frontend отправляет в backend заголовок X-Deck-Env
|
||
- backend выбирает base URL по whitelist
|
||
- если значение некорректное, fallback на test
|
||
|
||
### 3.3 Таблица и UX
|
||
- Фильтры статусов с чекбоксами (увеличены).
|
||
- Sticky header и правильный скролл области таблицы.
|
||
- Сортировки по колонкам.
|
||
- Статистика по статусам.
|
||
- Detail row с вкладками: параметры, история, зависимости, граф.
|
||
|
||
### 3.4 Зависимости и графы
|
||
Добавлены два режима:
|
||
- граф для конкретного инстанса
|
||
- общий граф для running
|
||
|
||
Оптимизации:
|
||
- lazy-load графа (не считать сразу)
|
||
- кэш графа на backend с TTL
|
||
- клиентская подвыборка subgraph
|
||
- индикаторы загрузки
|
||
- open large graph in modal/fullscreen behavior при большом числе узлов
|
||
|
||
UI графа:
|
||
- прямоугольные узлы
|
||
- более крупный и читаемый текст
|
||
- улучшенные стрелки/контраст
|
||
- упрощенный layout (grid-подход)
|
||
|
||
### 3.5 Визуал и брендинг
|
||
- day/night переключатель темы с сохранением в localStorage
|
||
- favicon/logo из docs assets
|
||
- удалены лишние декоративные элементы
|
||
|
||
## 4. Техническая архитектура
|
||
|
||
## Browser
|
||
- SPA рендерит UI
|
||
- вызывает backend по префиксу /dashboard/api
|
||
- хранит deck_token и deck_env в localStorage
|
||
|
||
## Backend (FastAPI)
|
||
Главные маршруты:
|
||
- GET /api/instances
|
||
- GET /api/instances/{uid}
|
||
- GET /api/graph
|
||
|
||
Транспорт:
|
||
- принимает X-Deck-Token
|
||
- принимает X-Deck-Env
|
||
- проксирует запросы в Deck API выбранного окружения
|
||
|
||
Граф:
|
||
- собирается из списка инстансов и деталей
|
||
- edges из dependencies/dependentInstances
|
||
- кэш in-memory по ключу token+env+statuses
|
||
|
||
## Kubernetes
|
||
- deployment/service/ingress в namespace terra
|
||
- публичный доступ через /dashboard
|
||
|
||
## 5. Эксплуатационные детали
|
||
|
||
- Сервис не использует БД.
|
||
- Основная интеграция backend - только с Deck API.
|
||
- Узкое место в производительности обычно внешний API, не сам UI.
|
||
- В проекте уже обсужден путь: сначала стабилизировать логику на Python, потом при необходимости переписать backend на Go с сохранением API контрактов.
|
||
|
||
## 6. История решений (сжатая)
|
||
|
||
1) Сначала починили критичные JS ошибки и нестабильный логин.
|
||
2) Исправили фильтры статусов и прокинули корректный parsing на backend.
|
||
3) Переделали скролл + sticky элементы.
|
||
4) Добавили графы зависимостей, затем несколько итераций UX/производительности.
|
||
5) Сделали lazy загрузку и кэш.
|
||
6) Подчистили визуал (читаемость, стрелки, тема, favicon/logo).
|
||
7) Реализовали выбор стенда PROD/DEV/TEST на логине с end-to-end маршрутизацией.
|
||
8) Вынесли сервис в новую репу-папку dashboard и добавили правила агента + gitignore.
|
||
|
||
## 7. Что уже перенесено в новую репу dashboard
|
||
|
||
Из старого пути cloud-dashboard в новый dashboard перенесены:
|
||
- Dockerfile
|
||
- main.py
|
||
- requirements.txt
|
||
- static/
|
||
- k8s/
|
||
|
||
Дополнительно создано:
|
||
- .github/copilot-instructions.md (скопированы правила агента)
|
||
- .gitignore (Python/кэши/локальные артефакты)
|
||
|
||
## 8. Что важно для нового агента
|
||
|
||
1) Не ломать контракт frontend/backend без явного запроса.
|
||
2) Заголовки X-Deck-Token и X-Deck-Env обязательны.
|
||
3) Поддерживать 3 стенда через whitelist.
|
||
4) Не тащить секреты/токены в git.
|
||
5) Для графа сохранять lazy-load и кэш (иначе будет тяжелая загрузка).
|
||
|
||
## 9. Рекомендованный план ближайших шагов
|
||
|
||
1) Сделать первичный commit в новой репе dashboard.
|
||
2) Настроить CI:
|
||
- lint
|
||
- build image
|
||
- push image
|
||
- deploy (опционально)
|
||
3) Добавить smoke tests:
|
||
- /api/instances с разными env
|
||
- /api/graph с фильтрами
|
||
4) Подготовить migration checklist для возможного будущего Go backend.
|
||
|
||
## 10. Definition of Done (текущее состояние)
|
||
|
||
Сервис:
|
||
- работает в k8s
|
||
- логин и фильтры стабильны
|
||
- графы и тема работают
|
||
- выбор стенда реализован и сохраняется
|
||
- код перенесен в новую папку/repo baseline
|
||
|
||
|
||
## 11. Текущие задачи (v9.7 — в работе)
|
||
|
||
Все 4 задачи согласованы с оператором. Реализовывать в таком порядке:
|
||
|
||
### Задача 1 — Стриминговая загрузка инстансов
|
||
- Backend `/api/instances/stream` уже есть (NDJSON, main.py строка ~297)
|
||
- Фронт **ещё использует старый** `/api/instances` (index.html строка ~1004)
|
||
- Нужно: переключить фронт на `/api/instances/stream`, строки добавлять в таблицу по одной по мере прихода
|
||
- Все загруженные инстансы держать в памяти (`allInstances`). К API обращаться ТОЛЬКО по кнопке "Обновить"
|
||
|
||
### Задача 2 — Метка "Актуально на ЧЧ:ММ:СС"
|
||
- Разместить **слева от кнопки "Обновить"**
|
||
- Показывать время завершения последней загрузки
|
||
- Обновлять при каждом refresh
|
||
|
||
### Задача 3 — Фильтрация зависимостей по чекбоксам
|
||
- В блоке "Зависимости" инстанса показывать ТОЛЬКО те инстансы, статус которых выбран чекбоксами (running/suspended/etc)
|
||
- При изменении чекбокса — сразу перерисовывать список зависимостей (без обращения к API, из памяти)
|
||
|
||
### Задача 4 — Переход по клику + кнопка "Назад"
|
||
- Клик на инстанс в блоке "Зависимости" → открыть его строку/детали в таблице
|
||
- Добавить кнопку "Назад" для возврата к исходному инстансу
|
||
|
||
### Правила разработки (напоминание):
|
||
- ЧАСТО коммитить: `git add -A && git commit` на ВМ в `~/terra/dashboard`
|
||
- Всё через SSH: `ssh -i ~/.ssh/naeel_vm_id_ed25519 -o StrictHostKeyChecking=no naeel@5.172.178.213`
|
||
- Не ломать существующий рабочий код
|
||
- Новая логика = новые функции в конце файла
|
||
|
||
---
|
||
|
||
## 12. Операционная дисциплина (КРИТИЧЕСКОЕ)
|
||
|
||
Для нового агента это обязательное правило:
|
||
- Все команды по проекту выполнять ТОЛЬКО через SSH на ВМ.
|
||
|
||
SSH-шаблон:
|
||
ssh -i ~/.ssh/naeel_vm_id_ed25519 -o StrictHostKeyChecking=no -o ConnectTimeout=10 naeel@5.172.178.213 КОМАНДА
|
||
|
||
Локально ЗАПРЕЩЕНО выполнять:
|
||
- git-команды проекта
|
||
- docker-команды
|
||
- kubectl-команды
|
||
- curl к API проекта
|
||
- bash/python/go/тесты проекта
|
||
|
||
Почему:
|
||
- так исключаются конфликты сред и ложные результаты;
|
||
- единая точка выполнения (ВМ) дает предсказуемость и воспроизводимость.
|