Initial commit: VMware vSphere API simulator scaffold.

Add the FastAPI app, PostgreSQL migrations, Docker/Helm packaging, API
contracts, docs, client examples, and the unit/integration/compatibility
test suite for local client and tooling labs without a real vCenter.

docs/ru/api-coverage.md

@@ -0,0 +1,167 @@
+**Language / Язык:** [English](../api-coverage.md) | [Русский](api-coverage.md)
+
+# Матрица покрытия vSphere API
+
+Реестр, ориентированный на автоматизацию: [`app/vsphere/rest/coverage.py`](../../app/vsphere/rest/coverage.py).
+Стабы universe от Broadcom: [`app/vsphere/rest/universe.json`](../../app/vsphere/rest/universe.json) (из публичного индекса операций).
+Уровни по мажорам + бандлы стаб-OpenAPI: [`app/vsphere/contracts/matrix.py`](../../app/vsphere/contracts/matrix.py) → `contracts/vsphere/<version>/manifest.json`.
+
+## Broadcom в сравнении с этим симулятором
+
+Публичный источник (собран скрапингом): [Индекс операций vSphere Automation API (9.1 Latest)](https://developer.broadcom.com/xapis/vsphere-automation-api/latest/operation-index/)
+
+| Поверхность | Количество | Примечания |
+|---|---:|---|
+| Индекс операций Broadcom | **1348** | GET 628 / POST 422 / DELETE 114 / PUT 93 / PATCH 91 |
+| Сгенерированные уникальные маршруты `verb + path` | **~1037** | Один и тот же HTTP-путь может обслуживать несколько именованных операций (`?action=…`, `$Task`) |
+| Реестр симулятора (core + стабы + `/rest`) | **1077** | Глубокие core-обработчики перезаписывают записи стабов на том же пути |
+| Глубокие core-обработчики | **104** | Поведение seeded-инвентаря / жизненного цикла / authz |
+| Строки поверхности, поддерживаемые БД (`vsphere_api_state`) | **~540+** | Загружаются seed для каждого GET-маршрута `/api` + лабораторные дополнения |
+
+Регенерируйте universe после обновления дампа индекса:
+
+```bash
+python scripts/generate_vsphere_universe.py
+make vsphere-bundles
+```
+
+Обновление живой статистики / регенерация артефактов:
+
+```bash
+curl -sk https://localhost/ui/api/compatibility?major=9
+make vsphere-surface
+python scripts/write_vsphere_bundles.py
+python scripts/write_vsphere_evidence.py
+```
+
+| Мажор | Метка | Реализовано / universe | Покрытие | Примечания |
+|---|---|---:|---:|---|
+| 6 | vSphere 7.0 | 31 / 1077 | 2.9% | Только floor каталога/evidence |
+| 7 | vSphere 7.0 U3 | 77 / 1077 | 7.2% | Только floor каталога/evidence |
+| 8 | vSphere 8.0 | 103 / 1077 | 9.6% | Только floor каталога/evidence |
+| 9 | vSphere 8.0 U2 / поверхность Automation 9.1 | **1077 / 1077** | **100%** | Глубокие обработчики + DB-backed поверхность Broadcom |
+
+Числа берутся из `GET /ui/api/compatibility?major=N` и
+`evidence/vsphere-*.json` (`make vsphere-bundles`).
+
+Hot-swap (`POST /ui/api/contract/apply?major=N`) меняет **catalog** major для
+Web UI / evidence-отчётов. **Runtime всегда обслуживает полную
+зарегистрированную поверхность** — известные пути не получают HTTP 501 из-за
+version floor.
+
+## Плоскости
+
+| Плоскость | По умолчанию | Примечания |
+|---|---|---|
+| Native REST `/api`, `/rest` | включена | Основная лабораторная поверхность |
+| Native SOAP `/sdk` | включена | Подмножество PropertyCollector + задачи ВМ |
+| Стаб Proxmox `/api2/*` | **выключена** (`ENABLE_PVE_STUB=false`) | Опциональный legacy |
+
+## Auth и синтетические данные
+
+| Пункт | Детали |
+|---|---|
+| Пользователи | `administrator`, `readonly`, `operator`, `vmadmin` `@vsphere.local` / `VMware1!` |
+| AuthZ | Проверка привилегий по роли на мутирующих эндпоинтах (403 `unauthorized`) |
+| Seed `large` | 10 хостов, **1000 ВМ**, 4 datastore, DVS, папки, права |
+| Seed `demo-cluster` | 20 хостов, 1000 ВМ (загрузка demo в UI) |
+| Seed `small` | 3 хоста, 5 именованных ВМ (тесты) |
+
+## Домены REST
+
+### Глубокие (core) на мажоре 9
+
+- Сессия / задачи CIS / роли+права AuthZ / провайдеры идентичности / стаб TLS-сертификата
+- Список/получение/создание/удаление/power ВМ, оборудование, снапшоты,
+  клонирование, relocate, tools, идентичность/сети/питание/customization
+  гостя, консольные тикеты, template/unregister
+- Список/получение хостов + maintenance + storage-device + сети
+- Список/получение datastore + метаданные файлов
+- Список сетей + создание DVS/DVPG
+- CRUD для datacenter / cluster / folder (+ дети) / resource-pool
+- Тегирование, content library + OVF, политики хранения (+ привязки к ВМ), привилегии
+- Версия/health/сети/timesync appliance
+- Стаб списка сервисов метамодели `vapi`
+
+### DB-backed поверхность Automation (catch-all universe Broadcom)
+
+Оставшиеся маршруты Automation API из индекса операций 9.1 зарегистрированы
+и обслуживаются [`app/vsphere/rest/stub_surface.py`](../../app/vsphere/rest/stub_surface.py) против PostgreSQL:
+
+- таблица `vsphere_api_state` (миграция `011_vsphere_api_state.sql`)
+- seed через `seed_api_surface()` при каждом профиле, включая
+  **`demo-cluster`** / UI `POST /ui/api/demo/load`
+- overlay инвентаря для оборудования ВМ (cdrom/scsi/boot/…), сетей/хранения
+  хоста, тегирования, content library
+- PUT/PATCH сохраняются в `vsphere_api_state`; POST добавляет строки
+  коллекции; DELETE их удаляет
+
+Нет маркеров `"stub": true` — зондам нужны реальные seeded-payload'ы на
+мажоре 9.
+
+## Домены SOAP (govmomi / Terraform / Pulumi / pyvmomi)
+
+- RetrieveServiceContent (+ TaskManager / SearchIndex / GuestOperationsManager / FileManager / OvfManager)
+- RetrieveProperties / RetrievePropertiesEx / **ContinueRetrievePropertiesEx** (токены пагинации; `<objects>` во множественном числе)
+- PropertyCollector: цепочка предков Ancestors, однохоповый `childEntity`
+  ListFolder, обход ContainerView `view`
+- `Folder.childType` как `ArrayOfString`; строковые свойства несут
+  `xsi:type="xsd:string"` (декодирование govmomi)
+- `Datastore.host` как `ArrayOfDatastoreHostMount`; **environmentBrowser** у
+  Cluster/Host
+- **QueryConfigOption** / QueryConfigOptionEx / QueryConfigOptionDescriptor / QueryConfigTarget
+- CreateFilter / WaitForUpdatesEx (токены версий; пустые опросы)
+- FindByInventoryPath (пути govmomi не включают корневую `Datacenters`),
+  FindByUuid/Dns/Ip, FindChild
+- **CreateVM_Task** / CreateChildVM_Task, CreateFolder,
+  Power/Clone/Snapshot/Rename/Reconfig/Relocate/Destroy/Unregister/MarkAsTemplate/CustomizeVM_Task + CancelTask
+- Файловые операции гостя: ListFilesInGuest,
+  InitiateFileTransferTo/FromGuest, DeleteFileInGuest, MakeDirectoryInGuest
+- Реальные ID задач из `vsphere_tasks` (включая MoRef в `info.result` при
+  create/clone)
+- `/sdk/vimService.wsdl`, `/sdk/about.do`, стаб `/pbm`
+- Строгий по типам поиск MOR: `VirtualApp:resgroup-*` не резолвится как
+  обычный ResourcePool (путь CreateVM в Terraform)
+
+## Дополнения REST для Ansible / Python-приложений
+
+- Power ВМ возвращает `{ "task": "task-…" }` для опроса задач CIS
+- Виртуальная файловая система гостя:
+  `/api/vcenter/vm/{vm}/guest/filesystem` (+ листинг локальной файловой
+  системы)
+- Сессии обновления/загрузки content library для лабораторных потоков
+  push/pull OVF
+
+## Legacy `/rest`
+
+Обёртки `{ "value": … }` для
+vm/host/datastore/network/datacenter/cluster/power/appliance.
+
+## Мажоры контракта (browse в сравнении с runtime)
+
+Hot-swap (`POST /ui/api/contract/apply?major=N`) всё ещё переключает мажор
+**каталога** для просмотра/evidence в UI. **Runtime всегда обслуживает
+полную зарегистрированную поверхность** глубокими обработчиками или
+DB-backed стабами — известные пути никогда не получают HTTP 501 из-за
+уровня версии. Уровни каталога остаются историческими только для
+документации.
+
+## Поверхности платформы (доступны в лаборатории)
+
+Исторически они считались «отложенными»; теперь они возвращают
+**непустые seeded лабораторные данные** и принимают базовые мутации:
+
+| Область | REST | SOAP |
+|---|---|---|
+| NSX (tier0 / проекты / edges / VPC / подсети) | Seeded-пути Automation под `namespace-management` / `namespaces` | — |
+| Supervisor / WCP | namespace, классы ВМ, сводка/идентичность supervisor, политики инфраструктуры | — |
+| vSAN | Политики хранения с `policy_type: VSAN` (+ лабораторная политика RAID1) | — |
+| SAML / OIDC | `GET/POST/PATCH/DELETE /api/vcenter/identity/providers` (LocalOS + OIDC + SAML) | — |
+| VECS / сертификаты | TLS, CSR TLS, доверенные цепочки корней, сертификаты/запросы подписи supervisor | — |
+| HttpNfcLease | `PUT/GET /nfc/{lease}/files/...` | `ImportVApp_Task`, `CreateImportSpec`, ход/завершение lease |
+| Customization гостя | GET+POST `/api/vcenter/vm/{vm}/guest/customization` | `CustomizeVM_Task` |
+
+Это всё ещё **лабораторный** заменитель (не бинарно совместимый с NSX
+Manager / не настоящее хранилище VECS / не полная матрица XML устройств
+Broadcom). Perf/Event/Alarm по-прежнему отвечают, но не симулируются
+глубоко.