# Arquitectura de datos y persistencia

## Objetivo

Definir las reglas de persistencia, integridad y evolución de datos. MariaDB y Sequelize son tecnologías objetivo documentadas; este documento no afirma su instalación efectiva.

## Límites de persistencia

Sequelize y sus modelos permanecen en Infrastructure; no forman contratos públicos ni se acceden desde Domain o Application. Cada repositorio gestiona un agregado o responsabilidad concreta y usa un mapper bidireccional por agregado:

```ts
toPersistence();
toDomain();
```

El mapper traduce representación de dominio y persistida, sin añadir lógica de negocio. Infrastructure reconstruye entidades mediante `rehydrate()`.

## Transacciones e integridad

Las operaciones agregadas se ejecutan en transacción cuando deben ser atómicas. Al modificar persistencia o lógica transaccional se comprueban atomicidad, consistencia, rollback, concurrencia, aislamiento, integridad referencial y compatibilidad con datos existentes. Una escritura satisfactoria no garantiza por sí sola que haya terminado la operación funcional completa.

Las invariantes críticas se refuerzan también en base de datos cuando resulte razonable. Las consultas y mutaciones preservan el aislamiento por `companyId` y `branchId` cuando corresponda y usan consultas parametrizadas o APIs seguras de Sequelize.

## Concurrencia e idempotencia

Las operaciones repetibles —comandos, peticiones reenviadas, reintentos, creaciones, integraciones, migraciones y actualizaciones— deben ser idempotentes cuando su semántica lo requiera. Una repetición accidental no produce efectos duplicados.

No usar `JSON.stringify` para detectar cambios de dominio; los Value Objects se comparan semánticamente mediante primitivas o métodos de igualdad apropiados.

## Migraciones e histórico

Los cambios estructurales se realizan mediante mecanismos controlados. Las migraciones preservan datos e histórico, no exigen reintroducción manual de información y son idempotentes cuando el procedimiento lo requiera. No eliminar columnas, tablas o datos legacy sin auditoría previa.

Las actualizaciones no destruyen ni sobrescriben datos operativos o históricos. Antes de un cambio estructural debe existir copia de seguridad recuperable; cuando corresponda, la actualización realiza copia automática y permite restauración o rollback sin depender de conocimientos técnicos del usuario Máster. Las migraciones y actualizaciones quedan registradas. Los cambios relevantes se validan en Beta antes de Producción.

No se elimina físicamente información con histórico cuando proceda desactivarla, incluidos tareas y grupos funcionales. Deben preservarse usuarios, expedientes, OF, tareas, imputaciones, errores, históricos, actividad, configuraciones y trazabilidad.

## Referencias

- [Ficha del proyecto UECKO](../Ficha%20del%20proyecto%20UECKO.md)
- [Arquitectura backend](backend.md)