Operating Room Scheduling and Surgical Team Management

The surgical suite module extends the core appointment system for procedures that require a dedicated operating room, a named surgical procedure, and a multi-role clinical team. Surgeries are stored as Cita records with tipo_cita = 'cirugia', which unlocks additional data fields (room validation, procedure linkage, and the team roster) that are not relevant to standard consultations.

Catalog Entities

Two catalog tables underpin all surgical scheduling. Only Administrador Clinica can manage these catalogs.

Sala (Room / Operating Room)

A Sala represents a physical space in the clinic. Rooms are shared between consultations and surgeries — the tipo field determines whether a room is eligible for surgical scheduling.

nombre

string

required

Display name for the room, e.g., “Quirófano 1” or “Consultorio Norte”.

tipo

string

required

Room classification. One of:

consultorio — general consultation room.
quirofano — operating room; required for surgical appointments.
recuperacion — post-operative recovery room.
especial — other specialized spaces.

capacidad

integer

Number of simultaneous patients the room supports (nullable).

equipamiento

array

JSON array listing installed equipment. Useful for staff planning.

estado

string

Current operational status. One of: disponible, ocupado, en_uso, mantenimiento.

activo

boolean

When false the room is hidden from appointment and surgery scheduling forms.

The Sala::scopeQuirofanos() scope (WHERE tipo = 'quirofano') is used by QuirofanoController to populate the room selector and to validate that the selected room is actually an operating room:

// QuirofanoController::store()
$sala = Sala::findOrFail($data['sala_id']);
if ($sala->tipo !== Sala::TIPO_QUIROFANO) {
    return back()->withInput()->withErrors([
        'sala_id' => 'La sala seleccionada no es un quirófano.'
    ]);
}

ProcedimientoQuirurgico (Surgical Procedure)

Each scheduled surgery is linked to one procedure from this catalog.

nombre

string

required

Procedure name, e.g., “Colecistectomía laparoscópica”.

descripcion

string

Extended description for staff reference (nullable).

duracion_estimada_minutos

integer

Expected procedure duration. This value is used to calculate hora_fin from hora_inicio when scheduling, identical to how Servicio.duracion_minutos works for consultations.

requiere_quirofano

boolean

Whether the procedure always requires an operating room (stored for reference; the QuirofanoController enforces this independently at the room-type level).

precio

decimal

Base price for billing purposes (nullable).

activo

boolean

Controls visibility in the scheduling form. Inactive procedures do not appear in the selector.

Scheduling a Surgery

POST /quirofanos creates a new surgical appointment. The request is validated, the DisponibilidadService is invoked to check for conflicts (same logic as consultations), and a Cita with tipo_cita = 'cirugia' is persisted along with the initial surgical team roster — all inside a single database transaction.

POST /{tenant}/quirofanos
Content-Type: application/json

{
  "paciente_id": 12,
  "medico_id": 5,
  "sala_id": 2,
  "procedimiento_quirurgico_id": 3,
  "fecha": "2025-09-15",
  "hora_inicio": "08:30",
  "notas": "Paciente con alergia a la penicilina.",
  "equipo": [
    {
      "es_externo": false,
      "user_id": 5,
      "rol_equipo": "cirujano_principal"
    },
    {
      "es_externo": false,
      "user_id": 9,
      "rol_equipo": "anestesiologo"
    },
    {
      "es_externo": true,
      "staff_externo_nombre": "Dr. Ramírez Ortiz",
      "staff_externo_email": "ramirez@externoejemplo.com",
      "staff_externo_rol": "Cirujano Asistente",
      "rol_equipo": "asistente"
    }
  ]
}

The duracion_minutos on the resulting Cita is taken directly from ProcedimientoQuirurgico.duracion_estimada_minutos.

Only users with the roles Doctor or Administrador Clinica can create, edit, or cancel surgical appointments. Recepcion can confirm team attendance but cannot schedule or modify surgeries. The Enfermero role can view the surgery schedule on the dashboard but cannot make any changes.

The Surgical Team (`CitaEquipo`)

Every Cita of type cirugia has a team roster stored in cita_equipo. Team members can be internal clinic staff (es_externo = false, linked via user_id) or external professionals (es_externo = true, identified by name and email).

Team Roles

Constant	Value	Description
`ROL_CIRUJANO_PRINCIPAL`	`cirujano_principal`	Lead surgeon.
`ROL_ANESTESIOLOGO`	`anestesiologo`	Anesthesiologist.
`ROL_ENFERMERO`	`enfermero`	Scrub or circulating nurse.
`ROL_ASISTENTE`	`asistente`	Surgical assistant.
`ROL_OTRO`	`otro`	Any other support role.

Adding and Removing Team Members

Team members are managed independently of the surgery itself so that adding a new member does not reset the confirmado status of those already on the roster. Add a member after surgery is created:

