metis-desk/docs/recursos-campos-y-plantillas.md

# Recursos, campos y plantillas

## Uso

El catálogo global de recursos se abre desde Catálogos globales → Catálogo de recursos. Cada compañía dispone de Recursos, para registrar elementos concretos, y Catálogo de recursos, para añadir definiciones propias y ajustar la disponibilidad.

Campos y plantillas de recursos son independientes de los de activos. Aunque se llamen igual, tienen UUID, datos, disponibilidad y referencias diferentes. El servidor rechaza campos de activos en plantillas de recursos y plantillas de activos al registrar recursos, y viceversa. El módulo resources no depende del módulo assets.

Las altas y ediciones se abren en modal desde la cabecera o una acción explícita del listado. La ayuda está antes del pie con Guardar y Cancelar. Los selectores de campo y plantilla ofrecen alta rápida mediante SelectWithAction. Se permite un modal adicional; ese formulario no abre un tercer nivel. Una definición guardada permanece aunque se cancele el formulario principal.

## Definiciones y ámbitos

Un campo representa una característica reutilizable de recursos. Admite texto, número, fecha, sí/no o lista de valores; nombre obligatorio, descripción y unidad opcionales. El tipo queda fijo tras el alta. En las listas se pueden añadir valores, pero no retirar los existentes.

Una plantilla reúne campos de recursos. Las plantillas propias pueden declarar uso Aplicación o Certificado digital para sus configuraciones por perfil; General conserva el comportamiento anterior. El uso queda fijo al crearla y las copias de serie heredan su uso, sin deducirlo por nombre. Aplicaciones y certificados por perfil están implementados. La caducidad de un certificado se consulta desde el recurso, sin duplicarse en el perfil. Los campos comienzan como opcionales; en plantillas propias pueden marcarse obligatorios. Se puede retirar un campo de una plantilla sin borrar su definición.

Hay definiciones globales y adiciones por compañía. Una plantilla global solo admite campos globales. Una plantilla local admite campos globales y de su propia compañía. Los nombres del mismo tipo no se duplican en el catálogo visible, ignorando mayúsculas y espacios exteriores.

Cada compañía puede activar o desactivar una definición global para su ámbito. Usar configuración global elimina el efecto del ajuste local. Las plantillas de serie se pueden editar desde el catálogo global; los campos de serie también se pueden editar globalmente, conservando su tipo y sus opciones existentes. Para personalizar una plantilla exclusivamente para una compañía, se puede crear una copia. No hay borrado físico.

## Datos de serie

Se incluyen 20 campos y seis plantillas:

| Plantilla | Campos |
| --- | --- |
| Buzón de correo | Dirección de correo, proveedor y contexto |
| Carpeta compartida | Ruta UNC, servidor como referencia documental y descripción |
| Aplicación | Proveedor, URL y descripción |
| Certificado digital | Titular, emisor, caducidad, huella digital y finalidad |
| Licencia de software | Producto, edición o plan, proveedor, modalidad, criterio de licenciamiento, cantidad contratada, referencia, caducidad, fecha de renovación, renovación automática y descripción |
| Recurso de acceso | Referencia; contexto estructurado de tipo de acceso, sistema y entorno |

Las características de serie son opcionales salvo la dirección válida exigida al registrar un buzón. Los datos se alimentan con claves de serie estables: reiniciar no duplica definiciones, cambia UUID ni reactiva elementos desactivados. No se crean recursos, personas o compañías de ejemplo.

Se validan tipos, fechas, listas y dirección de correo de los buzones. La dirección se normaliza a minúsculas y es única en la compañía, incluso para buzones inactivos. URL y ruta UNC siguen siendo texto sin vínculos estructurados con servidores. No se almacenan contraseñas ni claves privadas como funcionalidades de este catálogo.

## Recursos registrados

Un recurso pertenece a una compañía y tiene nombre, plantilla, estado activo, notas y características. No se pide persona, puesto ni dispositivo. Registrar un recurso no concede permisos ni configura equipos.

La plantilla queda fija tras el alta. Su especificación se captura al crear el recurso: nombres de campos, tipos, unidades, listas y obligatoriedad. Cambiar después el catálogo no reescribe las fichas ya registradas. Una plantilla desactivada impide nuevas altas, pero permite consultar y editar los recursos existentes con su especificación original.

El nombre es único dentro de compañía y plantilla, incluyendo recursos inactivos. Los recursos de acceso distinguen además tipo, sistema y entorno para conservar los contextos existentes. Las modificaciones conservan UUID y añaden revisión con fecha y usuario de Metis Desk. Repetir una edición equivalente no añade historial.

## Arquitectura y persistencia

ResourceCatalog es AggregateRoot. ResourceDefinition, TemplateField y CatalogAvailability son DomainEntity con UUID propio. ResourceDefinitionValues encapsula definiciones inmutables y referencias como UniqueID.

Resource es AggregateRoot y ResourceRevision es DomainEntity. ResourceSpecification y ResourceValues son Value Objects con comparación semántica. Nuevas raíces, definiciones, asociaciones, ajustes y revisiones reciben UUID v7.

Las tablas resource_catalogs, resource_definitions, resource_template_fields, resource_availability, resources y resource_revisions son independientes de las tablas de activos. Las migraciones son explícitas e idempotentes, con claves foráneas. Las escrituras se realizan en transacción bloqueando el catálogo global y después la compañía. El mapper reconstruye valores y verifica referencias, ámbito, especificación y última revisión.

GET /api/resource-catalog/:scope consulta definiciones; POST en esa ruta crea; POST /api/resource-catalog/:scope/:id/update edita; POST /api/resource-catalog/:scope/:id/status ajusta disponibilidad. scope es global o UUID de compañía.

