Employee Data Service

Punkt wejścia Spring Boota. Świadomie bez Locale.setDefault() — to była wcześniejsza wersja poprawki na komunikaty walidacji; wycofana na rzecz beana ograniczonego do samej walidacji (patrz ValidationConfig).

Jedyna bramka autoryzacji. OncePerRequestFilter, działa przed DispatcherServlet — dlatego 401 buduje własny ProblemDetail ręcznie (ale przez wspólny ObjectMapper, nie przez string literal).

if (!MessageDigest.isEqual(expectedApiKey, provided)) {
    // 401 + ProblemDetail przez wstrzyknięty ObjectMapper
}

Jedno miejsce mapujące wyjątki na odpowiedzi HTTP. @RestControllerAdvice z pięcioma handlerami: walidacja → 400, zły JSON/enum → 400, zły typ parametru (np. nie-UUID) → 400, brak rekordu → 404, wszystko inne → 500.

Wymusza angielskie komunikaty walidacji niezależnie od locale hosta. Bean LocalValidatorFactoryBean z owiniętym interpolatorem, który zawsze woła delegata z Locale.ENGLISH.

Prosty, jednozdaniowy wyjątek — konstruktor przyjmuje UUID, buduje komunikat "Employee not found: …". Łapany przez GlobalExceptionHandler → 404.

Serce sekcji bezpieczeństwa. AES-256-GCM: losowy 96-bit nonce na każde wywołanie, wynik = base64(nonce ‖ ciphertext+tag). Klucz z APP_ENCRYPTION_KEY, walidowany przy starcie (musi dekodować się do dokładnie 32 bajtów).

byte[] nonce = new byte[12]; // GCM_NONCE_LENGTH_BYTES
secureRandom.nextBytes(nonce);
cipher.init(ENCRYPT_MODE, key, new GCMParameterSpec(128, nonce));

JPA @Converter — transparentnie szyfruje przy zapisie (convertToDatabaseColumn) i deszyfruje przy odczycie (convertToEntityAttribute). Reszta kodu nie wie, że kolumna jest szyfrowana.

Statyczna funkcja maskująca — zostawia tylko ostatnie 4 cyfry: "***-**-6789". Jedyne miejsce, które konwertuje plaintext SSN na coś, co bezpiecznie trafia do odpowiedzi API.

if (digitsOnly.length() < 4) {
    throw new IllegalArgumentException(...);
}

Encja JPA — anemiczna, mapuje 1:1 na tabelę. id generowane przez Hibernate (GenerationType.UUID), pole ssn z @Convert(SsnAttributeConverter.class).

String ssnForInternalUseOnly() { return ssn; } // package-private

4 endpointy: POST, GET /{id}, GET (paginacja przez Pageable), DELETE /{id}. Cienka warstwa — cała logika w serwisie.

Logika biznesowa + transakcje. create/getById/list/delete — wszystkie cztery w tym samym, spójnym idiomie: findById(...).orElseThrow(...) tam, gdzie trzeba sprawdzić istnienie.

request → encja, encja → response. Jedyne miejsce, które woła SsnMasker.mask(employee.ssnForInternalUseOnly()) — most między domeną a API, gwarantujący brak wycieku plaintextu.

Własny constraint walidacyjny — poza formatem XXX-XX-XXXX sprawdza realne reguły SSA: obszar ≠ 000/666/900–999, grupa ≠ 00, numer seryjny ≠ 0000.

// "900" <= area <= "999" -- bezpieczne leksykograficznie,
// bo regex wcześniej gwarantuje dokładnie 3 cyfry
area.compareTo("900") >= 0

Dolna granica daty urodzenia (1900-01-01 do dziś) — zastępuje samo @Past, które przepuszczało np. rok 1700.

EmployeeRepository — zwykłe JpaRepository<Employee, UUID>, zero customowych metod. Gender — enum (MALE/FEMALE/OTHER/UNSPECIFIED). EmployeeCreateRequest/EmployeeResponse — rekordy DTO; response celowo nie ma pola z pełnym SSN, tylko maskedSsn.

spring.jpa.hibernate.ddl-auto=validate — Hibernate tylko sprawdza mapowanie, nigdy nie modyfikuje schematu; jedyne źródło prawdy to migracja Flyway. Dwie wymagane zmienne: APP_ENCRYPTION_KEY, APP_API_KEY — bez defaultów, brak = fail-fast.