4  Anexo C

4.1 Modelo de datos y persistencia

Eduardo Martínez

4.2 Proposito del anexo

Este anexo describe el modelo de datos de AdminG Systems, sus entidades principales, sus relaciones, las garantias de consistencia y la forma en que el almacenamiento soporta los requerimientos definidos en el Chapter 2 y la arquitectura del Chapter 3. La base actual usa SQLAlchemy y migraciones Alembic, con SQLite como persistencia inicial para desarrollo y despliegue controlado en VM. Para una operacion productiva con mayor concurrencia, se requiere migrar a PostgreSQL.

El modelo no solo guarda informacion. Tambien expresa reglas de negocio: que usuario posee clientes, que plan habilita caracteristicas, que cita puede generar pagos, que factura puede relacionarse con items, que inventario registra movimientos y que autorizaciones o documentos agregan trazabilidad.

4.3 Entidades principales

La entidad User representa el sujeto de acceso al sistema. Contiene correo, contrasena hasheada, rol, plan, estado, jerarquia de usuario padre y datos de negocio. A partir de ella se organizan clientes, pagos, inventario, configuraciones, documentos y usuarios de equipo. RefreshToken permite renovar sesiones sin exponer credenciales.

Customer representa la informacion de clientes. Puede conectarse con mascotas o entidades relacionadas, citas, pagos, CRM y documentos. Appointment administra agenda, servicios, estados y relacion con clientes. Service y ServicePackage permiten separar servicios individuales de paquetes comerciales.

El bloque financiero esta formado por Payment, PaymentItem, CashRegisterSession, CashTransaction, Invoice, InvoiceItem y Authorization. Esta separacion evita que un pago sea confundido con una factura o con una sesion de caja. Una factura documenta una obligacion o venta; un pago registra el movimiento economico; caja agrupa movimientos en una jornada; autorizaciones registran aprobaciones.

Inventario se organiza con InventoryCategory, InventoryItem, InventoryMovement e inventario especializado cuando aplica. Esta estructura permite controlar SKU, stock minimo, entradas, salidas y trazabilidad del producto. Planes se modela con Plan, PlanLimit y PlanFeature, lo que permite activar funciones sin modificar el nucleo de usuario.

4.4 Modelo entidad-relacion

4.5 Gestión de usuarios y subscripciones

Este subconjunto modela la autenticación, delegación de usuarios y control de capacidades según el plan contratado. Constituye la base de acceso y gobierno funcional de la plataforma.

4.5.1 Autenticación

El modelo de autenticación se basa en la entidad User, que almacena credenciales, rol, plan y jerarquía. RefreshToken permite renovar sesiones sin exponer contraseñas. La relación entre User y Plan habilita o restringe características según la suscripción. La entidad TeamUser facilita la delegación de acceso dentro de una organización, permitiendo queun usuario principal administre subusuarios con permisos específicos. Esta estructura soporta un control de acceso granular.

4.5.2 Delegación

La relación TEAM_USERS permite que un usuario principal delegue acceso a otros usuarios dentro de su organización. Esto es crucial para empresas que requieren múltiples usuarios con diferentes niveles de acceso. Por ejemplo, un gerente puede tener acceso completo, mientras que un empleado solo puede gestionar clientes o citas.

4.5.3 Capacidades por plan

La relación PLANS con PLAN_LIMITS y PLAN_FEATURES permite definir y habilitar características específicas según el plan contratado por cada usuario.

4.6 Clientes y gestión comercial

Modela la relación entre clientes, mascotas, citas y eventos de seguimiento comercial

4.7 Servicios y operación

Modela la ejecución de servicios, reservas, paquetes comerciales y la generación de transacciones derivadas de la operación diaria.

4.8 Facturación y caja

Agrupa la lógica financiera de la plataforma, permitiendo el registro de cobros, facturación, conciliación de pagos y control de caja.

4.9 Inventario

Representa la clasificación, control y trazabilidad de los elementos inventariables

4.10 Documentación y auditoría

4.11 Normalizacion y consistencia

El modelo separa entidades con responsabilidades distintas. Plan no almacena todas sus reglas en una columna extensa, sino que delega limites y caracteristicas a tablas relacionadas. Payment no debe reemplazar a Invoice, porque el documento legal y el movimiento de dinero tienen ciclos de vida diferentes. InventoryMovement evita sobrescribir la historia del stock: cada entrada o salida queda registrada.

Las garantias ACID se aplican especialmente en pagos, facturas e inventario. Si una factura descarga inventario y registra un pago, la operacion debe confirmarse completa o revertirse completa. SQLAlchemy facilita esta unidad de trabajo mediante sesiones y commits controlados. Las claves foraneas y validaciones de schemas reducen inconsistencias entre clientes, citas, pagos y usuarios.

4.12 Persistencia en VM y crecimiento

En la etapa evidenciada por las capturas, SQLite es util porque simplifica el despliegue en Oracle Free Tier. El archivo app.db puede vivir en disco persistente de la VM, con copias de seguridad programadas. Sin embargo, el uso de SQLite requiere prudencia: no es ideal para alta concurrencia, multiples instancias o analitica pesada. La ruta de evolucion natural es PostgreSQL, conservando SQLAlchemy y Alembic para minimizar cambios.

4.13 Informacion para gestionar e introducir

• Indicar ruta real de app.db en la VM Ubuntu.
• Documentar politica de backup: frecuencia, ubicacion y prueba de restauracion.
• Confirmar si se mantiene SQLite o se migra a PostgreSQL.
• Insertar captura del dashboard donde se observan clientes, citas, productos e ingresos.

4.14 Diccionario resumido

Entidad	Funcion
User	Identidad, rol, plan y jerarquia.
Customer	Cliente administrado por usuario u organizacion.
Appointment	Agenda y relacion con servicios.
Payment	Movimiento economico y estado de pago.
Invoice	Documento comercial/fiscal con items.
InventoryItem	Producto o SKU con stock.
InventoryMovement	Historial de entradas y salidas.
PlanFeature	Caracteristica habilitada por plan.
Authorization	Aprobacion formal de acciones sensibles.
AuditLog	Evidencia de cambios y trazabilidad.

4.15 Cierre

El modelo de datos de AdminG es el puente entre la arquitectura y la operacion real. Si las entidades se mantienen separadas, las reglas de negocio pueden crecer sin duplicidad. El proximo anexo toma este modelo como base para definir pruebas, seguridad, control de cambios y criterios de calidad.