semesterprojekt: implement full text adventure (phases 1-7)

Walking skeleton through Swing GUI: YAML-driven world (4 rooms,
4 items, 1 NPC), HashMap command dispatch with parser, three-tier
item hierarchy (readable / switchable / plain), and end-to-end
NPC give/receive flow. 67 tests green.

Semesterprojekt/docs/conventions.md

@@ -0,0 +1,88 @@
+# Konventionen
+
+Sprache, IDs, Package-Struktur, Naming.
+
+## Sprache
+
+- **Code:** Englisch — Klassen, Methoden, Felder, Enums, Package-Namen, Javadoc.
+- **YAML:** Englisch — Keys, IDs, alle Texte (descriptions, dialogue, readText, etc.).
+- **Doku-Prose** (`docs/*.md`): Deutsch — Diskussion mit dem Entwickler, keine Spec für Korrektoren.
+
+## IDs
+
+Slugs, keine UUIDs. Begründung in [item-model.md](item-model.md) und [yaml-schemas.md](yaml-schemas.md).
+
+| Regel | Beispiel | Gegenbeispiel |
+|---|---|---|
+| nur kleinbuchstaben | `kitchen`, `letter` | `Kitchen`, `LETTER` |
+| ASCII, keine Umlaute | `cellar`, `kueche` schlecht | `keller` gut, `küche` schlecht |
+| Mehrwortig: snake_case | `oil_lamp`, `old_man` | `oilLamp`, `old-man`, `oil lamp` |
+| keine führende Ziffer | `key1` | `1key` |
+| nur `[a-z0-9_]` | `key2` | `key#2`, `key@2` |
+
+Regex zur Validierung im `WorldValidator`:
+
+```
+^[a-z][a-z0-9_]*$
+```
+
+Geltungsbereich: id ist eindeutig **innerhalb seiner Entitätsart**. Ein Item und ein NPC dürfen `lamp` heißen (nicht empfohlen, aber technisch erlaubt).
+
+## Package-Struktur
+
+```
+thb.jeanluc.adventure
+├── model
+│   ├── Direction
+│   ├── Room
+│   ├── Player
+│   ├── Npc
+│   └── item              <- eigener Subpackage wegen Hierarchie
+│       ├── Item (abstract)
+│       ├── ReadableItem
+│       ├── SwitchableItem
+│       └── PlainItem
+├── io
+├── command
+├── game
+└── loader
+    └── dto
+```
+
+**Wann ein Subpackage:** wenn eine Klassenfamilie ≥ 3 Klassen umfasst und eine eigene Abstraktion bildet (`item`, evtl. später `command.impl`). Sonst flach lassen.
+
+## Naming
+
+Java-Standard:
+- Klassen: `UpperCamelCase`
+- Methoden, Felder, Parameter: `lowerCamelCase`
+- Konstanten: `UPPER_SNAKE_CASE`
+- Packages: `lowercase`, ohne Underscores wenn möglich
+
+YAML:
+- Keys: `lowerCamelCase` (`startRoom`, `readText`, `initialState`) — passt zu Jackson-Default-Mapping auf Java-Felder
+- IDs: siehe oben
+
+## Javadoc
+
+Pflicht laut Aufgabenstellung **an Klassen, Methoden, und Instanzvariablen**. Auch bei Lombok-Feldern wenn sie `@Getter`-exposed sind.
+
+Keep it sachlich — was tut die Klasse/Methode, nicht wie. Keine Geschichten erzählen.
+
+## Tests
+
+- Unit-Tests pro Domain-Klasse: `RoomTest`, `PlayerTest`, `ItemTest` etc.
+- Integration-Tests für Loader: `WorldLoaderTest` mit `src/test/resources/world/`-Fixtures
+- Naming: `methodName_condition_expectedResult` — z.B. `addExit_withNewDirection_storesNeighbour`
+
+## Lombok-Cheatsheet
+
+| Annotation | Wozu |
+|---|---|
+| `@Getter` | Getter für alle Felder |
+| `@RequiredArgsConstructor` | Konstruktor nur für finals ohne Initializer |
+| `@SuperBuilder` | Builder über Vererbung (statt `@Builder`) |
+| `@Slf4j` | `log`-Field für SLF4J |
+| `@ToString` | Nur wenn aussagekräftig — sonst weglassen |
+
+**Vermeiden:** `@Data` (zu viel auf einmal, generiert `equals/hashCode` was bei Room/Player unerwünscht ist).