chore: промежуточные изменения в TEST_STAND, docs, s.sh
This commit is contained in:
“Naeel”
@@ -0,0 +1,26 @@
|
||||
# `resource_name` в документации — план доработок
|
||||
|
||||
## Суть проблемы
|
||||
- `resource_name` — **Required: true** во всех 82+ сгенерированных ресурсах
|
||||
- Хардкодится в Go-шаблоне: `universal_rebuild/tools/gen_v2/generate_resources_v2.go:911`
|
||||
- Мапится на API-поле `displayName` (CRUD: `universal_rebuild/internal/resources_core/crud.go:30`)
|
||||
- В сгенерированной документации (`docs/30_registry/resources/*.md`) — **отсутствует полностью**
|
||||
- Нет ни в HCL-примерах, ни в таблицах параметров
|
||||
|
||||
## Причина
|
||||
Docs-генератор (`universal_rebuild/tools/docs_template_gen_v2/main.go`) читает только YAML-спеки, а `resource_name` — не API-параметр create-операции, его нет в YAML. Это мета-параметр уровня провайдера.
|
||||
|
||||
## Что править
|
||||
**Один файл:** `universal_rebuild/tools/docs_template_gen_v2/main.go`
|
||||
|
||||
1. **`exampleBlock()`** (~строка 373) — добавить `resource_name = "my-instance"` первой строкой в resource-блок
|
||||
2. **`buildCreateParamsPage()`** (~строка 411) — добавить секцию «Системные параметры» с описанием `resource_name` перед таблицей create-параметров
|
||||
|
||||
## Почему не YAML
|
||||
- `resource_name` — не API-параметр, это уровень Terraform-провайдера
|
||||
- Добавление в 42 YAML-спека семантически неверно + легко забыть при новых сервисах
|
||||
- Правильнее зеркально Go-генератору: один раз в docs-генераторе → охват всех ресурсов
|
||||
|
||||
## Чеклист
|
||||
- [ ] `resource_name` в HCL-примерах (exampleBlock)
|
||||
- [ ] `resource_name` в таблицах create-параметров (buildCreateParamsPage)
|
||||
@@ -0,0 +1,79 @@
|
||||
# Справочник разработчика (Dev Reference)
|
||||
|
||||
> Единый каталог проблем, решений, архитектурных решений и состояний провайдера.
|
||||
> **Цель:** чтобы агенты и разработчики НЕ повторяли одни и те же ошибки.
|
||||
|
||||
---
|
||||
|
||||
## Быстрый поиск
|
||||
|
||||
| Если нужно | Иди в |
|
||||
|-----------|-------|
|
||||
| Найти баг по названию/симптому | `01_BUGS_ALL.md` |
|
||||
| Найти баг по симптомам ("висит", "403", "inconsistent result") | `02_BUGS_BY_SYMPTOM.md` |
|
||||
| Найти баг по категории (polling, auth, generation, adopt) | `03_BUGS_BY_CATEGORY.md` |
|
||||
| Понять архитектуру (почему так сделано) | `04_ARCHITECTURE.md` |
|
||||
| Понять состояния ресурсов (RUNNING, SUSPEND, DELETED) | `05_STATE_MATRIX.md` |
|
||||
| **Агентам — прочитать ОБЯЗАТЕЛЬНО перед любыми правками** | `06_TLDR_FOR_AGENTS.md` |
|
||||
| Как добавить новую запись | `INSTRUCTION.md` |
|
||||
|
||||
---
|
||||
|
||||
## Алфавитный указатель терминов (см. `01_BUGS_ALL.md`)
|
||||
|
||||
| Термин | Раздел в 01_BUGS_ALL |
|
||||
|--------|---------------------|
|
||||
| 400 Bad Request | C — Modify: Invalid CFS parameter |
|
||||
| 401 Unauthorized | A — Authentication |
|
||||
| 403 DDoS-Guard | A — DDoS-Guard 403 |
|
||||
| 404 docs | K — Docs 404 |
|
||||
| 500 VM modify | G — VM 500 String[]→GUID |
|
||||
| adopt | L — Adopt/Resume |
|
||||
| create-only params | Q — Create-only params modification |
|
||||
| deleted filter | O — Deleted filter missing |
|
||||
| detach semantics | P — Destroy/Detach semantics |
|
||||
| disk decrease | R — Disk shrink |
|
||||
| displayName duplicate | M — Duplicate displayNames |
|
||||
| dtFinish | B — Polling hang |
|
||||
| GPG unknown issuer | I — GPG unknown issuer |
|
||||
| GPG invalid data | I — GPG invalid data |
|
||||
| HTTP/2 EOF | A — HTTP/2 ALPN EOF |
|
||||
| import | N — Import not implemented |
|
||||
| map/json format | E — Map/JSON/List invalid format |
|
||||
| operation_in_progress | L — Operation in progress |
|
||||
| orphan instance | S — Orphan on create abort |
|
||||
| polling hang | B — Polling hang |
|
||||
| ref_svc_id deleted | O — Ref svc showing deleted |
|
||||
| split() on null | H — Postgres split() on null |
|
||||
| String[]→GUID | F — VM FW failure |
|
||||
| subresource id unknown | T — Subresource id unknown |
|
||||
| suspend_on_destroy | P — Destroy semantics |
|
||||
| User-Agent | A — DDoS-Guard 403 |
|
||||
| YAML stale | U — YAML stale/validation |
|
||||
|
||||
---
|
||||
|
||||
## Статусы багов
|
||||
|
||||
| Метка | Значение |
|
||||
|-------|----------|
|
||||
| ✅ FIXED | Исправлено, версия указана |
|
||||
| ⚠️ OPEN | Не исправлено, известная проблема |
|
||||
| ❌ WORKAROUND | Есть обходное решение, но баг не закрыт |
|
||||
| 🟡 PLATFORM | Баг платформы/бэкенда, не провайдера |
|
||||
|
||||
---
|
||||
|
||||
## Источники данных
|
||||
|
||||
Справочник собран из:
|
||||
- `docs/50_history/` (00-24) — история спринтов
|
||||
- `HISTORY/OPUS/` — анализ Opus 4.8
|
||||
- `HISTORY/SONNET/0107.md` — debug DDoS-Guard
|
||||
- `HISTORY/2026-07-01_ddos_guard_403_and_registry_fix.md` — фикс registry
|
||||
- `docs/help/` — существующие глоссарии и error KB
|
||||
- `docs/20_discovery/` — discovery-материалы
|
||||
- `docs/60_strategy/` — стратегия и философия
|
||||
- Исходный код `universal_rebuild/`
|
||||
|
||||
Последнее обновление: 2026-07-01
|
||||
@@ -0,0 +1,68 @@
|
||||
# Инструкция: как добавить запись в справочник
|
||||
|
||||
## Формат одной записи (шаблон)
|
||||
|
||||
```markdown
|
||||
## [P0/P1/P2] Короткое название проблемы
|
||||
**Симптом:** что происходит, как проявляется
|
||||
**Причина:** root cause
|
||||
**Решение:** что сделали / что нужно сделать
|
||||
**Статус:** ✅ FIXED / ⚠️ OPEN / ❌ WORKAROUND / 🟡 PLATFORM
|
||||
**Версия:** vX.Y.Z (в какой версии исправлено, если есть)
|
||||
**Файлы:**
|
||||
- `путь/к/файлу.go:номер_строки` — что там
|
||||
**Источники:**
|
||||
- `docs/50_history/NN_*.md` — ссылка на историю
|
||||
- `HISTORY/...` — если описание в HISTORY/
|
||||
|
||||
## Пример заполнения
|
||||
|
||||
## [P0] POST 403 после DDoS-Guard
|
||||
**Симптом:** terraform apply → HTTP 403 на POST запросах к ColdFusion API
|
||||
**Причина:** DDoS-Guard блокирует запросы без User-Agent; %2F в URL ломает WAF
|
||||
**Решение:**
|
||||
1. `req.Header.Set("User-Agent", "Mozilla/5.0")` во всех HTTP-вызовах
|
||||
2. `rawQuery := "endpoint=" + path` (без url.Values, чтобы не было %2F)
|
||||
3. `TLSNextProto = make(map[string]func(...))` — отключить HTTP/2 ALPN
|
||||
4. `transport.Proxy = nil` — не использовать HTTPS_PROXY
|
||||
**Статус:** ⚠️ OPEN (User-Agent ✅ FIXED v5.0.75, POST всё ещё 403)
|
||||
**Файлы:**
|
||||
- `universal_rebuild/internal/core/client.go:865` — doRequest (User-Agent ✅)
|
||||
- `universal_rebuild/internal/core/client.go:522` — FindExistingInstances (User-Agent ✅)
|
||||
- `universal_rebuild/internal/core/client.go:597` — GetInstanceState (User-Agent ✅)
|
||||
- `universal_rebuild/internal/core/client.go:644` — GetInstanceStateRaw (User-Agent ✅)
|
||||
- `universal_rebuild/internal/resources_core/domain_collision.go:99` — коллизии доменов (User-Agent ✅)
|
||||
- `devops/01_generate_yamls.sh` — urllib без User-Agent 🔴
|
||||
**Источники:**
|
||||
- `HISTORY/SONNET/0107.md`
|
||||
- `HISTORY/2026-07-01_ddos_guard_403_and_registry_fix.md`
|
||||
```
|
||||
|
||||
## Правила
|
||||
|
||||
1. **Каждый баг — одна запись.** Не группировать разные проблемы в одну.
|
||||
2. **Симптом — конкретно:** что видит пользователь/агент (ошибка, код возврата, сообщение).
|
||||
3. **Файлы — с номерами строк:** `universal_rebuild/internal/core/client.go:865` (без `L`).
|
||||
4. **Статус — честно:** если не исправлено — ⚠️ OPEN.
|
||||
5. **Ссылки на источники** — относительные пути от корня репы.
|
||||
6. **Приоритет P0/P1/P2:**
|
||||
- **P0** — блокирует работу (apply падает, data loss)
|
||||
- **P1** — серьёзно мешает (wrong behaviour, needless calls)
|
||||
- **P2** — улучшение/cleanup
|
||||
|
||||
## Куда добавлять
|
||||
|
||||
| Тип записи | Файл |
|
||||
|-----------|------|
|
||||
| Новый баг (любой) | `01_BUGS_ALL.md` (в конец раздела по букве/категории) |
|
||||
| Новый симптом | `02_BUGS_BY_SYMPTOM.md` |
|
||||
| Новая категория | `03_BUGS_BY_CATEGORY.md` |
|
||||
| Архитектурное решение | `04_ARCHITECTURE.md` |
|
||||
| Новое состояние | `05_STATE_MATRIX.md` |
|
||||
| Критичное для агентов | `06_TLDR_FOR_AGENTS.md` |
|
||||
|
||||
## После добавления
|
||||
|
||||
1. Проверить что ссылки валидны (файлы существуют, строки примерно верны)
|
||||
2. Обновить `INDEX.md` — алфавитный указатель
|
||||
3. `git add + git commit + git push`
|
||||
@@ -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 не прятать
|
||||
Reference in New Issue
Block a user