AgendaPro/docs/superpowers/specs/2026-07-26-auto-assign-specialist-booking-redesign-design.md

Auto-asignación de especialista + rediseño de la página de reservas

Fecha: 2026-07-26 Estado: Borrador para revisión del usuario Alcance: Página pública de reservas (/b/:slug) + sección de Configuración + modelo de datos

1. Objetivo

1. Añadir en Configuración un check "Asignar especialista automáticamente" que, al activarse, omite el paso de elección de especialista para el cliente en la URL pública de reservas.
2. La asignación se resuelve con un algoritmo matemático que considera especialidad, eficiencia y —sobre todo— disponibilidad, garantizando que un especialista nunca atienda a dos clientes a la vez (sin traslape con citas ya agendadas).
3. En "Elige fecha y hora", reemplazar el <input type="date"> nativo por un calendario de mes siempre visible.
4. En escritorio, dividir "Elige fecha y hora" en dos columnas (calendario + horarios) para aprovechar el ancho de pantalla; en móvil se mantiene el stack actual.
5. Colores indicativos llamativos (alto contraste, mayor tamaño) para ayudar a usuarios mayores de 50, manteniendo el estilo moderno/fresco de AgendaPro y sin alterar los bloques de horario actuales.
6. Fix: iconos de "Tus datos" (nombre/teléfono/correo) que se solapan con el placeholder gris.

2. No-objetivos (YAGNI)

• Pasarela de pago / depósitos (require_deposit queda sin aplicar).
• Política de cancelación automatizada (fuera de alcance aquí).
• Recurrencia de citas, descansos/almuerzos puntuales.
• Vista de disponibilidad tipo FullCalendar en el flujo público (se usa una grilla de mes propia, más simple y enfocada).

3. Arquitectura

Nuevo módulo server/lib/scheduling.ts con funciones puras y testeables que centralizan toda la "data science":

• getWorkingHours(business, employee|null, date) → { start, end } | null (resuelve horario: empleado → si no, negocio; si el día es null, fuera de servicio).
• isAvailable(db, employeeId, startIso, endIso) → boolean (verifica traslape contra citas (scheduled, completed)).
• computeOccupiedMinutes(db, employeeId, date) → number (para load balance).
• specialtyMatch(employee, service) → 0..1.
• scoreCandidate(ctx) → { score, reasons }.
• autoAssign(db, { business, service, startIso, endIso }) → { employeeId, score, reasons } | null (filtra por hard constraints, luego scorea).

Se descarta una versión SQL-pura (window functions): el scoring ponderado es más legible y mantenible en TypeScript y el número de especialistas por negocio es pequeño (cabe en memoria). El módulo es importado por server/routes/booking.ts y server/routes/appointments.ts.

4. Modelo de datos (migración V3 → V4)

Función migrateV3ToV4 en server/db.ts (sigue el patrón de migrateV2ToV3).

Tabla businesses — 2 columnas

Columna	Tipo	Default	Notas
auto_assign_specialist	INTEGER NOT NULL	0	El check que omite el paso de especialista.
working_hours	TEXT (JSON)	ver backfill	Horario default del negocio por día.

Formato JSON: {"1":{"start":"09:00","end":"20:00"}, "2":{...}, ..., "6":null, "7":null} (1=Lun … 7=Dom; null = cerrado).

Tabla employees — 3 columnas

Columna	Tipo	Default	Notas
specialties	TEXT (JSON array)	'[]'	Etiquetas: ["Corte","Barba"]. Se comparan con service.category y tokens de service.name.
working_hours	TEXT (JSON)	NULL	Horario individual; NULL = hereda el del negocio.
efficiency_score	REAL NOT NULL	50	0–100. Lo captura el dueño.

Backfill (en la migración)

• auto_assign_specialist = 0 para todos.
• businesses.working_hours = {"1":{"start":"09:00","end":"20:00"},...,"5":{...},"6":null,"7":null} (replica el 09:00–20:00 Lun–Vie actualmente hardcodeado en booking.ts:57-58).
• employees.specialties = '[]', employees.working_hours = NULL, employees.efficiency_score = 50.

Tipos (shared/types.ts)

• Business añade auto_assign_specialist: boolean, working_hours: WorkingHours | null.
• Employee añade specialties: string[], working_hours: WorkingHours | null, efficiency_score: number.
• WorkingHours = Record<1..7, { start: string; end: string } | null>.

Settings API (server/routes/settings.ts)

• La lista blanca (settings.ts:8-20) añade: auto_assign_specialist, working_hours.

5. Algoritmo de auto-asignación (la "data science")

Restricción dura + score ponderado, para una cita candidata (servicio S, intervalo [t0, t1)):

5.1 Hard constraints — candidato válido si:

