docs: Opus questions round 2 — deep analysis of generation scripts and tools

2026-06-30 17:56:41 +04:00
parent 4235f3e05e
commit 966def9456
3 changed files with 640 additions and 0 deletions
@@ -0,0 +1,174 @@
+# Вопросы к 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)