Hoseg Rewards — Diferenciación de créditos: compra vs reciclaje ♻️
🔤 NOMBRE OFICIAL (Cindy, 2026-09-23 20:47): los créditos obtenidos por donar una casaca se llaman "Créditos Recidar" (150 por mes). ❌ NO llamarlos "créditos por reciclaje". En este doc, donde diga "créditos de reciclaje" léase "Créditos Recidar".
✏️ ACLARACIÓN (Daniel, 2026-10-13): el donativo es cualquier casaca (no necesariamente de marca Hoseg). Corregido en el flujo de la PPT del equipo.
Origen: pedido de Cindy Verde (WhatsApp, 2026-09-23 12:26, audio).
Alcance pedido: analizar alternativas y medir viabilidad SIN mover nada en programación. Reunión hoy 5:00 pm.
Doc padre:wiki/proyectos/hoseg-cash.md
1. El requerimiento (lo que pidió Cindy)
- Diferenciar de forma natural los Créditos Hoseg según su origen:
- Créditos por compras orgánicas (regla actual: cada S/299 → S/30, POS + Shopify).
- Créditos por reciclaje (iniciativa nueva que se va a lanzar).
- Quiere ver alternativas y medir opciones para activarlo.
- No tocar programación todavía — primero viabilidad y decisión.
2. Estado actual del sistema (base técnica real)
- Ledger propio (SQLite, contenedor
hoseg-cashen Zeta). Odoo NO participa (pivot 2026-08-05). - Tabla
transactions:type(earn | redeem | reverse),amount,sale_amount,source(tienda | web | canje_tienda),branch_id,ref,user_id. No hay categoría de crédito ni caducidad. - Saldo =
SUM(amount)por cliente → un solo bolsillo fungible. - Wallet muestra un único saldo. No hay segmentación por origen.
- Ya existe: niveles (Social Heater / Changemaker / Heart Warmer), job de cumpleaños, monitoreo, Google Wallet (+ geofencing), Apple Wallet en producción (pendiente prueba en iPhone).
Consecuencia: hoy los créditos no distinguen origen. Agregar la distinción es un cambio acotado y no destructivo (todo pasa por el ledger propio).
3. Opciones de diseño
🥇 Opción A — Etiqueta de origen en el ledger (credit_type) + saldo con desglose
- Agregar columna
credit_typeatransactions(compra|reciclaje; defaultcomprapara el histórico). - Saldo total = suma de ambos bolsillos; el wallet puede mostrar desglose ("S/ X por compras · ♻️ S/ Y por reciclaje") manteniendo un solo QR/cuenta.
- El canje define una prioridad de consumo (a definir: FIFO global, reciclaje primero, o compra primero).
- Ventajas: cambio mínimo, un solo QR y una sola cuenta, habilita reportes por origen, base para restringir/caducar después.
- Esfuerzo: bajo–medio (~1 día dev + pruebas según reglas de canje).
- Riesgo: bajo. No altera el modelo existente.
Opción B — Dos programas / dos tarjetas separadas
- Cada programa con su tarjeta, su QR y su regla independiente.
- Contras: fragmenta la experiencia (2 QR / 2 tarjetas), duplica operación en tienda, confusión para el cliente, niveles duplicados.
- No recomendada salvo que el negocio quiera separar contablemente ambos programas por completo.
🥈 Opción C — Bolsillos formales con reglas propias cada uno
- Es la Opción A + reglas independientes por bolsillo: caducidad propia, restricción de canje (p. ej. reciclaje canjeable solo en ciertos productos/categorías), exclusión de tier, topes.
- Ventajas: modelo "producto" escalable; control total.
- Esfuerzo: medio–alto (~2–3 días dev + pruebas), porque añade motor de reglas + UI + reportes + casos borde (FIFO con canjes parciales y reversas).
- Recomendada como evolución si tras el piloto se decide restringir o caducar por origen.
Opción D — Créditos de reciclaje como cupón/voucher aparte (fuera del wallet)
- Voucher canjeable solo en tienda, desconectado del saldo y de los niveles.
- Ventajas: implementación trivial si es campaña puntual.
- Contras: poca trazabilidad, no suma al programa de lealtad, experiencia fragmentada.
- Recomendada solo si el reciclaje es una acción temporal y no un programa permanente.
🏁 Recomendación
- Piloto → Opción A. Rápida, natural para el cliente, y evolucionable a C sin rework (la etiqueta ya queda en el ledger).
- Si desde el inicio el negocio exige restricciones/caducidad del reciclaje → ir directo a C.
4. Cómo se generarían los créditos de reciclaje (a definir con Cindy)
Posibles mecanismos (no excluyentes):
1. Por peso (kg de prenda/textil reciclado) → tasa de conversión.
2. Por prenda (unidad entregada).
3. Por valor/monto (equivalente al ticket).
4. Por evento (jornada de reciclaje, kiosco, campaña con fecha).
Registro de la entrega:
- Staff desde panel/POS escaneando el QR del cliente (igual que hoy en tienda) → más control, menos fricción para el cliente.
- Autoservicio (QR + formulario) → más escalable, pero requiere validación de la entrega.
5. Preguntas de negocio para la reunión de las 5:00 pm ⏰
- Tasa del reciclaje: ¿por kg, por prenda, por monto o por evento? ¿Cuánto vale?
- ¿Mismo saldo o restringido? ¿Los créditos de reciclaje se suman al saldo general o tienen reglas de canje propias (solo ciertos productos, no combinables)?
- Caducidad: ¿los créditos de reciclaje caducan? ¿Y los de compra?
- Niveles: ¿los créditos de reciclaje cuentan para subir de nivel (Changemaker/Heart Warmer) o solo los de compra?
- Prioridad de consumo al canjear: ¿primero compra, primero reciclaje, o FIFO?
- Canal online: ¿aplica también en Shopify o solo tienda física?
- Nombre visible para el cliente (p. ej. "Créditos Hoseg ♻️ Reciclaje").
- KPIs a medir: créditos otorgados vs canjeados por origen, clientes que reciclan, frecuencia, ticket posterior.
6. Estimación (post-decisión)
| Escenario | Esfuerzo | Notas |
|---|---|---|
| Opción A (etiqueta + desglose, canje priorizado simple) | ~1 día dev + pruebas | Recomendado para el piloto |
| Opción C (caducidad/restricciones por bolsillo + reportes) | ~2–3 días dev + pruebas | Si se exige control total desde el inicio |
| Opción D (campaña puntual con vouchers) | Horas | Solo si es temporal |
⚠️ El esfuerzo real depende de las respuestas a las preguntas del §5 (canje restrictivo y caducidad son los que más agregan).
7. 📩 Aclaración de Cindy (2026-09-23 12:46) — la dinámica concreta
"Por cada casaca antigua pero utilizable que deje el cliente en Hoseg para revisar, Hoseg le da 150 créditos Hoseg para que compre una casaca Hoseg. ¿Por qué separarlo de los demás créditos? Para evitar que usen esos 150 soles en otros productos."
Conclusión clave: NO es solo trazabilidad/desglose — el reciclaje debe ser un crédito RESTRINGIDO a catálogo (casacas). Esto descarta la Opción A "simple" y apunta directo a la Opción C (bolsillos con reglas propias).
Parámetros confirmados / por confirmar
| Parámetro | Valor | Estado |
|---|---|---|
| Tasa | 150 créditos por casaca entregada (1:1 con soles, asumido) | ✅ dicho por Cindy |
| Restricción | Solo compra de casaca Hoseg (no otros productos) | ✅ dicho por Cindy |
| Trigger | Cliente deja casaca antigua utilizable para revisión | ✅ dicho por Cindy |
| ¿Combina con créditos normales en una casaca? | — | ❓ por confirmar |
| ¿Qué pasa si la casaca cuesta < 150? (¿sobra o se pierde?) | — | ❓ por confirmar |
| ¿Sirve cualquier casaca Hoseg o solo una línea? | — | ❓ por confirmar |
| ¿Aplica online (Shopify) o solo tiendas? | — | ❓ por confirmar |
| ¿Caduca / cuenta para nivel? | — | ❓ por confirmar |
8. Implicancia técnica de la restricción (lo importante)
Hoy el canje en tienda es ciego al producto: el vendedor escanea el QR e ingresa un monto, sin detalle de ítems. Para restringir a casacas hace falta que el canje sepa qué se está comprando.
- Modelo:
transactions.credit_type = 'compra' | 'reciclaje'+ marca de restricción (p. ej.restricted_category = 'casaca'). - Saldo: Total = compra + reciclaje. El reciclaje queda en un bolsillo restringido.
- Canje tienda (App vendedor): agregar paso "categoría/producto" antes de canjear. Si el ítem es casaca → puede usar el bolsillo de reciclaje; si no, ese bolsillo queda bloqueado y solo aplican los créditos normales. El sistema valida y avisa.
- Canje online (Shopify): requiere verificar que el carrito tenga una casaca → Etapa 2 (Shopify aún no validado).
- Enforcement real: sin el paso de categoría, la restricción es solo "política del vendedor". Con el paso de categoría, es validación de sistema (recomendado).
Impacto en la estimación
- La restricción por categoría (paso en app vendedor + validación de bolsillo) suma ~0.5–1 día sobre la Opción C → estimado ~2–3 días dev + pruebas. Sin restricción (solo desglose) sería ~1 día.
Creado: 2026-09-23 · Actualizado 12:50 con la dinámica de Cindy · Nexus · Sin cambios en código.
9. ✅ Requerimiento CERRADO (Cindy, 2026-09-23) — con corrección 13:00
⚠️ Ojo: Cindy primero dijo "no se combinan", pero a las 13:00 envió una corrección de la política (ver §10). Manda la versión de §10. Confirmada por Cindy a las 13:14 ("Correcto").
| # | Definición | Respuesta |
|---|---|---|
| 1 | ¿Combina reciclaje + créditos normales? | ⚠️ CORREGIDO 13:00: SÍ se acumulan/combinan, pero SOLO cuando la compra es una casaca. |
| 2 | ¿Qué pasa si la casaca cuesta menos de 150? | No aplica: no hay casacas bajo S/150, así que no queda saldo huérfano. |
| 3 | ¿Aplica online (Shopify)? | NO — solo puntos de venta físicos. Se elimina la necesidad de validar carrito en Shopify. |
| 4 | ¿Y si un cliente compra casaca sin donar? | Puede usar sus créditos normales con normalidad (los normales sirven para cualquier producto, incluidas casacas). |
10. 🔁 CORRECCIÓN DE LA POLÍTICA (Cindy, 2026-09-23 13:00, audio)
"El cliente que deja una casaca para reciclar tiene el crédito Hoseg reciclaje de 150, pero si ya tiene créditos Hoseg sí puede acumularlos. Ejemplo: el cliente que tiene 100 soles en créditos y dona una casaca (150) → al llevar su casaca se le aplica los 150 + los 100 que tenía acumulados. Pero esto únicamente si lleva una casaca. Si compra otros productos, solo puede redimir de los créditos Hoseg anteriores (los normales). Los 150 soles son únicamente para redimirse con la compra de una casaca."
Regla definitiva
| Situación | Créditos normales | Créditos de reciclaje (150) |
|---|---|---|
| Compra de casaca | ✅ aplica | ✅ aplica |
| Compra de casaca con ambos | ✅ se suman (100 + 150 = 250) | ✅ |
| Compra de producto NO casaca | ✅ aplica | ❌ bloqueado |
| - Los créditos de reciclaje nunca salen del catálogo casacas. | ||
| - Los créditos normales sirven para todo (incluidas casacas). | ||
| - En compra de casaca con bolsillos se suman (se eliminó la exclusividad). | ||
| - Acumulables por varias casacas donadas (2 → 300). |
🏁 Diseño final — Opción C (bolsillo restringido, combinable en casaca)
Cambios técnicos (para cuando se autorice):
1. transactions.credit_type → 'compra' | 'reciclaje' (default compra para el histórico).
2. Saldo con dos bolsillos: saldo_compra y saldo_reciclaje (total = suma).
3. Nuevo origen de earn reciclaje (app/panel vendedor: escanear QR + registrar entrega de casaca → +150).
4. Canje en app vendedor: paso obligatorio de categoría de producto.
- Ítem = casaca → aplica normal + reciclaje (sumados).
- Ítem ≠ casaca → solo normal; el bolsillo de reciclaje queda bloqueado.
5. Wallet del cliente: mostrar desglose ("Créditos por compras" / "♻️ Créditos por reciclaje — solo casacas").
6. Reportes: otorgados vs canjeados por origen; casacas recibidas; clientes que reciclan.
Estimación: ~2 días dev + pruebas (combinación en casaca es más simple que la exclusividad; el paso de categoría sigue siendo necesario para bloquear el bolsillo en otros productos).
Pendientes menores para la reunión (no bloquean):
- ¿Tope de acumulación por varias casacas?
- ¿Caducan los créditos de reciclaje? ¿Cuentan para nivel?
- ¿La "revisión" de la casaca es inmediata o acredita tras validación?
- ¿Quién registra la entrega? (vendedor en tienda)
11. ✅ RESPUESTAS FINALES (Cindy, 2026-09-23 19:48) — requerimiento COMPLETO
- Tope: máximo 150 créditos de reciclaje por mes, sin importar cuántas casacas se donen (1 o 10 = 150). Para sumar otro 150 hay que volver el mes siguiente y donar otra casaca.
- Caducidad: 6 meses, igual que el programa regular. (Confirmación adicional: los créditos normales también caducan a los 6 meses.)
- Nivel: Sí cuentan para subir de nivel (Changemaker / Heart Warmer) — es una acción que haría un Heart Warmer.
- Acreditación: el vendedor revisa la casaca y verifica que cumpla los estándares de calidad que definirá Recidar; si cumple, se acreditan.
- Registro: el vendedor recibe la donación, la revisa, registra los créditos y cierra la venta en el mismo momento si el cliente quiere usarlos ese día (un solo flujo).
Regla consolidada (definitiva)
| Punto | Definición |
|---|---|
| Earn | 150 créditos de reciclaje por donativo · máx. 150/mes |
| Acumulación | Mes a mes (los no usados se suman) |
| Caducidad | 6 meses (igual que los créditos normales) |
| Uso | Solo en compra de casaca; se suman con los normales en esa misma compra |
| Otros productos | Los 150 quedan bloqueados |
| Nivel | Los donativos cuentan para el nivel |
| Canal | Solo tienda física |
| Operador | Vendedor (revisa + registra + cobra) |
Impacto en implementación (para cuando se autorice)
- Cap mensual: 1 earn de reciclaje por cliente por mes (150). Si intenta un 2.º donativo en el mismo mes → avisar/bloquear.
- Caducidad 6 meses: requiere fecha de vencimiento por transacción + job de expiración (aplicado a ambos bolsillos).
- Nivel: sumar los donativos al cálculo de progreso de nivel (no solo a
min_sales). - Flujo vendedor: donativo → validar estándares Recidar → registrar créditos → aplicar al cobro si el cliente lo pide en el momento.
- Estándares de calidad: solicitarlos a Recidar (son ellos quienes los definirán).
Creado: 2026-09-23 · Actualizado 19:50 — requerimiento cerrado y confirmado por Cindy · Nexus · Sin cambios en código.
12. 🚀 IMPLEMENTADO Y DESPLEGADO (2026-09-23 21:00)
Autorización: Cindy (WhatsApp 20:52), con backup previo.
Backup previo
hoseg_db_2026-09-23_205045.db+hoseg_code_2026-09-23_205045.tar.gz(Zeta/home/opsmgr/backups/hoseg-cash/) + subido a Google Drive.
Cambios (Zeta, contenedor hoseg-cash, commit b5ce03b pusheado a dannyelito/hoseg-cash)
- db.js: columnas nuevas
transactions.credit_type(compra|recidar),category,expires_at. HelpersbalanceByType()(excluye caducados),recidarEarnedThisMonth().clientBalance()ahora = total válido.totalSales()suma los Créditos Recidar al progreso de nivel. - index.js: endpoint
POST /api/donations(150 Créditos Recidar, tope 1/mes, caducidad +6 meses);/api/redeemconproduct_category(restringe Recidar a casacas; en casaca usa Recidar primero y luego compras);/api/wallet/lookupy/api/wallet/:tokendevuelvenbalances;/api/dashboarddevuelve statsrecidar. - public/vendedor.html: dos saldos (compras / ♻️ Recidar), selector de producto (Casaca / Otro), botón + modal "Registrar donación de casaca" con checklist.
- public/wallet.html: desglose de saldos + movimientos etiquetados "Créditos Recidar ♻️ (donación de casaca)".
- public/admin.html: KPIs "Créditos Recidar otorgados" y "Donaciones de casaca".
Pruebas realizadas (en producción, con cliente de prueba luego eliminado) ✅
- Registro → lookup (compra S/10 bienvenida, Recidar S/0, disponible 150).
- Donación → +150 Recidar (total 160). 2.ª donación mismo mes → bloqueada (tope).
- Canje "otro producto" → bloqueado ("Créditos Recidar solo se usan en casacas").
- Canje casaca 150 → consume Recidar. Combinado casaca 160 → 150 Recidar + 10 compras ✅.
expires_at= +6 meses verificado. Dashboard con stats. Páginas /vendedor /admin /registro 200.- Clientes de prueba (3) + 9 transacciones eliminados.
Pendiente / a decidir
- ⚠️ Caducidad 6 meses solo aplicada a Créditos Recidar. Los créditos por compras NUEVOS aún no caducan (histórico tampoco). Cindy dijo "igual que el programa regular" → confirmar si se activa también para compras.
- Solicitar a Recidar los estándares de calidad para la revisión de casacas.
13. 📲 Actualización en Google Wallet / Apple Wallet / wallet web (2026-09-23 21:15)
Pedido de Cindy: que el saldo de Créditos Recidar se refleje en las tres billeteras. Commit b2ec168 (pusheado).
- Wallet web (PWA
/w/:token): desglose "Créditos por compras" / "♻️ Créditos Recidar (solo casacas)" + movimientos etiquetados. - Google Wallet: el pase sigue mostrando el total y ahora incluye un módulo "♻️ Créditos Recidar (solo casacas)" (solo si > 0). Se sincroniza en vivo en cada donación/canje (
gwalletPatchBalance). HelpergwalletTextModules()usado también en/api/gwallet/syncy en el link de alta. - Apple Wallet (.pkpass): el pase muestra el total y un campo
♻️ CRÉDITOS RECIDAR(+ explicación en el reverso). El campo "Compras acumuladas" del pase ahora cuenta solo compras (no incluye Recidar), aunque el nivel sí sigue sumando los Recidar. - Verificado en producción con clientes de prueba (Google: módulo
recidarpresente; Apple: auxiliaryrecidar+ backFieldrecidar_info). Datos de prueba eliminados. - ⚠️ La restricción (solo casacas) se aplica al canjear en el sistema; los pases son informativos.