66 lines
4.5 KiB
Markdown
66 lines
4.5 KiB
Markdown
# Методология визуализации ресурсов и зависимостей (Golden Standard)
|
||
|
||
Этот документ описывает стандарт визуального представления инфраструктуры Nubes Cloud в виде Mermaid-диаграмм. Этот стандарт был выработан для обеспечения максимальной читаемости, точности параметров и отсутствия искажений при рендеринге в IDE и браузере.
|
||
|
||
---
|
||
|
||
## 1. Концепция "Золотого стандарта" узла
|
||
|
||
Каждый ресурс (Organization, vDC, VM и т.д.) представляется как "карточка" с жестко структурированным содержимым.
|
||
|
||
### Визуальные правила
|
||
1. **Моноширинный шрифт**: Обязательное использование `font-family:monospace` через `classDef`. Это позволяет выровнять символы по вертикали.
|
||
2. **Запрет переноса строк (No-Wrap)**:
|
||
- Имена и UUID не должны разрываться.
|
||
- Используются **неразрывные дефисы** (`‑`, Unicode `U+2011`) вместо обычных.
|
||
- Используются **неразрывные пробелы** (` `) для отступов.
|
||
3. **Выравнивание "Две колонки"**:
|
||
- **Центральная ось**: Двоеточие `:`. Все двоеточия в блоке должны находиться на одной вертикали.
|
||
- **Левая колонка (Ключи)**: Выравнивание по правому краю (Padding слева).
|
||
- **Правая колонка (Значения)**: Выравнивание по левому краю (Padding справа).
|
||
|
||
### Структура карточки
|
||
- **Заголовок**: Тип ресурса (курсивом) и Terraform-имя (жирным).
|
||
- **Разделитель ПАРАМЕТРЫ**: Содержит входные данные (Required/Optional в TF).
|
||
- **Разделитель СГЕНЕРИРОВАНО**: Содержит выходные данные (Computed в TF), такие как UUID и статусы.
|
||
|
||
---
|
||
|
||
## 2. Процесс обнаружения (Discovery)
|
||
|
||
Для составления точной карточки ресурса используется двухступенчатый процесс:
|
||
|
||
### Этап А: Анализ исходного кода (Go)
|
||
1. Переход в `internal/provider/`.
|
||
2. Анализ функции `Schema` в соответствующем файле ресурса (например, `vdc_resource.go`).
|
||
3. Классификация атрибутов:
|
||
- Если `Required: true` или `Optional: true` -> попадает в **ПАРАМЕТРЫ**.
|
||
- Если `Computed: true` -> попадает в **СГЕНЕРИРОВАНО**.
|
||
|
||
### Этап Б: Анализ API трафика (HAR)
|
||
1. Проверка реальных значений в HAR-файлах (`har/`).
|
||
2. Сопоставление параметров Terraform с полями JSON в API (используя `instanceOperationCfsParams`).
|
||
|
||
---
|
||
|
||
## 3. Техническая реализация в Mermaid
|
||
|
||
Пример кода, реализующего стандарт:
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
classDef resourceNode text-align:center,font-size:16px,font-family:monospace
|
||
|
||
NODE["<i>Тип ресурса</i><br/><b>имя_в_terraform</b><br/>━━━━ ПАРАМЕТРЫ ━━━━<br/> key : value <br/>━━━━ СГЕНЕРИРОВАНО ━━━━<br/> id : uuid‑123 "]:::resourceNode
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Иерархия и связи
|
||
|
||
Диаграммы строятся по принципу логической зависимости (Dependency Graph):
|
||
- **Прямая стрелка** (`-->`): Жёсткая зависимость (параметр одного ресурса ссылается на UID другого).
|
||
- **Пунктирная стрелка** (`-.->`): Косвенная зависимость или логическая связь (например, Edge и vApp в одной сети).
|
||
|
||
Рекомендуемое направление: `flowchart LR` (слева направо) для отображения жизненного цикла развертывания.
|