1. El empleado está active = 1.
2. Ofrece el servicio: existe fila en employee_services(employee_id, service_id).
3. [t0, t1) cae dentro de su horario laboral ese día (getWorkingHours). Si el día es cerrado → descartado.
4. No traslapa ninguna cita existente con status IN ('scheduled','completed'): para toda cita c, es falso que t0 < c.end_at && t1 > c.start_at (isAvailable).

→ Garantiza que un especialista jamás atiende a dos personas a la vez.

5.2 Score (0–100) de cada candidato válido

score = 50 * specialtyMatch + 30 * efficiency + 20 * (1 - loadBalance)

• specialtyMatch (0..1): 1.0 si una etiqueta de employee.specialties coincide (normalizado: lowercase, sin acentos, match por token/subcadena) con service.category o un token de service.name; 0.5 si ofrece el servicio (paso 2) pero sin coincidencia de etiqueta.
• efficiency (0..1): employee.efficiency_score / 100.
• loadBalance (0..1): min(1, ocupadoHoy / laborableHoy), donde ocupadoHoy = computeOccupiedMinutes (suma de duraciones de citas del día) y laborableHoy = minutos del turno ese día. A menor carga → mayor (1 - loadBalance) → premia reparto justo.

5.3 Desempate y resultado

• Mayor score gana. Empate → menor id (determinista).
• autoAssign devuelve { employeeId, score, reasons: string[] } para auditoría/UI.

5.4 Pesos

specialty 50 / efficiency 30 / load 20. Disponibilidad es restricción dura (peso infinito): nunca se viola.

6. Guard anti double-booking (transaccional)

Hoy POST /api/public/:slug/book (booking.ts:100-153) y POST /api/appointments (appointments.ts:75-167) insertan sin re-verificar conflictos (race condition). Fix:

• Envolver la creación en una transacción de SQLite (db.exec('BEGIN IMMEDIATE') o el equivalente de node:sqlite).
• Antes del INSERT, llamar a isAvailable(employeeId, t0, t1).
• Si ya no está libre → 409 Conflict con { error: "ESE_HORARIO_OCUPADO" }. El cliente público ve "Esa hora acaba de ocuparse, elige otra" y vuelve al paso de horario.
• En auto-asignación, autoAssign corre dentro de la misma transacción, sobre el estado ya bloqueado.

7. Flujo del wizard público (src/pages/public/BookingPage.tsx)

7.1 Pasos

• auto_assign_specialist = ON → 3 pasos: Servicio → Horario → Datos (sin paso Especialista).
• OFF → 4 pasos actuales, pero la card "Cualquiera" usa autoAssign (no más LIMIT 1).

7.2 Slots (GET /api/public/:slug/slots)

• Se mantiene la firma y la grilla de 30 min, pero el rango ahora se lee de getWorkingHours (negocio/empleado) en vez del hardcodeado 09:00–20:00.
• Cuando se omite el especialista, los candidatos son todos los empleados que ofrecen el servicio; un slot se muestra si al menos uno está libre (unión de disponibilidades). La asignación concreta se resuelve al confirmar.
• El payload del slot puede incluir un flag opcional hasMultiple para mostrar "varios especialistas disponibles" (informativo).

7.3 Confirmación

• Muestra el especialista asignado: avatar/color, nombre, rol, y 1–2 reasons legibles (p. ej. "Especialista en Corte · alta eficiencia · disponible"). El cliente nunca queda sin saber a quién le tocó.

8. UI — DateTimePicker (Elige fecha y hora)

8.1 Calendario de mes siempre visible (MonthCalendar)

• Componente nuevo (sin librería externa). Grilla Lun–Dom, header con mes/año + flechas ‹ › (limite ±3 meses).
• Días pasados o fuera de horario: atenuados (slate-100, texto slate-300), no seleccionables.
• Fin de semana: color tenue (no bloqueado salvo que working_hours sea null).
• Día con disponibilidad (≥1 slot): punto accent (naranja AgendaPro) bajo el número.
• Día seleccionado: relleno brand-500, texto blanco, ring-2 ring-brand-500/30, shadow-soft.
• Tipografía base >=16px; celda táctil >=44px (accesibilidad 50+).

8.2 Dos columnas en escritorio

• En el paso Horario, main pasa de max-w-2xl a max-w-5xl (solo en este paso).
• DateTimePicker: md:grid md:grid-cols-[minmax(0,1fr)_minmax(0,1.1fr)] md:gap-8 → calendario izquierda, tarjeta de horarios derecha.
• Tarjeta de horarios: encabezado con la fecha elegida en grande + agrupación visual de slots por Mañana / Tarde (etiquetas con color accent/brand suave). La grilla de bloques actual no se modifica (grid-cols-3 sm:grid-cols-4, estilos seleccionado/disponible idénticos).
• En <md se conserva el stack vertical actual (aprobado por el usuario).
• TopBar (max-w-3xl) y ActionBar (max-w-2xl) se ensanchan a max-w-5xl para acompañar.

