chore: промежуточные изменения в TEST_STAND, docs, s.sh

2026-07-02 11:31:38 +04:00
parent 76f0b82c96
commit 54647b2fbf
7 changed files with 408 additions and 4 deletions
@@ -0,0 +1,215 @@
+# ПЛАН: Создание общего справочника разработчика
+
+> Этот файл — инструкция для нового чата.
+> Прочитать перед началом работы.
+
+---
+
+## 1. Задача
+
+Создать единый справочник разработчика по ВСЕМ проектам, чтобы:
+- Агенты не повторяли одни и те же ошибки
+- Было удобно искать по любой теме/симптому
+- Было удобно добавлять новые записи
+
+## 2. Где разместить
+
+**Вариант A (рекомендую):** `/home/naeel/global-dev-reference/`
+
+Отдельная директория в `~`. Плюсы:
+- Не привязана к одному репозиторию
+- Агент видит файлы если workspace открыт на `/home/naeel/`
+- Можно проинициализировать git (опционально)
+- Можно сделать символическую ссылку из каждого проекта
+
+**Вариант B:** В `docs/help/dev-reference/` внутри tf_provider.
+- Минус: другие проекты не увидят.
+- Минус: привязано к одному репо.
+
+## 3. Какие проекты включить
+
+| Проект | Путь | Что содержит |
+|--------|------|-------------|
+| **tf_provider** | `/home/naeel/tf_provider/` | Terraform provider (Universal + Legacy), docs/, HISTORY/ |
+| **contracts** | `/home/naeel/nubes/contracts/` | Проект contracts |
+| **ipwhitelist** | `/home/naeel/ipwhitelist/` | Проект ipwhitelist |
+| **ВМ 5.172.178.213** | SSH: `naeel@5.172.178.213` | Registry-server, старые скрипты, история |
+| **terra/** | `/home/naeel/terra/` | Старые проекты (fission, IoT, karta, lang...) |
+
+## 4. Структура справочника
+
+```
+/home/naeel/global-dev-reference/
+├── INDEX.md                    # Оглавление + алфавитный указатель
+├── INSTRUCTION.md              # Как добавлять новую запись
+├── TLDR_FOR_AGENTS.md          # Агентам — прочитать ОБЯЗАТЕЛЬНО
+│
+├── projects/                   # По проектам
+│   ├── tf_provider/
+│   │   ├── BUGS.md            # Все баги tf_provider
+│   │   ├── ARCHITECTURE.md    # Ключевые архитектурные решения
+│   │   ├── STATE_MATRIX.md    # Матрица состояний инстансов
+│   │   └── PARAM_MAP.md       # Маппинг параметров create↔modify
+│   ├── contracts/
+│   │   └── BUGS.md
+│   ├── ipwhitelist/
+│   │   └── BUGS.md
+│   └── registry-vm/
+│       └── BUGS.md
+│
+└── cross-cutting/              # Сквозные темы (общие для всех проектов)
+    ├── AUTH.md                 # Проблемы аутентификации (токены, DDoS-Guard, GPG)
+    ├── POLLING.md              # Паттерны polling (dtFinish, таймауты)
+    ├── DDS_GUARD.md            # DDoS-Guard: где и как обходить
+    ├── GPG.md                  # GPG подписи: ключи, форматы, ошибки
+    ├── REGISTRY_PROTOCOL.md    # Terraform Registry Protocol
+    └── SSH_AND_VM.md           # Доступ к ВМ, sshfs, ключи
+```
+
+## 5. Формат одной записи (бага/решения)
+
+Каждый баг оформляется так:
+
+```markdown
+## [P0] Короткое название
+**Симптом:** что происходит, текст ошибки
+**Причина:** root cause
+**Решение:** что сделали/надо сделать
+**Статус:** ✅ FIXED / ⚠️ OPEN / ❌ WORKAROUND / 🟡 PLATFORM
+**Версия:** vX.Y.Z (где исправлено)
+**Файлы:**
+- `/абсолютный/путь/к/файлу.go:123` — что там
+**Источники:**
+- относительная ссылка на HISTORY файл
+```
+
+## 6. Что уже есть для tf_provider (ГОТОВЫЙ МАТЕРИАЛ)
+
+Уже собранные данные (можно сразу переносить):
+
+### Баги tf_provider (25+ штук):
+
+**A. Аутентификация и токены (P0)**
+- 401 Unauthorized — токен истёк
+- **403 DDoS-Guard (User-Agent)** — ✅ FIXED v5.0.75
+- **403 DDoS-Guard (POST)** — ⚠️ OPEN (причина не до конца ясна)
+- **HTTP/2 ALPN EOF** — ✅ FIXED (TLSNextProto)
+
+**B. Поллинг зависает (P0)**
+- Polling без dtFinish — ✅ FIXED (критерий dtFinish)
+- Polling игнорирует Instance Status ERROR/STOPPED — ✅ FIXED (waitForVMOperationAndInstanceStatus)
+- Polling не ловит асинхронные ошибки — ✅ FIXED (WaitForOperation)
+
+**C. Modify: Invalid CFS parameter 400 (P1)**
+- Разные svcOperationCfsParamId для create и modify — ✅ FIXED (runtime discovery)
+
+**D. Modify недоступен (P1)**
+- action modify not available — ✅ FIXED (guard через availableOperations)
+
+**E. Map/JSON/List invalid format 400 (P1)**
+- Пустые строки вместо {} / [] — ✅ FIXED (V2-V6 нормализации)
+- mapExample как `"\""` — ✅ FIXED (V6)
+
+**F. VM: зависание на FW (P0)**
+- String[]→GUID crash — ❌ WORKAROUND (валидатор, баг платформы)
+- accessIpList пустая строка — ✅ FIXED (ValidJSONArray + fallback)
+
+**G. VM modify: 500 checkParam (P1)**
+- Дублирование параметров при POST/PUT — ✅ FIXED (гибридный PUT/POST)
+
+**H. Postgres: split() on null (P0)**
+- Передан UUID бакета вместо UUID сервиса S3 — ✅ FIXED
+
+**I. GPG/Registry (P0)**
+- authentication signature from unknown issuer — ✅ FIXED (синхронизация ключей)
+- openpgp invalid data — ✅ FIXED (бинарная подпись без --armor)
+- Presigned URL не работает через Ingress — ✅ FIXED (proxy mode)
+- Registry Not Found (неполный ID) — ✅ FIXED
+- GPG ключ в репозитории secrets/ — ⚠️ OPEN
+
+**J. Документация 404 (P1)**
+- Неверный S3 ключ — ✅ FIXED (docs/ prefix)
+
+**K. Terraform Plugin Framework версии (P2)**
+- Несовместимость framework и plugin-go — ✅ FIXED (v1.4.2 + v0.19.1)
+
+**L. Adopt/Resume (P1)**
+- Ref-параметры не валидировались при adopt — ✅ FIXED v5.0.50 (ref_validation.go)
+- Duplicate displayNames — ✅ FIXED v5.0.50
+- operation_in_progress — ✅ FIXED v5.0.50
+
+**M. Сборка и CI (P1)**
+- Missing resources_yaml embed — ✅ FIXED v5.0.1
+- Повторная установка mkdocs — ✅ FIXED v5.0.4
+- Сборочный контейнер без git/zip/curl — ✅ FIXED
+- urllib без User-Agent (01_generate_yamls.sh) — ⚠️ OPEN
+- urllib без обработки ошибок API — ⚠️ OPEN
+- Нет retry в doRequest (429/503) — ⚠️ OPEN
+
+**N. Генерация (P1)**
+- Неизвестный kind тихо игнорируется — ⚠️ OPEN
+- YAML не валидируется — ⚠️ OPEN
+- format.Source пишет битый код — ⚠️ OPEN
+- Нет CI-диффа API vs YAML — ⚠️ OPEN
+- YAML устарел (новые операции в API) — ⚠️ OPEN
+
+**O. Destroy/Detach (P1)**
+- Destroy вызывал API delete для suspend-ресурсов — ✅ FIXED v5.0.8
+
+**P. Create-only params (P1)**
+- Needless modify при изменении create-only params — ✅ FIXED v5.0.38
+
+**Q. Subresource id unknown (P1)**
+- .id unknown после apply для subresource без modify — ✅ FIXED v5.0.7
+
+**R. Deleted filter (P0)**
+- План показывает deleted инстансы в ref_svc_id — ✅ FIXED v5.0.38
+- findInstanceUidByDisplayNameRefSvc без deleted filter — ✅ FIXED (в коде)
+- Три разные функции строят запросы к /instances — ⚠️ OPEN (рефакторинг)
+
+**S. Orphan при обрыве (P0)**
+- После POST /instances но до run — orphan not_created — ⚠️ OPEN
+
+**T. Тесты (P2)**
+- Всего 8 unit-тестов — ⚠️ OPEN
+- adopt, polling, генератор не покрыты — ⚠️ OPEN
+
+**U. Диск (P2)**
+- Disk decrease rejected (скейл-даун) — 🟡 PLATFORM
+
+**V. Стенды (P1)**
+- PROD_STAND/RABBIT указывает на test-endpoint — ⚠️ OPEN
+- Legacy провайдер не используется — ⚠️ OPEN
+
+## 7. Источники данных (где лежит)
+
+Все баги собраны из:
+- `/home/naeel/tf_provider/docs/50_history/` — файлы 00-24
+- `/home/naeel/tf_provider/HISTORY/OPUS/` — 7 файлов анализа
+- `/home/naeel/tf_provider/HISTORY/SONNET/0107.md`
+- `/home/naeel/tf_provider/HISTORY/2026-07-01_ddos_guard_403_and_registry_fix.md`
+- `/home/naeel/tf_provider/docs/help/` — существующие глоссарии
+- `/home/naeel/tf_provider/docs/20_discovery/`
+- `/home/naeel/tf_provider/docs/60_strategy/`
+- Анализ кода `universal_rebuild/`
+
+## 8. Порядок действий (для нового чата)
+
+1. Прочитать этот файл (PLAN_FOR_NEW_CHAT.md)
+2. Прочитать INDEX.md и INSTRUCTION.md (уже созданы)
+3. Решить где размещать: вариант A (~/global-dev-reference/) или вариант B (в tf_provider/docs/)
+4. Создать структуру директорий
+5. Наполнить BUGS.md для tf_provider (данные уже есть в п.6)
+6. Прочитать contracts, ipwhitelist, ВМ — собрать их баги
+7. Создать cross-cutting файлы (AUTH, POLLING, GPG...)
+8. Написать TLDR_FOR_AGENTS.md
+9. Если нужно — git init в global-dev-reference/
+10. Создать символические ссылки из проектов на справочник
+
+## 9. Ключевые требования
+
+- ⚡ **Каждый баг — ссылки на конкретные файлы и строки кода**
+- ⚡ **Удобный поиск** — INDEX с алфавитным указателем
+- ⚡ **лёгкое добавление** — INSTRUCTION с шаблоном
+- ⚡ **Агенты не тупят** — TLDR_FOR_AGENTS.md обязателен к прочтению
+- ⚡ **Статусы честные** — OPEN не прятать