Dermacielo — Plan de reactivación y mejora

Para Hermes: Ejecutar por tareas pequeñas, con revisión de cumplimiento y calidad; este documento es solo planificación, sin cambios al producto.

Objetivo: Retomar un CRM/agenda clínica/POS multi-sucursal seguro, usable y migrable desde Excel, sin perder trazabilidad ni interrumpir la operación.

Arquitectura propuesta: Tomar provisionalmente softvibeslab/derma como base técnica (React/TypeScript/Vite + Supabase/PostgreSQL), sujeto a validar despliegue, datos reales y propiedad funcional. Tratar RogerDevAndroid/dasboard_dermacielo como referencia funcional/legado y no conectar sus flujos de localStorage a pacientes reales. Autorización en base de datos (RLS), operaciones monetarias atómicas en servidor/SQL, frontend como interfaz y nunca como frontera de seguridad.

Stack: React, TypeScript, Vite, Tailwind, Supabase Auth/Postgres/Storage; pruebas unitarias/integración/E2E a incorporar tras auditar tooling.

Evidencia y límites actuales

• softvibeslab/derma (privado) tiene src/pages/{Dashboard,Patients,Appointments,Services,Payments,Reports,Import,Roles,Users,Workflow}.tsx, src/hooks/usePermissions.ts, src/lib/supabase.ts y 8 migraciones en supabase/migrations/. Su primera migración crea roles, users, patients, services, appointments, payments, patient_treatments, monthly_status, sucursales, promotions y activa RLS; aún no se ha auditado la totalidad de políticas ni el estado desplegado.
• src/hooks/usePermissions.ts contiene un mapa de permisos hardcodeado para administrador/cajero/cosmetóloga. Hay que comprobar coherencia con la base, incluyendo inactividad y sucursal.
• src/pages/Import.tsx maneja CSV; la inspección preliminar no encontró XLSX, deduplicación, dry-run ni rollback. No sustituir la migración verificada por una carga directa de datos vivos.
• RogerDevAndroid/dasboard_dermacielo (público) coincide con la estructura HTML/JS de la wiki. Su login.html usa usuarios/contraseñas en localStorage y precarga una cuenta de demostración; admin/js/auth.js verifica un token local. No consta que sea el código de producción. No publicar ni reutilizar ese mecanismo.
• La wiki suministrada describe un esquema distinto (clientes, citas, ventas) y un rol Recepción que no aparece en su matriz. No ejecutar ese SQL sobre la base existente sin reconciliación.

Decisiones de entrada — antes de código de producto

1. Identificar dominio/app realmente desplegada, repositorio y commit de despliegue, proyecto Supabase, propietarios, sucursales activas, usuarios y si hay datos reales. No copiar datos clínicos ni credenciales a entornos inseguros.
2. Confirmar con el responsable clínico/operativo los flujos MVP, roles (Admin, Cosmetóloga, Ventas, Caja, Recepción), permisos por sucursal, acceso a información médica y necesidades de reportes. No asumir que Admin debe poder leer todo expediente clínico.
3. Confirmar jurisdicción, aviso de privacidad, reglas de conservación, consentimiento, acceso/auditoría y facturación con asesoría legal/contable local; el plan no certifica cumplimiento normativo.
4. Definir si derma es sistema canónico y si el HTML legado contiene funciones o datos que haya que portar. Si la producción utiliza el legado, abrir antes un plan de contención y migración sin corte brusco.

Fase 0 — Rescate, línea base y riesgo inmediato (P0)

Tareas

1. Inventariar entornos, remotos, ramas, despliegues y esquemas reales; crear mapa «wiki ↔ implementación ↔ producción». Entregable docs/architecture/current-state.md en el repo elegido.
2. Ejecutar en una rama/entorno de prueba npm ci, npm run lint, npm run build y registrar fallos previos. Revisar README.md, .env.example, netlify.toml, src/contexts/AuthContext.tsx, src/components/ProtectedRoute.tsx, todas las migraciones y políticas Storage.
3. Determinar si el login público legado está expuesto en producción; si sí, restringir acceso y acordar remediación de autenticación antes de manipular expedientes. Auditar material sensible versionado y accesible públicamente; rotar secretos solo si se demuestra exposición, mediante procedimiento controlado. Nunca imprimir secretos en informes.
4. Planificar respaldo cifrado, restauración probada y entorno de staging con datos sintéticos; registrar responsable del respaldo y prueba de restauración.

