feat: live queue sync — start/end/extend appointments, real-time patient notifications

database/apply_schema.js

@@ -272,6 +272,37 @@ async function applySchema() {
         console.log(`[migration] ${tableName} table created.`);
       }
     }
+
+    // ── Migration: live queue columns on appointments ──────────────────────
+    const queueColumns = [
+      { columnName: 'started_at',    definition: 'DATETIME NULL DEFAULT NULL', after: 'updated_at' },
+      { columnName: 'ended_at',      definition: 'DATETIME NULL DEFAULT NULL', after: 'started_at' },
+      { columnName: 'extra_minutes', definition: 'INT NOT NULL DEFAULT 0',     after: 'ended_at'   },
+    ];
+    for (const col of queueColumns) {
+      await ensureColumnExists({ tableName: 'appointments', ...col });
+    }
+
+    // ── Migration: doctor_queue_status table ──────────────────────────────
+    const [queueStatusTableRows] = await connection.query(`
+      SELECT COUNT(*) AS total
+      FROM information_schema.TABLES
+      WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'doctor_queue_status'
+    `);
+    if (Number(queueStatusTableRows[0].total || 0) === 0) {
+      await connection.query(`
+        CREATE TABLE IF NOT EXISTS doctor_queue_status (
+          id            INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+          doctor_id     VARCHAR(10) NOT NULL,
+          queue_date    DATE        NOT NULL,
+          current_serial INT        NOT NULL DEFAULT 0,
+          is_active     TINYINT(1)  NOT NULL DEFAULT 0,
+          updated_at    DATETIME    NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+          UNIQUE KEY uq_doctor_queue (doctor_id, queue_date)
+        ) ENGINE=InnoDB
+      `);
+      console.log('[migration] doctor_queue_status table created.');
+    }
   } finally {
     await connection.end();
   }

src/routes/appointments.routes.js

@@ -10,6 +10,10 @@ const {
   rescheduleAppointment,
   respondToRescheduleRequest,
   updateAppointmentStatus,
+  startAppointment,
+  endAppointment,
+  extendAppointment,
+  getQueueStatus,
 } = require('../services/appointments.service');
 const { sendSuccess } = require('../utils/apiResponse');
 
@@ -125,4 +129,56 @@ router.patch('/:appointmentId/reschedule-request/respond', requireAuth('doctor')
   });
 });
 
+// ── Live Queue ─────────────────────────────────────────────────────────────
+
+// Doctor starts an appointment (sets started_at, bumps queue serial, pushes patients)
+router.post('/:appointmentId/start', requireAuth('doctor'), async (req, res) => {
+  const appointment = await startAppointment({
+    appointmentId: Number(req.params.appointmentId),
+    doctorId: req.auth.userIdentifier,
+  });
+
+  return sendSuccess(res, {
+    message: 'Appointment started.',
+    data: appointment,
+  });
+});
+
+// Doctor ends an appointment (sets ended_at, marks completed)
+router.post('/:appointmentId/end', requireAuth('doctor'), async (req, res) => {
+  const appointment = await endAppointment({
+    appointmentId: Number(req.params.appointmentId),
+    doctorId: req.auth.userIdentifier,
+  });
+
+  return sendSuccess(res, {
+    message: 'Appointment ended.',
+    data: appointment,
+  });
+});
+
+// Doctor extends an appointment by N minutes → push all later patients
+router.post('/:appointmentId/extend', requireAuth('doctor'), async (req, res) => {
+  const appointment = await extendAppointment({
+    appointmentId: Number(req.params.appointmentId),
+    doctorId: req.auth.userIdentifier,
+    addMinutes: req.body.addMinutes,
+  });
+
+  return sendSuccess(res, {
+    message: `Appointment extended by ${req.body.addMinutes} minute(s).`,
+    data: appointment,
+  });
+});
+
+// Get live queue status — usable by both patient and doctor (no auth required for polling)
+router.get('/queue-status', async (req, res) => {
+  const { doctorId, date } = req.query;
+  if (!doctorId || !date) {
+    return sendSuccess(res, { message: 'doctorId and date are required.', data: null });
+  }
+  const status = await getQueueStatus({ doctorId: String(doctorId).trim().toUpperCase(), date: String(date) });
+  return sendSuccess(res, { message: 'Queue status fetched.', data: status });
+});
+
 module.exports = router;

