docs: refresh project documentation
This commit is contained in:
Mikhail Chusavitin
@@ -1,104 +1,87 @@
|
||||
# 04 — Data Models
|
||||
|
||||
## AnalysisResult
|
||||
## Core contract: `AnalysisResult`
|
||||
|
||||
`internal/models/` — the central data contract shared by parsers, collectors, exporters, and the HTTP layer.
|
||||
`internal/models/models.go` defines the shared result passed between parsers, collectors, server handlers, and exporters.
|
||||
|
||||
**Stability rule:** Never break the JSON shape of `AnalysisResult`.
|
||||
Backward-compatible additions are allowed; removals or renames are not.
|
||||
Stability rule:
|
||||
- do not rename or remove JSON fields from `AnalysisResult`
|
||||
- additive fields are allowed
|
||||
- UI and exporter compatibility depends on this shape remaining stable
|
||||
|
||||
Key top-level fields:
|
||||
Key fields:
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `filename` | `string` | Uploaded filename or generated live source identifier |
|
||||
| `source_type` | `string` | `archive` or `api` |
|
||||
| `protocol` | `string` | `redfish`, `ipmi`, or empty for archive uploads |
|
||||
| `target_host` | `string` | BMC host for live collection |
|
||||
| `collected_at` | `time.Time` | Upload/collection timestamp |
|
||||
| `hardware` | `*HardwareConfig` | All normalized hardware inventory |
|
||||
| `events` | `[]Event` | Diagnostic events from parsers |
|
||||
| `fru` | `[]FRUInfo` | FRU/SDR-derived inventory details |
|
||||
| `sensors` | `[]SensorReading` | Sensor readings |
|
||||
| `raw_payloads` | `map[string]any` | Raw vendor data (e.g. `redfish_tree`) |
|
||||
| Field | Meaning |
|
||||
|------|---------|
|
||||
| `filename` | Original upload name or synthesized live source name |
|
||||
| `source_type` | `archive` or `api` |
|
||||
| `protocol` | `redfish`, `ipmi`, or empty for archive uploads |
|
||||
| `target_host` | Hostname or IP for live collection |
|
||||
| `source_timezone` | Source timezone/offset if known |
|
||||
| `collected_at` | Canonical collection/upload time |
|
||||
| `raw_payloads` | Raw source data used for replay or diagnostics |
|
||||
| `events` | Parsed event timeline |
|
||||
| `fru` | FRU-derived inventory details |
|
||||
| `sensors` | Sensor readings |
|
||||
| `hardware` | Normalized hardware inventory |
|
||||
|
||||
`raw_payloads` is the durable source for offline re-analysis (especially for Redfish).
|
||||
Normalized fields should be treated as derivable output from raw source data.
|
||||
## `HardwareConfig`
|
||||
|
||||
### Hardware sub-structure
|
||||
Main sections:
|
||||
|
||||
```
|
||||
HardwareConfig
|
||||
├── board BoardInfo — server/motherboard identity
|
||||
├── devices []HardwareDevice — CANONICAL INVENTORY (see below)
|
||||
├── cpus []CPU
|
||||
├── memory []MemoryDIMM
|
||||
├── storage []Storage
|
||||
├── volumes []StorageVolume — logical RAID/VROC volumes
|
||||
├── pcie_devices []PCIeDevice
|
||||
├── gpus []GPU
|
||||
├── network_adapters []NetworkAdapter
|
||||
├── network_cards []NIC (legacy/alternate source field)
|
||||
├── power_supplies []PSU
|
||||
└── firmware []FirmwareInfo
|
||||
```text
|
||||
hardware.board
|
||||
hardware.devices
|
||||
hardware.cpus
|
||||
hardware.memory
|
||||
hardware.storage
|
||||
hardware.volumes
|
||||
hardware.pcie_devices
|
||||
hardware.gpus
|
||||
hardware.network_adapters
|
||||
hardware.network_cards
|
||||
hardware.power_supplies
|
||||
hardware.firmware
|
||||
```
|
||||
|
||||
---
|
||||
`network_cards` is legacy/alternate source data.
|
||||
`hardware.devices` is the canonical cross-section inventory.
|
||||
|
||||
## Canonical Device Repository (`hardware.devices`)
|
||||
## Canonical inventory: `hardware.devices`
|
||||
|
||||
`hardware.devices` is the **single source of truth** for hardware inventory.
|
||||
`hardware.devices` is the single source of truth for device-oriented UI and Reanimator export.
|
||||
|
||||
### Rules — must not be violated
|
||||
Required rules:
|
||||
|
||||
1. All UI tabs displaying hardware components **must read from `hardware.devices`**.
|
||||
2. The Device Inventory tab shows kinds: `pcie`, `storage`, `gpu`, `network`.
|
||||
3. The Reanimator exporter **must use the same `hardware.devices`** as the UI.
|
||||
4. Any discrepancy between UI data and Reanimator export data is a **bug**.
|
||||
5. New hardware attributes must be added to the canonical device schema **first**,
|
||||
then mapped to Reanimator/UI — never the other way around.
|
||||
6. The exporter should group/filter canonical records by section, not rebuild data
|
||||
from multiple sources.
|
||||
1. UI hardware views must read from `hardware.devices`
|
||||
2. Reanimator conversion must derive device sections from `hardware.devices`
|
||||
3. UI/export mismatches are bugs, not accepted divergence
|
||||
4. New shared device fields belong in `HardwareDevice` first
|
||||
|
||||
### Deduplication logic (applied once by repository builder)
|
||||
Deduplication priority:
|
||||
|
||||
| Priority | Key used |
|
||||
|----------|----------|
|
||||
| 1 | `serial_number` — usable (not empty, not `N/A`, `NA`, `NONE`, `NULL`, `UNKNOWN`, `-`) |
|
||||
| 2 | `bdf` — PCI Bus:Device.Function address |
|
||||
| 3 | No merge — records remain distinct if both serial and bdf are absent |
|
||||
| Priority | Key |
|
||||
|----------|-----|
|
||||
| 1 | usable `serial_number` |
|
||||
| 2 | `bdf` |
|
||||
| 3 | keep records separate |
|
||||
|
||||
### Device schema alignment
|
||||
## Raw payloads
|
||||
|
||||
Keep `hardware.devices` schema as close as possible to Reanimator JSON field names.
|
||||
This minimizes translation logic in the exporter and prevents drift.
|
||||
`raw_payloads` is authoritative for replayable sources.
|
||||
|
||||
---
|
||||
Current important payloads:
|
||||
- `redfish_tree`
|
||||
- `redfish_fetch_errors`
|
||||
- `source_timezone`
|
||||
|
||||
## Source metadata fields (stored directly on `AnalysisResult`)
|
||||
Normalized hardware fields are derived output, not the long-term source of truth.
|
||||
|
||||
Carried by both `/api/status` and `/api/config`:
|
||||
## Raw export package
|
||||
|
||||
```json
|
||||
{
|
||||
"source_type": "api",
|
||||
"protocol": "redfish",
|
||||
"target_host": "10.0.0.1",
|
||||
"collected_at": "2026-02-10T15:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
Valid `source_type` values: `archive`, `api`
|
||||
Valid `protocol` values: `redfish`, `ipmi` (empty is allowed for archive uploads)
|
||||
|
||||
---
|
||||
|
||||
## Raw Export Package (reopenable artifact)
|
||||
|
||||
`Export Raw Data` does not merely dump `AnalysisResult`; it emits a reopenable raw package
|
||||
(JSON or ZIP bundle) that carries source data required for re-analysis.
|
||||
`/api/export/json` produces a reopenable raw-export artifact.
|
||||
|
||||
Design rules:
|
||||
- raw source is authoritative (`redfish_tree` or original file bytes)
|
||||
- imports must re-analyze from raw source
|
||||
- parsed field snapshots included in bundles are diagnostic artifacts, not the source of truth
|
||||
- raw source stays authoritative
|
||||
- uploads of raw-export artifacts must re-analyze from raw source
|
||||
- parsed snapshots inside the bundle are diagnostic only
|
||||
|
||||
Reference in New Issue
Block a user