# Справочник разработчика (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