# AGENTS.md

Diese Datei beschreibt die Arbeitsregeln fuer Codex und andere Coding-Agenten im gesamten
Repository. Vor einer Aenderung ist zu klaeren, welches Modul und welche Projektgruppe
fachlich verantwortlich sind.

## Projekt

Desktop-Fakturierungsanwendung fuer das Hochschulprojekt SE1, Team 1.

- Java 21, Maven, JUnit 5
- Swing-Oberflaeche mit FlatLaf
- lokale JSON-Persistenz unter `daten/` (nicht versioniert)
- deutsche Bezeichner, Kommentare, UI-Texte und Spezifikationen

## Module und Verantwortungsbereiche

| Bereich | Gruppe | Verantwortung |
|---------|--------|---------------|
| `src/main/java/de/team1/faktura/dokumente/` | A | Dokumentenzyklus, Belegnummern und PDF-Export |
| `src/main/java/de/team1/faktura/produkte/` | B | Produktverwaltung, Nummernvergabe und Loeschsperre |
| `src/main/java/de/team1/faktura/kunden/` | C | Kundenverwaltung, Nummernvergabe und Loeschsperre |
| `src/main/java/de/team1/faktura/gui/` | D | Swing-Oberflaeche, Panels, Dialoge und Wizard |
| `src/main/java/de/team1/faktura/gemeinsam/` | alle | EreignisBus, Persistenzhilfe, CSV und Exceptions |

Tests liegen spiegelbildlich unter `src/test/java/de/team1/faktura/`. Pflichtenhefte und
Diagramme der Gruppen liegen unter `dokumentation/anforderungen/` beziehungsweise
`dokumentation/diagramme/`.

Agenten sollen Modulgrenzen respektieren und nur die fuer die Aufgabe erforderlichen
Bereiche aendern. Gruppenuebergreifende Aenderungen sind erlaubt, wenn sie fuer eine
Schnittstelle oder Integration notwendig sind; Auswirkungen auf alle betroffenen Module
muessen dann mit Tests abgesichert werden. Lastenheft, Modultestplan, Project Charter und
Praesentation nur bearbeiten, wenn sie ausdruecklich Teil der Aufgabe sind.

## Allgemeine Entwicklungsregeln

- Bestehende Klassen, Schnittstellen, Repositories und Muster bevorzugen.
- Abhaengigkeiten werden in `Main.java` manuell verdrahtet; kein DI-Framework ergaenzen.
- Der `EreignisBus` ist der vorhandene Mechanismus fuer Aktualisierungen nach
  Datenveraenderungen.
- Persistenz erfolgt ueber die vorhandenen Repository-Schnittstellen und JSON-
  Implementierungen.
- Keine aufgabenfremden Refactorings, Umbenennungen oder Formatierungsaenderungen
  mitziehen.
- Neue Logik mit fokussierten JUnit-Tests absichern.

## Build und Tests

Der Maven-Wrapper ist nicht ausfuehrbar eingecheckt. Deshalb ueber die Shell starten:

```bash
sh mvnw compile
sh mvnw test
sh mvnw test -Dtest=NameDerTestklasse
sh mvnw test -Dtest=NameDerTestklasse#nameDerTestmethode
sh mvnw package
java -jar target/fakturierung-1.0.0.jar
```

Zunaechst die passende modulbezogene Testklasse ausfuehren, vor Commit oder Push den
vollstaendigen Testlauf starten. Neue Logik mit Tests auf der niedrigsten sinnvollen Ebene
absichern.

## Dokumentation und Diagramme

Markdown und PDF werden gemeinsam versioniert. Pflichtenhefte aus dem
Dokumentationsordner bauen, damit die relativen Diagrammpfade stimmen. Beispiel:

```bash
cd dokumentation/anforderungen
pandoc EINGABE.md -o AUSGABE.pdf --pdf-engine=tectonic
```

PlantUML aus dem Repository-Root rendern:

```bash
java -jar tools/plantuml.jar -tpng \
  dokumentation/diagramme/DATEI.puml
```

Nach Dokumentaenderungen die erzeugte PDF visuell pruefen. Diagramme duerfen nicht
abgeschnitten oder unlesbar klein sein. Quellen (`.md`, `.puml`) und erzeugte Artefakte
(`.pdf`, `.png`) konsistent aktualisieren.

## Git und Zusammenarbeit

- Vor Aenderungen `git status` und den aktuellen Remote-Stand pruefen.
- Vorhandene fremde oder lokale Aenderungen niemals verwerfen oder ueberschreiben.
- Nur aufgabenbezogene Dateien stagen; insbesondere `.DS_Store`, `target/` und `daten/`
  nicht committen.
- Vor Commit den Diff und `git diff --check` pruefen.
- Commit und Push nur nach ausdruecklicher Freigabe des Nutzers.
- Vor einem Push erneut synchronisieren und sicherstellen, dass alle Tests erfolgreich
  sind.