POST /{tenant}/quirofanos/{cita}/equipo
Body: {
  "es_externo": false,
  "user_id": 14,
  "rol_equipo": "enfermero"
}

Remove a member:

DELETE /{tenant}/quirofanos/equipo/{citaEquipo}

Confirming Attendance

Attendance is confirmed manually by Recepcion, Doctor, or Administrador Clinica — team members do not self-confirm:

PATCH /{tenant}/quirofanos/equipo/{citaEquipo}/confirmar

This sets confirmado = true on the CitaEquipo record.

Editing and Cancelling a Surgery

PATCH /quirofanos/{cita} updates the lead physician, room, procedure, and schedule. The same conflict detection runs as during creation (excluding the current record from the check). Passing overbooking_confirmado = true along with a notas_override justification overrides the conflict. POST /quirofanos/{cita}/cancelar cancels the surgery. A motivo is required. On cancellation the system sends notifications to the patient, the lead physician, and all team members. Both endpoints enforce tipo_cita === 'cirugia' with a 404 guard — they cannot be called on standard consultation appointments.

Conflict Detection for Surgeries

QuirofanoController injects the same DisponibilidadService used by CitaController. For surgical appointments the room (sala_id) is always required, so both the doctor and room conflict queries are always active:

$conflictos = $disponibilidad->resumenConflictos(
    $data['medico_id'],
    $data['sala_id'],  // always provided for surgeries
    $inicio,
    $fin
);

If conflicts are found and overbooking_confirmado is false, the form is returned with a conflicto_horario flash payload for the React UI to display.

Route Reference

Method	Path	Description	Required Role
`GET`	`/quirofanos`	Surgery schedule view (route registered; `QuirofanoController::index()` is not yet implemented — surgical data is currently served through the Dashboard)	Any authenticated
`POST`	`/quirofanos`	Schedule a new surgery	Doctor, Administrador Clinica
`PATCH`	`/quirofanos/{cita}`	Edit surgery (room, procedure, date/time)	Doctor, Administrador Clinica
`POST`	`/quirofanos/{cita}/cancelar`	Cancel a surgery	Doctor, Administrador Clinica
`POST`	`/quirofanos/{cita}/equipo`	Add a team member to the surgery	Doctor, Administrador Clinica
`DELETE`	`/quirofanos/equipo/{citaEquipo}`	Remove a team member	Doctor, Administrador Clinica
`PATCH`	`/quirofanos/equipo/{citaEquipo}/confirmar`	Confirm a team member’s attendance	Recepcion, Doctor, Administrador Clinica
`POST`	`/salas-quirofanos`	Create a room/OR	Administrador Clinica
`PATCH`	`/salas-quirofanos/{sala}`	Edit room details	Administrador Clinica
`PATCH`	`/salas-quirofanos/{sala}/toggle`	Activate or deactivate a room	Administrador Clinica
`DELETE`	`/salas-quirofanos/{sala}`	Delete a room	Administrador Clinica
`POST`	`/procedimientos-quirurgicos`	Create a procedure in the catalog	Administrador Clinica
`PATCH`	`/procedimientos-quirurgicos/{procedimiento}`	Edit a procedure	Administrador Clinica
`PATCH`	`/procedimientos-quirurgicos/{procedimiento}/toggle`	Activate or deactivate a procedure	Administrador Clinica
`DELETE`	`/procedimientos-quirurgicos/{procedimiento}`	Delete a procedure	Administrador Clinica

A Sala can only be used for a surgical appointment when its tipo is quirofano. Submitting a non-operating room for a surgical booking returns a validation error at the API level, regardless of the UI.

Get Started

Core Features

User Management & Security

Multi-Tenancy

Development

Operating Room Scheduling and Surgical Team Management

Catalog Entities

Sala (Room / Operating Room)

ProcedimientoQuirurgico (Surgical Procedure)

Scheduling a Surgery

The Surgical Team (`CitaEquipo`)

Team Roles

Adding and Removing Team Members

Confirming Attendance

Editing and Cancelling a Surgery

Conflict Detection for Surgeries

Route Reference

Build docs developers (and LLMs) love

Get Started

Core Features

User Management & Security

Multi-Tenancy

Development

Documentation Index

​Catalog Entities

​Sala (Room / Operating Room)

​ProcedimientoQuirurgico (Surgical Procedure)

​Scheduling a Surgery

​The Surgical Team (CitaEquipo)

​Team Roles

​Adding and Removing Team Members

​Confirming Attendance

​Editing and Cancelling a Surgery

​Conflict Detection for Surgeries

​Route Reference

Build docs developers (and LLMs) love

Catalog Entities

Sala (Room / Operating Room)

ProcedimientoQuirurgico (Surgical Procedure)

Scheduling a Surgery

The Surgical Team (`CitaEquipo`)

Team Roles

Adding and Removing Team Members

Confirming Attendance

Editing and Cancelling a Surgery

Conflict Detection for Surgeries

Route Reference