62 lines
2.3 KiB
Markdown
62 lines
2.3 KiB
Markdown
# Data Model And Migration Boundaries
|
|
|
|
## Naming Model
|
|
|
|
- Internal canonical naming uses `Machine` and `Part`.
|
|
- API/UI compatibility keeps `asset` and `component` terminology where already exposed.
|
|
- In domain aliases:
|
|
- `type Asset = Machine`
|
|
- `type Component = Part`
|
|
|
|
## Core Persistence Areas
|
|
|
|
- Asset registry: `machines`
|
|
- Component registry: `parts`
|
|
- Installations: `installations`
|
|
- Observations: `observations`
|
|
- Timeline: `timeline_events`
|
|
- Failures: `failure_events`
|
|
- Asset firmware state: `machine_firmware_states`
|
|
- Component history (canonical): `component_change_events`, `component_state_snapshots`
|
|
- Asset history (canonical): `asset_change_events`, `asset_state_snapshots`
|
|
- History jobs/audit: `history_recompute_jobs`, `history_admin_audit`
|
|
|
|
Out of active model:
|
|
- `projects` is legacy and not used by runtime handlers/contracts.
|
|
|
|
## Migration Policy
|
|
|
|
- Migrations are stored in `migrations/`.
|
|
- Schema migrations are applied at startup.
|
|
- Legacy entities removed in migration `0016_remove_legacy_features` remain out of active scope.
|
|
- History architecture was introduced in migration `0017_history_core`.
|
|
|
|
## Canonical State Model (History-First)
|
|
|
|
- `parts` and `machines` are current-state projections optimized for reads.
|
|
- `component_change_events` / `asset_change_events` are canonical state-change logs.
|
|
- `component_state_snapshots` / `asset_state_snapshots` store full after-state snapshots for each state-changing event.
|
|
- `timeline_events`, `installations`, `failure_events`, and `machine_firmware_states` are projections and may be rebuilt from history.
|
|
|
|
## History Event Storage Rules
|
|
|
|
- History events are versioned per entity (`version` is monotonic per component/asset).
|
|
- State-changing writes persist:
|
|
1. change event
|
|
2. after-state snapshot
|
|
3. projection updates (`parts` / `machines` and related projections)
|
|
4. timeline projection rows
|
|
- History event deletion is soft-delete (`is_deleted`) for normal user/admin flow.
|
|
- Hard restore is destructive for future history rows and is audited in `history_admin_audit`.
|
|
|
|
## Timeline Projection Linkage
|
|
|
|
`timeline_events` includes logical linkage back to history:
|
|
|
|
- `logical_entity_type`
|
|
- `logical_event_id`
|
|
- `correlation_id`
|
|
- `is_deleted`
|
|
|
|
This linkage is required for recompute, rollback/delete propagation, and paired asset/component timeline rendering.
|