dashboard/doc/CHAT_CONTEXT_FULL.md

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. Операционная дисциплина (КРИТИЧЕСКОЕ)

Для нового агента это обязательное правило:

• Все команды по проекту выполнять ТОЛЬКО через 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/тесты проекта

Почему:

• так исключаются конфликты сред и ложные результаты;
• единая точка выполнения (ВМ) дает предсказуемость и воспроизводимость.