metis-desk/docs/cuentas-grupos-y-recursos.md

# Cuentas, grupos, recursos y necesidades

## Dónde se gestionan

- Catálogos informáticos, en la navegación principal: sistemas, tipos de recurso, permisos disponibles y plantillas de grupos comunes.
- Compañías → ficha → Cuentas y accesos: cuentas, relaciones con personas, grupos, miembros, recursos, permisos concedidos, necesidades, cobertura y entornos. También permite añadir sistemas, tipos y permisos propios de la compañía.
- Los botones de alta están a la derecha de la cabecera. Los formularios sencillos se abren en modal; los extensos sustituyen el listado por una página de formulario. Edición e historial son acciones explícitas.

Los catálogos comienzan vacíos. Definir primero los sistemas comunes que se utilicen, como Dominio, Correo, Microsoft 365 o ERP. Las altas posteriores seleccionan esas definiciones; no se crean datos de ejemplo en la base de trabajo.

## Orden práctico

1. Definir sistemas, tipos de recurso y permisos en los catálogos globales. Las compañías pueden añadir elementos propios sin sustituir los globales.
2. Crear entornos de la compañía cuando haga falta distinguir dominios o instalaciones del mismo sistema.
3. Registrar cuentas y vincular sus titulares, personas autorizadas o responsables.
4. Crear grupos, opcionalmente desde una plantilla global, y registrar pertenencias de cuentas.
5. Registrar recursos y los permisos concedidos directamente a cuentas o mediante grupos.
6. Registrar las necesidades de las personas y vincular las vías que las cubren.

Una persona de la compañía no obtiene acceso a Metis Desk. Estos registros documentan sus cuentas en otros sistemas; no crean cuentas externas ni cambian permisos en esos sistemas.

## Catálogos y entornos

Los sistemas, tipos de recurso y permisos pueden ser globales o propios de una compañía. El selector combina ambos ámbitos. Los nombres no se duplican en la lista visible, ignorando mayúsculas y espacios exteriores. Los permisos se distinguen por su tipo de recurso.

Los entornos pertenecen a una compañía y un sistema. Su elección es opcional. Sus nombres son únicos dentro de esa combinación. Un entorno no se traslada a otro sistema.

Desactivar una definición impide seleccionarla en nuevas altas, pero conserva los registros existentes. Los registros afectados se señalan para revisar. No hay borrado físico ni desactivación en cascada.

## Cuentas

Datos: compañía, sistema, entorno opcional, identificador de acceso, uso personal/compartido/técnico, estado activo, caducidad opcional y observaciones.

Compañía, sistema, entorno y uso quedan fijos. El identificador, estado, caducidad y observaciones pueden cambiar, conservando UUID e historial.

La combinación compañía + sistema + entorno + identificador es única, incluyendo cuentas inactivas. El identificador distingue mayúsculas y minúsculas; se eliminan los espacios exteriores.

- Personal: como máximo un titular simultáneo. Puede registrarse sin titular y aparecerá pendiente de completar.
- Compartida: varias personas autorizadas. Sin ninguna relación abierta aparece pendiente de completar.
- Técnica: responsable opcional y único simultáneamente. La responsabilidad no concede acceso.

Los cambios de titular, personas autorizadas y responsables conservan periodos independientes. Los periodos incompatibles no se solapan. El nuevo titular puede registrarse aunque quede pendiente retirar el acceso anterior.

Las nuevas relaciones de acceso requieren una cuenta activa y no caducada. Una responsabilidad técnica puede registrarse sobre una cuenta inactiva o caducada. Las personas deben estar activas y pertenecer a la misma compañía.

Una fecha vencida no desactiva automáticamente la cuenta: genera un aviso si sigue registrada como activa. La caducidad es válida hasta el final de la fecha indicada. El cálculo de fecha de referencia utiliza UTC, igual que los timestamps del servidor.

Las contraseñas y secretos no forman parte de los campos de las cuentas.

## Grupos y plantillas

