Premios y su ciclo de vida¶
Un premio en este sistema no es un dato estático: nace como una definición, se materializa en unidades físicas, se asigna a un sorteo, se sortea, y termina entregado o cerrado. Cada uno de esos pasos es una transición con reglas, y toda transición queda auditada. Esta página explica ese ciclo de vida —por qué está modelado en dos niveles, cómo se mueve una unidad de premio de punta a punta, y cómo el sistema garantiza que el inventario de la campaña cierre exacto al final.
Dos niveles: PremioTipo y PremioUnidad¶
El premio se modela en dos capas, y la distinción es la clave de todo lo demás:
- PremioTipo es la definición: "Bicicleta playera × 10", con su valor unitario y su cantidad. Es la plantilla, no algo físico.
- PremioUnidad es cada unidad individual generada de ese tipo. Si el tipo dice "× 10", el sistema genera 10 unidades. Son las que se asignan, se sortean y se entregan.
El operador carga los premios por tipo y cantidad, y el sistema genera las unidades. Es un lote único para toda la campaña.
El stock nunca se descuadra
El stock_disponible no es un contador paralelo que alguien incrementa y decrementa: es el COUNT exacto de unidades en estado Disponible. Al ser una consulta sobre el estado real, no puede desincronizarse de la verdad. Es un invariante de la CONSTITUTION. La lista real de tipos, cantidades y valores la entrega Caracol; el modelo es genérico (PremioTipo × cantidad → PremioUnidad) y no bloquea el desarrollo.
El ciclo de estados de una unidad¶
Una PremioUnidad recorre estados con transiciones definidas. El camino feliz es Disponible → Asignado → Sorteado → Otorgado, pero hay retrocesos legítimos y un estado terminal para cerrar lo que no se entregó.
| Estado | Qué significa |
|---|---|
| Disponible | La unidad está en el stock, sin asignar. Cuenta para stock_disponible. |
| Asignado | Reservada para un sorteo futuro, con su prelación. Todavía no se sorteó. |
| Sorteado | Tiene un ganador en un acta ejecutada. Aún no se entregó. |
| Otorgado | Entregada al ganador, con verificación de DNI. Estado terminal. |
| NO_OTORGADO | Cerrada sin entregar tras el cierre de campaña, con motivo. Estado terminal. |
Asignar y "repartir automáticamente"¶
Antes de un sorteo, las unidades se asignan a él con su prelación (el orden en que se reparten). Para ahorrarle trabajo al operador, el gestor ofrece "repartir automáticamente": distribuye el stock en partes iguales entre las semanas como punto de partida. La asignación final y la prelación siguen siendo decisión del operador; el reparto automático es una sugerencia, no una imposición.
Los retrocesos: desasignar y devolver¶
No todo avanza en línea recta, y el modelo lo contempla:
- Desasignar (
Asignado → Disponible): mientras el sorteo no se ejecutó, una unidad asignada puede volver al stock. - Devolución al stock (
Sorteado → Disponible): una unidad ya sorteada cuya entrega no prospera —y todavía hay sorteos futuros— vuelve al stock para reasignarse. Siempre con motivo y auditada.
Toda reasignación o devolución exige motivo y queda auditada
Ningún retroceso es silencioso. Quién, cuándo y por qué quedan registrados en un EventoPremio. Es un invariante de la CONSTITUTION: el inventario de premios es dinero real y su historia tiene que ser reconstruible.
La entrega¶
Cuando un ganador retira su premio, la entrega registra fecha + sucursal + responsable + verificación del DNI contra el acta. Esa verificación de DNI es la que ata a la persona que retira con la que salió sorteada: no alcanza con presentarse, hay que ser quien el acta dice.
Una unidad pasa a Otorgado —estado terminal— recién con esa entrega verificada.
Cuando el titular no aparece: suplentes, plazo y cierre¶
El camino de entrega tiene desvíos previstos por las bases:
- Incontactable o rechazo del titular → el premio pasa al siguiente suplente del acta, en orden. Los suplentes están justamente para esto (10 por acta).
- Suplentes agotados o plazo de retiro vencido → según el momento:
- Si todavía hay sorteos futuros, la unidad se devuelve al stock para reasignarse.
- Si es post-cierre y ya no hay a dónde devolverla, pasa a
NO_OTORGADO.
El plazo de retiro (10 días corridos desde el primer contacto registrado) no se automatiza: un scheduler que despoje a un ganador legítimo violaría la ejecución-por-humano y sería injusto. En cambio, se visibiliza: la vista de ganadores muestra si el plazo está vencido, y registrar una entrega sobre un plazo vencido exige una confirmación explícita del operador —advierte, no bloquea. La decisión sigue siendo humana. Ver ADR-025.
Por qué existe NO_OTORGADO
Tras el cierre de campaña ya no hay "próximos sorteos" a los que devolver una unidad no entregada. Sin un estado terminal, la máquina de estados quedaría abierta y el stock arrastraría unidades fantasma. NO_OTORGADO cierra la unidad de forma explícita, con motivo (suplentes agotados o plazo vencido) y auditoría. Así, cada unidad termina en Otorgado o NO_OTORGADO, y la rendición ante Caracol es un simple COUNT: nada queda en el limbo. Ver ADR-008.
La auditoría: EventoPremio¶
Cada cambio de estado de una unidad —asignado, desasignado, sorteado, otorgado, devuelto al stock, reasignado a suplente, no otorgado— deja un registro EventoPremio con motivo, usuario y fecha/hora. No es un log opcional: es la trazabilidad que permite reconstruir la historia completa de cualquier premio, desde que se generó del tipo hasta su estado terminal.
El inventario cierra exacto
La combinación de un stock_disponible que es COUNT real, un estado terminal explícito y un evento por cada transición da una propiedad valiosa al cierre: el inventario cuadra sin ambigüedad. Cada unidad tiene un estado final y una historia auditada de cómo llegó ahí.
Dónde sigue¶
- Para cómo se sortean los ganadores que después se entregan acá, Motor de sorteo y acta.
- Para las entidades
PremioTipo,PremioUnidad,EventoPremioyResultadoSorteo, el Modelo de datos. - Para operar entregas y pases a suplente, Gestionar ganadores y entregas.