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

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

---

## 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 не прятать