tf_provider/HISTORY/OPUS/3006_2_scripts_questions.md

Вопросы к Opus 4.8: Анализ генерационных скриптов и промежуточного кода

Контекст: Ты уже проанализировал ПРОВАЙДЕР (client.go, crud.go, gen_v2). Теперь нужен анализ СКРИПТОВ ГЕНЕРАЦИИ — как API-данные превращаются в YAML, Go-код и документацию. Режим: Plan (только чтение). Все пути относительно /home/naeel/tf_provider/.

---

Вопрос 1: Bash-скрипты — полный аудит

Файлы:

• devops/01_generate_yamls.sh — API → YAML
• devops/02_generate_resources_and_docs_v2.sh — YAML → Go + Docs
• devops/03_build_and_upload_provider.sh — сборка + S3
• devops/04_build_and_publish_docs.sh — публикация документации

Задача: прочитай ВСЕ 4 скрипта полностью. Для каждого проверь:

1. Обработка ошибок:

   • Что происходит при set -e — на каком шаге скрипт упадёт?
   • Есть ли trap для очистки временных файлов?
   • Что если API вернул 500? Пустой ответ? Битый JSON?
   • Что если services_list.txt пустой?

2. Зависимости:

   • Какие внешние инструменты нужны (go, python3, mc, gpg, mkdocs)?
   • Проверяются ли они перед запуском?
   • Что если инструмент отсутствует — понятная ли ошибка?

3. Идемпотентность:

   • Можно ли перезапустить скрипт при обрыве?
   • Чистит ли он предыдущий мусор перед генерацией?
   • Что с параллельным запуском двух экземпляров?

4. User-Agent / DDoS-Guard:

   • 01_generate_yamls.sh вызывает python urllib для получения имён сервисов (строка ~170). Есть ли там User-Agent?
   • Как Go-бинари (service_spec_gen) получают токен? Через env?

5. Профили (test/prod/dev):

   • Как скрипты определяют какой профиль использовать?
   • Что если --profile не указан? Есть ли защита от запуска без профиля?
   • Где хранятся сгенерированные артефакты для каждого профиля?

---

Вопрос 2: service_spec_gen — API → YAML (ключевой генератор)

Файл: universal_rebuild/tools/service_spec_gen/generate_service_spec.go

Мы уже добавили User-Agent, но проверь остальное:

1. HTTP-клиент:

   • Есть ли retry при ошибках API (429, 503, network)?
   • Какой таймаут? http.Client{Timeout: 30s} — достаточно ли?
   • Используется ли http.DefaultClient или свой?

2. Парсинг ответа API:

   • Структуры serviceInfo, serviceOperationInfo, operationInfo — все ли поля API маппятся?
   • Есть ли поля которые API возвращает, но генератор игнорирует (потеря данных)?
   • Что если API вернёт неожиданный формат — будет panic или ошибка?

3. Классификация операций (classifyOperation):

   • Как определяется kind (instance/subresource/action)?
   • Правило: create/modify/delete/suspend/resume → instance, create_*/modify_*/delete_* → subresource, остальное → action. Все ли кейсы покрыты?
   • Что с новыми префиксами, которые могут появиться (например, restart_*)?

4. Сбор параметров:

   • Поля ParamSpec — все ли constraints из API сохраняются (maxLength, minLength, regex, uniqueScope, dependsOn)?
   • normalizeDefault — правильно ли обрабатывает null/числа/строки?
   • normalizeValueList — преобразует []interface{} в []string. Что если элемент не строка?

5. Выходной YAML:

   • yaml.Marshal — сохраняет ли все поля корректно (omitempty, вложенные структуры)?
   • Имя файла: {id}_{name}.yaml. Что если имя содержит спецсимволы?

---

Вопрос 3: gen_v2 — YAML → Go (уже проанализирован, но проверь детали)

Файл: universal_rebuild/tools/gen_v2/generate_resources_v2.go

Мы уже добавили validateSpec(). Проверь:

1. Обработка ошибок генерации:

   • format.Source — что при ошибке форматирования? Пишет битый код или паникует?
   • writeInstanceResource / writeSubresource / writeActionResource — обрабатывают ли ошибки template.Execute?

2. Вычисление CreateOnly:

   • computeCreateOnly = параметр в create но не в modify → ForceNew. Что если modify-операция существует но не содержит этот параметр потому что он неизменяем? Это корректно?

3. Subresource identity:

   • Если нет modify → все параметры ForceNew. Если есть modify → как определяется identity?
   • buildSubresourceForceNewCodes — правильная ли логика?

4. JSON-параметры:

   • data_type: json → IsJson=true + JsonNormalize plan-modifier. Достаточно ли этого для всех JSON-типов (map, array, object)?

---

Вопрос 4: docs_template_gen_v2 — генерация документации

Файлы: universal_rebuild/tools/docs_template_gen_v2/main.go

1. Что именно генерируется?

   • Какие страницы/файлы создаются?
   • Формат выхода — Markdown для mkdocs?
   • Все ли поля из YAML используются (MAN, params, outputs, lifecycle)?

2. Покрытие:

   • Генерируется ли документация для subresource и action ресурсов?
   • Есть ли index/overview страницы?
   • Примеры (HCL examples) — откуда берутся?

3. Ошибки:

   • Что при битом YAML? Пустых операциях?
   • Флаг -exclude clickhouse — почему хардкод?

---

Вопрос 5: service_ops_gen и service_params_gen — нужны ли они?

Файлы:

• universal_rebuild/tools/service_ops_gen/generate_service_ops.go
• universal_rebuild/tools/service_params_gen/generate_service_params.go

Эти тулы выглядят как устаревшие (в коде написано APPEND-ONLY). service_spec_gen заменил их (генерирует унифицированный YAML вместо отдельных ops/params YAML).

1. Используются ли они где-то в скриптах?
2. Можно ли их удалить?
3. Есть ли gen/ (v1) — он ещё нужен?

---

Вопрос 6: embed.go и resources_yaml

Файлы:

• universal_rebuild/resources_yaml/embed.go
• devops/profiles/*/generated/resources_yaml/embed.go

1. embed.go использует //go:embed *.yaml — встраивает YAML в бинарник. Зачем?
2. Где в коде провайдера используется resources_yaml.Files?
3. Почему embed.go создаётся bash-скриптом, а не лежит в репо?

---

Вопрос 7: Профили и CI

Файлы:

• devops/profiles/test/, prod/, dev/
• devops/ci/pipeline.yaml
• .github/workflows/

1. Как CI-пайплайн связан с профилями?
2. Есть ли автоматический прогон генерации в CI?
3. Как происходит деплой — через operator в K8s или вручную?
4. devops/10_yaml_stability_run.sh — зачем несколько скриптов стабильности (10-13)?

---

Вопрос 8: Практическая проверка

Мы сегодня попробовали сгенерировать YAML для postgres (service_id=90) и обнаружили что API добавил 2 новые операции (backup, reconcile) которых нет в старом сгенерированном коде.

Задача: проверь ВСЕ сервисы из services_list.txt на наличие YAML в devops/profiles/test/generated/resources_yaml/. Какие сервисы есть в списке но отсутствуют в сгенерированных YAML? Какие YAML есть но сервис исключён из списка?

---

Формат ответа

На каждый вопрос: что прочитал → проблема → предложение → приоритет (P0/P1/P2).

Особое внимание:

• Bash-скриптам (01_generate_yamls.sh — самый критичный)
• HTTP-клиентам в Go-генераторах (UA, retry, таймауты)
• Целостности данных (не теряем ли поля API при генерации YAML)