8.3 Colores indicativos (alta legibilidad, sin romper la marca)

• No se introducen colores nuevos estridentes; se refuerza contraste y tamaño y se usa accent como señal secundaria.
• Seleccionado: bg-brand-500 text-white shadow-soft + badge Check (más grande).
• Disponible: border-slate-200 bg-white, hover → border-brand-400 bg-brand-50.
• Indisponible: bg-slate-100 text-slate-300 + ícono de candado sutil.
• Texto de etiquetas y campos >=16px; estado enfocado con ring más visible.

9. UI — Fix de iconos en "Tus datos" (y app-wide)

9.1 Causa raíz

src/index.css:272-284: .input { padding: 0.55rem 0.75rem } (shorthand) tiene la misma especificidad (0,1,0) que .pl-9 de Tailwind. Como @tailwind utilities; se emite antes en el archivo, la regla .input (posterior) gana y fija padding-left: 0.75rem (12px), justo donde inicia el icono (left-3 = 12px, ancho 16px → ocupa 12–28px). El texto arranca en 12px → solape. Afecta a 9 inputs de la app.

9.2 Fix

1. Envolver .input, .select, .textarea (y demás reglas de componente custom) en @layer components { … } en src/index.css. Así las utilidades del layer utilities (incluido pl-*) siempre ganan, independientemente del orden de fuente. Resuelve los 9 sitios a la vez.
2. En los 3 fields de "Tus datos" subir pl-9 → pl-10 (icono left-3 + 16px → texto a 40px, ~12px de holgura, mejor para 50+). Opcionalmente replicar pl-10 en los otros 6 inputs con icono para consistencia.

10. UI — Configuración (src/pages/SettingsPage.tsx)

• Card "Reservas online" (:64-101): añade
  • Check "Asignar especialista automáticamente" con helper "El cliente no elige especialista; lo asigna el sistema según especialidad, eficiencia y disponibilidad".
  • Editor de horario del negocio: grilla 7 días, cada uno con switch activo + start/end (type=time). Persiste en businesses.working_hours.
• El listado de campos del mutation PATCH (SettingsPage.tsx:28-49) incluye los nuevos.

11. UI — Ficha de Especialista (edición de empleado)

• Vista de edición de empleado añade:
  • Especialidades (input de chips/tags → array).
  • Horario laboral (default: "Heredar del negocio"; si se edita, grilla 7 días como en el negocio).
  • Eficiencia (slider 0–100 con etiqueta descriptiva).
• Endpoints existentes PATCH /api/employees/:id se extienden con los 3 campos en la lista blanca.

12. Plan de pruebas

• Unit (scheduling): isAvailable (casos de traslape en bordes), specialtyMatch (acentos/case), scoreCandidate (monotocidad de cada factor), autoAssign (elige óptimo, desempate determinista, respeta horario, ninguno disponible → null).
• Integración (rutas): reservar la misma hora dos veces → la 2ª da 409; reservar con auto-assign activo asigna y no traspasa.
• Build/estático: npm run typecheck y npm run lint limpios.
• E2E si aplica: flujo público completo con check activo (3 pasos) y sin check (4 pasos).

13. Riesgos y mitigaciones

Riesgo	Mitigación
Datos vacíos al migrar (sin especialidades/eficiencia)	Defaults neutros: specialties=[], efficiency=50. El algoritmo degrada a disponibilidad + load balance.
Race condition de doble reserva	Transacción BEGIN IMMEDIATE + isAvailable dentro de la misma.
Performance con muchos especialistas	N por negocio es chico; peor caso O(N·slots·citas). Cache de computeOccupiedMinutes por (employee, date).
Cambio de working_hours rompe slots pasados	Solo afecta a fechas futuras; citas pasadas no se revalidan.
@layer components cambia cascada	Re-auditar visualmente inputs/selects existentes; los utilities ya pensados para ganar.

14. Entregables (resumen de archivos)

• Nuevos: server/lib/scheduling.ts.
• Migración: server/db.ts (migrateV3ToV4).
• Backend rutas: server/routes/booking.ts, server/routes/appointments.ts, server/routes/settings.ts, server/routes/employees.ts.
• Tipos: shared/types.ts.
• Frontend: src/pages/public/BookingPage.tsx (MonthCalendar, layout 2 col, flujo 3/4 pasos, confirmación), src/pages/SettingsPage.tsx, ficha de empleado, src/lib/publicApi.ts, src/lib/api.ts.
• Estilos: src/index.css (@layer components + fix de padding).