Asset-Lebenszyklus & Tracking-Modi

Das Asset-Modell unterscheidet zwei Dinge: den Tracking-Modus des Asset-Typs (PERSON / LOCATION / CONSUMABLE) und den Lebenszyklus-Status des einzelnen Assets. Der Modus bestimmt den Anker (Person oder Standort) und welche Aktionen möglich sind; der Status beschreibt den aktuellen Lebenszyklus-Zustand. Bei jedem Schreibvorgang prüft der Server, dass Modus, Status und Anker zueinander passen. Diese Seite ist die konzeptionelle Grundlage; die konkreten Endpunkte stehen in der Assets API.

Tracking-Modi (AssetType.trackingMode)

Der Modus wird am Asset-Typ festgelegt und gilt für alle Assets dieses Typs. Er bestimmt, ob es sich um Verbrauchsmaterial handelt und ob Assets an Personen oder an Standorte gebunden werden. Solange der Typ keine Assets hat, ist der Modus frei änderbar; danach antwortet die API mit HTTP 409.

Modus	Anker	User erlaubt?	Ausgabe-Weg	Besonderheit
PERSON	User	✅	Checkout / Handover	Unikat; locationId zusätzlich möglich (Lager-/Büroort)
LOCATION	Standort	❌ nie	Install / Deinstall	kein Handover (Standort kann nicht bestätigen)
CONSUMABLE	Menge	❌ nie	Mengen-Zuweisung (ConsumableAssignment)	reduzierte Statusmenge; keine CMDB-Relations/Handover; immer standalone

Standort ≠ „installiert": Ein AVAILABLE-Asset darf einen Standort (Lagerort) haben. „Installiert" ist der Status IN_USE, nicht „hat eine locationId".

Status-Taxonomie (11 Status)

Jedes Asset hat genau einen der folgenden 11 Status.

