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.

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

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.
GREEN — napisz minimalny kod produkcyjny, który zazielenia test. Nie dodawaj funkcji, których żaden test nie wymaga.
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).

2.3 KiB Raw Permalink Blame History