Saltar a contenido

Motor de sorteo y acta

El sorteo es el momento más delicado del sistema: reparte premios reales, ante clientes reales, con bases legales de por medio. Un reclamo —"¿por qué ganó ese y no yo?"— tiene que poder responderse con evidencia, no con "confiá en el sistema". Por eso el motor de sorteo está diseñado alrededor de una sola obsesión: que el resultado sea reproducible y auditable. Esta página explica cómo se eligen los elegibles, cómo se sortea, y por qué el acta es la pieza legal que protege a Caracol y al cliente por igual.

Qué chances entran: los elegibles

No todas las chances participan de todos los sorteos. Cada sorteo toma su ventana de chances, definida por la fecha de emisión del ticket.

  • La ventana de un sorteo es [fecha_sorteo_anterior, fecha_sorteo_actual): las chances emitidas desde el sorteo previo hasta este. El primer semanal toma desde el inicio de vigencia; lo emitido después del último semanal cae en el sorteo de cierre (ADR-001).
  • De esa ventana se excluyen los DNIs ya adjudicados en actas previas de la campaña: quien ya ganó no vuelve a entrar (ADR-003).

Bucketing por emisión: por qué un voucher tardío participa de su semana

Como la ventana se mide por emisión, un voucher emitido el lunes 08/09 y registrado recién el 16/09 participa del sorteo cuya ventana contiene el 08/09, no del que estaba corriendo cuando se registró. La fecha de registración no cambia a qué sorteo pertenece la chance: manda la emisión firmada en el token. Esto hace que el query de elegibles sea determinista y auditable, y cierra el hueco de guardar vouchers para la semana conveniente.

La exclusión de adjudicados y el dedup por DNI

Hay dos reglas contra "ganar dos veces", y operan en momentos distintos:

  • Exclusión entre actas (por adjudicación). Un DNI que salió ganador en un acta queda adjudicado —retire o no el premio— y se excluye de los elegibles de todos los sorteos siguientes de la campaña. La exclusión es por haber sido sorteado, no por haber retirado: no depende del estado de entrega. Los suplentes promovidos también quedan adjudicados.
  • Dedup dentro del acta (por DNI). Al recorrer la lista ordenada de una misma ejecución, un DNI con varias chances gana a lo sumo un premio por acta: sus chances extra se saltan. Alguien con 3 chances no ocupa 3 posiciones de ganador.

Ningún DNI gana dos premios, ninguna unidad va en dos actas

Estas dos reglas —dedup por DNI intra-acta y exclusión por adjudicación entre actas— son invariantes de la CONSTITUTION, no preferencias. Están respaldadas además por ADR-024: la ejecución de sorteos de una misma campaña se serializa con un lock de campaña, para que dos sorteos ejecutándose casi a la vez no le den el premio al mismo DNI por leer estado desactualizado. En la operación real los sorteos se ejecutan de a uno, pero la defensa está igual.

Cómo se ejecuta: siempre por decisión humana

El sorteo nunca se dispara solo. La hora publicada en las bases (los lunes 10:00, el cierre el sábado) es una referencia, no un trigger. La ejecución ocurre por la acción de un operador desde el gestor, con un botón "Ejecutar sorteo" que muestra un resumen de elegibles y pide confirmación.

Por qué no hay scheduler

Un scheduler ejecutaría el sorteo con datos que nadie revisó, y podría fallar en silencio un lunes 10:00 sin nadie delante. Con ejecución manual siempre hay un humano responsable frente al acta, no hay código de scheduling que auditar, y un feriado o una demora se maneja operativamente sin tocar nada. El porqué está en ADR-009, y es un invariante de la CONSTITUTION. El paso a paso operativo está en Ejecutar un sorteo.

El proceso, paso a paso

Cada ejecución sortea N ganadores + 10 suplentes en una sola acta ordenada. La N no es un parámetro suelto: se deriva de las unidades de premio asignadas a ese sorteo. La prelación es 1 a 1: el primer sorteado se lleva el premio de prelación 1, el segundo el de prelación 2, y así.

Diagrama

Cuando faltan elegibles: se sortea lo que hay

¿Qué pasa si una semana floja deja menos chances elegibles que posiciones a cubrir? El motor no falla y no espera: sortea sobre los elegibles que existan. Si alcanzan para K posiciones (K < N), el acta registra K resultados y las unidades sin ganador quedan en estado Asignado, a la espera de una decisión del operador (devolución al stock o NO_OTORGADO según el momento). Con cero elegibles, el acta se registra vacía y válida, sin error.

El acta refleja fielmente la escasez

Fallar la ejecución bloquearía un sorteo publicado; esperar más participaciones violaría la fecha de las bases. Sortear lo disponible es la única opción que respeta lo prometido. El acta muestra exactamente lo que hubo. Ver ADR-012.

El acta: inmutable y reproducible

Acá está el corazón de la auditabilidad. Cada ejecución persiste un snapshot completo e inmutable:

  • la lista ordenada de chance_id elegibles,
  • el hash de esa lista (para detectar cualquier alteración),
  • el seed (semilla del generador pseudoaleatorio),
  • el algo@version (el algoritmo y su versión, p. ej. fisher-yates-sha256@1),
  • los filtros aplicados (la ventana de emisión y las exclusiones),
  • la prelación de premios y los ganadores y suplentes en orden.

La propiedad que esto garantiza es simple y poderosa: lista + seed + algo@version → mismo resultado, siempre. Cualquiera que tenga el acta puede volver a correr el motor sobre ese snapshot y obtener exactamente los mismos ganadores y suplentes. Ante un reclamo, el resultado se reproduce; no se argumenta.

El acta ejecutada no se altera jamás

No existe un endpoint ni una operación que modifique un acta ejecutada: es inmutable por diseño, y hay un golden test obligatorio de reproducibilidad que la CONSTITUTION exige antes de dar por converger el backend. Cambiar el algoritmo obliga a una nueva algo@version; las actas viejas se siguen reproduciendo con la suya. Ver ADR-004. Una ejecución errónea no se "re-ejecuta": se resuelve por decisión humana documentada fuera del sistema (nueva asignación + nuevo sorteo).

Lo sorteado vs. lo entregado: dos cosas distintas

Un matiz que evita confundir el artefacto legal con la operación: el acta congela el premio sorteado originalmente de cada posición (premio_unidad_id_original), y ese dato no cambia nunca. El estado de entrega —a quién se le entregó, si se devolvió, si pasó a un suplente— evoluciona con la operación y se exporta por separado, rotulado como "estado al momento del export".

Así, dos exports del mismo acta en momentos distintos tienen una sección de acta idéntica (el sorteo, inmutable) y, eventualmente, una sección de entrega distinta (lo operativo, que se mueve). El sorteo protege su valor legal sin perder la trazabilidad de las entregas. El porqué está en ADR-025.

Dónde sigue