Sync hardware ingest contract v2.7

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

@@ -1,6 +1,6 @@
 ---
 title: Hardware Ingest JSON Contract
-version: "2.1"
+version: "2.7"
 updated: "2026-03-15"
 maintainer: Reanimator Core
 audience: external-integrators, ai-agents
@@ -9,7 +9,7 @@ language: ru
 
 # Интеграция с Reanimator: контракт JSON-импорта аппаратного обеспечения
 
-Версия: **2.1** · Дата: **2026-03-15**
+Версия: **2.7** · Дата: **2026-03-15**
 
 Документ описывает формат JSON для передачи данных об аппаратном обеспечении серверов в систему **Reanimator** (управление жизненным циклом аппаратного обеспечения).
 Предназначен для разработчиков смежных систем (Redfish-коллекторов, агентов мониторинга, CMDB-экспортёров) и может быть включён в документацию интегрируемых проектов.
@@ -22,6 +22,9 @@ language: ru
 
 | Версия | Дата | Изменения |
 |--------|------|-----------|
+| 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`) |
 | 2.4 | 2026-03-15 | Добавлена первая волна component telemetry: health/life поля для `cpus`, `memory`, `storage`, `pcie_devices`, `power_supplies` |
 | 2.3 | 2026-03-15 | Добавлены component telemetry поля: `pcie_devices.temperature_c`, `pcie_devices.power_w`, `power_supplies.temperature_c` |
 | 2.2 | 2026-03-15 | Добавлено поле `numa_node` у `pcie_devices` для topology/affinity |
@@ -38,6 +41,7 @@ language: ru
 3. **Частичность** — можно передавать только те секции, данные по которым доступны. Пустой массив и отсутствие секции эквивалентны.
 4. **Строгая схема** — endpoint использует строгий JSON-декодер; неизвестные поля приводят к `400 Bad Request`.
 5. **Event-driven** — импорт создаёт события в timeline (LOG_COLLECTED, INSTALLED, REMOVED, FIRMWARE_CHANGED и др.).
+6. **Без синтеза со стороны интегратора** — сборщик передаёт только фактически собранные значения. Нельзя придумывать `serial_number`, `component_ref`, `message`, `message_id` или другие идентификаторы/атрибуты, если источник их не предоставил или парсер не смог их надёжно извлечь.
 
 ---
 
@@ -127,7 +131,8 @@ GET /ingest/hardware/jobs/{job_id}
     "storage":        [ ... ],
     "pcie_devices":   [ ... ],
     "power_supplies": [ ... ],
-    "sensors":        { ... }
+    "sensors":        { ... },
+    "event_logs":     [ ... ]
   }
 }
 ```
@@ -157,6 +162,7 @@ GET /ingest/hardware/jobs/{job_id}
 | `status_changed_at` | string RFC3339 | Время последнего изменения статуса |
 | `status_history` | array | История переходов статусов (см. ниже) |
 | `error_description` | string | Текст ошибки/диагностики |
+| `manufactured_year_week` | string | Дата производства в формате `YYYY-Www`, например `2024-W07` |
 
 **Объект `status_history[]`:**
 
@@ -178,6 +184,7 @@ GET /ingest/hardware/jobs/{job_id}
 - Если источник хранит историю — передавайте `status_history` отсортированным по `changed_at` по возрастанию.
 - Не включайте записи `status_history` без `changed_at`.
 - Все даты — RFC3339, рекомендуется UTC (`Z`).
+- `manufactured_year_week` используйте, когда источник знает только год и неделю производства, без точной календарной даты.
 
 ---
 
@@ -250,12 +257,14 @@ GET /ingest/hardware/jobs/{job_id}
 | `life_remaining_pct` | float | нет | Остаточный ресурс / health, % |
 | `life_used_pct` | float | нет | Использованный ресурс / wear, % |
 | `serial_number` | string | нет | Серийный номер (если доступен) |
