docs(TODO): баг docs-generator - вложенный map-fixed как блок вместо = {}

2026-09-21 19:57:48 +03:00
parent d608fba338
commit 92e04daea5
1 changed files with 90 additions and 0 deletions
@@ -0,0 +1,90 @@
+# docs-generator: неверный HCL-синтаксис для вложенных параметров (map-fixed / array-map-fixed)
+
+Дата: 2026-09-21 | Версия провайдера: 2.0.4 | Статус: не исправлено
+
+## Суть проблемы
+
+Docs-генератор рендерит вложенные параметры (`map-fixed`) в HCL-примерах как **блоки**:
+
+```hcl
+routed_net_configuration {
+  ip_addr_pool = "10.10.102.0/24"
+  main_dns     = "81.22.46.22"
+  second_dns   = "185.247.187.77"
+}
+```
+
+Но resource-generator объявляет эти поля как `schema.SingleNestedAttribute`, а в HCL это **аргумент**, который задаётся через `=` и объект:
+
+```hcl
+routed_net_configuration = {
+  ip_addr_pool = "10.10.102.0/24"
+  main_dns     = "81.22.46.22"
+  second_dns   = "185.247.187.77"
+}
+```
+
+Пользователь копирует пример из доки → `terraform validate` падает:
+
+```
+Error: Unsupported block type
+  on edge.tf line 15, in resource "nubes_vc_nsxt" "edge":
+  15:   routed_net_configuration {
+Blocks of type "routed_net_configuration" are not expected here.
+Did you mean to define argument "routed_net_configuration"?
+If so, use the equals sign to assign it a value.
+```
+
+## Доказательства
+
+- Пример из доки (сгенерирован): `generated/dev/docs/vc_nsxt_example.md` — блок используется и в minimal, и в full примере.
+- Реальная схема: `generated/dev/go/22_vc_nsxt_resource.go:81` —
+  `"routed_net_configuration": schema.SingleNestedAttribute{Required: true, Attributes: {...}}`.
+- Практика: `cd DEV_STAND/FullPipe && terraform validate` на блоке → `Unsupported block type`.
+  После замены на `= { ... }` → `Success! The configuration is valid.`
+- Масштаб:
+  - `grep -rho 'schema\.[A-Za-z]*NestedAttribute' generated/dev/go/*.go | sort | uniq -c`
+    → `75 schema.SingleNestedAttribute`, `ListNestedAttribute` — **0**.
+  - Сервисов с `map-fixed` в YAML: ~25 (19_vc_org, 21_vc_vdc, 22_vc_nsxt, 28_vc_vm_v3,
+    86_k8s_velero, 89_flask, 90_postgres, ..., 151_k8s_openbao, 153_nifi).
+
+## Причина
+
+`TOOLS/docs-generator/internal/writers/writers.go`, функция `formatParamOrBlock` (~строка 707):
+
+- ~строка 715: `fmt.Sprintf("%s%s {\n", indent, paramCode)` — рендерит `map-fixed` как блок;
+- ~строка 739: то же самое для ветки `array-map-fixed` («dynamic блок»).
+
+Resource-generator (`TOOLS/resource-generator`, шаблон `instance.go`) для вложенных
+параметров использует `schema.SingleNestedAttribute` (хелпер `NestedSchemaBlock`).
+Значит docs-generator обязан рендерить `= { ... }`, а не блок.
+
+Дополнительно: `array-map-fixed` (ветка `p.HasSubParams && p.IsJson`) resource-generator
+отдаёт как обычный `schema.StringAttribute` (JSON-строка), напр. в 21_vc_vdc:
+`"storage_config": schema.StringAttribute{... Default: stringdefault.StaticString("[{}]")}`.
+Т.е. и эта ветка в доке рендерится неверно (блок вместо JSON-строки).
+
+## Что править
+
+**Один файл:** `TOOLS/docs-generator/internal/writers/writers.go`, `formatParamOrBlock`.
+
+1. `map-fixed` (`p.HasSubParams && !p.IsJson`): заменить `"%s%s {\n"` → `"%s%s = {\n"`
+   (закрывающая `}` остаётся `"%s}\n"`).
+2. `array-map-fixed` (`p.HasSubParams && p.IsJson`): привести к реальному типу —
+   JSON-строка (`jsonencode([...])`), НЕ блок. Предварительно сверить со схемой ресурса.
+3. Проверить вызывающий код: `exampleBlock` (~строка 288) и `minimalExampleBlock` (~строка 325)
+   — оба дергают `formatParamOrBlock`.
+
+## Чеклист
+
+- [ ] `formatParamOrBlock`: `map-fixed` → `param = { ... }` (аргумент, не блок)
+- [ ] `formatParamOrBlock`: `array-map-fixed` → JSON-строка / `jsonencode`, не блок
+- [ ] Проверить `exampleBlock` и `minimalExampleBlock`
+- [ ] Перегенерировать доки (`./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/dev`)
+- [ ] Скопировать пример из доки для 2-3 сервисов с `map-fixed` и прогнать `terraform validate`
+- [ ] (опционально) юнит-тест на рендер вложенного параметра
+
+## Примечание
+
+Текущий обходной путь в `DEV_STAND/FullPipe/edge.tf` уже использует правильный синтаксис
+(`routed_net_configuration = { ... }`), поэтому `terraform validate` проходит.