Modelo de datos¶

El Sistema de Premios corre sobre SQL Server, versionado con Flyway (V1 a V12 al momento de escribir esto). Esta página documenta el esquema real — columnas, tipos SQL Server e invariantes — tal como quedó tras aplicar todas las migraciones. Para el porqué de cada decisión de diseño (por qué una sola campaña vigente, por qué el acta es inmutable, por qué Cliente es un solo tipo) anda a Decisiones de arquitectura; acá vas a encontrar la forma, no el motivo.

Diagrama de entidades¶

Convenciones del esquema¶

• Nombres de tabla y columna: snake_case, en español (mismo vocabulario que CONTEXT.md del proyecto).
• PKs: BIGINT IDENTITY(1,1) en casi todas las tablas — la excepción es clave_firma, cuya PK es el propio key_id TINYINT (no hace falta un id sintético para una clave).
• Timestamps: DATETIME2, casi siempre NOT NULL DEFAULT SYSUTCDATETIME() para las marcas de auditoría (creado_en, fecha_registro, fecha_hora).
• Enums como VARCHAR + CHECK: el proyecto no usa tipos enumerados nativos de SQL Server; cada estado es un VARCHAR acotado por un CONSTRAINT ck_..._... CHECK (columna IN (...)). Se listan los valores válidos en cada tabla más abajo.
• Bloqueo optimista (version): premio_unidad, asignacion_premio, resultado_sorteo y cliente tienen una columna version BIGINT NOT NULL DEFAULT 0 (agregada en V9 y V12). Hibernate la incrementa en cada UPDATE; si otra transacción ya avanzó la fila, la operación falla con OptimisticLockException, traducido a 409 por el manejador de errores del gestor. Motivo: son las cuatro entidades que dos operadores del gestor pueden llegar a mutar en simultáneo (entrega, pase a suplente, devolución al stock, edición de cliente).
• Hash, nunca el dato sensible en claro: chance.hash_token, voucher_prueba.hash_token y reconocimiento_dispositivo.hash_reconocimiento persisten un CHAR(64) (SHA-256 hex) — nunca el token del QR ni el secreto de reconocimiento del dispositivo. Ver El token del QR para el detalle de cómo se calcula ese hash.

campania¶

La promoción completa. Solo puede existir una fila con estado = 'vigente' — invariante garantizada a nivel de base de datos, no solo en la capa de aplicación.

CREATE UNIQUE INDEX ux_campania_vigente ON campania (estado) WHERE estado = 'vigente';

sorteo¶

Cada evento de sorteo dentro de una campaña: los semanales más el de cierre.

premio_tipo¶

Catálogo de premios por tipo y cantidad ("Bicicleta playera × 10").

premio_unidad¶

Cada unidad física individual generada a partir de un premio_tipo.

asignacion_premio¶

Vincula una premio_unidad a un sorteo, con su orden de prelación.

cliente¶

El padrón. Una persona identificada por DNI — un único tipo de entidad tanto para quien participa del sorteo como para altas post-campaña (D5 del dominio: sin un tipo lead aparte).

chance¶

Una participación registrada: un voucher consumido + un DNI. Es la entidad de mayor volumen del sistema — tiene tres índices dedicados a los caminos calientes del motor de sorteo y el panel.

Índices de camino caliente: (cliente_id, campania_id, fecha_emision) y (campania_id, fecha_emision) para la ventana de elegibles del motor de sorteo y el tope diario (V2); (campania_id, fecha_registro) para las señales antifraude del panel (V7).

voucher_rechazado¶

Registro interno de todo voucher rechazado — nunca se le muestra al cliente el motivo real (mensaje siempre genérico), pero queda acá para antifraude y soporte.

El motivo bot (V4) es el honeypot: un campo invisible del formulario (contacto_web) que solo un bot llena — si llega no vacío, se registra acá y la respuesta es idéntica a la de Caso A.

acta¶

Snapshot inmutable y reproducible de la ejecución de un sorteo.

resultado_sorteo¶

Cada posición del acta: ganador o suplente, en orden.

contacto_ganador¶

Cada intento de contacto con un ganador o suplente — prueba frente al plazo de retiro.

clave_firma¶

Claves HMAC de firma del token, por key_id — permiten rotar sin cortar la emisión.

consentimiento_privacidad¶

Consentimiento permanente del cliente a comunicaciones — una fila por cliente.

aceptacion_bases¶

Aceptación de las bases y condiciones, por campaña y versión.

evento_premio¶

Auditoría de todo cambio de estado de una premio_unidad.

voucher_prueba¶

Auditoría de cada voucher generado por el modo prueba del gestor (nunca habilitable en producción — el bean del controller ni se registra sin el flag sp.modo-prueba.enabled).

reconocimiento_dispositivo¶

Agregada en V11 (ADR-027). Permite que la landing "reconozca" un dispositivo ya usado para saltar el tipeo del DNI en visitas siguientes, sin persistir el DNI en el navegador.

evento_dato_cliente¶

Agregada en V12 (ADR-028). Auditoría de todo cambio de dato de un cliente — nunca expuesta por la API pública, mismo criterio que voucher_rechazado.

Índices de soporte de FK¶

SQL Server, a diferencia de MySQL/InnoDB, no crea automáticamente un índice para cada foreign key. La migración V6__indices_fk.sql agrega un índice no-clustered dedicado a cada una de las 10 FKs que no tenían ya un índice compuesto cuyas columnas líderes coincidieran — sin esto, los joins contra la tabla referenciada podían forzar un table scan completo de la tabla hija.

Ver también¶

• El token del QR (Anexo A) — cómo se calcula chance.hash_token.
• API HTTP — superficie que lee y escribe sobre este esquema.
• Casos de participación (A–E) — el flujo de negocio que crea filas en chance, cliente y voucher_rechazado.
• El motor de sorteo y el acta — cómo se llenan acta y resultado_sorteo.