metis-desk/docs/intervenciones-y-plantillas.md

# Intervenciones y plantillas

## Alcance implementado

Catálogo independiente de las plantillas de procesos de personas y de los catálogos de activos y recursos. Cada plantilla representa un procedimiento repetible. No almacena personas, equipos, cuentas ni accesos concretos de una compañía.

Disponible en Catálogos globales y en la sección Plantillas de intervención de cada compañía. La compañía ve las globales y sus propias plantillas. Las globales solo se editan desde su catálogo; copiarlas desde una compañía crea una variante local independiente.

## Datos y reglas

- Nombre obligatorio, hasta 160 caracteres, único en su ámbito incluso estando inactiva.
- Descripción opcional, hasta 4.000 caracteres.
- Activa/inactiva. No hay borrado; se conserva el historial.
- Entre 1 y 100 pasos ordenados. Cada paso tiene UUID, título obligatorio hasta 200 caracteres, instrucciones opcionales hasta 4.000 caracteres e indicador de comprobación obligatoria antes de finalizar.
- Los pasos admiten títulos iguales: se identifican por UUID, nunca por su texto.
- Crear y copiar genera UUID v7 para agregados, revisiones y pasos desde la interfaz. Reordenar o editar mantiene la identidad del paso.
- Copiar crea pasos con identidades nuevas y una plantilla activa, sin copiar su historial. Guardar exige un nombre que no exista en el ámbito destino.
- Compañía inmutable. Una variante se crea por copia.
- Las ediciones conservan instantáneas completas y ordenadas con actor y fecha. Un guardado sin cambios no añade revisiones.
- Alta idempotente mediante requestKey: el reintento devuelve la plantilla existente si coincide con los valores originales, actor y ámbito. Reutilizar la clave con otra información devuelve conflicto.
- Edición condicionada a expectedRevisionId: una edición desactualizada se rechaza sin sobrescribir cambios.
- Operaciones serializadas mediante bloqueo transaccional de catálogo y restricciones de claves en MariaDB.

## Datos iniciales

Se suministran seis procedimientos orientativos: alta de persona, baja de persona, sustitución de equipo, configuración de correo, preparación de portátil para teletrabajo y revisión periódica de equipo. Sus comprobaciones son inicialmente opcionales para permitir adaptación. Se pueden editar y desactivar.

Las claves de incorporación son estables: reiniciar o repetir la migración no duplica ni restaura los datos iniciales modificados. Nunca se incorporan datos operativos de compañías.

## UI

Listado con búsqueda, filtro de inactivas, ámbito y acciones de editar/copiar. Alta mediante botón en la cabecera derecha. Alta y edición en modal con pasos que se pueden añadir, quitar y mover arriba/abajo. Ayuda contextual inmediatamente antes del pie Guardar/Cancelar. Historial desplegable con las instantáneas completas. Textos es/en.

## Arquitectura y API

InterventionTemplate es AggregateRoot; InterventionTemplateValues es Value Object; InterventionTemplateStep e InterventionTemplateRevision son DomainEntity. Todo tiene identidad UniqueID.

- GET /api/intervention-templates/global
- GET /api/intervention-templates/:companyId (globales y propias)
- POST /api/intervention-templates/:scope
- POST /api/intervention-templates/:scope/:id/update

scope es global o UUID de compañía. Escritura: values, requestKey y expectedRevisionId (null en alta). Entrada estricta, autenticación, protección de origen y CSRF del servidor. La edición debe corresponder exactamente al ámbito de la URL.

Persistencia en intervention_templates e intervention_template_revisions; intervention_template_lock es un bloqueo técnico, no una entidad de negocio. Migración explícita e idempotente. Mapper bidireccional con validación del historial, posiciones, fechas y coherencia de última revisión.

## Intervenciones implementadas

Intervenciones por compañía y vista global en la barra de espacios (I). Búsqueda por referencia, asunto, compañía y técnico; filtros de estado, técnico, compañía y rango de fecha prevista. Sin filtros se muestran todas las pendientes, en curso, finalizadas y canceladas.

### Datos

