docs: пометить отменённый заход модификаторов как LEGACY + исправить ложные факты

- баннеры «ЛОЖНЫЙ ПУТЬ — ОТМЕНЕНО» на 4 файла HISTORY/OPUS/2026-09-22_modifier_* и docs/60_strategy/modifier_resources_ideology_and_specification.md - vIPConfigure: replace-семантика, НЕ накопительная (по тесту docs/ORG_IP_MODIFIER_TEST_2026-09-22.md) - обновлены ссылки на перенесённые материалы (docs/... -> NOTES/..., HOW_TO/...)
2026-09-24 07:51:25 +03:00
parent d93ff66482
commit 2d8e435dd4
59 changed files with 23 additions and 6 deletions
@@ -0,0 +1,106 @@
+# План: чистка реестра + новая нумерация версий по стендам
+
+> Для Flash. Цель — убрать ВСЕ старые залитые версии (легаси) и ввести единый
+> принцип нумерации, чтобы старое (5.1.17 и т.п.) больше нигде не всплывало.
+
+## Новый принцип нумерации (ЗАФИКСИРОВАТЬ)
+
+| Стенд | Namespace | Диапазон версий | Первая версия по новой схеме |
+|---|---|---|---|
+| **prod** | `nubes` | `1.*.*` | `1.0.0` |
+| **dev** | `nubes-dev` | `2.*.*` | `2.0.0` |
+| **test** | `nubes-test` | `3.*.*` | `3.0.0` |
+
+> ⛔ Старые схемы (`prod=2.*`, `dev=3.*`, `test=5.*`, а также `0.0.1`) — ЛЕГАСИ.
+> Никогда больше не использовать.
+
+## Текущее состояние в S3 (нужно УДАЛИТЬ ВСЁ)
+
+Бакет `nubes-terraform-registry`, префикс `tf-registry.containerk8s.services.ngcloud.ru/<ns>/nubes/`:
+
+- `nubes-dev`: `3.0.2 3.0.3 3.0.4 3.0.5 3.0.6`
+- `nubes` (prod): `2.0.2 2.0.3 2.0.5 2.0.6`
+- `nubes-test`: `0.0.1 5.0.1 5.0.2 5.0.3 5.0.4 5.0.5 5.1.17`
+
+## Шаг 1 — Удалить все залитые версии из S3
+
+Креды на запись: subuser `super` аккаунта `1112_terraform`,
+передаются через переменные окружения `S3_ACCESS_KEY` и `S3_SECRET_KEY`.
+
+```bash
+mc alias set super-s3 https://s3.msk-1.ngcloud.ru "$S3_ACCESS_KEY" "$S3_SECRET_KEY" --api S3v4
+
+# Удалить ВСЕ версии каждого стенда (рекursивно, включая подфайлы)
+mc rm --recursive --force super-s3/nubes-terraform-registry/tf-registry.containerk8s.services.ngcloud.ru/nubes-test/nubes/
+mc rm --recursive --force super-s3/nubes-terraform-registry/tf-registry.containerk8s.services.ngcloud.ru/nubes-dev/nubes/
+mc rm --recursive --force super-s3/nubes-terraform-registry/tf-registry.containerk8s.services.ngcloud.ru/nubes/nubes/
+```
+
+Проверка после удаления (должно быть пусто):
+```bash
+mc ls super-s3/nubes-terraform-registry/tf-registry.containerk8s.services.ngcloud.ru/nubes-test/nubes/
+mc ls super-s3/nubes-terraform-registry/tf-registry.containerk8s.services.ngcloud.ru/nubes-dev/nubes/
+mc ls super-s3/nubes-terraform-registry/tf-registry.containerk8s.services.ngcloud.ru/nubes/nubes/
+```
+
+## Шаг 2 — Зафиксировать новую нумерацию в конфигах и док-файлах
+
+Обновить (каждый файл — по новому принципу prod=1.*, dev=2.*, test=3.*):
+
+1. **`VERSIONS.md`** — таблица версий по стендам + схема:
+   - PROD → `1.*` (первая `1.0.0`)
+   - DEV → `2.*` (первая `2.0.0`)
+   - TEST → `3.*` (первая `3.0.0`)
+2. **`TOOLS/config/prod/profile.env`** → `VERSION="1.0.0"`
+3. **`TOOLS/config/dev/profile.env`** → `VERSION="2.0.0"`
+4. **`TOOLS/config/test/profile.env`** → `VERSION="3.0.0"`
+5. **`DOCS_PIPELINE/README.md`** — раздел про нумерацию версий (схема выше).
+6. **`docs/30_registry/guides/getting-started.md`** — `version = "..."` в примере привести
+   к актуальной (или оставить как «подставьте нужную», но НЕ 5.0.5 и не 5.1.17).
+
+> ⚠️ Проверить, что в этих файлах нигде не осталось `5.1.17`, `5.0.x`, `3.0.x`
+> (кроме новой схемы), `2.0.x` (кроме новой `1.x` для prod). Сделать `grep -rn`.
+
+## Шаг 3 — Перегенерировать провайдеры по новой схеме (01→02→03)
+
+Для каждого стенда (порядок test → dev → prod), версия = первая по новой схеме:
+
+```bash
+cd /home/naeel/TF/tf_provider
+
+# TEST → 3.0.0
+./TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/test
+./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/test
+S3_ACCESS_KEY="$S3_ACCESS_KEY" S3_SECRET_KEY="$S3_SECRET_KEY" \
+  ./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/test 3.0.0
+
+# DEV → 2.0.0
+./TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/dev
+./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/dev
+S3_ACCESS_KEY="$S3_ACCESS_KEY" S3_SECRET_KEY="$S3_SECRET_KEY" \
+  ./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/dev 2.0.0
+
+# PROD → 1.0.0
+./TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/prod
+./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/prod
+S3_ACCESS_KEY="$S3_ACCESS_KEY" S3_SECRET_KEY="$S3_SECRET_KEY" \
+  ./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/prod 1.0.0
+```
+
+> Документацию (04) НЕ запускать — пользователь пока не просил.
+
+## Предусловия (ПРОВЕРЕНО)
+
+- Go 1.23.1, docker, `mc`, GPG-ключи — на месте.
+- Токены API `secrets/{dev,test,prod}.token` — ОБНОВЛЕНЫ 2026-09-03 (валидны, exp 2027-03-02).
+- `operation_timeouts.json` в каждом профиле — на месте.
+- S3-креды на запись бинарников — `super` subuser (см. выше).
+- `registry.env`: hostname `tf-registry.containerk8s.services.ngcloud.ru`, bucket `nubes-terraform-registry`.
+
+## Контроль
+
+После каждого `03` — сообщение `Done. Version X.Y.Z uploaded.`
+После всех — в S3 должны остаться ТОЛЬКО:
+- `nubes/nubes/1.0.0/`
+- `nubes-dev/nubes/2.0.0/`
+- `nubes-test/nubes/3.0.0/`
@@ -0,0 +1,223 @@
+> ⛔ **LEGACY / НЕ ИСТОЧНИК ИСТИНЫ (помечено 2026-09-24).**
+> Этот план относится к отменённому заходу (метки `kind: modifier` в YAML + реестр в `yaml-generator`).
+> Актуальное состояние и выводы: `docs/CHAT_RESUME_IAC_2026-09-24.md`,
+> `docs/SHTURVAL_IAC_MODIFY_ANALYSIS_2026-09-23.md`, `docs/OPUS_ANSWER_IAC_SHTURVAL_MODIFY_2026-09-23.md`.
+
+# ПЛАН реализации: редизайн ресурсов-модификаторов (kind: modifier)
+
+Основа: `HISTORY/OPUS/2026-09-22_modifier_architecture_project.md`.
+Ревью плана: `HISTORY/OPUS/2026-09-22_modifier_plan_review.md`.
+Цель — закрыть все классы багов A–E, без костылей, по согласованной архитектуре.
+
+Порядок шагов (исправлен по ревью): шаблон (4) зависит от core/resources_core (5–7),
+поэтому: 1 → 2 → 3 → 5 → 6 → 7 → 4 → 8 → регенерация → 9 → 10.
+
+---
+
+## Шаг 1. Контракт YAML в `TOOLS/lib/types.go`
+
+Файл: `TOOLS/lib/types.go`, `OperationSpec`.
+
+Добавить поля (тег yaml, omitempty):
+```go
+DeleteStrategy string      `yaml:"delete_strategy,omitempty"` // "" → noop_warn
+Idempotency    string      `yaml:"idempotency,omitempty"`     // "" → none
+DeleteParams   []ParamSpec `yaml:"delete_params,omitempty"`
+```
+Enum `delete_strategy`: `noop_warn` | `inverse` | `error`.
+Enum `idempotency`: `none` | `check_before_run`.
+
+Проверка: `TOOLS/resource-generator` получает поля через алиас `OperationSpec = lib.OperationSpec` — отдельной правки не нужно, но `go build ./...` в lib и в resource-generator.
+
+---
+
+## Шаг 2. GenModifier — производные поля
+
+Файл: `TOOLS/resource-generator/internal/types/types.go`, `GenModifier`.
+
+Добавить:
+```go
+DeleteStrategy string       // нормализованный enum (noop_warn|inverse|error)
+Idempotency    string       // none|check_before_run
+DeleteParams   []Param      // из spec.DeleteParams (ConvertParams), только при inverse
+```
+
+---
+
+## Шаг 3. LoadSpecs — заполнение modifier + валидация
+
+Файл: `TOOLS/resource-generator/internal/loader/loader.go`, ветка `op.Kind == "modifier"`.
+
+До `continue`:
+- `modifier.DeleteStrategy = normalizeDeleteStrategy(op.DeleteStrategy)` (пусто → `noop_warn`);
+- `modifier.Idempotency = normalizeIdempotency(op.Idempotency)` (пусто → `none`);
+- `modifier.DeleteParams = ConvertParams(op.DeleteParams)` (при inverse).
+
+Helpers `normalizeDeleteStrategy`/`normalizeIdempotency` — добавить в `loader.go`
+(тот же пакет, рядом с веткой modifier).
+
+Файл: `loader.go`, `ValidateSpec` — расширить fail-fast для modifier:
+- `delete_strategy` вне enum → ошибка;
+- `delete_strategy == "inverse"` и пуст `delete_params` → ошибка;
+- каждый `delete_params.code` обязан существовать в `op.Params` (сравнение по lower-code) → иначе ошибка;
+- `idempotency` вне enum → ошибка.
+
+---
+
+## Шаг 4. Шаблон `modifier.go` — редизайн
+
+Файл: `TOOLS/resource-generator/internal/templates/modifier.go`.
+
+4.1. **Убрать `CompactParams`** — в Create/Update передавать map напрямую
+(все заданные поля; решение о досылке — в core).
+
+4.2. **Единый `reconcile()`** — вынести общее тело Create/Update в приватный метод
+`reconcile(ctx, model *Model, override map[string]string)`, вызываемый из Create и Update
+(override=nil). Устраняет дубль веток. **override нужен для Delete=inverse** (см. 4.4),
+так как Delete не имеет plan — только state.
+
+4.3. **ID = identity** — `plan.ID = BuildActionID(instanceUID, modifierName)`
+(убрать operation из ID). Реализовать через существующий `BuildActionID(instanceUID, "", modifierName)`
+или новый helper `BuildModifierID(instanceUID, modifierName)`.
+⚠️ **миграция state:** смена формата ID изменит ID уже задеплоенных модификаторов →
+Terraform форснёт replace. Принять решение ДО: сохранить старый формат ИЛИ явный
+state-migration план. По умолчанию — сохранить формат `uid:operation:modifier`, не менять формат.
+
+4.4. **Delete по стратегии**:
+```
+{{- if eq .DeleteStrategy "error" }}
+  Delete → AddError (запрет destroy); ⚠️ конфликт с replace: replace = Delete→Create,
+  при error пользователь не сможет заменить модификатор. Решение: запретить replace
+  у error-модификаторов (документировать) или отличить «чистый destroy» от replace.
+{{- else if eq .DeleteStrategy "inverse" }}
+  Delete → reconcile(state-model, override=delete_params)
+  (delete_params — финальные wire-строки: "false", готовый JSON; обработать как override)
+{{- else }}
+  Delete → RemoveResource + AddWarning («эффект остаётся на платформе»)
+{{- end }}
+```
+
+4.5. **Pre-check idempotency** — в reconcile при `eq .Idempotency "check_before_run"`:
+передавать флаг в вызов операции (см. шаг 6). ⚠️ при unknown (computed ref) pre-check
+skip — сравнение невозможно.
+
+---
+
+## Шаг 5. JSON-эквивалентность в нейтральный пакет (снять цикл импорта)
+
+Проблема: `JSONStringsEquivalent` в `resources_core`, а comparison нужен в `core`.
+- создать `provider/internal/core/jsonutil/jsonutil.go`:
+  перенести `JSONStringsEquivalent` + `normalizeJSONIfPossible` + `encodeCanonicalJSON` +
+  `writeCanonicalJSON` + `normalizeJSONScalarsToStrings` из `resources_core/json_normalize.go`;
+- `resources_core/json_normalize.go` — **оставить реэкспорт-обёртку** `JSONStringsEquivalent`
+  (не заменять вызовы по resources_core — иначе диф на инстансы).
+
+Проверка: `go build ./...`, нет цикла импорта.
+
+---
+
+## Шаг 6. core — pre-check `modifierDesiredEqualsCurrent`
+
+Файл: `provider/internal/core/operation_run_bycode.go` (или новый `modifier_compare.go`).
+
+Добавить (unexported, вызов внутри core):
+```go
+func (c *UniversalClient) modifierDesiredEqualsCurrent(
+    desired map[string]string, cfsParams []universalCfsParam) bool
+```
+Логика:
+- маппинг code→param по **двум** алиасам: `p.Code` И `p.SvcOperationCfsParam`
+  (как в operation_run_bycode.go:50-58);
+- для каждого desired-кода → live `ParamValue`;
+- bool/int/string → нормализовать обе стороны `normalizeUniversalValueV6` + сравнение строк;
+- map-fixed → `jsonutil.JSONStringsEquivalent`;
+- **array-map-fixed → `jsonutil.JSONStringsEquivalent` по сырым значениям, НЕ через normalize**
+  (`normalizeUniversalValueV6` не строит дефолт для array-map-fixed, params.go:33);
+- desired — только явно заданные коды (до досылки live/default);
+- если desired содержит unknown (computed ref) — сравнение невозможно, pre-check пропустить.
+
+Опционально: добавить в `RunInstanceOperationUniversalByCode` параметр `idempotent bool`
+(или новый метод-обёртка). В `operation_run_bycode.go` после `fetchOperationCfsParams`:
+```
+if idempotent && c.modifierDesiredEqualsCurrent(paramsByID, cfsParams) {
+    return nil   // skip run
+}
+```
+idle-гейт (`waitForInstanceIdle`) уже стоит выше — не трогать.
+
+---
+
+## Шаг 7. Передача флага `idempotent` вплоть до client
+
+Цепочка: шаблон → `resources_core.RunOperationByCodeWithTimeout` → `core.RunInstanceOperationUniversalByCode`.
+- **добавить НОВЫЙ метод `RunOperationByCodeIdempotent(...)` в `resources_core/crud.go`**,
+  НЕ менять сигнатуру `RunOperationByCodeWithTimeout` (его зовут инстансы);
+- пробросить флаг в `RunInstanceOperationUniversalByCode` (новый параметр или обёртка).
+
+---
+
+## Шаг 8. YAML-разметка (источник-канон) в `TOOLS/yaml-generator`
+
+Источник-канон — реестр исключений `serviceSpecificModifiers` в
+`TOOLS/yaml-generator/main.go` (Ключ — имя сервиса → имя modifier).
+`generated/dev` перегенерируется — туда НЕ вносить вручную.
+
+Контракт в `lib.OperationSpec` (алиас в обоих генераторах), значит yaml-generator
+должен проставлять флаги при маршале. Расширить реестр со `map[string]string`
+до структуры, несущей: `ModifierName`, `DeleteStrategy`, `Idempotency`,
+`DeleteParams []struct{Code,Value}`:
+
+```go
+type modifierException struct {
+    ModifierName   string
+    DeleteStrategy string          // noop_warn | inverse | error
+    Idempotency    string          // none | check_before_run
+    DeleteParams   []deleteParam   // только для inverse
+}
+type deleteParam struct { Code, Value string }
+
+var serviceSpecificModifiers = map[string]modifierException{
+    "vc_org":  {ModifierName: "ip_space", DeleteStrategy: "error", Idempotency: "check_before_run"},
+    "vc_nsxt": {ModifierName: "network", DeleteStrategy: "inverse",
+                DeleteParams: []deleteParam{{"needEnableAVI", "false"}}},
+}
+```
+
+В цикле над ops (там, где `Kind="modifier"`): проставить `op.DeleteStrategy`,
+`op.Idempotency`, `op.DeleteParams`.
+
+⚠️ При переходе с `map[string]string` на структуру: `ModifierName` берётся из структуры
+(сейчас `modName, ok := serviceSpecificModifiers[name]` — строка 95 main.go).
+
+---
+
+## Порядок коммитов (по смыслу)
+
+1. `feat(lib): delete_strategy/idempotency/delete_params в OperationSpec`
+2. `feat(gen): GenModifier расширение + LoadSpecs + ValidateSpec + normalize-helpers`
+3. `refactor(core): вынести JSON-эквивалентность в jsonutil (+реэкспорт)`
+4. `feat(core): modifierDesiredEqualsCurrent + RunOperationByCodeIdempotent`
+5. `feat(gen): шаблон modifier — reconcile(override), Delete стратегия, ID identity`
+6. `feat(yaml): реестр исключений модификаторов (delete_strategy/idempotency)`
+7. `test(core,gen): unit-кейсы`
+8. `chore(dev): bump версии`
+
+---
+
+## Открытый вопрос — закрыт
+
+Источник-канон — реестр `serviceSpecificModifiers` в `TOOLS/yaml-generator/main.go`.
+Разметка `delete_strategy`/`idempotency` расширяет этот реестр, а НЕ правится вручную
+в `generated/dev`.
+
+---
+
+## Решения, нуждающиеся в подтверждении (из ревью)
+
+1. **ID=identity → РЕШЕНО: формат ID НЕ меняем** (оставить `uid:operation:modifier`).
+   Смена формата форснёт replace у задеплоенных модификаторов и вызовет баг E.
+   Идемпотентность — через pre-check, не через ID. Шаг 4.3 отменён (ID остаётся как есть).
+2. **`error` + replace.** Пользователь не сможет заменить error-модификатор.
+   Предлагаю: оставить `error` только для «чистого» destroy, документировать запрет replace.
+3. **Разметка по default** — `ip_space`: `delete_strategy=error`, `idempotency=check_before_run`;
+   `network`: `delete_strategy=inverse`, delete_params=[needEnableAVI=false], idempotency=none.
@@ -0,0 +1,78 @@
+# План: перегенерация провайдеров всех стендов (версия 0.0.1)
+
+> Для Flash. Генерацию выполняет Flash по этому плану. Документацию НЕ трогать.
+
+## Цель
+Перегенерировать код Terraform-провайдера Nubes для 3 стендов из API и залить
+бинарники **версии 0.0.1**. Документацию не генерировать и не публиковать.
+
+## Версия
+`0.0.1` — для всех трёх стендов.
+
+## Порядок стендов
+`test` → `dev` → `prod`
+
+## Команды (для каждого стенда, по порядку)
+
+```bash
+cd /home/naeel/TF/tf_provider
+
+# стенд = test | dev | prod
+./TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/<стенд>
+./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/<стенд>
+./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/<стенд> 0.0.1
+```
+
+Полные команды:
+```bash
+# TEST
+./TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/test
+./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/test
+./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/test 0.0.1
+
+# DEV
+./TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/dev
+./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/dev
+./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/dev 0.0.1
+
+# PROD
+./TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/prod
+./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/prod
+./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/prod 0.0.1
+```
+
+## Что делает каждый шаг
+
+| Шаг | Результат |
+|---|---|
+| `01` | тянет YAML-спеки ресурсов из API стенда → `generated/<стенд>/resources_yaml/` |
+| `02` | YAML → **Go-код** (`generated/<стенд>/go/`) + `.md`-доки (`generated/<стенд>/docs/`, побочный продукт — НЕ публикуем) |
+| `03` | кросс-сборка linux/windows/darwin amd64 (`go build -ldflags "-X main.version=0.0.1 -X main.address=tf-registry.containerk8s.services.ngcloud.ru/<ns>/nubes"`) → `SHA256SUMS` + GPG-подпись → `mc cp` в S3 |
+
+## Namespace и target S3 (автоматически из profile.env + registry.env)
+
+| Стенд | Namespace | Бинарники в S3 |
+|---|---|---|
+| dev | `nubes-dev` | `terraform-registry/tf-registry.containerk8s.services.ngcloud.ru/nubes-dev/nubes/0.0.1/` |
+| test | `nubes-test` | `terraform-registry/tf-registry.containerk8s.services.ngcloud.ru/nubes-test/nubes/0.0.1/` |
+| prod | `nubes` | `terraform-registry/tf-registry.containerk8s.services.ngcloud.ru/nubes/nubes/0.0.1/` |
+
+## Предусловия — ПРОВЕРЕНО, всё готово
+- Go 1.23.1, docker 29.1.3, `mc`, GPG (`secrets/private_key.asc`, `public_key.asc`).
+- Токены API: `secrets/{dev,test,prod}.token` на месте.
+- API-эндпоинты доступны (HTTP 403 без токена — ожидаемо, токен передаёт 01).
+- `TOOLS/config/<стенд>/operation_timeouts.json` на месте.
+- `registry.env`: `REGISTRY_HOSTNAME=tf-registry.containerk8s.services.ngcloud.ru`, `S3_BUCKET=terraform-registry`.
+
+## Чего НЕ делать
+- НЕ запускать `04_build_and_publish_docs.sh` (документация не нужна сейчас).
+- НЕ менять версию `0.0.1` на другую.
+- НЕ трогать `.venv`/mkdocs (для 03 не нужны).
+
+## Контроль успеха
+Каждый `03` должен завершиться сообщением `Done. Version 0.0.1 uploaded.`
+Проверка версии в реестре после заливки (опционально):
+```bash
+curl -s https://tf-registry.containerk8s.services.ngcloud.ru/v1/providers/<ns>/nubes/versions
+```
+(должна появиться `0.0.1`).