Cada grupo pertenece a una compañía, sistema y entorno opcional. Tiene nombre visible, identificador real en el sistema, descripción opcional y estado activo. Compañía, sistema y entorno no cambian tras el alta.

El identificador es único dentro de su compañía, sistema y entorno, incluso estando inactivo. Distingue mayúsculas y minúsculas como los identificadores de cuentas.

Las plantillas globales proponen nombre, descripción y sistema opcional. Al elegir una plantilla se copian esos valores y se permite personalizarlos. Cambiar la plantilla no modifica grupos existentes. Una plantilla no contiene miembros ni permisos.

Los miembros son cuentas del mismo sistema y entorno. No hay grupos anidados. Los grupos pueden estar vacíos. Desactivar un grupo conserva sus pertenencias y señala las abiertas para revisar.

## Periodos y configuración

Cada relación tiene UUID, fecha de inicio y fecha de fin opcional. Sin fecha de fin está abierta; con fecha de fin está cerrada. Las fechas documentan periodos: no hay un planificador de activaciones o cierres futuros. Un periodo puede terminar el mismo día que comienza el siguiente.

Las autorizaciones de personas, pertenencias a grupos y permisos concedidos distinguen:

| Estado de configuración | Significado |
| --- | --- |
| Pendiente de configurar | Autorización registrada; falta realizar la configuración |
| Configurada | Se ha registrado que la configuración está realizada |
| Pendiente de retirar | Autorización cerrada; falta eliminar el acceso |
| Retirada | Se ha confirmado su eliminación |
| Cerrada sin configurar | Terminó antes de llegar a configurarse |

Cerrar una relación configurada pasa automáticamente a pendiente de retirar. La confirmación de retirada se registra después, editando la relación. Cerrar una relación pendiente la deja cerrada sin configurar. Un alta puede indicar que el acceso ya estaba configurado.

No se permite marcar retirada una relación abierta. Las responsabilidades técnicas no llevan estado de configuración. No hay duplicados abiertos ni periodos solapados para la misma relación; titulares y responsables únicos tampoco se solapan entre personas diferentes.

Cada cambio registra una revisión con UUID, fecha y usuario de Metis Desk. La interfaz muestra el nombre del usuario. Las revisiones anteriores se conservan y repetir una edición semánticamente idéntica no añade historial.

## Recursos y permisos

Cada recurso tiene nombre, tipo, estado, ubicación o referencia opcional, sistema y entorno opcionales y observaciones. Puede existir antes de inventariar el activo que lo aloja. Su nombre es único por compañía, tipo, sistema y entorno.

La ubicación o referencia puede cambiar manteniendo el UUID. Tipo, sistema y entorno identifican el contexto del recurso y quedan fijos.

Los permisos disponibles se definen por tipo: lectura/modificación para carpetas, lectura/enviar como para buzones, etc. Son configurables globalmente y ampliables por compañía.

Cada autorización concede un permiso sobre un recurso a una cuenta o a un grupo, nunca a ambos en el mismo registro. Puede haber varios permisos distintos para el mismo destinatario. Solo admite permisos del tipo correspondiente. La compañía debe coincidir, aunque el sistema del recurso y el de la cuenta puedan ser distintos: por ejemplo, un NAS autenticado mediante el directorio corporativo.

No hay equivalencias entre permisos, herencia ni denegaciones. Administración no incluye Lectura automáticamente. Registrar un acceso no demuestra que exista en el sistema externo; la configuración se confirma manualmente.

## Necesidades y cobertura

Una necesidad relaciona una persona con un recurso y uno o varios permisos necesarios. Puede registrarse antes de conocer la cuenta que se utilizará. Conserva periodo, observaciones e historial.

Las vías de cobertura vinculan:

- Necesidad.
- Permiso concedido.
- Relación de la persona con su cuenta.
- Pertenencia al grupo, cuando el permiso se concede a través de un grupo.

El servidor comprueba que la persona, cuenta, recurso, permiso y grupo corresponden. Una responsabilidad técnica no sirve como relación de acceso.

