Glosario del dominio¶
El Sistema de Premios tiene un vocabulario propio, en español, que aparece por todos lados: en el modelo de datos, en los endpoints, en las bases del sorteo y en las conversaciones con Caracol. Esta página define los términos reales del sistema, agrupados por categoría, para que cuando los leas en el código, en un acta o en una reunión sepas exactamente de qué se habla. Muchos términos se apoyan en otros: si uno te lleva a otro, seguilo, porque el dominio es una red, no una lista suelta.
Fuente de autoridad
El vocabulario canónico vive en el CONTEXT.md del proyecto; el porqué de cada forma vive en las Decisiones de arquitectura (ADRs), referenciadas como (Dn/ADR-nnn). Cuando necesites el detalle de columnas, índices y estados, la referencia es el Modelo de datos.
Campaña y sorteos¶
La estructura sobre la que se monta todo: una promoción que contiene varios eventos de sorteo.
| Término | Definición |
|---|---|
| Campaña | La promoción completa (la "Sorteo 50 años"). Contiene N Sorteos y define los textos de la landing, la vigencia, la regla de chances, el tope diario, las bases (version_bases), la clave de firma vigente y el lote de premios. Solo puede existir una Campaña en estado vigente, garantizado a nivel base de datos (ADR-013). |
| Sorteo | Cada evento dentro de la Campaña: los semanales (Sorteo Semana 1..N) más el Sorteo de cierre. Tiene fecha y hora publicada —referencia en las bases, no un disparo automático—, premios asignados con prelación y, una vez ejecutado, su Acta. |
| promoId | Identificador de la promoción dentro del token (offset 1, 4 bytes), nativo del backoffice de Caracol (M1). Su política de asignación y reuso está DIFERIDA (ADR-014): fuera del alcance de esta entrega. |
El voucher y su token¶
El cupón físico y los datos firmados que viajan dentro del QR. Acá está el corazón de la idea "autocontenida".
| Término | Definición |
|---|---|
| Voucher | El cupón impreso en el ticket de compra con su QR. Es autocontenido: todo lo que la web necesita para validarlo viaja firmado dentro del token, sin sincronización cajas ↔ web. |
| Token | Los 35 caracteres de la URL del QR: base64url(datos[16 bytes] + HMAC-SHA256 truncada a 10 bytes). El layout normativo está en el Anexo A. En la base se persiste su hash, nunca el token en claro. |
| Codificación canónica | La forma única a la que se normaliza el token antes de validar o registrar. Garantiza que dos codificaciones del mismo voucher resuelvan al mismo registro, para que nadie saque doble chance por una variante de encoding. |
| Fecha de emisión | La fecha y hora en que la caja imprimió el voucher (offsets 8/10 del token). Es la fecha que manda: toda decisión temporal —vigencia, día del tope, a qué sorteo pertenece la chance— se resuelve por emisión, nunca por la fecha de registración (ADR-002). |
Participación: chances y clientes¶
Lo que ocurre cuando un cliente escanea un QR y participa.
| Término | Definición |
|---|---|
| Chance | Una participación registrada: voucher consumido + DNI. La regla de esta campaña es 1 voucher = 1 chance. Su fecha relevante es siempre la de emisión del ticket. |
| Cliente / Padrón | Una persona registrada por DNI (único). Hay un solo tipo Cliente, tanto para quien participa como para altas post-campaña (ADR-005); fecha_nacimiento, sexo y email son opcionales. El conjunto de clientes es el padrón, permanente y propio de Caracol. |
| Casos A–E | Los cinco resultados posibles de escanear un QR. Ver Los casos de participación para el flujo completo. En síntesis: A firma inválida (error genérico) · B token ya usado · C promoción no vigente por fecha de emisión (alta al padrón sin chance) · D vigente + DNI nuevo (alta + chance) · E vigente + DNI registrado (confirmación de un toque). |
| Tope diario | El máximo de chances por DNI por día de emisión (valor de esta campaña: 5). El voucher que lo supera se rechaza sin consumirse y se informa al cliente (ADR-006). |
| Consentimiento de privacidad | Permiso permanente, por Cliente: acepta la política de privacidad y las comunicaciones comerciales (ADR-007). |
| Aceptación de bases | Aceptación por Campaña: version_bases + fecha y hora. En las pantallas de participar, el botón de confirmar implica la aceptación (UX de un toque); el link "Bases y condiciones" está en el footer de todas las pantallas. |
El sorteo y el acta¶
Los términos del motor que decide ganadores de forma auditable. Profundizados en Motor de sorteo y acta.
| Término | Definición |
|---|---|
| Elegibles | Las chances que participan de un sorteo: las de la ventana [fecha_sorteo_anterior, fecha_sorteo_actual) por fecha de emisión (ADR-001), excluyendo los DNIs ya adjudicados en la Campaña (ADR-003). |
| Adjudicado | Un DNI que salió ganador en un acta, retire o no el premio. Queda excluido de los sorteos siguientes de la Campaña. Es distinto de "Otorgado" (que es el premio ya entregado): la exclusión es por haber sido sorteado, no por haber retirado. |
| Acta | El registro inmutable y reproducible de una ejecución de sorteo: lista ordenada de chance_id elegibles + hash + seed + algo@version + filtros + prelación + ganadores y suplentes. Cumple que lista + seed + algo@version → mismo resultado (ADR-004). |
| Prelación | El orden 1.º, 2.º, … de los premios asignados a un sorteo. Se corresponde 1 a 1 con el orden del acta: el primer sorteado se lleva el premio de prelación 1, y así. |
| Suplente | Una posición extra sorteada en la misma acta (10 por acta) que recibe el premio ante la incontactabilidad o el rechazo del titular, en orden. Un suplente promovido también pasa a ser adjudicado. |
Premios y su ciclo¶
Cómo se modela lo que se reparte. Profundizado en Premios y su ciclo de vida.
| Término | Definición |
|---|---|
| PremioTipo | La definición de un premio por tipo y cantidad ("Bicicleta playera × 10"). No es una unidad física: es la plantilla de la que el sistema genera las unidades. |
| PremioUnidad | La unidad física individual generada de un tipo. Recorre el ciclo Disponible → Asignado → Sorteado → Otorgado, más el terminal NO_OTORGADO. El stock_disponible es siempre el COUNT exacto de unidades en estado Disponible, nunca un contador paralelo que se pueda descuadrar. |
| NO_OTORGADO | El estado terminal de una unidad tras el cierre de la campaña: suplentes agotados o plazo de retiro vencido sin entrega, siempre con motivo y auditoría (ADR-008). Distinto de Disponible: cierra la unidad sin dejar stock fantasma. |
| Plazo de retiro | Los días que tiene el ganador para retirar el premio desde el primer contacto registrado (parámetro de esta campaña: 10 días corridos). Vencido, habilita la devolución al stock o el pase a NO_OTORGADO. |
Claves y seguridad¶
Los términos de la firma del token y su rotación.
| Término | Definición |
|---|---|
| ClaveFirma / keyId | El registro clave_firma(key_id, secreto_cifrado, estado, vigencia_*). El servidor valida contra la clave que indica el keyId (offset 0) del token, lo que permite rotar la clave sin corte de servicio (ADR-010). Es HMAC simétrico: el "keystore" es una tabla cifrada, no un JKS de PKI. El secreto se guarda cifrado at-rest, nunca en claro en repo ni logs. |
| Reconocimiento del dispositivo | Un mecanismo opcional para acelerar la segunda participación desde el mismo teléfono sin re-pedir el DNI. El backend emite un secreto opaco que el navegador guarda; el DNI nunca toca el navegador (ADR-027). Se llama "reconocimiento", nunca "token", para no colisionar con el voucher. |
Las piezas y los módulos¶
Quién es quién en la arquitectura. Ampliado en Arquitectura del sistema.
| Término | Definición |
|---|---|
| Gestor | La web de administración para Caracol (M5): campañas, premios, sorteos, ganadores, clientes y reportes. Autenticada, sin presupuesto de peso. |
| Landing | La web de participación (M4): la página que abre el QR. Anónima, de un solo uso, carga instantánea en 3G. Corre sobre Preact para pesar poco. |
| M1–M6 | Los módulos del proyecto: M1 backoffice de promos (existente de Caracol), M2 POS de emisión (existente), M3 backend de participación, M4 landing, M5 gestor, M6 puesta en marcha. Lo construido en este proyecto (greenfield) es M3, M4 y M5. |
| WorkDone | El proyecto de referencia visual y de stack para el gestor (React + Vite + shadcn parcial). La landing no hereda su peso. |
Para ver cómo estos términos se conectan en flujos concretos, seguí por Los casos de participación o el Motor de sorteo y acta.