Add storage block geometry to audit and viewer

2026-04-29 17:39:11 +03:00
parent c0dbbf96ad
commit ec89616585
11 changed files with 565 additions and 47 deletions
--- a/bible-local/docs/hardware-ingest-contract.md
+++ b/bible-local/docs/hardware-ingest-contract.md
@@ -1,7 +1,7 @@
 ---
 title: Hardware Ingest JSON Contract
-version: "2.7"
-updated: "2026-03-15"
+version: "2.10"
+updated: "2026-04-29"
 maintainer: Reanimator Core
 audience: external-integrators, ai-agents
 language: ru
@@ -9,7 +9,7 @@ language: ru

 # Интеграция с Reanimator: контракт JSON-импорта аппаратного обеспечения

-Версия: **2.7** · Дата: **2026-03-15**
+Версия: **2.10** · Дата: **2026-04-29**

 Документ описывает формат JSON для передачи данных об аппаратном обеспечении серверов в систему **Reanimator** (управление жизненным циклом аппаратного обеспечения).
 Предназначен для разработчиков смежных систем (Redfish-коллекторов, агентов мониторинга, CMDB-экспортёров) и может быть включён в документацию интегрируемых проектов.
@@ -22,6 +22,9 @@ language: ru

 | Версия | Дата | Изменения |
 |--------|------|-----------|
+| 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` и измеренным значениям |
 | 2.7 | 2026-03-15 | Явно запрещён синтез данных в `event_logs`; интеграторы не должны придумывать серийные номера компонентов, если источник их не отдал |
 | 2.6 | 2026-03-15 | Добавлена необязательная секция `event_logs` для dedup/upsert логов `host` / `bmc` / `redfish` вне history timeline |
 | 2.5 | 2026-03-15 | Добавлено общее необязательное поле `manufactured_year_week` для компонентных секций (`YYYY-Www`) |
@@ -131,8 +134,9 @@ GET /ingest/hardware/jobs/{job_id}
    "storage":        [ ... ],
    "pcie_devices":   [ ... ],
    "power_supplies": [ ... ],
-    "sensors":        { ... },
-    "event_logs":     [ ... ]
+    "sensors":         { ... },
+    "event_logs":      [ ... ],
+    "platform_config": { ... }
  }
 }
 ```
@@ -343,6 +347,9 @@ GET /ingest/hardware/jobs/{job_id}
 | `type` | string | нет | Тип: `NVMe`, `SSD`, `HDD` |
 | `interface` | string | нет | Интерфейс: `NVMe`, `SATA`, `SAS` |
 | `size_gb` | int | нет | Размер в ГБ |
+| `logical_block_size_bytes` | int64 | нет | Логический размер пользовательского блока данных, например `512` или `4096` |
+| `physical_block_size_bytes` | int64 | нет | Физический размер блока, если известен, например `4096` |
+| `metadata_bytes_per_block` | int64 | нет | Metadata / protection bytes на логический блок, например `0` или `8` |
 | `temperature_c` | float | нет | Температура накопителя, °C (telemetry) |
 | `power_on_hours` | int64 | нет | Время работы, часы |
 | `power_cycles` | int64 | нет | Количество циклов питания |
@@ -363,6 +370,11 @@ GET /ingest/hardware/jobs/{job_id}

 Диск без `serial_number` игнорируется. Изменение `firmware` создаёт событие `FIRMWARE_CHANGED`.