La cobertura se calcula a partir de los vínculos registrados. Para estar cubierta, una necesidad abierta debe tener todos sus permisos cubiertos por vías autorizadas y configuradas. La persona, cuenta, recurso, permiso y grupo deben seguir habilitados; la cuenta no debe estar caducada. Una pertenencia retirada o cerrada deja de cubrirla.

Se admiten varias vías y la pérdida de una no deja la necesidad pendiente si otra cubre el mismo permiso. Los vínculos anteriores permanecen consultables. La lista indica qué permisos faltan.

Cerrar una necesidad no retira automáticamente accesos. Un permiso puede seguir sirviendo a otra necesidad o a otros miembros de un grupo. Una necesidad vinculada y autorizada justifica el permiso aunque su configuración esté pendiente. Los accesos sin una necesidad vigente que los justifique se señalan para revisar, sin calificarlos automáticamente como indebidos.

## Avisos

Se calculan al consultar los datos: cuentas incompletas o caducadas, personas inactivas con relaciones abiertas, destinos inactivos, catálogos desactivados, configuraciones y retiradas pendientes, necesidades sin cubrir y accesos sin necesidad cubierta.

Por ahora los avisos no generan tareas ni actúan sobre sistemas externos. Reactivar un elemento no restaura configuraciones ni relaciones cerradas.

## Arquitectura y persistencia

El módulo companies mantiene las capas de dominio, aplicación e infraestructura. AccessWorkspace es una raíz independiente para el catálogo global o la configuración informática de una compañía. Cada espacio tiene UUID propio. AccessItem representa una entidad tipada por su definición; AccessRevision es una entidad de historial. Ambas tienen UUID v7 para nuevas identidades.

AccessValues es un valor compuesto inmutable, con UUID, Name y CalendarDate reconstruidos como Value Objects y ausencia mediante Maybe. La definición discriminada y sus schemas viven en el dominio; los contratos HTTP comunes exponen esos valores sin importar ORM. Result representa fallos esperados.

MariaDB almacena:
- access_workspaces: identidad del agregado y ámbito de compañía.
- access_items: entidades con definición tipada serializada en JSON.
- access_revisions: versiones, secuencia, actor y timestamp.
- access_references y access_person_references: referencias relacionales para impedir huérfanos y conservar las dependencias.

Los JSON se validan y reconstruyen al cargar; no son bolsas de campos libres. No se aceptan claves desconocidas. La última revisión debe corresponder con el estado actual. Las revisiones se añaden, no se sobrescriben.

Las migraciones son explícitas e idempotentes. Los cambios se realizan dentro de transacciones, bloqueando primero el catálogo global y después la compañía. Esta serialización evita altas concurrentes duplicadas y colisiones entre catálogos globales y locales. Las pertenencias y reglas entre ámbitos se validan en el dominio.

La gestión usa GET /api/access/global o /api/access/:companyId. Las altas usan POST en esas rutas con {values}; las ediciones POST /api/access/:scope/:id/update. Todas requieren sesión válida. Las escrituras requieren origen y CSRF válidos. El actor se obtiene de la sesión, nunca del cuerpo enviado por el navegador.

## Validación

42 pruebas pasan en el proyecto, incluyendo reglas de dominio, contratos, renderizado de interfaz y HTTP con MariaDB. La integración usa exclusivamente metis_desk_test y comprueba aislamiento, UUID, duplicados, campos inmutables, historial, idempotencia, caducidad, responsabilidades técnicas, concurrencia y pérdida de cobertura al retirar una pertenencia.

Se ha comprobado en navegador el catálogo global, el selector combinado global/local, el alta de cuenta con entorno y caducidad, el vínculo con persona, su cierre automático como retirada pendiente, el historial con actor y las casillas de permisos necesarios.

Pasan typecheck, lint, test, check y build. La compilación conserva el aviso previo sobre el tamaño del paquete frontend.

## Pendiente para futuras entregas

Configuración por ordenador o móvil, POP/IMAP, teletrabajo y acceso remoto, inventario y modelos de activos, procesos y plantillas de alta/cambio/salida, relación con licencias e integraciones con sistemas externos.