GET /api/resources/:companyId lista recursos; POST en esa ruta crea; POST /api/resources/:companyId/:id/update edita. Todas las rutas requieren sesión. Las escrituras exigen origen y token CSRF; el actor procede de la sesión.

## Migración de buzones y recursos de acceso: implementada

Al iniciar el servidor, después de las migraciones de correo y perfiles, se traspasan todos los buzones y los recursos básicos de Cuentas y accesos. El proceso usa una transacción y bloquea catálogo y compañías en orden estable. Reiniciar no duplica registros ni añade revisiones. Una colisión de identidad, un historial inválido o una última revisión incoherente detiene el traspaso y revierte la transacción.

Cada recurso conserva su UUID original; cada revisión conserva UUID, actor, fecha, orden y valores equivalentes. No se crea una revisión artificial de migración. Los usos del buzón, configuraciones de correo, permisos, necesidades, cobertura y carpetas de perfiles conservan sus referencias.

Correspondencias:
- Buzón → plantilla Buzón de correo; dirección y contexto pasan a características. Tipo corporativo/externo y cuenta relacionada opcional se conservan como contexto estructurado. El nombre inicial es la dirección (hasta 100 caracteres; la dirección completa permanece en su campo).
- Recurso básico → plantilla Recurso de acceso; referencia pasa a característica. Nombre, notas, estado, tipo de acceso, sistema y entorno se conservan. No se deduce una plantilla especializada por su nombre o tipo.

La ficha editable y su historial pertenecen a Resource. La integración es parte de ResourceValues, con campos estrictos y comparación semántica. El tipo de buzón, los identificadores de sus campos y el contexto de acceso quedan fijos; la cuenta documental del buzón puede cambiar con historial.

En la interfaz desaparecen el listado Buzones de correo y la pestaña Recursos de Cuentas y accesos. Todos se crean y editan en Recursos mediante modal. La ficha de un buzón permite vincular personas o finalizar su uso. Las altas rápidas de buzón o recurso desde otros formularios guardan también en el nuevo modelo.

Para conservar las claves foráneas y los lectores actuales de permisos y perfiles, mailboxes/mailbox_revisions y access_items/access_revisions de tipo resource se mantienen como proyecciones de compatibilidad. El adaptador de infraestructura de resources actualiza estas proyecciones en la misma transacción que la ficha; solo añade nuevas revisiones y nunca reescribe las originales. No son un segundo catálogo editable. Las antiguas rutas de escritura de buzón y recurso básico devuelven 409 RESOURCE_MOVED; consultas, usos, permisos y configuraciones continúan disponibles.

POP/IMAP pertenece a la configuración de correo por perfil; letras de unidad pertenecen al mapeo de carpetas. No se incorporan a los campos del recurso común. La migración no configura equipos ni concede o retira permisos reales.

## Validación

Las pruebas con MariaDB de test comprueban UUID y revisiones originales, repetición idempotente, edición canónica y actualización de proyecciones, aislamiento por compañía y rechazo de escrituras antiguas. Se mantienen las pruebas de múltiples correos, permisos, necesidades, cobertura y perfiles. Las pruebas de dominio cubren correo inválido o ausente, normalización, cuenta opcional, cambio auditado y tipo fijo.

La comprobación en navegador usa los datos existentes de desarrollo, sin crear registros ficticios: ficha, historial, personas vinculadas, edición modal y selectores.

## Licencias de software: registro implementado

Una licencia es un Resource de la compañía creado con la plantilla de serie Licencia de software. Se registra en Recursos → Nuevo recurso, seleccionando esa plantilla; no constituye un activo ni una instalación de aplicación. Ejemplos: Microsoft 365 Business Standard, ESET Endpoint contratado para la empresa o licencia perpetua de ERP.

Nombre, plantilla y estado siguen el contrato común. Todas las características de esta plantilla son opcionales. Modalidad ofrece Suscripción, Perpetua, OEM y Otra; criterio ofrece Por usuario, Por dispositivo, Por servidor, Concurrente, Corporativa y Otro. Cantidad contratada es una característica numérica documental; no representa plazas libres ni impone aún reglas de asignación. Caducidad y fecha de renovación se registran independientemente. Renovación automática distingue sí, no y sin datos. No almacenar claves de activación.

Se reutilizan proveedor, referencia, caducidad y descripción del catálogo de recursos. Los siete campos nuevos y la plantilla se incorporan de forma idempotente al arrancar, sin cambiar identidades, fichas existentes ni disponibilidad configurada. La plantilla de serie se puede editar globalmente o copiar para personalizarla en una compañía; se puede desactivar globalmente o para una compañía. La ayuda específica aparece al final del modal, antes de Guardar y Cancelar.

La ficha captura su especificación y conserva revisiones como cualquier recurso. Registrar una licencia no crea asignaciones, vínculos con aplicaciones/cuentas/equipos, avisos de vencimiento ni cálculos de capacidad. Estas relaciones y avisos quedan pendientes de una entrega posterior.

## Organización de campos

Las plantillas permiten organizar campos en secciones ordenadas, globales o propias de compañía. Consultar [Secciones de campos en plantillas](secciones-de-campos-en-plantillas.md) para las reglas, presentación y conservación de datos existentes.


## Persistencia relacional

El catálogo, las especificaciones congeladas y los valores actuales e históricos de recursos se almacenan en columnas y tablas relacionadas. Véase [normalización de la persistencia](normalizacion-de-la-persistencia.md).

El arranque añade únicamente las definiciones ausentes y no sobrescribe las plantillas existentes. Las ediciones conservan UUID y clave de serie; el uso especializado de la plantilla permanece fijo. Los recursos ya creados conservan su especificación capturada, incluso si posteriormente se retiran campos de la plantilla.