Sistema de Premios — Sorteo Aniversario Caracol¶
Esta es la documentación central del Sistema de Premios desarrollado por Tipre para Supermercados Caracol, con motivo de sus 50 años. El sistema convierte cada compra en una chance de sorteo: el ticket imprime un voucher con QR firmado, el cliente lo escanea desde su celular, ingresa su DNI y participa de sorteos semanales. En paralelo, cada participación construye un padrón propio de clientes con consentimiento para futuras acciones comerciales.
Ver toda la documentación en PDF
De un vistazo
- Cliente: Supermercados Caracol · Proveedor: Tipre
- Campaña de referencia: "Sorteo 50 años" — 100 premios, vigencia 01/09 → 09/10/2026
- Piezas construidas: backend de participación, landing móvil, gestor web
- Sin dependencia de nube: corre en un servidor del cliente, con backup diario
Qué problema resuelve y para quién¶
Una promoción de sorteo tradicional obliga a sincronizar las cajas con un sistema central: cada ticket emitido tiene que "avisarle" a la web que existe. Eso es frágil (si se cae la red entre la caja y el server, se pierden participaciones) y lento de montar. El Sistema de Premios elimina esa dependencia con una idea central:
El QR es autocontenido. Todo lo que la web necesita del ticket —sucursal, caja, fecha de emisión, número de comprobante— viaja firmado dentro del token. No hay sincronización cajas ↔ web. La caja imprime, y la web valida la firma sola.
A partir de ahí, el sistema le sirve a tres actores distintos:
- El cliente de Caracol escanea el QR de su ticket y participa en segundos, desde el celular, sin instalar nada.
- El operador de Caracol administra toda la campaña desde el gestor web: carga premios, arma los sorteos, los ejecuta, gestiona a los ganadores y sus entregas, y consulta reportes.
- El equipo de soporte puede rastrear cualquier voucher, cliente o chance para responder consultas y resolver incidencias.
Las tres piezas del sistema¶
El Sistema de Premios no es una sola aplicación, sino un backend y dos frontends con propósitos —y presupuestos de peso— muy distintos. Todo vive en un mismo repositorio y se empaqueta en un único jar que sirve las tres cosas.
| Pieza | Stack | Qué hace |
|---|---|---|
| Backend | Java 17 · Spring Boot 4 · SQL Server · Flyway | Fuente de verdad: valida vouchers (casos A–E), administra padrón, chances, premios y su ciclo, motor de sorteo + acta reproducible, antifraude y la API del gestor. |
| Landing | Preact + Vite (build mínimo) | La web que abre el QR. Anónima, de un solo uso, carga instantánea en 3G de salón. Funciona en móvil y PC. Incluye escaneo del DNI por cámara. |
| Gestor | React 18 · Vite · Tailwind (estilo shadcn) · PWA | Panel de administración para Caracol: campañas, premios, sorteos, ganadores, clientes, reportes y modo prueba. |
Diagrama de alto nivel¶
El contrato entre las cajas y el sistema es únicamente el token (ver El token del QR): el sistema no conoce el POS ni el backoffice de promociones de Caracol, sólo sabe validar la firma de lo que llega en el QR.
Cómo está organizada esta documentación¶
Seguimos el framework Diátaxis: cuatro tipos de página según lo que el lector necesita en ese momento.
| Sección | Para qué sirve | Pregunta que responde |
|---|---|---|
| Entender el sistema | Comprender el porqué y el cómo | "¿Cómo funciona? ¿Por qué está diseñado así?" |
| Referencia técnica | Consultar datos exactos | "¿Qué endpoints, modelos y configuración hay?" |
| Instalación y puesta en marcha | Resolver una tarea concreta | "¿Cómo lo instalo / opero paso a paso?" |
| Manual de usuario | Operar y dar soporte | "Soy de Caracol, ¿cómo uso el sistema día a día?" |
| Propuesta comercial | Presentar el producto | "¿Qué es y qué valor tiene, en dos páginas?" |
Por dónde empezar
- Si sos técnico y vas a instalarlo: Arquitectura → Instalar en el servidor.
- Si sos de Caracol y vas a operarlo: Manual de usuario.
- Si querés la visión de producto: Propuesta comercial.