contract: bump to v2.11 — add sfp_modules[], deprecate scalar sfp_* fields

bible-local/docs/hardware-ingest-contract.md

@@ -1,7 +1,7 @@
 ---
 title: Hardware Ingest JSON Contract
-version: "2.10"
-updated: "2026-04-29"
+version: "2.11"
+updated: "2026-06-19"
 maintainer: Reanimator Core
 audience: external-integrators, ai-agents
 language: ru
@@ -9,7 +9,7 @@ language: ru
 
 # Интеграция с Reanimator: контракт JSON-импорта аппаратного обеспечения
 
-Версия: **2.10** · Дата: **2026-04-29**
+Версия: **2.11** · Дата: **2026-06-19**
 
 Документ описывает формат JSON для передачи данных об аппаратном обеспечении серверов в систему **Reanimator** (управление жизненным циклом аппаратного обеспечения).
 Предназначен для разработчиков смежных систем (Redfish-коллекторов, агентов мониторинга, CMDB-экспортёров) и может быть включён в документацию интегрируемых проектов.
@@ -22,6 +22,7 @@ language: ru
 
 | Версия | Дата | Изменения |
 |--------|------|-----------|
+| 2.11 | 2026-06-19 | В `pcie_devices[]` добавлен необязательный массив `sfp_modules[]` с идентификацией и DOM telemetry SFP/QSFP-модулей. Скалярные поля `sfp_temperature_c` / `sfp_tx_power_dbm` / `sfp_rx_power_dbm` / `sfp_voltage_v` / `sfp_bias_ma` помечены как deprecated (принимаются, но `sfp_modules[]` имеет приоритет) |
 | 2.10 | 2026-04-29 | Для `hardware.storage[]` добавлены необязательные числовые поля `logical_block_size_bytes`, `physical_block_size_bytes`, `metadata_bytes_per_block` для нормализованного описания формата блока накопителя |
 | 2.9 | 2026-03-19 | Добавлена необязательная секция `hardware.platform_config` — произвольный объект с настройками платформы (BIOS/Redfish); хранится как latest-snapshot per machine |
 | 2.8 | 2026-03-15 | Поле `location` удалено из всех `sensors.*`; сенсоры передаются только по `name` и измеренным значениям |
@@ -422,11 +423,12 @@ GET /ingest/hardware/jobs/{job_id}
 | `battery_temperature_c` | float | нет | Температура батареи / supercap, °C |
 | `battery_voltage_v` | float | нет | Напряжение батареи / supercap, В |
 | `battery_replace_required` | bool | нет | Требуется замена батареи / supercap |
-| `sfp_temperature_c` | float | нет | Температура SFP/optic, °C |
-| `sfp_tx_power_dbm` | float | нет | TX optical power, dBm |
-| `sfp_rx_power_dbm` | float | нет | RX optical power, dBm |
-| `sfp_voltage_v` | float | нет | Напряжение SFP, В |
-| `sfp_bias_ma` | float | нет | Bias current SFP, мА |
+| `sfp_temperature_c` | float | нет | Температура SFP/optic, °C *(deprecated since 2.11)* |
+| `sfp_tx_power_dbm` | float | нет | TX optical power, dBm *(deprecated since 2.11)* |
+| `sfp_rx_power_dbm` | float | нет | RX optical power, dBm *(deprecated since 2.11)* |
+| `sfp_voltage_v` | float | нет | Напряжение SFP, В *(deprecated since 2.11)* |
+| `sfp_bias_ma` | float | нет | Bias current SFP, мА *(deprecated since 2.11)* |
+| `sfp_modules` | array | нет | Установленные SFP/QSFP-модули по портам (см. sfp_modules[]) |
 | `bdf` | string | нет | Deprecated alias для `slot`; при наличии ingest нормализует его в `slot` |
 | `device_class` | string | нет | Класс устройства (см. список ниже) |
 | `manufacturer` | string | нет | Производитель |
@@ -444,10 +446,43 @@ GET /ingest/hardware/jobs/{job_id}
 `numa_node` передавайте для NIC / InfiniBand / RAID / GPU, когда источник знает CPU/NUMA affinity. Поле сохраняется в snapshot-атрибутах PCIe-компонента и дублируется в telemetry для topology use cases.
 Поля `temperature_c` и `power_w` используйте для device-level telemetry GPU / accelerator / smart PCIe devices. Они не влияют на идентификацию компонента.
 
+**Deprecated поля sfp_\*:** Скалярные поля `sfp_temperature_c`, `sfp_tx_power_dbm`, `sfp_rx_power_dbm`, `sfp_voltage_v`, `sfp_bias_ma` продолжают приниматься, но помечены как deprecated since 2.11. Если в payload одновременно присутствуют `sfp_modules[]` и deprecated sfp_-скаляры — приоритет у `sfp_modules[]`, скаляры игнорируются. Deprecated поля будут удалены в версии 3.0.
+
 **Генерация serial_number при отсутствии или `"N/A"`:** `{board_serial}-PCIE-{slot}`, где `slot` для PCIe равен BDF.
 
 `slot` — единственный канонический адрес компонента. Для PCIe в `slot` передавайте BDF. Поле `bdf` сохраняется только как переходный alias на входе и не должно использоваться как отдельная координата рядом со `slot`.
 