+Формат вида `512+8` в контракт не добавляется отдельным строковым полем. Если источник знает такую форму, он должен передавать её как:
+- `logical_block_size_bytes = 512`
+- `metadata_bytes_per_block = 8`
+- `physical_block_size_bytes = 512` или `4096`, если известен физический размер блока
+
 ```json
 "storage": [
  {
@@ -370,6 +382,9 @@ GET /ingest/hardware/jobs/{job_id}
    "type": "NVMe",
    "model": "INTEL SSDPF2KX076T1",
    "size_gb": 7680,
+    "logical_block_size_bytes": 512,
+    "physical_block_size_bytes": 4096,
+    "metadata_bytes_per_block": 8,
    "temperature_c": 38.5,
    "power_on_hours": 12450,
    "unsafe_shutdowns": 3,
@@ -592,7 +607,6 @@ PSU без `serial_number` игнорируется.
 | Поле | Тип | Обязательно | Описание |
 |------|-----|-------------|----------|
 | `name` | string | **да** | Уникальное имя сенсора в рамках секции |
-| `location` | string | нет | Физическое расположение |
 | `rpm` | int | нет | Обороты, RPM |
 | `status` | string | нет | Статус: `OK`, `Warning`, `Critical`, `Unknown` |

@@ -601,7 +615,6 @@ PSU без `serial_number` игнорируется.
 | Поле | Тип | Обязательно | Описание |
 |------|-----|-------------|----------|
 | `name` | string | **да** | Уникальное имя сенсора |
-| `location` | string | нет | Физическое расположение |
 | `voltage_v` | float | нет | Напряжение, В |
 | `current_a` | float | нет | Ток, А |
 | `power_w` | float | нет | Мощность, Вт |
@@ -612,7 +625,6 @@ PSU без `serial_number` игнорируется.
 | Поле | Тип | Обязательно | Описание |
 |------|-----|-------------|----------|
 | `name` | string | **да** | Уникальное имя сенсора |
-| `location` | string | нет | Физическое расположение |
 | `celsius` | float | нет | Температура, °C |
 | `threshold_warning_celsius` | float | нет | Порог Warning, °C |
 | `threshold_critical_celsius` | float | нет | Порог Critical, °C |
@@ -623,29 +635,29 @@ PSU без `serial_number` игнорируется.
 | Поле | Тип | Обязательно | Описание |
 |------|-----|-------------|----------|
 | `name` | string | **да** | Уникальное имя сенсора |
-| `location` | string | нет | Физическое расположение |
 | `value` | float | нет | Значение |
 | `unit` | string | нет | Единица измерения |
 | `status` | string | нет | Статус |

 **Правила sensors:**
 - Идентификатор сенсора: пара `(sensor_type, name)`. Дубли в одном payload — берётся первое вхождение.
+- `location` для сенсоров передавать не нужно и не следует: в Reanimator location/slot используется только для проверки перемещения и установки компонентов, а не для last-known-value sensor ingest.
 - Сенсоры без `name` игнорируются.
 - При каждом импорте значения перезаписываются (upsert по ключу).

 ```json
 "sensors": {
  "fans": [
-    { "name": "FAN1", "location": "Front", "rpm": 4200, "status": "OK" },
-    { "name": "FAN_CPU0", "location": "CPU0", "rpm": 5600, "status": "OK" }
+    { "name": "FAN1", "rpm": 4200, "status": "OK" },
+    { "name": "FAN_CPU0", "rpm": 5600, "status": "OK" }
  ],
  "power": [
-    { "name": "12V Rail", "location": "Mainboard", "voltage_v": 12.06, "status": "OK" },
-    { "name": "PSU0 Input", "location": "PSU0", "voltage_v": 215.25, "current_a": 0.64, "power_w": 137.0, "status": "OK" }
+    { "name": "12V Rail", "voltage_v": 12.06, "status": "OK" },
+    { "name": "PSU0 Input", "voltage_v": 215.25, "current_a": 0.64, "power_w": 137.0, "status": "OK" }
  ],
  "temperatures": [
-    { "name": "CPU0 Temp", "location": "CPU0", "celsius": 46.0, "threshold_warning_celsius": 80.0, "threshold_critical_celsius": 95.0, "status": "OK" },
-    { "name": "Inlet Temp", "location": "Front", "celsius": 22.0, "threshold_warning_celsius": 40.0, "threshold_critical_celsius": 50.0, "status": "OK" }
+    { "name": "CPU0 Temp", "celsius": 46.0, "threshold_warning_celsius": 80.0, "threshold_critical_celsius": 95.0, "status": "OK" },
+    { "name": "Inlet Temp", "celsius": 22.0, "threshold_warning_celsius": 40.0, "threshold_critical_celsius": 50.0, "status": "OK" }
  ],
  "other": [
    { "name": "System Humidity", "value": 38.5, "unit": "%", "status": "OK" }
@@ -655,6 +667,31 @@ PSU без `serial_number` игнорируется.

 ---

+## Секция platform_config
+
+Необязательный объект с произвольными ключами — настройки платформы как есть из источника (BIOS, Redfish, IPMI).
+
+| Поле | Тип | Обязательно | Описание |
+|------|-----|-------------|----------|
+| `platform_config` | object | нет | Произвольный объект: ключи — строки, значения — строки, числа, булевы |
+
+**Правила platform_config:**
+- Содержимое объекта не валидируется: передавайте параметры как есть.
+- При каждом импорте хранится latest-snapshot per machine; история изменений по каждому ключу накапливается отдельно.
+- Если секция отсутствует или равна `null` — данные платформы не обновляются.
+
+```json
+"platform_config": {
+  "SecureBoot": "Enabled",
+  "BiosVersion": "06.08.05",
+  "TpmEnabled": true,
+  "NumaEnabled": false,
+  "HyperThreading": "Enabled"
+}
+```
+
+---
+
 ## Обработка статусов компонентов

 | Статус | Поведение |
@@ -787,6 +824,12 @@ PSU без `serial_number` игнорируется.
      "other": [
        { "name": "System Humidity", "value": 38.5, "unit": "%" }
      ]
+    },
+    "platform_config": {
+      "SecureBoot": "Enabled",
+      "BiosVersion": "06.08.05",
+      "TpmEnabled": true,
+      "HyperThreading": "Enabled"
    }
  }
 }