Split schema and project documentation into focused contracts

This commit is contained in:
mchus committed 2026-10-03 09:35:38 +03:00
1 parent b0e6402d66
commit d0d7233700
21 files changed
+405 -327

No files matched your search

@@ -0,0 +1,35 @@
# Contract: Project Architecture Documents
Part of [Project Bible](../contract.md).
## system-overview.md Rules
- List what is **in scope** and what is **explicitly out of scope**.
- Out of scope section prevents scope creep; update it when you reject a feature.
- Include tech stack and local run command.
## data-model.md Rules
- Document canonical naming: if domain model uses `Machine` but API uses `asset`, say so explicitly.
- List all DB tables with one-line description of each.
- Document any non-obvious invariants (e.g. "parts are projections of history, not source of truth").
- Migration policy: how migrations are numbered and applied.
## api-surface.md Rules
- Every endpoint: method, path, brief description, key response fields.
- Group by domain area (Registry, Ingest, Timeline, etc.).
- Note any endpoints that are UI-only routes vs JSON API.
- Document pagination, filtering params where non-obvious.
## runtime-flows.md Rules
This is the most important file. Document flows that are **easy to break**:
- Mutation paths (what happens step by step when user does X)
- Event/time source priority rules
- Deduplication logic
- Cross-entity side effects (e.g. removing a component affects asset status)
- Anything that caused a bug or regression: add a "DO NOT reintroduce" note
Format each flow as a numbered list of steps, not prose.
+6 -63
View File
@@ -1,6 +1,6 @@
# Contract: Project Bible (bible-local/) # Contract: Project Bible (bible-local/)
Version: 1.0 Version: 1.1
## Purpose ## Purpose
@@ -35,68 +35,6 @@ Optional (add when relevant):
INTEGRATION_GUIDE.md - external system integration (formats, protocols) INTEGRATION_GUIDE.md - external system integration (formats, protocols)
``` ```
## system-overview.md Rules
- List what is **in scope** and what is **explicitly out of scope**.
- Out of scope section prevents scope creep; update it when you reject a feature.
- Include tech stack and local run command.
## data-model.md Rules
- Document canonical naming: if domain model uses `Machine` but API uses `asset`, say so explicitly.
- List all DB tables with one-line description of each.
- Document any non-obvious invariants (e.g. "parts are projections of history, not source of truth").
- Migration policy: how migrations are numbered and applied.
## api-surface.md Rules
- Every endpoint: method, path, brief description, key response fields.
- Group by domain area (Registry, Ingest, Timeline, etc.).
- Note any endpoints that are UI-only routes vs JSON API.
- Document pagination, filtering params where non-obvious.
## runtime-flows.md Rules
This is the most important file. Document flows that are **easy to break**:
- Mutation paths (what happens step by step when user does X)
- Event/time source priority rules
- Deduplication logic
- Cross-entity side effects (e.g. removing a component affects asset status)
- Anything that caused a bug or regression: add a "DO NOT reintroduce" note
Format each flow as a numbered list of steps, not prose.
## Architectural Decision Log (ADL)
Write a decision entry when:
- You choose between two non-obvious approaches
- You intentionally reject a feature or pattern
- A bug caused a rule change (e.g. cursor safety)
- You freeze or deprecate something
**Format:**
```markdown
# Decision: <short title>
**Date:** YYYY-MM-DD
**Status:** active | superseded by YYYY-MM-DD-topic.md
## Context
What situation made this decision necessary.
## Decision
What was decided, stated clearly.
## Consequences
What this means going forward. What is now forbidden or required.
```
- One decision per file, named `YYYY-MM-DD-short-topic.md`.
- When a decision is superseded, add `superseded by` to the old file's status; do not delete it.
- Record the decision **in the same commit** as the code that implements it.
## What NOT to Put in bible-local/ ## What NOT to Put in bible-local/
- Generic rules (CSV format, logging, pagination) -> these are in `bible/rules/patterns/` - Generic rules (CSV format, logging, pagination) -> these are in `bible/rules/patterns/`
@@ -111,3 +49,8 @@ What this means going forward. What is now forbidden or required.
- If a section becomes outdated, fix or delete it; stale docs are worse than no docs. - If a section becomes outdated, fix or delete it; stale docs are worse than no docs.
- Bible files are in **English only**. - Bible files are in **English only**.
- Do not use em dash in Bible files; prefer ASCII punctuation such as `-`, `:`, or `;` depending on the sentence. - Do not use em dash in Bible files; prefer ASCII punctuation such as `-`, `:`, or `;` depending on the sentence.
## Topic Contracts
- [Architecture documents](architecture/contract.md)
- [Decision records and promotion to shared rules](decisions/contract.md)
@@ -0,0 +1,37 @@
# Contract: Project Decisions
Part of [Project Bible](../contract.md).
## Architectural Decision Log (ADL)
Write a decision entry when:
- You choose between two non-obvious approaches
- You intentionally reject a feature or pattern
- A bug caused a rule change (e.g. cursor safety)
- You freeze or deprecate something
**Format:**
```markdown
# Decision: <short title>
**Date:** YYYY-MM-DD
**Status:** active | superseded by YYYY-MM-DD-topic.md
## Context
What situation made this decision necessary.
## Decision
What was decided, stated clearly.
## Consequences
What this means going forward. What is now forbidden or required.
```
- One decision per file, named `YYYY-MM-DD-short-topic.md`.
- When a project-specific decision is superseded, add `superseded by` to its status; retain
its unique rationale. Shared knowledge promoted to `bible` is not a second local decision:
after the updated submodule is available, remove the local shared rules and replace their
index entries with links to the owning contracts. Preserve only project-specific bindings
and consequences locally; delete a file if no unique local knowledge remains.
- Record the decision **in the same commit** as the code that implements it.
@@ -0,0 +1,13 @@
# Changelog
| Версия | Дата | Изменения |
|--------|------|-----------|
| 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` |
| 2.8 | 2026-03-15 | Поле `location` удалено из всех `sensors.*` |
| 2.7 | 2026-03-15 | Явно запрещён синтез данных в `event_logs` |
| 2.6 | 2026-03-15 | Добавлена секция `event_logs` |
| 2.5 | 2026-03-15 | Добавлено `manufactured_year_week` для всех компонентов |
| 2.4 | 2026-03-15 | Component telemetry: health/life поля для всех секций |
| 2.0 | 2026-02-01 | `status_history`, `status_changed_at`; async job response |
| 1.0 | 2026-01-01 | Начальная версия |
@@ -0,0 +1,15 @@
# Contract: Hardware Ingest - board
Part of [hardware components](../contract.md), schema version 2.10.
## board (обязательная)
| Поле | Тип | Обязательно | Описание |
|------|-----|-------------|----------|
| `serial_number` | string | **да** | Серийный номер (ключ идентификации Asset) |
| `manufacturer` | string | нет | Производитель |
| `product_name` | string | нет | Модель |
| `part_number` | string | нет | Партномер |
| `uuid` | string | нет | UUID системы |
Значения `"NULL"` в строковых полях трактуются как отсутствие данных.
@@ -0,0 +1,15 @@
# Contract: Hardware Components
Part of [Hardware Ingest JSON](../contract.md), schema version 2.10.
Read the contract for each component section you send or consume.
- [board (обязательная)](board/contract.md)
- [firmware](firmware/contract.md)
- [cpus](cpus/contract.md)
- [memory](memory/contract.md)
- [storage](storage/contract.md)
- [pcie_devices](pcie_devices/contract.md)
- [power_supplies](power_supplies/contract.md)
- [sensors (опционально)](sensors/contract.md)
- [event_logs (опционально)](event_logs/contract.md)
- [platform_config (опционально)](platform_config/contract.md)
@@ -0,0 +1,23 @@
# Contract: Hardware Ingest - cpus
Part of [hardware components](../contract.md), schema version 2.10.
## cpus
| Поле | Тип | Описание |
|------|-----|----------|
| `socket` | int | **обязательно**; используется для генерации serial |
| `model` | string | Модель процессора |
| `manufacturer` | string | |
| `cores` / `threads` | int | |
| `frequency_mhz` / `max_frequency_mhz` | int | |
| `temperature_c` | float | Telemetry, °C |
| `power_w` | float | Telemetry, Вт |
| `throttled` | bool | Thermal/power throttling |
| `correctable_error_count` / `uncorrectable_error_count` | int | |
| `life_remaining_pct` / `life_used_pct` | float | Health/wear, % |
| `serial_number` | string | Если доступен |
| `firmware` | string | Версия микрокода (Microcode level — передавать как есть) |
| `present` | bool | По умолчанию `true` |
Генерация serial при отсутствии: `{board_serial}-CPU-{socket}`
@@ -0,0 +1,21 @@
# Contract: Hardware Ingest - event_logs
Part of [hardware components](../contract.md), schema version 2.10.
## event_logs (опционально)
Нормализованные операционные логи. Не попадают в history timeline. Дедуплицируются по `(asset, source, fingerprint)`.
| Поле | Тип | Обязательно | Описание |
|------|-----|-------------|----------|
| `source` | string | **да** | `host`, `bmc`, `redfish` |
| `message` | string | **да** | Нормализованный текст события |
| `event_time` | string RFC3339 | нет | |
| `severity` | string | нет | `OK`, `Info`, `Warning`, `Critical`, `Unknown` |
| `message_id` | string | нет | Код события источника |
| `component_ref` | string | нет | Ссылка на компонент/слот |
| `fingerprint` | string | нет | Внешний dedup-key; если нет — система вычисляет свой |
| `is_active` | bool | нет | Событие всё ещё активно |
| `raw_payload` | object | нет | Сырой vendor-specific payload |
Запрещено синтезировать `message`, `message_id`, `component_ref`, serial/device identifiers.
@@ -0,0 +1,12 @@
# Contract: Hardware Ingest - firmware
Part of [hardware components](../contract.md), schema version 2.10.
## firmware
| Поле | Тип | Обязательно |
|------|-----|-------------|
| `device_name` | string | **да** |
| `version` | string | **да** |
Записи с пустым `device_name` или `version` игнорируются. Изменение версии создаёт событие `FIRMWARE_CHANGED`.
@@ -0,0 +1,22 @@
# Contract: Hardware Ingest - memory
Part of [hardware components](../contract.md), schema version 2.10.
## memory
| Поле | Тип | Описание |
|------|-----|----------|
| `slot` | string | |
| `present` | bool | По умолчанию `true` |
| `serial_number` | string | Обязателен для создания записи |
| `part_number` | string | Используется как модель |
| `manufacturer` | string | |
| `size_mb` | int | |
| `type` | string | `DDR3`, `DDR4`, `DDR5` |
| `max_speed_mhz` / `current_speed_mhz` | int | |
| `temperature_c` | float | Telemetry |
| `correctable_ecc_error_count` / `uncorrectable_ecc_error_count` | int | |
| `life_remaining_pct` / `life_used_pct` / `spare_blocks_remaining_pct` | float | |
| `performance_degraded` / `data_loss_detected` | bool | |
Модуль без `serial_number`, с `present=false` или `status=Empty` игнорируется.
@@ -0,0 +1,26 @@
# Contract: Hardware Ingest - pcie_devices
Part of [hardware components](../contract.md), schema version 2.10.
## pcie_devices
| Поле | Тип | Описание |
|------|-----|----------|
| `slot` | string | Канонический адрес (BDF). `bdf` — deprecated alias, нормализуется при ingest |
| `vendor_id` / `device_id` | int | PCI ID (decimal) |
| `numa_node` | int | NUMA/CPU affinity |
| `device_class` | string | `MassStorageController`, `StorageController`, `NetworkController`, `EthernetController`, `FibreChannelController`, `VideoController`, `ProcessingAccelerator`, `DisplayController` (список открытый) |
| `manufacturer` / `model` / `serial_number` / `firmware` | string | |
| `link_width` / `max_link_width` | int | |
| `link_speed` / `max_link_speed` | string | `Gen3`, `Gen4`, `Gen5` |
| `mac_addresses` | string[] | MAC-адреса портов |
| `temperature_c` / `power_w` | float | Device-level telemetry |
| `life_remaining_pct` / `life_used_pct` | float | |
| `ecc_corrected_total` / `ecc_uncorrected_total` | int64 | |
| `hw_slowdown` | bool | |
| `battery_charge_pct` / `battery_health_pct` / `battery_temperature_c` / `battery_voltage_v` | float | |
| `battery_replace_required` | bool | |
| `sfp_temperature_c` / `sfp_tx_power_dbm` / `sfp_rx_power_dbm` / `sfp_voltage_v` / `sfp_bias_ma` | float | Optical telemetry |
| `present` | bool | По умолчанию `true` |
Генерация serial при отсутствии или `"N/A"`: `{board_serial}-PCIE-{slot}`
@@ -0,0 +1,8 @@
# Contract: Hardware Ingest - platform_config
Part of [hardware components](../contract.md), schema version 2.10.
## platform_config (опционально)
Произвольный объект с настройками платформы (BIOS/Redfish/IPMI) как есть из источника.
При каждом импорте хранится latest-snapshot per machine.
@@ -0,0 +1,19 @@
# Contract: Hardware Ingest - power_supplies
Part of [hardware components](../contract.md), schema version 2.10.
## power_supplies
| Поле | Тип | Описание |
|------|-----|----------|
| `slot` | string | |
| `present` | bool | По умолчанию `true` |
| `serial_number` | string | Обязателен для создания записи |
| `part_number` / `model` / `vendor` | string | |
| `wattage_w` | int | |
| `firmware` | string | |
| `input_type` | string | Например `ACWideRange` |
| `input_voltage` / `input_power_w` / `output_power_w` / `temperature_c` | float | Telemetry |
| `life_remaining_pct` / `life_used_pct` | float | |
PSU без `serial_number` игнорируется.
@@ -0,0 +1,17 @@
# Contract: Hardware Ingest - sensors
Part of [hardware components](../contract.md), schema version 2.10.
## sensors (опционально)
Данные хранятся как last-known-value на уровне Asset. Идентификатор: `(sensor_type, name)`.
Поле `location` передавать не нужно — игнорируется. Сенсоры без `name` игнорируются.
```json
"sensors": {
"fans": [{ "name": "FAN1", "rpm": 4200, "status": "OK" }],
"power": [{ "name": "12V Rail", "voltage_v": 12.06, "status": "OK" }],
"temperatures": [{ "name": "CPU0 Temp", "celsius": 46.0, "threshold_warning_celsius": 80.0, "threshold_critical_celsius": 95.0, "status": "OK" }],
"other": [{ "name": "System Humidity", "value": 38.5, "unit": "%" }]
}
```
@@ -0,0 +1,28 @@
# Contract: Hardware Ingest - storage
Part of [hardware components](../contract.md), schema version 2.10.
## storage
| Поле | Тип | Описание |
|------|-----|----------|
| `slot` | string | BDF (`0000:18:00.0`) для PCIe-подключённых |
| `serial_number` | string | Обязателен для создания записи |
| `model` / `manufacturer` | string | |
| `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 | Физический размер блока |
| `metadata_bytes_per_block` | int64 | Metadata/protection bytes на блок, например `0` или `8` |
| `temperature_c` | float | Telemetry |
| `power_on_hours` / `power_cycles` / `unsafe_shutdowns` | int64 | |
| `media_errors` / `error_log_entries` | int64 | |
| `written_bytes` / `read_bytes` | int64 | |
| `life_used_pct` / `life_remaining_pct` / `available_spare_pct` | float | |
| `reallocated_sectors` / `current_pending_sectors` / `offline_uncorrectable` | int64 | |
| `firmware` | string | Изменение создаёт `FIRMWARE_CHANGED` |
| `present` | bool | По умолчанию `true` |
Формат `512+8` не передаётся строкой — только через `logical_block_size_bytes` + `metadata_bytes_per_block`.
Диск без `serial_number` игнорируется.
+7 -263
View File
@@ -26,268 +26,12 @@ Content-Type: application/json
Ответ `202 Accepted` с `job_id`. Результат: `GET /ingest/hardware/jobs/{job_id}`. Ответ `202 Accepted` с `job_id`. Результат: `GET /ingest/hardware/jobs/{job_id}`.
## Структура верхнего уровня
```json ## Topic Contracts
{
"filename": "redfish://10.10.10.103",
"source_type": "api",
"protocol": "redfish",
"target_host": "10.10.10.103",
"collected_at": "2026-02-10T15:30:00Z",
"hardware": {
"board": { ... },
"firmware": [ ... ],
"cpus": [ ... ],
"memory": [ ... ],
"storage": [ ... ],
"pcie_devices": [ ... ],
"power_supplies": [ ... ],
"sensors": { ... },
"event_logs": [ ... ],
"platform_config": { ... }
}
}
```
| Поле | Тип | Обязательно | Описание | - [Структура верхнего уровня](envelope/contract.md)
|------|-----|-------------|----------| - [Общие поля статуса компонентов](status/contract.md)
| `collected_at` | string RFC3339 | **да** | Время сбора данных | - [Обработка отсутствующих serial_number](identity/contract.md)
| `hardware` | object | **да** | Аппаратный снапшот | - [Секции hardware](components/contract.md)
| `hardware.board.serial_number` | string | **да** | Серийный номер платы/сервера | - [Минимальный валидный пример](examples/minimal.md)
| `target_host` | string | нет | IP или hostname | - [Changelog](changelog.md)
| `source_type` | string | нет | `api`, `logfile`, `manual` |
| `protocol` | string | нет | `redfish`, `ipmi`, `snmp`, `ssh` |
| `filename` | string | нет | Идентификатор источника |
## Общие поля статуса компонентов
Применяются ко всем компонентным секциям (`cpus`, `memory`, `storage`, `pcie_devices`, `power_supplies`).
| Поле | Тип | Описание |
|------|-----|----------|
| `status` | string | `OK`, `Warning`, `Critical`, `Unknown`, `Empty` |
| `status_checked_at` | string RFC3339 | Время последней проверки |
| `status_changed_at` | string RFC3339 | Время последнего изменения |
| `status_history` | array | История переходов (`status`, `changed_at` обязательны) |
| `error_description` | string | Текст ошибки/диагностики |
| `manufactured_year_week` | string | Дата производства `YYYY-Www`, например `2024-W07` |
Правила статуса:
- Не включайте записи `status_history` без `changed_at`.
- `status_history` сортировать по `changed_at` по возрастанию.
- Все даты — RFC3339, рекомендуется UTC (`Z`).
| Статус | Поведение |
|--------|-----------|
| `OK` | Нормальная обработка |
| `Warning` | Создаётся событие `COMPONENT_WARNING` |
| `Critical` | Создаётся событие `COMPONENT_FAILED` + запись в `failure_events` |
| `Unknown` | Компонент считается рабочим, создаётся событие `COMPONENT_UNKNOWN` |
| `Empty` | Компонент не создаётся/не обновляется |
## Секции hardware
### board (обязательная)
| Поле | Тип | Обязательно | Описание |
|------|-----|-------------|----------|
| `serial_number` | string | **да** | Серийный номер (ключ идентификации Asset) |
| `manufacturer` | string | нет | Производитель |
| `product_name` | string | нет | Модель |
| `part_number` | string | нет | Партномер |
| `uuid` | string | нет | UUID системы |
Значения `"NULL"` в строковых полях трактуются как отсутствие данных.
### firmware
| Поле | Тип | Обязательно |
|------|-----|-------------|
| `device_name` | string | **да** |
| `version` | string | **да** |
Записи с пустым `device_name` или `version` игнорируются. Изменение версии создаёт событие `FIRMWARE_CHANGED`.
### cpus
| Поле | Тип | Описание |
|------|-----|----------|
| `socket` | int | **обязательно**; используется для генерации serial |
| `model` | string | Модель процессора |
| `manufacturer` | string | |
| `cores` / `threads` | int | |
| `frequency_mhz` / `max_frequency_mhz` | int | |
| `temperature_c` | float | Telemetry, °C |
| `power_w` | float | Telemetry, Вт |
| `throttled` | bool | Thermal/power throttling |
| `correctable_error_count` / `uncorrectable_error_count` | int | |
| `life_remaining_pct` / `life_used_pct` | float | Health/wear, % |
| `serial_number` | string | Если доступен |
| `firmware` | string | Версия микрокода (Microcode level — передавать как есть) |
| `present` | bool | По умолчанию `true` |
Генерация serial при отсутствии: `{board_serial}-CPU-{socket}`
### memory
| Поле | Тип | Описание |
|------|-----|----------|
| `slot` | string | |
| `present` | bool | По умолчанию `true` |
| `serial_number` | string | Обязателен для создания записи |
| `part_number` | string | Используется как модель |
| `manufacturer` | string | |
| `size_mb` | int | |
| `type` | string | `DDR3`, `DDR4`, `DDR5` |
| `max_speed_mhz` / `current_speed_mhz` | int | |
| `temperature_c` | float | Telemetry |
| `correctable_ecc_error_count` / `uncorrectable_ecc_error_count` | int | |
| `life_remaining_pct` / `life_used_pct` / `spare_blocks_remaining_pct` | float | |
| `performance_degraded` / `data_loss_detected` | bool | |
Модуль без `serial_number`, с `present=false` или `status=Empty` игнорируется.
### storage
| Поле | Тип | Описание |
|------|-----|----------|
| `slot` | string | BDF (`0000:18:00.0`) для PCIe-подключённых |
| `serial_number` | string | Обязателен для создания записи |
| `model` / `manufacturer` | string | |
| `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 | Физический размер блока |
| `metadata_bytes_per_block` | int64 | Metadata/protection bytes на блок, например `0` или `8` |
| `temperature_c` | float | Telemetry |
| `power_on_hours` / `power_cycles` / `unsafe_shutdowns` | int64 | |
| `media_errors` / `error_log_entries` | int64 | |
| `written_bytes` / `read_bytes` | int64 | |
| `life_used_pct` / `life_remaining_pct` / `available_spare_pct` | float | |
| `reallocated_sectors` / `current_pending_sectors` / `offline_uncorrectable` | int64 | |
| `firmware` | string | Изменение создаёт `FIRMWARE_CHANGED` |
| `present` | bool | По умолчанию `true` |
Формат `512+8` не передаётся строкой — только через `logical_block_size_bytes` + `metadata_bytes_per_block`.
Диск без `serial_number` игнорируется.
### pcie_devices
| Поле | Тип | Описание |
|------|-----|----------|
| `slot` | string | Канонический адрес (BDF). `bdf` — deprecated alias, нормализуется при ingest |
| `vendor_id` / `device_id` | int | PCI ID (decimal) |
| `numa_node` | int | NUMA/CPU affinity |
| `device_class` | string | `MassStorageController`, `StorageController`, `NetworkController`, `EthernetController`, `FibreChannelController`, `VideoController`, `ProcessingAccelerator`, `DisplayController` (список открытый) |
| `manufacturer` / `model` / `serial_number` / `firmware` | string | |
| `link_width` / `max_link_width` | int | |
| `link_speed` / `max_link_speed` | string | `Gen3`, `Gen4`, `Gen5` |
| `mac_addresses` | string[] | MAC-адреса портов |
| `temperature_c` / `power_w` | float | Device-level telemetry |
| `life_remaining_pct` / `life_used_pct` | float | |
| `ecc_corrected_total` / `ecc_uncorrected_total` | int64 | |
| `hw_slowdown` | bool | |
| `battery_charge_pct` / `battery_health_pct` / `battery_temperature_c` / `battery_voltage_v` | float | |
| `battery_replace_required` | bool | |
| `sfp_temperature_c` / `sfp_tx_power_dbm` / `sfp_rx_power_dbm` / `sfp_voltage_v` / `sfp_bias_ma` | float | Optical telemetry |
| `present` | bool | По умолчанию `true` |
Генерация serial при отсутствии или `"N/A"`: `{board_serial}-PCIE-{slot}`
### power_supplies
| Поле | Тип | Описание |
|------|-----|----------|
| `slot` | string | |
| `present` | bool | По умолчанию `true` |
| `serial_number` | string | Обязателен для создания записи |
| `part_number` / `model` / `vendor` | string | |
| `wattage_w` | int | |
| `firmware` | string | |
| `input_type` | string | Например `ACWideRange` |
| `input_voltage` / `input_power_w` / `output_power_w` / `temperature_c` | float | Telemetry |
| `life_remaining_pct` / `life_used_pct` | float | |
PSU без `serial_number` игнорируется.
### sensors (опционально)
Данные хранятся как last-known-value на уровне Asset. Идентификатор: `(sensor_type, name)`.
Поле `location` передавать не нужно — игнорируется. Сенсоры без `name` игнорируются.
```json
"sensors": {
"fans": [{ "name": "FAN1", "rpm": 4200, "status": "OK" }],
"power": [{ "name": "12V Rail", "voltage_v": 12.06, "status": "OK" }],
"temperatures": [{ "name": "CPU0 Temp", "celsius": 46.0, "threshold_warning_celsius": 80.0, "threshold_critical_celsius": 95.0, "status": "OK" }],
"other": [{ "name": "System Humidity", "value": 38.5, "unit": "%" }]
}
```
### event_logs (опционально)
Нормализованные операционные логи. Не попадают в history timeline. Дедуплицируются по `(asset, source, fingerprint)`.
| Поле | Тип | Обязательно | Описание |
|------|-----|-------------|----------|
| `source` | string | **да** | `host`, `bmc`, `redfish` |
| `message` | string | **да** | Нормализованный текст события |
| `event_time` | string RFC3339 | нет | |
| `severity` | string | нет | `OK`, `Info`, `Warning`, `Critical`, `Unknown` |
| `message_id` | string | нет | Код события источника |
| `component_ref` | string | нет | Ссылка на компонент/слот |
| `fingerprint` | string | нет | Внешний dedup-key; если нет — система вычисляет свой |
| `is_active` | bool | нет | Событие всё ещё активно |
| `raw_payload` | object | нет | Сырой vendor-specific payload |
Запрещено синтезировать `message`, `message_id`, `component_ref`, serial/device identifiers.
### platform_config (опционально)
Произвольный объект с настройками платформы (BIOS/Redfish/IPMI) как есть из источника.
При каждом импорте хранится latest-snapshot per machine.
## Обработка отсутствующих serial_number
Интегратор не подставляет вымышленные значения, хеши или placeholder-идентификаторы.
Разрешены только server-side fallback-правила:
| Тип | Поведение |
|-----|-----------|
| CPU | Генерируется: `{board_serial}-CPU-{socket}` |
| PCIe | Генерируется: `{board_serial}-PCIE-{slot}` |
| Memory | Компонент игнорируется |
| Storage | Компонент игнорируется |
| PSU | Компонент игнорируется |
Если `serial_number` не уникален внутри payload для того же `model`: первое вхождение — оригинальный serial, дубли получают `NO_SN-XXXXXXXX`.
## Минимальный валидный пример
```json
{
"collected_at": "2026-02-10T15:30:00Z",
"target_host": "192.168.1.100",
"hardware": {
"board": {
"serial_number": "SRV-001"
}
}
}
```
## Changelog
| Версия | Дата | Изменения |
|--------|------|-----------|
| 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` |
| 2.8 | 2026-03-15 | Поле `location` удалено из всех `sensors.*` |
| 2.7 | 2026-03-15 | Явно запрещён синтез данных в `event_logs` |
| 2.6 | 2026-03-15 | Добавлена секция `event_logs` |
| 2.5 | 2026-03-15 | Добавлено `manufactured_year_week` для всех компонентов |
| 2.4 | 2026-03-15 | Component telemetry: health/life поля для всех секций |
| 2.0 | 2026-02-01 | `status_history`, `status_changed_at`; async job response |
| 1.0 | 2026-01-01 | Начальная версия |
@@ -0,0 +1,37 @@
# Contract: Hardware Ingest - Envelope
Part of [Hardware Ingest JSON](../contract.md), schema version 2.10.
## Структура верхнего уровня
```json
{
"filename": "redfish://10.10.10.103",
"source_type": "api",
"protocol": "redfish",
"target_host": "10.10.10.103",
"collected_at": "2026-02-10T15:30:00Z",
"hardware": {
"board": { ... },
"firmware": [ ... ],
"cpus": [ ... ],
"memory": [ ... ],
"storage": [ ... ],
"pcie_devices": [ ... ],
"power_supplies": [ ... ],
"sensors": { ... },
"event_logs": [ ... ],
"platform_config": { ... }
}
}
```
| Поле | Тип | Обязательно | Описание |
|------|-----|-------------|----------|
| `collected_at` | string RFC3339 | **да** | Время сбора данных |
| `hardware` | object | **да** | Аппаратный снапшот |
| `hardware.board.serial_number` | string | **да** | Серийный номер платы/сервера |
| `target_host` | string | нет | IP или hostname |
| `source_type` | string | нет | `api`, `logfile`, `manual` |
| `protocol` | string | нет | `redfish`, `ipmi`, `snmp`, `ssh` |
| `filename` | string | нет | Идентификатор источника |
@@ -0,0 +1,13 @@
# Минимальный валидный пример
```json
{
"collected_at": "2026-02-10T15:30:00Z",
"target_host": "192.168.1.100",
"hardware": {
"board": {
"serial_number": "SRV-001"
}
}
}
```
@@ -0,0 +1,18 @@
# Contract: Hardware Ingest - Identity
Part of [Hardware Ingest JSON](../contract.md), schema version 2.10.
## Обработка отсутствующих serial_number
Интегратор не подставляет вымышленные значения, хеши или placeholder-идентификаторы.
Разрешены только server-side fallback-правила:
| Тип | Поведение |
|-----|-----------|
| CPU | Генерируется: `{board_serial}-CPU-{socket}` |
| PCIe | Генерируется: `{board_serial}-PCIE-{slot}` |
| Memory | Компонент игнорируется |
| Storage | Компонент игнорируется |
| PSU | Компонент игнорируется |
Если `serial_number` не уникален внутри payload для того же `model`: первое вхождение — оригинальный serial, дубли получают `NO_SN-XXXXXXXX`.
@@ -0,0 +1,29 @@
# Contract: Hardware Ingest - Status
Part of [Hardware Ingest JSON](../contract.md), schema version 2.10.
## Общие поля статуса компонентов
Применяются ко всем компонентным секциям (`cpus`, `memory`, `storage`, `pcie_devices`, `power_supplies`).
| Поле | Тип | Описание |
|------|-----|----------|
| `status` | string | `OK`, `Warning`, `Critical`, `Unknown`, `Empty` |
| `status_checked_at` | string RFC3339 | Время последней проверки |
| `status_changed_at` | string RFC3339 | Время последнего изменения |
| `status_history` | array | История переходов (`status`, `changed_at` обязательны) |
| `error_description` | string | Текст ошибки/диагностики |
| `manufactured_year_week` | string | Дата производства `YYYY-Www`, например `2024-W07` |
Правила статуса:
- Не включайте записи `status_history` без `changed_at`.
- `status_history` сортировать по `changed_at` по возрастанию.
- Все даты — RFC3339, рекомендуется UTC (`Z`).
| Статус | Поведение |
|--------|-----------|
| `OK` | Нормальная обработка |
| `Warning` | Создаётся событие `COMPONENT_WARNING` |
| `Critical` | Создаётся событие `COMPONENT_FAILED` + запись в `failure_events` |
| `Unknown` | Компонент считается рабочим, создаётся событие `COMPONENT_UNKNOWN` |
| `Empty` | Компонент не создаётся/не обновляется |
+4 -1
View File
@@ -11,7 +11,10 @@ links = {}
errors = [] errors = []
for document in documents: for document in documents:
text = re.sub(r'```.*?```', '', document.read_text(), flags=re.S) source = document.read_text()
if len(re.findall(r'^```', source, flags=re.M)) % 2:
errors.append(f'{document.relative_to(root)}: unclosed code block')
text = re.sub(r'```.*?```', '', source, flags=re.S)
targets = [] targets = []
for reference in re.findall(r'\[[^\]]*\]\(([^)]+)\)', text): for reference in re.findall(r'\[[^\]]*\]\(([^)]+)\)', text):
if re.match(r'[a-zA-Z]+:|#', reference): if re.match(r'[a-zA-Z]+:|#', reference):