- Compañía obligatoria e inmutable.
- UUID v7 y referencia global I-000001.
- Ticket opcional de la misma compañía. Un ticket admite varias intervenciones; una actuación interna no exige ticket.
- Asunto obligatorio (200 caracteres).
- Estado: pendiente, en curso, finalizada o cancelada.
- Técnico responsable opcional mientras esté pendiente/cancelada; obligatorio en curso/finalizada.
- Modalidad: remota, presencial u otra.
- Fecha prevista, inicio/fin reales opcionales. El fin no puede ser anterior al inicio.
- Tiempo manual en minutos enteros, opcional; null significa desconocido, cero es un valor conocido. No se calcula automáticamente por diferencia de fechas.
- Diagnóstico, trabajo realizado y resolución (10.000 caracteres cada uno). Trabajo realizado obligatorio para finalizar.
- Múltiples personas, puestos de trabajo, activos y recursos afectados de la misma compañía.
- Pasos opcionales con UUID, título, instrucciones, indicador obligatorio, estado (pendiente/en curso/hecho/no aplica) y notas.

### Procedimientos

Una intervención sencilla puede existir sin pasos ni plantilla. Los pasos pueden añadirse manualmente. En el alta se puede aplicar una plantilla global o de la compañía; Aplicar sustituye los pasos actuales, como indica el formulario, y genera nuevas identidades para la ejecución. Se pueden adaptar los pasos.

Se captura en InterventionProcedure la identidad y revisión de la plantilla junto con todos sus valores originales. Esta procedencia es inmutable; editar o desactivar la plantilla no cambia la intervención. La plantilla debe estar activa y la revisión elegida vigente al crear la intervención. El reintento de un alta ya guardada sigue devolviendo su intervención aunque la plantilla haya cambiado.

Finalizar exige técnico, trabajo realizado y que cada paso obligatorio esté hecho o marcado no aplica con motivo. Los pasos opcionales pendientes no bloquean. La ejecución de los pasos queda reflejada en el historial; la ficha identifica quién y cuándo pasó cada paso a hecho. Editar sus notas no cambia ese autor/fecha, pero reabrirlo y completarlo de nuevo sí.

No se modifican automáticamente cuentas, activos ni recursos al marcar un paso. Finalizar una intervención no cambia el estado del ticket. Se puede reabrir una intervención conservando su historial.

### Formularios y tickets

Alta y edición en modales con ayuda antes del pie. La selección de compañía queda fija al editar o iniciar desde un ticket. Cambiar la compañía en el alta limpia ticket, afectados, procedimiento y pasos. Seleccionar ticket propone asunto, afectados y técnico solo cuando esos campos están vacíos.

Desde un ticket se puede crear una intervención con asunto y afectados propuestos. La ficha del ticket consulta sus intervenciones relacionadas. Altas rápidas de compañía, ticket, plantilla y elementos afectados mediante SelectWithAction, manteniendo el borrador principal.

### Arquitectura y persistencia

Intervention es AggregateRoot; InterventionValues e InterventionProcedure son Value Objects; InterventionStep e InterventionRevision son DomainEntity con UUID. Igualdad semántica; el orden de pasos importa, el de afectados no.

Application valida compañía, ticket, técnico y afectados, admitiendo referencias inactivas ya existentes pero rechazando nuevas asignaciones a elementos inactivos. Collaboración con puertos del mismo módulo; el inventario se obtiene a través de los servicios públicos ya utilizados por tickets.

Persistencia en interventions e intervention_revisions con FK a compañía, ticket y técnico. intervention_counter es una secuencia técnica. Alta idempotente mediante requestKey, revisión esperada al editar y bloqueo transaccional para evitar sobrescrituras concurrentes. Snapshot e historial coherentes mediante mapper bidireccional. Migración explícita e idempotente.

API autenticada, protección de origen/CSRF y entrada estricta:
- GET /api/interventions (global)
- GET /api/interventions/:companyId
- GET /api/interventions/:companyId/lookups
- POST /api/interventions/:companyId
- POST /api/interventions/:companyId/:id/update

Escritura: values, requestKey, expectedRevisionId (null en alta) y template (null o id/revisionId durante el alta; null al editar). La procedencia aplicada no se cambia durante una edición.

## Validación

Pruebas de dominio y persistencia: límites, pasos repetidos por UUID, igualdad semántica, orden, no-op, fechas e historial. Pruebas web es/en, ayuda inferior, listado sin formulario y copia con identidades nuevas. Integración HTTP/MariaDB: autenticación, CSRF, origen, ámbitos, altas, duplicados, reintentos, edición, concurrencia, historial y conservación de datos iniciales tras repetir migraciones.


Las pruebas de intervenciones cubren actuaciones sencillas, requisitos de cierre, no aplicación justificada, fechas, minutos, historial, snapshots, idempotencia, concurrencia, compañía de ticket/afectados, procedimientos versionados, no cierre automático del ticket, filtros es/en y autor de finalización de pasos.