add: documentation

2026-06-30 15:45:24 +04:00
parent 540c1f7293
commit ca276d200f
1055 changed files with 47294 additions and 0 deletions
@@ -0,0 +1,65 @@
+# Методология визуализации ресурсов и зависимостей (Golden Standard)
+
+Этот документ описывает стандарт визуального представления инфраструктуры Nubes Cloud в виде Mermaid-диаграмм. Этот стандарт был выработан для обеспечения максимальной читаемости, точности параметров и отсутствия искажений при рендеринге в IDE и браузере.
+
+---
+
+## 1. Концепция "Золотого стандарта" узла
+
+Каждый ресурс (Organization, vDC, VM и т.д.) представляется как "карточка" с жестко структурированным содержимым.
+
+### Визуальные правила
+1. **Моноширинный шрифт**: Обязательное использование `font-family:monospace` через `classDef`. Это позволяет выровнять символы по вертикали.
+2. **Запрет переноса строк (No-Wrap)**: 
+   - Имена и UUID не должны разрываться. 
+   - Используются **неразрывные дефисы** (`‑`, Unicode `U+2011`) вместо обычных.
+   - Используются **неразрывные пробелы** (`&nbsp;`) для отступов.
+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>Тип&nbsp;ресурса</i><br/><b>имя_в_terraform</b><br/>━━━━&nbsp;ПАРАМЕТРЫ&nbsp;━━━━<br/>&nbsp;&nbsp;&nbsp;key&nbsp;:&nbsp;value&nbsp;&nbsp;&nbsp;<br/>━━━━&nbsp;СГЕНЕРИРОВАНО&nbsp;━━━━<br/>&nbsp;&nbsp;&nbsp;&nbsp;id&nbsp;:&nbsp;uuid‑123&nbsp;"]:::resourceNode
+```
+
+---
+
+## 4. Иерархия и связи
+
+Диаграммы строятся по принципу логической зависимости (Dependency Graph):
+- **Прямая стрелка** (`-->`): Жёсткая зависимость (параметр одного ресурса ссылается на UID другого).
+- **Пунктирная стрелка** (`-.->`): Косвенная зависимость или логическая связь (например, Edge и vApp в одной сети).
+
+Рекомендуемое направление: `flowchart LR` (слева направо) для отображения жизненного цикла развертывания.