src/services/appointments.service.js

@@ -20,6 +20,9 @@ const APPOINTMENT_SELECT = `
     a.serial_number,
     a.status,
     a.notes,
+    a.started_at,
+    a.ended_at,
+    a.extra_minutes,
     a.created_at,
     a.updated_at,
     rr.id AS reschedule_request_id,
@@ -545,6 +548,252 @@ async function respondToRescheduleRequest({ appointmentId, doctorId, response })
   return appointment;
 }
 
+// ── Parse "HH:MM AM/PM" → minutes since midnight ─────────────────────────────
+function timeSlotToMinutes(slot) {
+  const match = String(slot || '').match(/^(\d{1,2}):(\d{2})\s*(AM|PM)$/i);
+  if (!match) return 0;
+  let h = parseInt(match[1], 10);
+  const m = parseInt(match[2], 10);
+  const meridiem = match[3].toUpperCase();
+  if (meridiem === 'PM' && h !== 12) h += 12;
+  if (meridiem === 'AM' && h === 12) h = 0;
+  return h * 60 + m;
+}
+
+function minutesToTimeSlot(minutes) {
+  const h = Math.floor(minutes / 60);
+  const m = minutes % 60;
+  const meridiem = h < 12 ? 'AM' : 'PM';
+  const displayH = h === 0 ? 12 : h > 12 ? h - 12 : h;
+  return `${String(displayH).padStart(2, '0')}:${String(m).padStart(2, '0')} ${meridiem}`;
+}
+
+// ── Start an appointment (doctor marks it "in progress") ─────────────────────
+async function startAppointment({ appointmentId, doctorId }) {
+  const { createInAppNotification } = require('./notifications.service');
+  const today = new Date().toISOString().slice(0, 10);
+
+  const info = await withTransaction(async (connection) => {
+    const [apptRows] = await connection.execute(
+      `SELECT id, doctor_id, patient_phone, appointment_date, time_slot, serial_number, status
+       FROM appointments WHERE id = ? AND doctor_id = ? LIMIT 1 FOR UPDATE`,
+      [appointmentId, doctorId],
+    );
+    if (apptRows.length === 0) throw new HttpError(404, 'Appointment not found.', 'APPOINTMENT_NOT_FOUND');
+
+    const appt = apptRows[0];
+    if (appt.status === 'cancelled') throw new HttpError(400, 'Cannot start a cancelled appointment.', 'APPOINTMENT_CANCELLED');
+    if (appt.status === 'completed') throw new HttpError(400, 'Appointment already completed.', 'APPOINTMENT_COMPLETED');
+
+    // Mark started
+    await connection.execute(
+      `UPDATE appointments SET started_at = NOW(), status = 'confirmed', updated_at = NOW() WHERE id = ?`,
+      [appointmentId],
+    );
+
+    // Upsert queue status
+    await connection.execute(
+      `INSERT INTO doctor_queue_status (doctor_id, queue_date, current_serial, is_active)
+       VALUES (?, ?, ?, 1)
+       ON DUPLICATE KEY UPDATE current_serial = VALUES(current_serial), is_active = 1, updated_at = NOW()`,
+      [doctorId, appt.appointment_date, appt.serial_number],
+    );
+
+    return {
+      patientPhone: appt.patient_phone,
+      serialNumber: appt.serial_number,
+      appointmentDate: appt.appointment_date,
+      timeSlot: appt.time_slot,
+    };
+  });
+
+  // Fetch ALL today's appointments for this doctor (to compute expected times)
+  const todayAppts = await query(
+    `SELECT id, patient_phone, serial_number, time_slot, extra_minutes, status
+     FROM appointments
+     WHERE doctor_id = :doctorId AND appointment_date = :date AND status <> 'cancelled'
+     ORDER BY serial_number ASC`,
+    { doctorId, date: info.appointmentDate },
+  );
+
+  // Compute cumulative extra delay so far (all serials < current)
+  let cumulativeExtra = 0;
+  for (const row of todayAppts) {
+    if (Number(row.serial_number) < info.serialNumber) {
+      cumulativeExtra += Number(row.extra_minutes || 0);
+    }
+  }
+
+  // Notify patients whose serial > current
+  const doctorRows = await query(`SELECT name FROM doctors WHERE id = :doctorId LIMIT 1`, { doctorId });
+  const doctorName = doctorRows[0]?.name || 'Your doctor';
+
+  for (const row of todayAppts) {
+    if (Number(row.serial_number) <= info.serialNumber) continue;
+    const baseMinutes = timeSlotToMinutes(row.time_slot);
+    const expectedTime = minutesToTimeSlot(baseMinutes + cumulativeExtra);
+
+    createInAppNotification({
+      userType: 'patient',
+      userIdentifier: row.patient_phone,
+      category: 'appointment_queue_update',
+      title: 'Doctor Started Session',
+      body: `Dr. ${doctorName} is now seeing Serial #${info.serialNumber}. Your Serial: #${row.serial_number}. Est. time: ${expectedTime}.`,
+      metadata: {
+        type: 'appointment_started',
+        doctorId,
+        doctorName,
+        currentSerial: info.serialNumber,
+        yourSerial: Number(row.serial_number),
+        expectedTime,
+      },
+    }).catch(() => null);
+  }
+
+  return getAppointmentById(appointmentId);
+}
+
+// ── End an appointment ────────────────────────────────────────────────────────
+async function endAppointment({ appointmentId, doctorId }) {
+  await withTransaction(async (connection) => {
+    const [apptRows] = await connection.execute(
+      `SELECT id, doctor_id, status FROM appointments WHERE id = ? AND doctor_id = ? LIMIT 1 FOR UPDATE`,
+      [appointmentId, doctorId],
+    );
+    if (apptRows.length === 0) throw new HttpError(404, 'Appointment not found.', 'APPOINTMENT_NOT_FOUND');
+
+    await connection.execute(
+      `UPDATE appointments SET ended_at = NOW(), status = 'completed', updated_at = NOW() WHERE id = ?`,
+      [appointmentId],
+    );
+  });
+
+  return getAppointmentById(appointmentId);
+}
+
+// ── Extend an appointment (add N minutes, push affected patients) ─────────────
+async function extendAppointment({ appointmentId, doctorId, addMinutes }) {
+  const { createInAppNotification } = require('./notifications.service');
+  const mins = parseInt(addMinutes, 10);
+  if (!mins || mins < 1 || mins > 60) throw new HttpError(400, 'addMinutes must be 1–60.', 'INVALID_MINUTES');
+
+  const info = await withTransaction(async (connection) => {
+    const [apptRows] = await connection.execute(
+      `SELECT id, doctor_id, patient_phone, appointment_date, time_slot, serial_number, extra_minutes, status
+       FROM appointments WHERE id = ? AND doctor_id = ? LIMIT 1 FOR UPDATE`,
+      [appointmentId, doctorId],
+    );
+    if (apptRows.length === 0) throw new HttpError(404, 'Appointment not found.', 'APPOINTMENT_NOT_FOUND');
+    const appt = apptRows[0];
+
+    const newExtra = Number(appt.extra_minutes || 0) + mins;
+    await connection.execute(
+      `UPDATE appointments SET extra_minutes = ?, updated_at = NOW() WHERE id = ?`,
+      [newExtra, appointmentId],
+    );
+
+    return {
+      appointmentDate: appt.appointment_date,
+      serialNumber: Number(appt.serial_number),
+    };
+  });
+
+  // Fetch ALL today's appointments for this doctor
+  const todayAppts = await query(
+    `SELECT id, patient_phone, serial_number, time_slot, extra_minutes, status
+     FROM appointments
+     WHERE doctor_id = :doctorId AND appointment_date = :date AND status <> 'cancelled'
+     ORDER BY serial_number ASC`,
+    { doctorId, date: info.appointmentDate },
+  );
+
+  // Re-compute cumulative delay for each serial > current
+  let cumulativeExtra = 0;
+  for (const row of todayAppts) {
+    if (Number(row.serial_number) <= info.serialNumber) {
+      cumulativeExtra += Number(row.extra_minutes || 0);
+    }
+  }
+
+  const doctorRows = await query(`SELECT name FROM doctors WHERE id = :doctorId LIMIT 1`, { doctorId });
+  const doctorName = doctorRows[0]?.name || 'Your doctor';
+
+  for (const row of todayAppts) {
+    if (Number(row.serial_number) <= info.serialNumber) continue;
+    const baseMinutes = timeSlotToMinutes(row.time_slot);
+    const expectedTime = minutesToTimeSlot(baseMinutes + cumulativeExtra);
+
+    createInAppNotification({
+      userType: 'patient',
+      userIdentifier: row.patient_phone,
+      category: 'appointment_queue_update',
+      title: 'Appointment Delayed',
+      body: `Dr. ${doctorName} added ${mins} min. Your Serial #${row.serial_number} — new est. time: ${expectedTime}.`,
+      metadata: {
+        type: 'appointment_extended',
+        doctorId,
+        doctorName,
+        addedMinutes: mins,
+        currentSerial: info.serialNumber,
+        yourSerial: Number(row.serial_number),
+        expectedTime,
+      },
+    }).catch(() => null);
+  }
+
+  return getAppointmentById(appointmentId);
+}
+
+// ── Get live queue status for a doctor on a given date ───────────────────────
+async function getQueueStatus({ doctorId, date }) {
+  const normalizedDate = normalizeDate(date, 'date');
+
+  const [queueRows] = await Promise.all([
+    query(
+      `SELECT current_serial, is_active
+       FROM doctor_queue_status
+       WHERE doctor_id = :doctorId AND queue_date = :date LIMIT 1`,
+      { doctorId, date: normalizedDate },
+    ),
+  ]);
+
+  const currentSerial = Number(queueRows[0]?.current_serial || 0);
+  const isActive = Boolean(queueRows[0]?.is_active);
+
+  const todayAppts = await query(
+    `SELECT id, patient_phone, serial_number, time_slot, extra_minutes, status
+     FROM appointments
+     WHERE doctor_id = :doctorId AND appointment_date = :date AND status <> 'cancelled'
+     ORDER BY serial_number ASC`,
+    { doctorId, date: normalizedDate },
+  );
+
+  // Compute cumulative extra for each appointment
+  let cumulativeExtra = 0;
+  const items = todayAppts.map((row) => {
+    if (Number(row.serial_number) < currentSerial) {
+      cumulativeExtra += Number(row.extra_minutes || 0);
+    }
+    const baseMinutes = timeSlotToMinutes(row.time_slot);
+    return {
+      serialNumber: Number(row.serial_number),
+      patientPhone: row.patient_phone,
+      timeSlot: row.time_slot,
+      expectedTime: minutesToTimeSlot(baseMinutes + cumulativeExtra),
+      extraMinutes: Number(row.extra_minutes || 0),
+      status: row.status,
+    };
+  });
+
+  return {
+    doctorId,
+    date: normalizedDate,
+    currentSerial,
+    isActive,
+    appointments: items,
+  };
+}
+
 module.exports = {
   createAppointment,
   getAppointmentById,
@@ -555,4 +804,8 @@ module.exports = {
   rescheduleAppointment,
   respondToRescheduleRequest,
   updateAppointmentStatus,
+  startAppointment,
+  endAppointment,
+  extendAppointment,
+  getQueueStatus,
 };

src/utils/serializers.js

@@ -106,6 +106,9 @@ function mapAppointment(row) {
           status: row.reschedule_status,
         }
       : null,
+    startedAt: row.started_at || null,
+    endedAt: row.ended_at || null,
+    extraMinutes: Number(row.extra_minutes || 0),
   };
 }