# Szpitale-graph — instrukcje projektu

Aplikacja Java 21 + Maven + Spring Shell budująca graf szpitali w Neo4j. Architektura warstwowa (`ingest` → canonical JSON → `load`). Szczegóły w [PLAN.md](PLAN.md).

## Proces tworzenia oprogramowania: TDD (obowiązkowy)

Każda zmiana logiki (nowa klasa, metoda, poprawka buga) powstaje w cyklu **red → green → refactor**. Agent NIE pisze kodu produkcyjnego zanim nie istnieje test, który go wymaga.

### Cykl

1. **RED** — napisz test opisujący pożądane zachowanie. Uruchom go i zobacz, że **failuje** (kompiluje się, ale asercja/logika nie przechodzi). Test bez uprzedniej porażki nic nie dowodzi.
2. **GREEN** — napisz **minimalny** kod produkcyjny, który zazielenia test. Nie dodawaj funkcji, których żaden test nie wymaga.
3. **REFACTOR** — posprzątaj kod i test przy zielonym pasku. Po refaktorze testy nadal zielone.

Powtarzaj małymi krokami. Jeden zachowaniowy przyrost = jeden obieg cyklu.

### Zasady

- **Test najpierw.** Bug fix zaczyna się od testu, który reprodukuje buga (RED), dopiero potem poprawka.
- **Testy jednostkowe** (bez Neo4j) dla: normalizacji (`NameNormalizer`, `PartyNormalizer`), deduplikacji (`Deduplicator`), parsowania źródeł (`MarkdownRegistrySource`), serializacji canonical (`CanonicalWriter`/`CanonicalReader`). Szybkie, deterministyczne, bez I/O sieciowego.
- **Testy integracyjne** dla warstwy `load`: Neo4j przez **Testcontainers** (`org.testcontainers:neo4j`, już w `pom.xml`). Sprawdzają idempotencję `MERGE`, constrainty schematu i raporty walidatora.
- Nazwy testów opisują zachowanie: `metoda_warunek_oczekiwanyWynik` (np. `normalize_polishDiacritics_stripped`).
- Testy w `src/test/java`, mirror pakietów z `src/main/java`.
- Zielony build (`mvn test`) jest warunkiem uznania zadania za zrobione. Jeśli testy nie mogą się uruchomić (brak `mvn`/Neo4j), zgłoś to jawnie — nie deklaruj sukcesu.

### Kolejność przy dług technicznym

Istniejący kod produkcyjny powstał bez testów. Przy dotykaniu klasy bez pokrycia: najpierw dopisz **charakteryzujący** test dla aktualnego zachowania (green), potem prowadź zmianę cyklem TDD.

## Build

- `mvn test` — testy; `mvn compile` — kompilacja; `mvn spring-boot:run` — uruchomienie CLI.
- Neo4j lokalnie: `docker compose up -d` (patrz `szpitale-graph/docker-compose.yml`).