Split schema and project documentation into focused contracts
This commit is contained in:
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.
|
||||||
@@ -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` игнорируется.
|
||||||
@@ -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` | Компонент не создаётся/не обновляется |
|
||||||
@@ -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):
|
||||||
|
|||||||
Reference in new issue
Block a user