Qué construimos
Un sistema de canje de puntos. Los puntos ganados los calcula y entrega un sistema externo (por cada venta de baterías); nuestra plataforma administra el catálogo de premios, ejecuta el canje llevando el registro de puntos usados, y gestiona el estado de cada pedido. Todo con un panel administrativo por roles y una experiencia móvil para el vendedor.
El modelo es de una sola moneda: puntos canjeables directamente por premios. No incluye niveles, categorías ni medallas: el enfoque es simple y directo, centrado en ganar, ver el saldo y canjear.
Decisiones que cierran el alcance
Dos puntos deben confirmarse con Baterías Ecuador en el arranque, porque determinan la arquitectura y el esfuerzo.
Cómo se conectan los puntos
El sistema externo es la fuente de verdad de los puntos ganados. Necesitamos saber si expone una API que devuelva el saldo por vendedor, o si solo hay base de datos / archivos.
Experiencia del vendedor
Next.js resuelve el lado administrativo. Para el vendedor final se usa una PWA responsive sobre el mismo Next.js: funciona como app en el celular, sin costo de tiendas.
Cómo encaja todo
El sistema externo alimenta los puntos ganados. La plataforma (Next.js + PostgreSQL) concentra usuarios, saldo, catálogo y pedidos, y se accede por dos vías: el panel admin y la app del vendedor.
Roles y permisos
Cuatro perfiles, con control de acceso por recurso mediante un esquema de roles y permisos (RBAC).
Motor de puntos y canje
La pieza más sensible del sistema. Un vendedor no puede gastar puntos que no tiene, ni canjear dos veces.
Cómo se protege el canje
Al mostrar el saldo se usa el caché (refrescado por un job periódico) para no consultar el externo en cada pantalla. Al canjear, la validación es en tiempo real dentro de una transacción con bloqueo sobre el ledger del vendedor: se comprueba que el disponible cubra el costo, se registra el débito y se crea el pedido, todo de forma atómica. Cada canje lleva una clave de idempotencia para que un doble clic o reintento no genere dos débitos. Un job de reconciliación compara nuestro acumulado contra el externo y alerta cualquier diferencia.
Ciclo de vida del pedido
El canje crea un pedido en Pendiente. El gestor de pedidos lo mueve por la cola desde el panel administrativo; cada cambio queda registrado y notifica al vendedor.
El vendedor consulta el estado en su sección “Mis pedidos”. Las notificaciones de cambio de estado salen por correo; WhatsApp y push quedan como fase futura. Tras la entrega, el vendedor puede dejar feedback sobre el proceso de canje; los resultados se consolidan en un tablero para el administrador.
Fases del desarrollo
Discovery
Definir el contrato de integración con el sistema externo y confirmar las decisiones de arranque.
BloqueanteNúcleo administrativo
Autenticación, roles y permisos, modelo de datos, y CRUD de catálogo y usuarios en el panel administrativo (Next.js).
Puntos y canje
Integración con el externo, libro mayor de puntos, y motor de canje con bloqueo transaccional e idempotencia.
Frontend del vendedor
PWA con inicio (saldo de puntos), catálogo, canje y “mis pedidos”.
Gestión de pedidos
Panel del gestor de pedidos, estados, historial de cambios y notificaciones por correo.
Reportería y endurecimiento
Tableros (incluyendo resultados del feedback del vendedor), auditoría, pruebas de carga sobre el canje y ajustes de seguridad.
Riesgos y dependencias
Qué incluye y qué no incluye
Delimitación formal del desarrollo. Lo que queda fuera es tan importante como lo que entra.
✓ Incluye
- Backend en Next.js con panel administrativo integrado y base de datos en PostgreSQL.
- Módulo de usuarios y vendedores con roles: super admin, admin de catálogo y gestor de pedidos.
- Catálogo de premios: alta y edición, costo en puntos, stock, categorías, imágenes y activación.
- Integración con el sistema externo para obtener los puntos ganados por vendedor (vía la API que provea el cliente).
- Motor de canje: libro mayor de puntos usados, cálculo de saldo disponible, control transaccional e idempotencia.
- Módulo de pedidos con estados e historial de cambios, operado por el gestor de pedidos.
- App del vendedor (PWA responsive): saldo, catálogo, canje y seguimiento de pedidos.
- Notificaciones por correo ante cambios de estado del pedido.
- Módulo de feedback del vendedor sobre la entrega y el proceso de canje, con tablero de resultados en el panel administrativo.
- Auditoría de acciones sensibles (canjes y cambios de estado).
- Despliegue en el entorno acordado y documentación básica de uso.
✕ No incluye
- Desarrollo o modificación del sistema externo que calcula y entrega los puntos (responsabilidad del cliente).
- Categorías, niveles o medallas: el modelo es de puntos directos.
- Programa de referidos, donaciones o cupones de terceros.
- Aplicación móvil nativa (iOS / Android); se contempla como fase futura sobre la misma API.
- Pasarelas de pago: el canje es por puntos, no involucra dinero.
- Notificaciones por WhatsApp o push (fase futura).
- Logística y envío físico de los premios; el sistema solo refleja los estados.
- Migración de datos históricos, salvo que se especifique aparte.
Supuestos y dependencias
- El sistema externo expone una API con el saldo de puntos por vendedor; de no existir, se acuerda una importación programada con saldo no instantáneo.
- El cliente provee la infraestructura (servidor / hosting) con las especificaciones mínimas, o se cotiza por separado.
- El contenido de los premios (imágenes y descripciones) es provisto por el cliente.
Costos del proyecto
Un pago único por el desarrollo descrito en este documento, más un plan de mantenimiento mensual opcional para mantener la plataforma actualizada y funcionando.
| Servicio | Detalle | Valor |
|---|---|---|
| Desarrollo de plataforma de fidelización | Alcance completo descrito en este documento: backend, panel administrativo, motor de canje, catálogo, módulo de pedidos, módulo de feedback y app del vendedor (PWA). | $5.500,00pago único |
| Mantenimiento mensual |
4 horas mensuales de soporte y mantenimiento sobre la plataforma en producción. Incluye:
|
$120,00por mes |