# 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

| Hito | Evidencia exigida | Decisión |
| --- | --- | --- |
| H0: diagnóstico | despliegue real + mapa de datos + baseline + exposición evaluada | elegir repo canónico y contención |
| H1: seguridad | RLS/Storage por rol y sucursal, respaldo/restauración probados | habilitar pruebas con datos sintéticos |
| H2: piloto | recorrido clínico/comercial E2E y cierres conciliados | autorizar piloto limitado |
| H3: migración | dry-run, anomalías revisadas y reconciliación firmada | aprobar carga productiva |
| H4: lanzamiento | monitoreo, capacitación, rollback y aceptación operativa | expandir sucursales |

## 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.