Slice 4 (Module 03): Patient discovery API — list/search doctors + upcoming free slots

[mGasiorek998]

What to build

Ship the public read endpoints that Module 04's patient-side discovery UI will consume. No UI in this slice — the PRD assigns the patient-facing pages to Module 04, but the API surface belongs in Module 03 alongside the schema it queries.

• Fill in doctorContract with listDoctors and listUpcomingSlots.
• GET /doctors?search= behind requireAuth() only: returns a flat array of { userId, firstName, lastName, specialization }. Empty or absent search returns all doctors. With search, applies a case-insensitive substring match (Postgres ILIKE '%term%') against any of first_name, last_name, specialization. No pagination.
• GET /doctors/{doctorId}/slots?upcoming=true behind requireAuth() only: returns slots with status='free' and starts_at >= now() UTC, sorted ascending by starts_at. The upcoming=true query param is required for this slice; behaviour without it is undefined and may 400.
• Use case + repository for both, encapsulating the search/filter SQL.

Acceptance criteria

• GET /doctors (no search) returns all doctors as a flat array { userId, firstName, lastName, specialization }.
• GET /doctors?search=KOWAL matches a doctor whose last_name is "Kowalski" (case-insensitive substring).
• GET /doctors?search=cardio matches a doctor whose specialization contains "Cardiology".
• GET /doctors/{doctorId}/slots?upcoming=true excludes slots with starts_at < now() and excludes slots with status booked.
• GET /doctors/{doctorId}/slots?upcoming=true returns slots sorted ascending by starts_at.
• Both endpoints return 401 without a JWT.
• Both endpoints accept a patient JWT and a doctor JWT (any authenticated role).
• pnpm verify exits 0.

User stories covered

• US fix: api-client doubles base URL in fetch call #8: As a patient, I want to browse a list of all registered doctors, so that I can find a doctor to book with.
• US Slice 1 (Module 02): Document upload & list — foundation #9: As a patient, I want to search doctors by name or specialization using a partial, case-insensitive keyword, so that I can quickly narrow the list to relevant specialties.
• US Slice 2 (Module 02): Delete document with atomic cascade #10: As a patient, I want to see the upcoming free slots for a specific doctor, so that I can choose a time that works for me before confirming a booking.
• US Slice 3 (Module 02): Per-doctor sharing management (grant / revoke / state) #11: As any authenticated user, I want the upcoming slots list to exclude past slots and already-booked slots, so that I only see genuinely available times.

Blocked by

• Slice 1 (Module 03): Doctor profile read/update + specialization column #19
• Slice 2a (Module 03): Slot table + list-own + read-only slot management page #20