ani67/docs/APPOINTMENTS_SYSTEM.md

Sistema de Agendamiento de Citas Telemáticas

📋 Checklist de Implementación

1. Base de Datos (Prisma)

• Crear modelo Appointment en schema.prisma
• Agregar campos: pacienteId, medicoId, chatReportId, fecha, estado, roomName, motivoRechazo
• Estados: PENDIENTE, APROBADA, RECHAZADA, COMPLETADA, CANCELADA
• Relaciones con User (paciente), User (medico), ChatReport
• Migración de base de datos

2. Backend APIs

• POST /api/appointments - Crear cita (paciente)
• GET /api/appointments - Listar citas (filtro por rol)
• GET /api/appointments/[id] - Detalle de cita
• PATCH /api/appointments/[id]/approve - Aprobar (médico) - NO genera roomName
• POST /api/appointments/[id]/start-meeting - Iniciar videollamada (genera roomName)
• PATCH /api/appointments/[id]/reject - Rechazar (médico)
• PATCH /api/appointments/[id]/complete - Marcar completada
• DELETE /api/appointments/[id] - Cancelar (paciente)

3. Frontend - Componentes

• AppointmentCard - Card para mostrar cita
• AppointmentForm - Formulario nueva cita
• AppointmentsList - Lista de citas
• AppointmentStatusBadge - Badge de estado
• JitsiMeetRoom - Componente para videollamada
• AppointmentActions - Botones aprobar/rechazar

4. Frontend - Páginas

• /appointments - Vista paciente (crear/ver citas)
• /appointments/doctor - Vista médico (aprobar citas)
• /appointments/[id] - Detalle de cita
• /appointments/[id]/meet - Sala Jitsi

5. UI/UX

• Agregar item "Citas" en Sidebar
• Badge con contador de citas pendientes (médico)
• Botón "Agendar Cita" en MedicalAlert (RECOMENDADO/URGENTE)
• Modal de confirmación para aprobar/rechazar
• Estados de loading y errores

6. Integración Jitsi Meet

• Script external_api.js en layout
• Componente React con Jitsi
• Generar roomName único cuando se inicia videollamada (NO al aprobar)
• Validación de horario: permitir unirse 15 min antes hasta 1 hora después
• Configuración: moderador para médico
• Controles: mute, video, compartir pantalla

7. Validaciones y Seguridad

• Middleware: solo pacientes crean citas
• Middleware: solo médicos aprueban/rechazan
• Validar acceso a sala: solo paciente y médico de esa cita
• Rate limiting en creación de citas
• Validación de fechas (no pasadas)

8. Notificaciones (Opcional)

• Toast al crear cita
• Toast al aprobar/rechazar
• Badge de notificaciones en sidebar

---

🗂️ Estructura de Archivos

prisma/
  schema.prisma (+ modelo Appointment)

src/app/api/appointments/
  route.ts (GET, POST)
  [id]/route.ts (GET, PATCH, DELETE)
  [id]/approve/route.ts
  [id]/reject/route.ts

src/app/appointments/
  page.tsx (paciente)
  doctor/page.tsx (médico)
  [id]/page.tsx (detalle)
  [id]/meet/page.tsx (sala Jitsi)

src/components/appointments/
  AppointmentCard.tsx
  AppointmentForm.tsx
  AppointmentsList.tsx
  AppointmentStatusBadge.tsx
  AppointmentActions.tsx
  JitsiMeetRoom.tsx

src/hooks/
  useAppointments.ts

---

📊 Modelo de Datos

model Appointment {
  id            String   @id @default(cuid())
  createdAt     DateTime @default(now())
  updatedAt     DateTime @updatedAt
  
  // Relaciones
  pacienteId    String
  paciente      User     @relation("PatientAppointments", fields: [pacienteId], references: [id])
  medicoId      String?
  medico        User?    @relation("DoctorAppointments", fields: [medicoId], references: [id])
  chatReportId  String?  @unique
  chatReport    ChatReport? @relation(fields: [chatReportId], references: [id])
  
  // Info de la cita
  fechaSolicitada DateTime
  estado        String   // PENDIENTE, APROBADA, RECHAZADA, COMPLETADA, CANCELADA
  motivoConsulta String
  motivoRechazo String?
  
  // Jitsi
  roomName      String?  @unique
  
  @@index([pacienteId])
  @@index([medicoId])
  @@index([estado])
}

---

🎯 Prioridades

1. FASE 1 - MVP (3-4h)

   • Schema + migración
   • APIs básicas (crear, listar, aprobar)
   • Páginas paciente y médico (simple)
   • Integración Jitsi básica

2. FASE 2 - Mejoras (2-3h)

   • UI mejorada con estados
   • Validaciones completas
   • Badge de notificaciones
   • Botón desde MedicalAlert

3. FASE 3 - Pulido (1-2h)

   • Notificaciones toast
   • Manejo de errores robusto
   • Loading states
   • Responsivo mobile

---

🔧 Configuración Jitsi

const domain = 'meet.jit.si';
const options = {
  roomName: `appointment-${appointmentId}-${Date.now()}`,
  width: '100%',
  height: 700,
  parentNode: document.querySelector('#jitsi-container'),
  configOverwrite: {
    startWithAudioMuted: true,
    startWithVideoMuted: false,
  },
  interfaceConfigOverwrite: {
    TOOLBAR_BUTTONS: [
      'microphone', 'camera', 'closedcaptions', 'desktop',
      'fullscreen', 'fodeviceselection', 'hangup',
      'chat', 'recording', 'etherpad', 'settings', 'videoquality',
    ],
  },
  userInfo: {
    displayName: userName,
  }
};

---

📝 Notas

• Usar Jitsi público (meet.jit.si) inicialmente
• Self-host después (requiere servidor propio)
• RoomName único: appointment-{id}-{timestamp} (generado al iniciar videollamada)
• Moderador: asignar al médico
• Considerar límite de citas simultáneas por médico
• Flujo de creación de citas: Las citas se crean SOLO desde el chatbot cuando la IA recomienda una consulta médica (estados RECOMENDADO/URGENTE). Los pacientes no pueden crear citas manualmente desde la página de citas.
• Flujo de videollamadas: El roomName NO se genera al aprobar la cita, solo cuando un usuario intenta unirse en el horario válido (15 min antes hasta 1 hora después). Esto evita salas creadas prematuramente.