docs: record universal dev generator fix plan and Sol review prompt

2026-09-03 10:36:45 +03:00
parent 02b7d7b701
commit 62d8d7b45d
2 changed files with 130 additions and 0 deletions
@@ -0,0 +1,85 @@
+# Баг Dev-генератора: рассинхрон nested-параметра
+
+**Дата:** 2026-09-03
+**Статус:** план решения, изменения не выполнены
+
+## Симптом
+
+Сборка Dev-провайдера падает на сгенерированном `95_nodejs_resource.go`:
+
+```text
+plan.JsonEnv.IsNull undefined
+plan.JsonEnv.IsUnknown undefined
+plan.JsonEnv.ValueString undefined
+```
+
+## Причина
+
+В Dev API один и тот же параметр `jsonEnv` описан по-разному:
+
+- в `create` — `map` с `sub_params` (`DB_PASS`), то есть nested-параметр;
+- в `modify` — `map` без `sub_params`, то есть параметр выглядит плоским.
+
+Генератор объединяет параметры через `params.Merge`. Поэтому в канонической
+`SchemaParams` `jsonEnv` становится nested и модель содержит
+`*NodejsJsonEnvModel`.
+
+Однако `params.AlignParamTypes` переносит вложенные параметры только когда у
+параметра операции уже установлен `HasSubParams`. У `modify.jsonEnv` этот флаг
+ложный, поэтому `ModifyParams` сохраняет scalar-представление.
+
+Шаблон `Update` видит `modify.jsonEnv` как scalar и генерирует вызовы
+`IsNull()`, `IsUnknown()` и `ValueString()`. В сгенерированной модели это
+указатель на nested-структуру, поэтому Go-код не компилируется.
+
+## Универсальное решение
+
+Генератор не должен содержать условий для Dev, Test, Prod или конкретного
+сервиса. Нужна единая нормализация всех operation params относительно общей
+канонической схемы:
+
+```text
+schemaParams = Merge(createParams, modifyParams, deleteParams)
+createParams = NormalizeAgainstSchema(createParams, schemaParams)
+modifyParams = NormalizeAgainstSchema(modifyParams, schemaParams)
+deleteParams = NormalizeAgainstSchema(deleteParams, schemaParams)
+```
+
+Нормализация должна рекурсивно переносить из канонической схемы структурные
+свойства:
+
+- `Type`;
+- `HasSubParams`;
+- `SubParams` и их типы.
+
+Собственные свойства конкретной операции должны сохраняться: `ID`,
+`Required`, `Default`, описания и остальные operation-specific поля.
+
+После нормализации `SchemaParams.jsonEnv` и `ModifyParams.jsonEnv` будут иметь
+одинаковую nested-структуру, а шаблон сгенерирует nested-обработку вместо
+scalar-методов.
+
+## Граница ответственности
+
+Расхождение Dev API остаётся дефектом входной схемы, но не должно ломать
+универсальный генератор. Исправление только YAML Dev или специальная проверка
+`jsonEnv` были бы стендовыми обходами и не решают общий класс проблем.
+
+## Обязательная проверка
+
+Добавить генераторный тест на общий случай:
+
+```text
+create:  map-fixed/map с sub_params
+modify:  тот же code без sub_params
+ожидание: modify после нормализации — nested
+```
+
+Проверка результата: сгенерированный Go-код должен компилироваться, а nested
+параметр не должен получать scalar-вызовы в `Update`.
+
+## Текущий статус стендов
+
+- Test `3.0.0` опубликован.
+- Prod `1.0.0` опубликован.
+- Dev `2.0.0` не опубликован: сборка остановилась на компиляции generated Go.
@@ -0,0 +1,45 @@
+# Проверка решения бага Dev-генератора
+
+Ты выполняешь короткий read-only review. Ничего не меняй, не запускай генерацию,
+не собирай и не публикуй провайдер.
+
+## Задача
+
+Проверь, правильно ли диагностирован баг и правильно ли предложено решение:
+
+1. `create.jsonEnv` может быть nested (`sub_params`), а `modify.jsonEnv` — без
+   `sub_params`.
+2. `Merge` формирует каноническую схему из параметров операций.
+3. `AlignParamTypes` выравнивает типы, но не переносит `HasSubParams/SubParams`,
+   если у operation-параметра `HasSubParams` изначально false.
+4. Шаблон `Update` поэтому генерирует scalar-вызовы для поля, которое в модели
+   является nested-структурой.
+5. Универсальное решение — нормализовать каждый набор operation params
+   относительно канонической `SchemaParams`, рекурсивно наследуя структурные
+   свойства, без условий по стенду или сервису.
+
+## Прочитать только эти файлы
+
+1. `TOOLS/resource-generator/internal/params/params.go`
+2. `TOOLS/resource-generator/internal/loader/loader.go`
+3. `TOOLS/resource-generator/internal/helpers/helpers.go` — только функции
+   `IsNested` и связанные с nested-моделями
+4. `TOOLS/resource-generator/internal/templates/instance.go` — только участки
+   `Update` и проверки `IsNested`
+5. `TOOLS/resource-generator/internal/types/types.go`
+6. `generated/dev/resources_yaml/95_nodejs.yaml` — только `jsonEnv` в create и modify
+7. `generated/dev/go/95_nodejs_resource.go` — только модель `JsonEnv` и `Update`
+
+Не изучай остальные сервисы, стенды, историю проекта или API вне этих файлов.
+
+## Формат ответа
+
+Ответь максимум в 5 коротких пунктах:
+
+- **Вердикт:** прав / частично прав / неправ.
+- **Доказательство:** одна конкретная цепочка от YAML до ошибочного Go-кода.
+- **Решение:** корректно ли выравнивать operation params по канонической схеме.
+- **Риск:** один главный риск предлагаемого решения.
+- **Итог:** что именно нужно изменить или что менять не следует.
+
+Не предлагай реализацию, diff, рефакторинг или дополнительные исследования.