Status	Bedeutung	User erlaubt?	typischer Anker
ORDERED	bestellt, nicht geliefert	❌	—
RECEIVED	geliefert, noch nicht einsatzbereit	❌	—
AVAILABLE	verfügbar/einsatzbereit (Lager), frei zuweisbar	❌	optional locationId
RESERVED	vorgemerkt — noch keine Ausgabe („reserviert für X" ist fachlich PENDING_ACCEPTANCE)	❌	—
PENDING_ACCEPTANCE	Personen-Handover läuft, Bestätigung offen	✅ (recipient)	User
IN_USE	in Betrieb — PERSON: beim User / LOCATION: am Standort installiert	modus-abhängig	User oder Standort
MAINTENANCE	in Wartung/Reparatur — Anker kann bleiben	ja (behält User)	evtl. User
RETURN_PENDING	Rückgabe läuft, User hat es noch, wartet auf IT	✅ (User)	User
RETIRED	außer Betrieb (reaktivierbar)	❌	—
LOST	verloren/gestohlen (Pflicht-Grund)	❌	locationId bleibt (letzter Ort)
DISPOSED	entsorgt (final)	❌	—

Status-Gruppen und ihre Regeln

Gruppe	Mitglieder	Zweck
Ohne Benutzer	ORDERED, RECEIVED, AVAILABLE, RESERVED, RETIRED, LOST, DISPOSED	kein User erlaubt
Anker erforderlich	IN_USE, PENDING_ACCEPTANCE, RETURN_PENDING	mind. ein Anker (User/Standort)
Ausgabe möglich aus	AVAILABLE, RESERVED, MAINTENANCE	Ausgangsstatus für Ausgabe/Installation
Rückgabe-Ziel	AVAILABLE, MAINTENANCE, RETIRED	Zielstatus bei Rücknahme (Checkin/confirmReturn)
Außer Betrieb	DISPOSED, RETIRED, LOST	keine neuen Lizenz-/Vertrags-Verknüpfungen; die Zuweisung muss aufgehoben sein
Begründung erforderlich	LOST	Pflicht-Kommentar (statusNote)
Verbrauchsmaterial	ORDERED, RECEIVED, AVAILABLE, RETIRED, DISPOSED	erlaubte Status für CONSUMABLE-Typen
Manuell setzbar	9 (alle außer PENDING_ACCEPTANCE, RETURN_PENDING)	per Formular/Update/Bulk wählbar
Per Bulk setzbar	ORDERED, RECEIVED, AVAILABLE, RESERVED, MAINTENANCE, RETIRED, DISPOSED	per Bulk setzbar; nicht enthalten sind IN_USE (braucht ein Übergabeprotokoll) und LOST (braucht eine Begründung)
Endstatus	DISPOSED	keine weiteren Übergänge

MAINTENANCE gehört bewusst weder zu „Ohne Benutzer" noch zu „Anker erforderlich": ein PERSON-Gerät in Wartung behält seinen User, ein LOCATION-Gerät seinen Standort. PENDING_ACCEPTANCE und RETURN_PENDING entstehen nur durch Aktionen — sie stehen nicht im manuellen Status-Dropdown, sondern werden ausschließlich über Übergabe und Rückgabe erreicht. IN_USE lässt sich manuell setzen (z. B. „Wartung beenden" für ein Gerät, das seinen User behalten hat); eine neue Zuweisung läuft dabei aber nur über Ausgabe, Installation oder Übergabe (siehe Regel unten).

Anker-Regeln

Der Server prüft bei jedem Schreibvorgang (Anlegen, Ändern, Bulk sowie Ausgabe, Rücknahme, Installation, Deinstallation, Übergabe) den resultierenden Zustand. Die erste verletzte Regel wird mit HTTP 400 und dem folgenden Fehlercode gemeldet:

Regel	Bedingung	Fehlercode
Consumable ohne User	CONSUMABLE ⟹ assignedToId == null	CONSUMABLE_NO_DIRECT_ASSIGNEE
Consumable-Status	CONSUMABLE ⟹ status ∈ {ORDERED, RECEIVED, AVAILABLE, RETIRED, DISPOSED}	CONSUMABLE_INVALID_STATUS
LOCATION ohne User	LOCATION ⟹ assignedToId == null	LOCATION_ASSET_CANNOT_HAVE_USER
Status ohne Benutzer	Status der Gruppe „Ohne Benutzer" ⟹ kein User	ASSET_STATUS_ASSIGNED_CONFLICT
Anker-Pflicht	status ∈ {IN_USE, PENDING_ACCEPTANCE, RETURN_PENDING} ⟹ User und/oder Standort	ASSET_STATUS_NEEDS_ANCHOR
PERSON strikt	PERSON ∧ status ∈ {IN_USE, PENDING_ACCEPTANCE, RETURN_PENDING} ⟹ User (Standort reicht nicht)	PERSON_ASSET_NEEDS_USER
Notiz-Pflicht	status = LOST ⟹ Kommentar	ASSET_LOST_REQUIRES_NOTE

Flow-Only-Regel: Ein PATCH /api/assets/:id darf assignedToId nicht im selben Aufruf mit dem Übergang nach IN_USE ändern → ASSET_ASSIGN_VIA_FLOW_ONLY. Zuweisung läuft ausschließlich über Checkout/Handover/Install. (Ein IN_USE→IN_USE-Besitzerwechsel und status-only-Änderungen bleiben erlaubt.)

Übergangsmatrix

Unikate (PERSON/LOCATION):

Von	Nach
ORDERED	RECEIVED, DISPOSED
RECEIVED	AVAILABLE, MAINTENANCE, DISPOSED
AVAILABLE	RESERVED, PENDING_ACCEPTANCE, IN_USE, MAINTENANCE, RETIRED, LOST, DISPOSED
RESERVED	AVAILABLE, PENDING_ACCEPTANCE, IN_USE, LOST
PENDING_ACCEPTANCE	IN_USE, AVAILABLE
IN_USE	AVAILABLE, RETURN_PENDING, MAINTENANCE, RETIRED, LOST, DISPOSED
MAINTENANCE	AVAILABLE, IN_USE, PENDING_ACCEPTANCE, RETURN_PENDING, RETIRED, LOST, DISPOSED
RETURN_PENDING	AVAILABLE, MAINTENANCE, RETIRED, IN_USE
RETIRED	AVAILABLE, DISPOSED
LOST	AVAILABLE, DISPOSED
DISPOSED	— (terminal)

Verbrauchsmaterial (CONSUMABLE) — reduzierte Matrix:

Von	Nach
ORDERED	RECEIVED, DISPOSED
RECEIVED	AVAILABLE, DISPOSED
AVAILABLE	RETIRED, DISPOSED
RETIRED	AVAILABLE, DISPOSED
DISPOSED	— (terminal)

Die drei Lebenszyklen

PERSON — Anker = User

• Direkt-Checkout: → IN_USE + User, sofort, CHECKOUT_DIRECT-Protokoll. Externe Empfänger: User anlegen + Mail. Kein Bestätigungsschritt.
• Handover mit Bestätigung: → PENDING_ACCEPTANCE + Recipient + Mail; Accept → IN_USE; Reject/Cancel → Revert auf Vorzustand.
• Rücknahme: Checkin / confirmReturn → AVAILABLE | MAINTENANCE | RETIRED, User geleert.

LOCATION — Anker = Standort (kein Handover)

• Installieren: → IN_USE + locationId (kein User), deployedAt gesetzt. Direkte IT-Aktion + Activity-Log.
• Deinstallieren: → AVAILABLE | MAINTENANCE, locationId geleert (Historie im Log), deployedAt geleert. Option keepLocation lässt den Standort stehen.

CONSUMABLE — Menge

Der Status hängt nicht an einem Anker: i. d. R. AVAILABLE, dazu quantity und Mengen-Zuweisungen (ConsumableAssignment, an einen User ODER einen Standort). Reduzierte Statusmenge, kein Handover, keine CMDB-Relations.

Feld-Wahrheitstabelle (was jede Aktion setzt/leert)

Aktion	status	assignedToId	locationId	deployedAt	Protokoll
Direkt-Checkout (PERSON)	IN_USE	→ User	—	→ now	CHECKOUT_DIRECT; Mail extern
Handover erstellen	PENDING_ACCEPTANCE	→ recipient	—	—	Mail an Empfänger
Handover Accept	IN_USE	(bleibt)	—	→ now	Mail an Initiator
Install (LOCATION)	IN_USE	null	→ Standort	→ now	Activity
Checkin / confirmReturn	AVAILABLE|MAINTENANCE|RETIRED	→ null	(bleibt)	→ null	RETURN; Mail
Deinstall (LOCATION)	AVAILABLE|MAINTENANCE	null	→ null	→ null	Activity
Wartung setzen	MAINTENANCE	unverändert	unverändert	unverändert	Activity (statusNote optional)
Verloren melden	LOST	→ null	bleibt (letzter Ort)	→ null	Activity (statusNote Pflicht)
Retire / Dispose	RETIRED / DISPOSED	→ null	bleibt	(retiredAt/disposedAt)	Activity; blockt bei aktiven Vertrags-/Lizenz-Links

Felder (API)

AssetType

Feld	Typ	Beschreibung
trackingMode	Enum (Default PERSON)	PERSON | LOCATION | CONSUMABLE. Unveränderlich, sobald der Typ Assets hat (sonst 409).
standalone	Boolean (Default true)	false = Einbau-Komponente (z.B. RAM/SSD): keine eigenständige Ausgabe/Handover, folgt dem Container via Co-Move. CONSUMABLE ist immer standalone.
requiresConfirmation	Boolean (Default false)	Handover mit Empfänger-Bestätigung als Default für diesen Typ.
hasTypePermissions	Boolean	Typ-Sperre: für Assets dieses Typs gelten nur die typbezogenen Berechtigungen (siehe Permissions).

Asset

Feld	Typ	Beschreibung
statusNote	String? (Text)	Grund/Kommentar des aktuellen Status. Pflicht bei LOST, optional bei RESERVED/MAINTENANCE; beim Status-Wechsel ersetzt/geleert. Wird im Overview-Tab angezeigt und koexistiert mit dem Handover-damageReport (getrennte Fakten).
quantity	Int (Default 1)	Menge — nur bei CONSUMABLE-Typ relevant.
deployedAt	DateTime?	Zeitpunkt der Inbetriebnahme; außerhalb aktiver Zustände geleert.

Verwandte Dokumentation