3.1 KiB
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 deben permanecer en Infrastructure; no forman contratos públicos ni se acceden desde Domain o Application. Los nombres de tablas y columnas deben mantenerse coherentes con las convenciones existentes del proyecto. Cada repositorio gestiona un agregado o responsabilidad concreta y usa un mapper bidireccional por agregado:
toPersistence();
toDomain();
El mapper debe traducir representación de dominio y persistida, sin añadir lógica de negocio. Infrastructure reconstruye entidades mediante rehydrate().
Transacciones e integridad
Las operaciones agregadas deben ejecutarse 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 deben preservar el aislamiento por companyId y branchId cuando corresponda y usar 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 reglas funcionales de continuidad del histórico, actualización sin pérdida, backup, rollback y validación Beta se definen en la Ficha del proyecto UECKO. Para cumplirlas, la persistencia debe proporcionar mecanismos técnicos de copia recuperable y restauración o rollback antes de cambios estructurales cuando corresponda; las migraciones y actualizaciones deben quedar registradas. Los cambios relevantes deben poder validarse 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.