fix(GRO-2180): normalize portal appointments API shape so /appointments loads

The /api/portal/appointments endpoint returns ISO startTime/endTime plus
nested pet/service/staff objects, but the portal client Appointment type
expected flat date/time/petName fields. isUpcoming() read appt.date/appt.time
(both undefined), so parseTimeTo24Hour(undefined) threw a TypeError; the
useEffect try/catch set the error state and the success-path-only Book New
button became unreachable.

- Add normalizeAppointment() at the fetch boundary mapping the API shape to the
  flat Appointment shape (derives display date/time from startTime, duration
  from the start/end delta), tolerant of the legacy flat shape.
- Prefer absolute startTime in isUpcoming(); fall back to date/time.
- Harden parseTimeTo24Hour against blank/undefined input (no NaN).
- Add Appointment.startTime/endTime to the type.
- Tests: normalizeAppointment + isUpcoming(startTime) + parseTimeTo24Hour safety.
- Update UAT_PLAYBOOK.md §5.12.2 and new §5.12d regression cases.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

src/portal/sections/Appointments.tsx

@@ -36,6 +36,10 @@ export interface Appointment {
   petId: string;
   serviceId: string;
   groomerId: string | null;
+  // Absolute ISO instants as returned by `/api/portal/appointments`. `date`/`time`
+  // below are the locally-formatted display strings derived from `startTime`.
+  startTime?: string;
+  endTime?: string;
   date: string;
   time: string;
   status: 'scheduled' | 'confirmed' | 'pending' | 'waitlisted' | 'completed' | 'cancelled' | 'no-show';
@@ -91,13 +95,15 @@ export function formatDate(dateStr: string): string {
   });
 }
 
-export function parseTimeTo24Hour(time: string): string {
-  const parts = time.split(' ');
+export function parseTimeTo24Hour(time: string | null | undefined): string {
+  const parts = (time ?? '').split(' ');
   const hoursMinutes = parts[0] ?? '';
   const period = parts[1] ?? '';
   const [hoursStr, minutesStr] = hoursMinutes.split(':');
-  const hours = parseInt(hoursStr ?? '0', 10);
-  const minutes = parseInt(minutesStr ?? '0', 10);
+  // `|| '0'` (not `?? '0'`) so empty strings from blank/undefined input
+  // fall back to 0 rather than parsing to NaN.
+  const hours = parseInt(hoursStr || '0', 10);
+  const minutes = parseInt(minutesStr || '0', 10);
   let hours24 = hours;
   if (period === 'PM' && hours !== 12) hours24 += 12;
   if (period === 'AM' && hours === 12) hours24 = 0;
@@ -106,10 +112,86 @@ export function parseTimeTo24Hour(time: string): string {
 
 export function isUpcoming(appt: Appointment): boolean {
   const now = new Date();
-  const apptDate = new Date(`${appt.date}T${parseTimeTo24Hour(appt.time)}`);
+  // Prefer the absolute ISO `startTime` from the API; fall back to the
+  // locally-formatted date/time pair for already-normalized/legacy shapes.
+  const apptDate = appt.startTime
+    ? new Date(appt.startTime)
+    : new Date(`${appt.date}T${parseTimeTo24Hour(appt.time)}`);
   return apptDate > now && appt.status !== 'cancelled' && appt.status !== 'completed';
 }
 
+// ─── API → UI shape normalization ────────────────────────────────────────────
+// `/api/portal/appointments` returns ISO `startTime`/`endTime` plus nested
+// pet/service/staff objects, NOT the flat `date`/`time`/`petName` shape the
+// portal UI renders. Every field below is optional so the legacy flat shape
+// (used by tests/fixtures) is tolerated unchanged.
+export interface RawApiAppointment {
+  id: string;
+  startTime?: string | null;
+  endTime?: string | null;
+  status: Appointment['status'];
+  confirmationStatus?: Appointment['confirmationStatus'];
+  customerNotes?: string | null;
+  notes?: string | null;
+  pet?: { id?: string | null; name?: string | null; photo?: string | null } | null;
+  service?: { id?: string | null; name?: string | null } | null;
+  staff?: { id?: string | null; name?: string | null } | null;
+  // Legacy / already-flat fields
+  petId?: string;
+  serviceId?: string;
+  groomerId?: string | null;
+  date?: string;
+  time?: string;
+  petName?: string;
+  serviceName?: string;
+  groomerName?: string;
+  duration?: number;
+  price?: number;
+  addOns?: string[];
+}
+
+function toLocalDateString(d: Date): string {
+  const year = d.getFullYear();
+  const month = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+function toLocalTimeString(d: Date): string {
+  return d.toLocaleTimeString('en-US', { hour: 'numeric', minute: '2-digit', hour12: true });
+}
+
+// Maps a raw API appointment into the flat `Appointment` shape the portal
+// renders. Derives display `date`/`time` from the absolute `startTime` and
+// `duration` from the start/end delta. Tolerates the legacy flat shape.
+export function normalizeAppointment(raw: RawApiAppointment): Appointment {
+  const start = raw.startTime ? new Date(raw.startTime) : null;
+  const end = raw.endTime ? new Date(raw.endTime) : null;
+  const derivedDuration =
+    start && end ? Math.round((end.getTime() - start.getTime()) / 60000) : undefined;
+
+  return {
+    id: raw.id,
+    petId: raw.pet?.id ?? raw.petId ?? '',
+    serviceId: raw.service?.id ?? raw.serviceId ?? '',
+    groomerId: raw.staff?.id ?? raw.groomerId ?? null,
+    startTime: raw.startTime ?? undefined,
+    endTime: raw.endTime ?? undefined,
+    date: start ? toLocalDateString(start) : raw.date ?? '',
+    time: start ? toLocalTimeString(start) : raw.time ?? '',
+    status: raw.status,
+    petName: raw.pet?.name ?? raw.petName,
+    serviceName: raw.service?.name ?? raw.serviceName,
+    groomerName: raw.staff?.name ?? raw.groomerName,
+    duration: raw.duration ?? derivedDuration,
+    price: raw.price,
+    notes: raw.notes ?? undefined,
+    customerNotes: raw.customerNotes ?? undefined,
+    addOns: raw.addOns,
+    confirmationStatus: raw.confirmationStatus,
+  };
+}
+
 const STATUS_COLORS: Record<string, string> = {
   confirmed: 'bg-green-100 text-green-700',
   pending: 'bg-amber-100 text-amber-600',
@@ -173,7 +255,8 @@ export const AppointmentsSection: React.FC<AppointmentsSectionProps> = ({ sessio
 
         if (response.ok) {
           const data = await response.json();
-          const fetchedAppointments: Appointment[] = data.appointments || data || [];
+          const rawAppointments: RawApiAppointment[] = data.appointments || data || [];
+          const fetchedAppointments: Appointment[] = rawAppointments.map(normalizeAppointment);
 
           const upcoming = fetchedAppointments.filter((appt) => isUpcoming(appt));
           const past = fetchedAppointments.filter((appt) => !isUpcoming(appt));