34 lines
2.3 KiB
Markdown
34 lines
2.3 KiB
Markdown
# 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`).
|