Salida: mapa de sistemas firmado, riesgo P0 resuelto o aislado, baseline reproducible y ruta de rollback. No pasar de fase con autenticación falsa o acceso anónimo a datos de pacientes.

Fase 1 — Seguridad, modelo y permisos (P0/P1)

Tareas incrementales (test rojo → cambio mínimo → test verde por cada una)

1. Congelar el esquema vigente a partir de migraciones y esquema real. Documentar correspondencias entre patients/appointments/payments y clientes/citas/ventas; aplicar solo migraciones aditivas/reversibles. Archivos: supabase/migrations/<timestamp>_*.sql, src/lib/supabase.ts (preferir tipos generados), docs/data-model.md.
2. Especificar matriz rol × acción × recurso × sucursal × estado incluyendo Recepción/Ventas/Caja. Separar metadata operativa de contenido clínico; negar acceso por defecto. Evitar que el frontend hardcodeado sea autoridad: alinear src/hooks/usePermissions.ts y src/components/ProtectedRoute.tsx con las mismas capacidades que RLS, verificadas por pruebas de diferentes usuarios.
3. Revisar vínculo auth.users ↔ users, cuentas inactivas, funciones privilegiadas, SECURITY DEFINER, políticas de SELECT/INSERT/UPDATE/DELETE y pertenencia a sucursal. Nunca incluir service-role key en Vite. Testear intentos de acceso cruzado entre roles/sucursales, incluso por llamadas directas a Supabase, no solo UI.
4. Separar patients de información clínica sensible; añadir expedientes, notas con autor/fecha, consentimientos versionados, documentos en bucket privado con políticas y acceso temporal, auditoría de lectura/cambios y retención aprobada. Preferir desactivación/anonimización gobernada a borrado en cascada de historia clínica.
5. Preparar índices/constraints: estados y enums/checks, cantidades y montos positivos, unicidad de identificadores, FK según historial, fechas coherentes, y prevención de solapamiento de citas por recurso (persona/equipo/sucursal) con protección transaccional.

Aceptación: conjunto automatizado de permisos permite solo operaciones autorizadas; acceso directo no elude la UI; archivos clínicos no públicos; restauración verificada.

Fase 2 — MVP operativo de principio a fin (P1)

Orden de cortes verticales, uno por PR pequeño:

1. CRM: alta/búsqueda/deduplicación razonable, ficha y cambios auditados (src/pages/Patients.tsx). Acordar qué datos son obligatorios y quién los ve.
2. Agenda: disponibilidad, equipo/operadora/sucursal, zona horaria local, estados y reprogramación sin doble reserva (src/pages/Appointments.tsx). Probar dos reservas simultáneas.
3. Catálogo y paquetes: servicio/producto, duración, precio histórico al momento de venta; paquetes y sesiones pendientes si la operación los utiliza (src/pages/Services.tsx, nuevas migraciones). No alterar precios reales sin aprobación.
4. Venta y caja: carrito, pagos mixtos/parciales si requeridos, devolución/anulación con motivo y permiso, folio transaccional, cierre diario por sucursal, idempotencia y conciliación. Si Payments.tsx no cubre venta detallada, crear src/pages/Pos.tsx y ruta en src/App.tsx después de aprobar flujo. Nunca calcular el total confiable solo en el cliente.
5. Expediente: consentimiento, notas por sesión y documentos clínicos privados con estados de carga/error; pantalla nueva src/pages/Records.tsx solo tras terminar el modelo y permisos.
6. Dashboard y reportes por rol: citas, ingresos cobrados, ventas, anulaciones, gastos, sesiones pendientes; cada indicador con definición de cálculo y filtro de sucursal/periodo (src/pages/Dashboard.tsx, Reports.tsx).