-| `firmware` | string | нет | Версия микрокода |
+| `firmware` | string | нет | Версия микрокода; если логгер отдает `Microcode level`, передавайте его сюда как есть |
 | `present` | bool | нет | Наличие (по умолчанию `true`) |
 | + общие поля статуса | | | см. раздел выше |
 
 **Генерация serial_number при отсутствии:** `{board_serial}-CPU-{socket}`
 
+Если источник использует поле/лейбл `Microcode level`, его значение передавайте в `cpus[].firmware` без дополнительного преобразования.
+
 ```json
 "cpus": [
   {
@@ -282,7 +291,6 @@ GET /ingest/hardware/jobs/{job_id}
 | Поле | Тип | Обязательно | Описание |
 |------|-----|-------------|----------|
 | `slot` | string | нет | Идентификатор слота |
-| `location` | string | нет | Физическое расположение |
 | `present` | bool | нет | Наличие модуля (по умолчанию `true`) |
 | `serial_number` | string | нет | Серийный номер |
 | `part_number` | string | нет | Партномер (используется как модель) |
@@ -328,7 +336,7 @@ GET /ingest/hardware/jobs/{job_id}
 
 | Поле | Тип | Обязательно | Описание |
 |------|-----|-------------|----------|
-| `slot` | string | нет | Идентификатор слота |
+| `slot` | string | нет | Канонический адрес установки PCIe-устройства; передавайте BDF (`0000:18:00.0`) |
 | `serial_number` | string | нет | Серийный номер |
 | `model` | string | нет | Модель |
 | `manufacturer` | string | нет | Производитель |
@@ -404,7 +412,7 @@ GET /ingest/hardware/jobs/{job_id}
 | `sfp_rx_power_dbm` | float | нет | RX optical power, dBm |
 | `sfp_voltage_v` | float | нет | Напряжение SFP, В |
 | `sfp_bias_ma` | float | нет | Bias current SFP, мА |
-| `bdf` | string | нет | Bus:Device.Function, например `0000:18:00.0` |
+| `bdf` | string | нет | Deprecated alias для `slot`; при наличии ingest нормализует его в `slot` |
 | `device_class` | string | нет | Класс устройства (см. список ниже) |
 | `manufacturer` | string | нет | Производитель |
 | `model` | string | нет | Модель |
@@ -421,7 +429,9 @@ 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. Они не влияют на идентификацию компонента.
 
-**Генерация serial_number при отсутствии или `"N/A"`:** `{board_serial}-PCIE-{slot}`
+**Генерация serial_number при отсутствии или `"N/A"`:** `{board_serial}-PCIE-{slot}`, где `slot` для PCIe равен BDF.
+
+`slot` — единственный канонический адрес компонента. Для PCIe в `slot` передавайте BDF. Поле `bdf` сохраняется только как переходный alias на входе и не должно использоваться как отдельная координата рядом со `slot`.
 
 **Значения `device_class`:**
 
@@ -441,7 +451,7 @@ GET /ingest/hardware/jobs/{job_id}
 ```json
 "pcie_devices": [
   {
-    "slot": "PCIeCard2",
+    "slot": "0000:3b:00.0",
     "vendor_id": 5555,
     "device_id": 4401,
     "numa_node": 0,
@@ -450,7 +460,6 @@ GET /ingest/hardware/jobs/{job_id}
     "sfp_temperature_c": 36.2,
     "sfp_tx_power_dbm": -1.8,
     "sfp_rx_power_dbm": -2.1,
-    "bdf": "0000:3b:00.0",
     "device_class": "EthernetController",
     "manufacturer": "Intel",
     "model": "X710 10GbE",
@@ -526,6 +535,58 @@ PSU без `serial_number` игнорируется.
 }
 ```
 
+---
+
+### event_logs
+
+Нормализованные операционные логи сервера из `host`, `bmc` или `redfish`.
+
+Эти записи не попадают в history timeline и не создают history events. Они сохраняются в отдельной deduplicated log store и отображаются в отдельном UI-блоке asset logs / host logs.
+
+| Поле | Тип | Обязательно | Описание |
+|------|-----|-------------|----------|
+| `source` | string | **да** | Источник лога: `host`, `bmc`, `redfish` |
+| `event_time` | string RFC3339 | нет | Время события из источника; если отсутствует, используется время ingest/collection |
+| `severity` | string | нет | Уровень: `OK`, `Info`, `Warning`, `Critical`, `Unknown` |
+| `message_id` | string | нет | Идентификатор/код события источника |
+| `message` | string | **да** | Нормализованный текст события |
+| `component_ref` | string | нет | Ссылка на компонент/устройство/слот, если извлекается |
+| `fingerprint` | string | нет | Внешний готовый dedup-key; если не передан, система вычисляет свой |
+| `is_active` | bool | нет | Признак, что событие всё ещё активно/не погашено, если источник умеет lifecycle |
+| `raw_payload` | object | нет | Сырой vendor-specific payload для диагностики |
+
+**Правила event_logs:**
+- Логи дедуплицируются в рамках asset + source + fingerprint.
+- Если `fingerprint` не передан, система строит его из нормализованных полей (`source`, `message_id`, `message`, `component_ref`, временная нормализация).
+- Интегратор/сборщик логов не должен синтезировать содержимое событий: не придумывайте `message`, `message_id`, `component_ref`, serial/device identifiers или иные поля, если они отсутствуют в исходном логе или не были надёжно извлечены.
+- Повторное получение того же события обновляет `last_seen_at`/счётчик повторов и не должно создавать новый timeline/history event.
+- `event_logs` используются для отдельного UI-представления логов и не изменяют canonical state компонентов/asset по умолчанию.
+
+```json
+"event_logs": [
+  {
+    "source": "bmc",
+    "event_time": "2026-03-15T14:03:11Z",
+    "severity": "Warning",
+    "message_id": "0x000F",
+    "message": "Correctable ECC error threshold exceeded",
+    "component_ref": "CPU0_C0D0",
+    "raw_payload": {
+      "sensor": "DIMM_A1",
+      "sel_record_id": "0042"
+    }
+  },
+  {
+    "source": "redfish",
+    "event_time": "2026-03-15T14:03:20Z",
+    "severity": "Info",
+    "message_id": "OpenBMC.0.1.SystemReboot",
+    "message": "System reboot requested by administrator",
+    "component_ref": "Mainboard"
+  }
+]
+```
+
 #### sensors.fans
 
 | Поле | Тип | Обязательно | Описание |
@@ -608,10 +669,12 @@ PSU без `serial_number` игнорируется.
 
 ## Обработка отсутствующих serial_number
 
+Общее правило для всех секций: если источник не вернул серийный номер и сборщик не смог его надёжно извлечь, интегратор не должен подставлять вымышленные значения, хеши, локальные placeholder-идентификаторы или серийные номера "по догадке". Разрешены только явно оговорённые ниже server-side fallback-правила ingest.
+
 | Тип | Поведение |
 |-----|-----------|
 | CPU | Генерируется: `{board_serial}-CPU-{socket}` |
-| PCIe | Генерируется: `{board_serial}-PCIE-{slot}` (если serial = `"N/A"` или пустой) |
+| PCIe | Генерируется: `{board_serial}-PCIE-{slot}` (если serial = `"N/A"` или пустой; `slot` для PCIe = BDF) |
 | Memory | Компонент игнорируется |
 | Storage | Компонент игнорируется |
 | PSU | Компонент игнорируется |
@@ -687,7 +750,7 @@ PSU без `serial_number` игнорируется.
     ],
     "pcie_devices": [
       {
-        "slot": "PCIeCard1",
+        "slot": "0000:18:00.0",
         "device_class": "EthernetController",
         "manufacturer": "Intel",
         "model": "X710 10GbE",