+#### pcie_devices[].sfp_modules[]
+
+Необязательный массив установленных SFP/QSFP-модулей для данного PCIe-устройства. Один элемент — один порт. Используйте для многопортовых NIC (ConnectX-6 Dx, Intel X710, Mellanox HDR и др.).
+
+| Поле | Тип | Обязательно | Описание |
+|------|-----|-------------|----------|
+| `port` | int | **да** | Номер порта на NIC (0-based). Ключ дедупликации внутри устройства |
+| `identifier` | string | нет | Тип модуля: `SFP`, `SFP+`, `SFP28`, `QSFP+`, `QSFP28`, `QSFP-DD`, `DAC` |
+| `connector` | string | нет | Тип разъёма: `LC`, `MPO`, `RJ45`, `DAC`, `AOC`, `No separable connector` |
+| `vendor` | string | нет | Производитель модуля из EEPROM |
+| `part_number` | string | нет | Партномер из EEPROM |
+| `serial_number` | string | нет | Серийный номер из EEPROM |
+| `revision` | string | нет | Ревизия из EEPROM |
+| `wavelength_nm` | int | нет | Длина волны, нм (0 для DAC/медных кабелей) |
+| `transceiver_type` | string | нет | `10GBase-SR`, `10GBase-LR`, `25GBase-SR`, `100GBase-SR4`, `DAC`, … |
+| `temperature_c` | float | нет | Температура модуля, °C (DOM telemetry) |
+| `voltage_v` | float | нет | Напряжение питания, В (DOM telemetry) |
+| `tx_power_dbm` | float | нет | TX оптическая мощность, dBm (DOM telemetry) |
+| `rx_power_dbm` | float | нет | RX оптическая мощность, dBm (DOM telemetry) |
+| `bias_ma` | float | нет | Bias current, мА (DOM telemetry) |
+
+**Ключ дедупликации:** `(pcie_devices[].slot, sfp_modules[].port)`.
+
+**Правила ingest:**
+- При каждом импорте — полная замена `sfp_modules[]` для данного `pcie_devices[].slot` (upsert всего массива целиком).
+- Если `sfp_modules` отсутствует или `null` — существующие данные SFP не трогать.
+- Если `sfp_modules: []` (пустой массив) — трактовать как «модули не обнаружены», очистить сохранённые данные.
+- Дубли по `port` внутри одного `pcie_devices[]` — невалидны, endpoint возвращает `400` с описанием поля.
+- Модули без `serial_number` допустимы (многие DAC-кабели не имеют SN); сохраняются по ключу `(slot, port)`.
+- Изменение `serial_number` или `part_number` модуля на порту создаёт событие `COMPONENT_CHANGED` для PCIe-устройства с описанием «SFP module replaced on port N».
+
 **Значения `device_class`:**
 
 | Значение | Назначение |
@@ -472,16 +507,47 @@ GET /ingest/hardware/jobs/{job_id}
     "numa_node": 0,
     "temperature_c": 48.5,
     "power_w": 18.2,
-    "sfp_temperature_c": 36.2,
-    "sfp_tx_power_dbm": -1.8,
-    "sfp_rx_power_dbm": -2.1,
     "device_class": "EthernetController",
-    "manufacturer": "Intel",
-    "model": "X710 10GbE",
-    "serial_number": "K65472-003",
-    "firmware": "9.20 0x8000d4ae",
+    "manufacturer": "Mellanox",
+    "model": "ConnectX-6 Dx",
+    "serial_number": "MT2012X12345",
+    "firmware": "22.35.2010",
     "mac_addresses": ["3c:fd:fe:aa:bb:cc", "3c:fd:fe:aa:bb:cd"],
-    "status": "OK"
+    "status": "OK",
+    "sfp_modules": [
+      {
+        "port": 0,
+        "identifier": "QSFP28",
+        "connector": "LC",
+        "vendor": "Mellanox",
+        "part_number": "MFA1A00-C003",
+        "serial_number": "MT2124VS09999",
+        "revision": "A",
+        "wavelength_nm": 850,
+        "transceiver_type": "100GBase-SR4",
+        "temperature_c": 36.4,
+        "voltage_v": 3.29,
+        "tx_power_dbm": -1.8,
+        "rx_power_dbm": -2.1,
+        "bias_ma": 7.2
+      },
+      {
+        "port": 1,
+        "identifier": "QSFP28",
+        "connector": "LC",
+        "vendor": "Mellanox",
+        "part_number": "MFA1A00-C003",
+        "serial_number": "MT2124VS09998",
+        "revision": "A",
+        "wavelength_nm": 850,
+        "transceiver_type": "100GBase-SR4",
+        "temperature_c": 35.9,
+        "voltage_v": 3.28,
+        "tx_power_dbm": -1.9,
+        "rx_power_dbm": -2.3,
+        "bias_ma": 7.1
+      }
+    ]
   }
 ]
 ```
@@ -793,7 +859,24 @@ PSU без `serial_number` игнорируется.
         "model": "X710 10GbE",
         "serial_number": "K65472-003",
         "mac_addresses": ["3c:fd:fe:aa:bb:cc", "3c:fd:fe:aa:bb:cd"],
-        "status": "OK"
+        "status": "OK",
+        "sfp_modules": [
+          {
+            "port": 0,
+            "identifier": "SFP+",
+            "connector": "LC",
+            "vendor": "Intel",
+            "part_number": "FTLX8574D3BCV-IT",
+            "serial_number": "FNS123456789",
+            "wavelength_nm": 850,
+            "transceiver_type": "10GBase-SR",
+            "temperature_c": 34.1,
+            "voltage_v": 3.30,
+            "tx_power_dbm": -2.5,
+            "rx_power_dbm": -3.0,
+            "bias_ma": 6.8
+          }
+        ]
       }
     ],
     "power_supplies": [