10. Alarm-Dienst

client.alarm() ist der Zugriffspunkt. Es stehen zwei Funktionen zur Verfügung: Einzelabfrage und Abfrage der jüngsten Alarmereignisse. Werden detaillierte Statistiken oder CRUD-Operationen auf der Alarmkonfiguration (Config) benötigt, kann das Daten-Gateway direkt verwendet werden.

9.1 Methodenübersicht

Methode	Rückgabetyp	HTTP	Endpunkt
get(alarm_seq)	AlarmResponseV5 oder null	GET	/api/v5/alarm/{seq}
list(limit)	List<AlarmResponseV5>	GET	/api/v5/alarm?limit=...

limit ≤ 1000 empfohlen. Werden mehr Daten benötigt, empfiehlt sich die direkte Abfrage über das Daten-Gateway.

9.2 AlarmResponseV5 DTO

Enthält den Alarmdatensatz selbst sowie das JOIN-Ergebnis zur Position (tag/opc/site).

Felder des Alarmdatensatzes

Feld	Typ	Beschreibung
alarm_seq	long	Alarmsequenz (PK)
alarm_config_id	String	ID der Alarmkonfiguration
priority	String	Priorität (HI_HI, HI, LO, LO_LO, TRIP)
description	String	Alarmmeldung
is_on	String	Aktuell aktiv (Y/N)
is_read	String	Gelesen (Y/N)
on_timestamp	long	Auftrittszeitpunkt (Millisekunden)
off_timestamp	long	Rücksetzzeitpunkt (0 = nicht zurückgesetzt)
on_duration	long	Dauer (Millisekunden)

Positions-JOIN-Felder (in der list-Antwort enthalten)

Feld	Beschreibung
tag_id, tag_name, tag_description	Tag-Informationen
opc_id, opc_name	OPC-Informationen
site_id, site_name	Site-Informationen
tag_location	Asset-Pfad als Zeichenkette (SITE > AREA > LINE > EQUIPMENT)

Bei der Einzelabfrage get() wird häufig nur der mm_alarm-Datensatz gefüllt, während die JOIN-Felder null sind. Für die Anzeige in der UI wird empfohlen, das Ergebnis von list() zu verwenden.

9.3 Alarmprioritäten

Code	Bedeutung	Übliche Farbe
HI_HI	Gefahr (Critical)	Rot
HI	Warnung (Warning)	Orange
LO	Information (Info)	Gelb
LO_LO	Rückkehr (Recovery)	Blau
TRIP	Trip (Zwangsabschaltung)	Schwarz

9.4 Anwendungsbeispiele

Liste der jüngsten Alarme

import java.util.List;
import plantpulse.api.v5.dto.response.AlarmResponseV5;

List<AlarmResponseV5> alarms = client.alarm().list(50);
for (AlarmResponseV5 a : alarms) {
    System.out.printf("[%s] %s - %s (%s)%n",
        a.getPriority(),
        a.getSite_name(),
        a.getDescription(),
        a.getTag_location());
}

Beispielausgabe:

[HI_HI] 대전공장 - Spindle 온도 임계치 초과 (SITE_DJ > A_0001 > L_0001 > CNC #1)
[HI]    대전공장 - 압력 상한 (SITE_DJ > A_0001 > L_0001 > Press #2)

Einzelabfrage

AlarmResponseV5 alarm = client.alarm().get(12345L);
if (alarm != null) {
    System.out.println("발생 시각: " + alarm.getOn_timestamp());
    System.out.println("우선순위: " + alarm.getPriority());
    System.out.println("지속 시간: " + alarm.getOn_duration() + " ms");
}

Nur aktive Alarme filtern (clientseitig)

V5 unterstützt keine serverseitige Filterung nach aktiven Alarmen, daher erfolgt dies clientseitig.

import java.util.stream.Collectors;

List<AlarmResponseV5> active = client.alarm().list(500).stream()
        .filter(a -> "Y".equals(a.getIs_on()))
        .collect(Collectors.toList());

System.out.println("현재 활성 알람: " + active.size() + "건");

Gruppierung nach Site

import java.util.Map;
import java.util.stream.Collectors;

Map<String, Long> bySite = client.alarm().list(1000).stream()
        .filter(a -> "Y".equals(a.getIs_on()))
        .collect(Collectors.groupingBy(
                AlarmResponseV5::getSite_id,
                Collectors.counting()));

bySite.forEach((siteId, count) ->
    System.out.printf("%s: %d건%n", siteId, count));

Anzahl nach Priorität

Map<String, Long> byPriority = client.alarm().list(1000).stream()
        .collect(Collectors.groupingBy(
                AlarmResponseV5::getPriority,
                Collectors.counting()));

9.5 Einsatzszenarien

Szenario — Echtzeit-Alarm-Dashboard

while (running) {
    List<AlarmResponseV5> alarms = client.alarm().list(100);

    long critical = alarms.stream()
            .filter(a -> "Y".equals(a.getIs_on()))
            .filter(a -> "HI_HI".equals(a.getPriority()))
            .count();

    updateDashboard(alarms, critical);
    Thread.sleep(1_000);
}

Szenario — Nur Alarme einer bestimmten Anlagenlinie

String targetLine = "SITE_DJ > A_0001 > L_0001";

List<AlarmResponseV5> lineAlarms = client.alarm().list(500).stream()
        .filter(a -> a.getTag_location() != null
                  && a.getTag_location().startsWith(targetLine))
        .collect(Collectors.toList());

Nächste Schritte

• Tag-Dienst — Alarmschwellenwerte über patchAlarm festlegen
• Path-Dienst — Baumpfad des Assets, an dem der Alarm aufgetreten ist