terraform/tf_provider
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1208104f7721e704af04f986187fbf1b0626b16f
tf_provider/docs/help/dev-reference/PLAN_FOR_NEW_CHAT.md
T

11 KiB
Raw Blame History

ПЛАН: Создание общего справочника разработчика

Этот файл — инструкция для нового чата. Прочитать перед началом работы.

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. Формат одной записи (бага/решения)

Каждый баг оформляется так:

## [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 не прятать
Reference in New Issue View Git Blame Copy Permalink