Aceptación: con datos sintéticos, un recorrido completo prospecto→cita→servicio→cobro→nota→cierre funciona para roles pertinentes; un rol no autorizado no puede ver ni modificar otros datos.

Fase 3 — Migración controlada desde Excel/CSV (P1)

1. Catalogar cada libro/hoja real, columnas, período, responsable, calidad y destino; no asumir que TRANSFERENCIAS equivale a gastos. Obtener archivos de fuente autorizada sin publicarlos.
2. Definir reglas de normalización (teléfono, nombre, sucursal, fechas/hora, importes y moneda), identificadores de origen y deduplicación revisable; casos ambiguos a cuarentena, nunca fusión silenciosa.
3. Extender src/pages/Import.tsx o crear proceso de staging de backend para vista previa, validación, dry-run, errores por fila, lotes idempotentes y manifiesto de importación. Si XLSX es necesario, añadir parser con tests; no confundir CSV con soporte Excel.
4. Ensayar carga a staging restaurable: conteos por hoja/tabla, montos y fechas conciliados, muestreo manual, permisos, cancelación y reejecución sin duplicados. Aprobar reconciliación por responsable del cliente antes de producción.
5. Ejecutar importación real en ventana acordada, conservar origen inmutable, registrar lote y poder revertir por lote sin borrar registros preexistentes.

Aceptación: reporte antes/después de conteos, rechazos y totales firmado; reejecución idempotente y rollback probado.

Fase 4 — UX, operación y lanzamiento (P1/P2)

• Entrevistar a recepción, caja y cosmetólogas sobre tareas de alta frecuencia. Definir navegación por rol y estados vacío/cargando/error/éxito, accesibilidad, tablet de recepción y teclado. Antes de elegir dirección visual, inspeccionar referencias actuales (DesignRush y otras), traducir principios, no copiar diseños; prototipar una ficha de paciente + agenda y pedir aprobación.
• Añadir pruebas de componentes y flujos E2E en repo elegido (src/**/*.test.ts(x), e2e/*.spec.ts; elegir runner tras auditoría), CI con lint/build/tests y pruebas de RLS con cuentas sintéticas.
• Configurar ambientes staging/producción separados, migraciones en CI, headers apropiados, observabilidad sin datos clínicos, alertas, backups/restore y guía de soporte. Documentar RPO/RTO acordados, capacitación por rol y pilotaje de una sucursal antes del despliegue general.
• Liberación por etapas con plan de reversión, criterios de suspensión ante fuga, discrepancia monetaria o error de agenda; documentar quién autoriza salida y quién atiende incidentes.

Hitos y criterios de decisión

Riesgos y preguntas abiertas

• ¿Cuál repositorio/commit y Supabase sirven hoy el dominio? No se ha verificado la web ni se dispone del esquema/datos de producción.
• ¿Existe conexión entre ambas aplicaciones o son prototipos independientes? No mezclar ni sobrescribir datos hasta aclararlo.
• ¿La clínica requiere expediente médico formal, fotos antes/después, firma, facturación fiscal, stock/paquetes o WhatsApp? Requerimientos y obligaciones a validar, no prometer de antemano.
• El repo HTML es público; su login local es inadecuado para datos reales. La exposición productiva sigue sin comprobarse.
• La wiki está afectada por mojibake y contiene un rol faltante; regenerarla en UTF-8 y convertirla en requisitos versionados con decisiones explícitas.

Primera acción verificable

En la primera sesión de reanudación, obtener solo metadatos, no expedientes: URL del despliegue, repo/commit conectado, proyecto Supabase (identificador no secreto), responsables y datos reales sí/no. Producir docs/architecture/current-state.md y ejecutar baseline del repo elegido. Esto permite confirmar o corregir la arquitectura propuesta antes de modificar código.