pi_mcps/java/mss-failsafe/docs/AI_INSTRUCTIONS.md

AI Instruktionen für Code-Generierung

Ziel: Ein konsistenter Kontext für zukünftige automatische Ergänzungen.

Projekt-Kurzprofil

• Typ: Java EE 8 (javax), WAR, JSF + PrimeFaces, Hibernate JPA.
• Java Version: 11 (Compiler Plugin).
• Schichten: Model (Entities), Business (Manager), Controller (JSF Beans), View (XHTML).

Wichtige Basisklassen

• AbstractEntity: Basisklasse aller Entities (enthält ID – Details nicht gezeigt, aber zentral).
• AbstractManager<T>: Generisches CRUD mit save, saveAll, etc.
• AbstractController<E>: UI State & Utilities.

Konventionen (Kurz)

• Neue Entities: extend AbstractEntity, Named Queries definieren.
• Neue Manager: @Stateless, extends AbstractManager<Entity>, implementiert getEntityManager().
• Neue Controller: @Named, Scope Annotation (@ViewScoped etc.), extends AbstractController<Entity>, implementiert getManager().
• Temporäre (nicht persistierte) Objekte: negative ID (Fake) bis finalem Speichern.

CRUD Muster (Beispiel)

@Stateless
public class ExampleEntityManager extends AbstractManager<ExampleEntity> {
    @PersistenceContext(name = "pu_person") EntityManager em;
    public ExampleEntityManager(){ super(ExampleEntity.class); }
    @Override protected EntityManager getEntityManager(){ return em; }
}

Typische Aufgaben für Generierung

1. Neue Domain + Entity + Manager + Controller + XHTML.
2. PDF-Ausgabe Erweiterung.
3. Batch-Speichern mehrerer neuer Entities.
4. Klon-Operationen: Copy-Konstruktor nutzen, Child-IDs auf null setzen, Referenzen neu knüpfen.
5. Fragebogen-Workflow: add/remove (siehe QUESTIONNAIRE_WORKFLOW.md).

Qualitätssicherung

• Nach Code-Erzeugung: Prüfe Kompilierung (mvn -q test / package).
• Sicherstellen: Keine direkten System.out Prints in Produktionscode.
• Logging: LOGGER.error(e) bei Exceptions.

Häufige Edge Cases

• Null Checks vor Persist/Remove.
• Negative ID Objekte dürfen nicht direkt gelöscht (erst persistieren oder aus Collection entfernen).
• Lazy Collections müssen initialisiert vor Iteration (via refresh oder Hibernate.initialize).

Verbesserungsvorschläge (safe additions)

• Service Layer Einführen (wenn Logik Manager übersteigt).
• Bean Validation (@NotNull, @Size) auf Entities.
• Einheitliche Exception Klasse.

Generierungs-Präferenzen

• Bevorzugt vorhandene Muster exakt replizieren.
• Keine neuen Frameworks ohne Bedarf.
• Code kommentieren nur bei komplexer Logik.

Anti-Pattern vermeiden

• Business Logik direkt im Controller.
• Duplizierte Query Strings ohne Named Query.

---

Letzte Aktualisierung: 2025-10-20