metis-desk/docs/personas-y-departamentos.md

# Personas y departamentos

## Uso

Abrir una compañía y elegir Personas o Departamentos.

- Nueva persona, a la derecha de la cabecera, abre un modal. Nombre obligatorio; puesto general, email y teléfono opcionales. El estado activo y la marca Contacto de la compañía se editan por separado.
- El listado permite buscar por nombre y mostrar solo contactos. Abrir ficha muestra los datos de la persona y sus asignaciones.
- Nuevo departamento abre un modal con nombre y estado activo. Los nombres son únicos dentro de cada compañía, ignorando mayúsculas y espacios exteriores. No hay departamentos anidados.
- Desde la ficha de una persona, Asignar departamento abre un modal con departamento, puesto específico opcional, fecha de inicio, fecha de fin opcional y marca de departamento principal.
- Editar una asignación permite corregir su puesto, periodo o carácter principal. Historial muestra las versiones anteriores y cuándo se registraron.

Las personas de las compañías no tienen acceso a Metis Desk. No se crean usuarios ni contraseñas al dar de alta una persona. Un contacto es una persona marcada como contacto; no una segunda entidad ni una cuenta de acceso.

## Reglas

Una persona pertenece a una compañía y puede tener asignaciones a varios departamentos de esa misma compañía. Su puesto general es independiente del puesto en cada departamento. Los emails no identifican personas ni necesitan ser únicos.

Cada periodo tiene fecha de inicio y una fecha de fin opcional. Sin fecha de fin la asignación está abierta. Con fecha de fin está cerrada, aunque la fecha sea futura: en esta entrega las fechas documentan periodos y no hay un planificador que active o cierre asignaciones automáticamente.

Solo puede existir una asignación abierta por persona y departamento, y un único departamento principal entre las asignaciones abiertas de esa persona. Los periodos del mismo departamento no pueden solaparse. La fecha de fin marca el límite del periodo: una nueva asignación puede comenzar el mismo día que termina la anterior. No se permite una fecha de fin anterior al inicio. Una asignación cerrada no puede ser principal.

Para cambiar de puesto conservando periodos independientes, cerrar el periodo anterior y crear el siguiente. Corregir una asignación también conserva las versiones anteriores. Repetir una edición idéntica no añade una revisión.

Desactivar una persona o un departamento conserva sus asignaciones e historial. No permite nuevas asignaciones ni reabrir las cerradas; sí permite corregir o cerrar las existentes. La ficha de una persona inactiva avisa si quedan asignaciones abiertas. Reactivar no crea nuevas asignaciones automáticamente. No hay borrado físico.

## Identidad y compatibilidad

Company sigue siendo la raíz del agregado. Person, Department, DepartmentAssignment, AssignmentRevision y Site son entidades con UniqueID propio. Los nuevos identificadores son UUID v7; los anteriores se conservan.

Name, EmailAddress, PhoneNumber y CalendarDate encapsulan los valores. Maybe expresa la ausencia de datos opcionales. Result representa errores esperados. El dominio no depende de DTOs HTTP ni de Sequelize.

Los contactos existentes pasan a ser personas con isContact=true, conservando UUID, compañía y datos. La tabla company_contacts conserva su nombre para mantener los registros y relaciones. Las rutas antiguas de contactos siguen disponibles; la propiedad contacts de la respuesta contiene las personas marcadas como contacto.

Las tablas company_departments, person_department_assignments y department_assignment_revisions almacenan departamentos, periodos e historial. Las claves foráneas compuestas garantizan que persona y departamento pertenecen a la misma compañía. Cada escritura bloquea el agregado de compañía dentro de una transacción. Las revisiones se insertan y no se sobrescriben. Al cargar se comprueban valores, periodos, secuencia del historial y correspondencia de la última revisión con el estado actual.

Las migraciones son explícitas, conservan los datos y pueden ejecutarse de nuevo sin duplicar tablas o restricciones.

## API

Todas las rutas requieren sesión válida. Las escrituras requieren origen y token CSRF válidos. Las mutaciones devuelven la ficha completa de compañía.

| Método | Ruta | Operación |
| --- | --- | --- |
| POST | /api/companies/:companyId/people | Crear persona |
| POST | /api/companies/:companyId/people/:id/update | Editar persona |
| POST | /api/companies/:companyId/departments | Crear departamento |
| POST | /api/companies/:companyId/departments/:id/update | Editar departamento |
| POST | /api/companies/:companyId/people/:personId/assignments | Crear asignación |
| POST | /api/companies/:companyId/people/:personId/assignments/:id/update | Editar asignación |
| GET | /api/companies/:companyId | Consultar personas, departamentos, asignaciones, historial y sedes |

Las pertenencias cruzadas se rechazan. El departamento de una asignación existente no se traslada mediante edición; se cierra y se crea otra.

## Alcance de esta entrega

Implementado: personas, clasificación como contacto, departamentos, puestos específicos, departamento principal, periodos e historial de asignaciones.

Cuentas informáticas, grupos, recursos, autorizaciones y necesidades se gestionan en Cuentas y accesos de la compañía. No implican acceso de estas personas a Metis Desk.

Pendiente: configuración por dispositivos, teletrabajo, procesos y plantillas e inventario de activos. Los datos de estas funciones no se crean todavía.