# Mechanismus: Refresh & Fake-ID

## Problemstellung
Im UI werden häufig neue Objekte in Collections angezeigt, bevor sie persistiert sind. Diese benötigen eine temporäre Identifikation (ID) für Auswahl/Operationen, ohne den Datenbankzustand zu verfälschen.

## Fake-ID Strategie
- Negative Long Werte (< 0) kennzeichnen nicht persistierte Objekte.
- Erzeugung: `AbstractController.createFakeID(Collection<ENT>)`:
  - Startwert -1.
  - Falls bereits negative IDs existieren → Nimmt die kleinste negative und subtrahiert 1.
  - Ergebnis: Sequenz -1, -2, -3 ... (absteigend).

## Persistieren
Vor finalem Speichern (z.B. `SecurityAreaController.save()`):
1. Alle Entities mit `id < 0` → `setId(null)`.
2. `AbstractManager.saveAll()` unterscheidet durch `entity.getId() == null` zwischen Persist und Merge.
3. Datenbank vergibt positive ID (Auto Increment / Sequence).

## Vorteile
- Klare Unterscheidung UI-temporär vs. persistent.
- Verhindert versehentliches Auslösen von Merge bei noch nicht existierenden DB Zeilen.

## Risiken
- Verwechslung negativ gesetzter IDs mit echten IDs (nicht möglich, da DB positive IDs generiert).
- Direkte Verwendung negativer IDs in DB-Operationen (vermeiden: Prüfen auf `id > 0` vor `em.find`).

## Refresh
- Methode `AbstractController.refrehSelected()` (Tippfehler im Namen, historisch) ruft `getManager().refresh(selected)`.
- `AbstractManager.refresh(entity)`:
  - Falls ID null → `save(entity)` (persistiert neues Objekt).
  - `merge` für Managed Zustand und `Hibernate.initialize(entity)` zur Lazy Init.

## Best Practices
- Nach komplexen Änderungen (Add/Remove Child Collections) Refresh durchführen wenn UI weitere Lazy Properties benötigt.
- Beim Klonen persistenter Objekte zuerst DB-Laden → danach Kopie erstellen.

## Potentielle Verbesserungen
- Korrektur Tippfehler `refrehSelected()` → `refreshSelected()` (Refactoring + Suchanpassungen).
- Kennzeichnung Fake-ID generierender Methoden mit JavaDoc für Klarheit.

---
Aktualisiert: 2025-10-20
# MSS Failsafe – Developer Einstieg

Dieses Verzeichnis bündelt technische Instruktionsdateien zur schnelleren Einarbeitung und zur Unterstützung automatischer Code-Generierung.

## Quick Start
1. Java Version: Quell-/Ziellevel im POM: 11 (Property 1.8 ist historisch, der Compiler-Plugin setzt auf 11). Nutze lokal JDK 11.
2. Application Server: Java EE 8 kompatibel (z.B. Payara 5 / WildFly 20 / GlassFish 5). Dependencies `javax.*` statt `jakarta.*`.
3. Build:
   ```cmd
   mvn clean package
   ```
   Ergebnis: `target/mss-1.0-SNAPSHOT.war`.
4. Deployment: WAR in kompatiblen EE 8 Server einspielen. Konfiguriere Datenquelle `pu_person` (JPA Persistence Unit – siehe `@PersistenceContext(name = "pu_person")`).
5. Logging: Log4j2 Konfiguration in `src/main/resources/log4j2.xml`.
6. Frontend: JSF 2.3 + PrimeFaces 11 + PrimeFlex 2.0.

## Wichtigste Schichten
- model: JPA Entities (`AbstractEntity` Basis – enthält ID).
- business: `*Manager` Klassen (Stateless EJBs) kapseln CRUD + Fachlogik.
- controller: View/Request/Session Scoped JSF Backing Beans (Interaktion UI ↔ Business Layer).
- webapp: XHTML Seiten (JSF Components + PrimeFaces).
- resources: Text-/Konfigurationsdateien, Checklisten.

## Kern-Patterns
- Manager erben von `AbstractManager<T>` (generisches CRUD mit `save`, `saveAll`, `remove`, `refresh`).
- Controller erben von `AbstractController<E>` (Message Handling, Fake-ID-Erzeugung für neue (noch nicht persistierte) Entities, PDF Hilfen, Auswahlzustand `selected/created`).
- Negative IDs (< 0) werden als temporäre (noch nicht persistierte) Objekte verwendet – wichtig bei UI-Listen vor Sammel-Speichern.
- Lazy Collections werden vor Nutzung mit `Hibernate.initialize(...)` initialisiert (Refresh/Reload Methoden).

## Erweiterung – Schnellanleitung
1. Neue Entity anlegen (JPA @Entity, extends `AbstractEntity`).
2. Manager erstellen: `@Stateless`, extends `AbstractManager<YourEntity>`, implementiert `getEntityManager()`. Zusätzliche Named Queries in Entity definieren.
3. Controller erstellen: `@Named`, Scope festlegen (`@ViewScoped`, `@SessionScoped`, etc.), extends `AbstractController<YourEntity>`, injiziere Manager mit `@EJB`.
4. XHTML Seite/Fragment erstellen und Controller referenzieren (`#{yourController}`) + PrimeFaces Komponenten.
5. Tests (optional, derzeit kaum vorhanden) – vorschlagen: Architektur-Test + Manager CRUD Test.

## Fragebögen / Sicherheitsbereiche
Ein ausführlicher Workflow liegt in `QUESTIONNAIRE_WORKFLOW.md` und `SECURITY_AREA_DOMAIN.md`.

## PDF-Erzeugung
- Verwendet iText (5.x + 7.x Module). Utilities liegen in `AbstractController` (Tabellen, Kopfzeilen, Seitennummern).
- Logo Pfad `LOGO_PATH = /rundata/logo.png` – stelle sicher, dass Datei beim Deployment verfügbar ist.

## Automatisierte Tools / AI Hinweise
Siehe `AI_INSTRUCTIONS.md` für formatierte Kontextbereitstellung.

## Nächste Verbesserungen (Empfehlungen)
- Konsolidierung auf iText7 (Legacy 5.x entfernen).
- Einheitliche Exception-Strategie (momentan Logging + bool Rückgabe).
- Mehr Unit Tests (Persistenz, Controller Interaktionen via Arquillian / Payara Micro).
- Migrationspfad Richtung Jakarta EE 9+ (Namespace Wechsel).

---
Letzte Aktualisierung: 2025-10-20