Productos Ciclicos (Cajas de Envío)

PARTE 1: DESCRIPCIÓN PARA LINEAR PROJECT

---

Productos Ciclicos (Cajas de Envío)

Descripción

Habilitar la creación de productos cíclicos (cajas, ediciones, entregas) y permitir asignarlos a notas de envío de suscripciones físicas, permitiendo que el sistema identifique correctamente qué producto debe entregarse en cada período según el ciclo de la suscripción.

⚠️ Nota importante sobre disponibilidad:

Esta funcionalidad estará controlada por una feature flag y solo estará disponible para tenants que la tengan activada. El objetivo es mantener la UI limpia para clientes que no necesitan esta funcionalidad.

Contexto de Negocio

Actualmente, las notas de envío de suscripciones físicas no tienen forma de indicar qué "caja" o "edición" específica debe enviarse al suscriptor. Esto genera:

• Trabajo manual: Los administradores deben recordar o consultar externamente qué caja corresponde a cada período
• Errores en envíos: Mayor probabilidad de enviar la caja incorrecta
• Falta de trazabilidad: No hay registro de qué caja se envió en cada nota de envío
• Limitaciones de negocio: Clientes como Tinta Fresca no pueden migrar completamente de WordPress a Publica.la Caso de uso principal (Tinta Fresca): Un usuario se suscribe en septiembre → debe recibir la "Caja 23 - Septiembre 2025". Al mes siguiente, automáticamente debe recibir "Caja 24 - Octubre 2025". Si pausa la suscripción y la reactiva 3 meses después, debe recibir la caja del mes actual (no las 3 atrasadas).

Objetivos

• Automatizar la asignación de cajas: El sistema debe determinar automáticamente qué caja corresponde a cada nota de envío según el período vigente
• Permitir gestión manual: Los administradores deben poder configurar ciclos de cajas y corregir asignaciones cuando sea necesario
• Mantener coherencia temporal: Las cajas deben ser correlativas sin gaps temporales entre una y otra
• Soportar múltiples productos cíclicos: Un tenant puede tener diferentes líneas de productos cíclicos (ej: Club General, Club Niños)
• Facilitar operación: Reducir el trabajo manual y errores en la preparación de envíos

Usuarios Impactados

• Administradores de Tienda: Configuran productos cíclicos, crean y gestionan ciclos, supervisan asignaciones
• Personal de Fulfillment: Consultan las notas de envío para saber qué caja preparar y enviar
• Suscriptores: Reciben la caja correcta según su período de suscripción (impacto indirecto)

Alcance (Scope)

In Scope

• Gestión de Productos Cíclicos (Backend + Dashboard)

• CRUD completo de productos cíclicos

• Asociación de productos cíclicos con planes de suscripción específicos

• Activación/desactivación de productos

• Listado, búsqueda y paginación

• Gestión de Ciclos (Backend + Dashboard)

• CRUD completo de ciclos asociados a productos cíclicos

• Numeración secuencial automática de ciclos

• Configuración de períodos (fecha inicio y fin)

• Generación automática de ciclos basados en el anterior

• Validación de coherencia temporal (sin solapamientos)

• Diferenciación entre ciclos auto-generados y manuales

• Integración con Notas de Envío

• Asignación automática de ciclo vigente al generar shipping note

• Columna "Producto Cíclico" en tabla de shipping notes (condicional a feature flag)

• Visualización de tipo de asignación (Auto/Manual/Editada)

• Suscripciones pausadas y reactivadas

• Feature Flag

• Flag enable_cyclic_products para controlar disponibilidad por tenant

• UI condicional en dashboard y shipping notes

Out of Scope

• Multi-tenant desde inicio: Esta primera iteración se enfoca en Tinta Fresca, pero el diseño debe permitir que cualquier tenant con la feature flag activa pueda usarlo
• Migración de datos: No se migrará información de WordPress; Tinta Fresca empezará de cero
• Integración con WordPress: No hay sincronización ni comunicación con sistemas legacy
• Reportes y métricas: No se incluyen dashboards o reportes específicos de productos cíclicos
• Notificaciones automáticas: No se envían alertas cuando un ciclo está por terminar
• Historial de cambios automático: La auditoría de cambios en asignaciones queda a discusión técnica (puede ir en fase posterior)
• API y Webhooks: No se expone información de productos cíclicos en APIs externas
• Stock y fulfillment avanzado: No se maneja inventario de cajas ni optimización logística
• Múltiples productos cíclicos en una suscripción: Se soporta que un usuario tenga múltiples suscripciones con diferentes productos cíclicos, pero cada suscripción solo tiene un producto cíclico asignado

Decisiones Pendientes (TBD)

¿Necesitamos mantener un historial auditable de cambios manuales en las asignaciones de cajas?

User Flows de Alto Nivel

Admin: Configuración Inicial de Producto Cíclico

1. Admin accede a nueva sección "Productos Cíclicos" en Dashboard
2. Crea nuevo producto cíclico (ej: "Caja Tinta Fresca")
3. Asocia planes de suscripción relevantes
4. Crea primer ciclo manualmente:
   • Define fecha de inicio (ej: 1 sept 2025)
   • Define fecha de fin (ej: 30 sept 2025)
   • Ingresa título (ej: "Caja 23 - Septiembre 2025")
5. Sistema genera número de ciclo automático (#1) Valor para el usuario: Configuración rápida y estructurada de productos recurrentes

Admin: Gestión de Ciclos Continuos

1. Admin revisa listado de ciclos de un producto
2. Sistema muestra estado de cada ciclo (próximo/en curso/finalizado)
3. Admin identifica que necesita crear próximo ciclo
4. Sistema pre-completa:
   • Fecha inicio (día después del último ciclo)
   • Número secuencial
   • Título sugerido
5. Admin solo define fecha fin y confirma
6. Sistema valida coherencia temporal Valor para el usuario: Mantenimiento eficiente de ciclos sin gaps temporales

Sistema: Asignación Automática en Nueva Nota de Envío

1. Sistema genera nota de envío para suscripción renovada
2. Detecta que el plan tiene producto cíclico asociado
3. Identifica ciclo vigente según fecha de creación de la nota
4. Asigna automáticamente el ciclo a la not
5. Marca asignación como tipo "Auto"
6. Nota de envío muestra: "Caja 24 - Octubre 2025" con badge "Auto"

Valor para el usuario: Asignación correcta sin intervención manual

Admin: Corrección Manual de Caja Asignada

1. Admin revisa notas de envío pendientes
2. Identifica que una nota tiene caja incorrecta
3. Hace clic en selector de caja en la fila
4. Selecciona caja correcta del desplegable
5. Sistema actualiza asignación y marca como "Editada"
6. Nota de envío muestra nueva caja con badge "Editada" Valor para el usuario: Flexibilidad para corregir casos especiales

Sistema: Manejo de Suscripción Pausada y Reactivada

1. Usuario pausa suscripción en septiembre (Caja 23)
2. Sistema no genera notas de envío durante pausa
3. Usuario reactiva suscripción en diciembre
4. Sistema genera nueva nota de envío
5. Identifica ciclo vigente en diciembre (Caja 26)
6. Asigna Caja 26 (NO las 3 cajas intermedias)
7. Próxima renovación asignará Caja 27 Valor para el usuario: Comportamiento coherente sin deuda de cajas

Sistema: Manejo de Pago Fallido y Recuperado

1. Sistema intenta cobrar suscripción en septiembre (Caja 23)
2. Pago falla repetidamente durante septiembre
3. Sistema sigue intentando en octubre
4. Pago finalmente se procesa en octubre
5. Sistema genera nota de envío con fecha de octubre
6. Asigna ciclo vigente en octubre (Caja 24, NO Caja 23)
7. Usuario recibe caja del mes en que efectivamente se cobró Valor para el usuario: Asignación basada en realidad de cobro, no intención

Reglas de Negocio

Reglas de Creación de Productos Cíclicos

• Un producto cíclico puede estar asociado a uno o múltiples planes de suscripción
• Un tenant puede tener múltiples productos cíclicos activos simultáneamente

Reglas de Creación y Gestión de Ciclos

• Los ciclos deben ser correlativas y no puede haber gaps temporales entre uno y otro
• La fecha de inicio de un ciclo N+1 DEBE ser el día siguiente a la fecha fin del ciclo N
• Si es el primer ciclo, el admin debe definir manualmente la fecha de inicio
• El número de ciclo es secuencial y auto-incremental (1, 2, 3...)
• Los ciclos pueden ser tipo "auto" (generados automáticamente) o "manual" (creados manualmente)
• No se pueden editar ciclos que ya finalizaron (estado "finalizada")
• Si un ciclo esta en curso solo se puede editar la fecha de finalización,
• No se pueden eliminar ciclos
• La fecha de fin no puede ser anterior a la fecha de inicio
• Los períodos de ciclos del mismo producto no pueden solaparse

Reglas de Asignación Automática

• Al generar una nota de envío, el sistema verifica si el plan tiene producto cíclico asociado
• Si tiene producto cíclico, identifica el ciclo cuyo período contiene la fecha de creación de la nota y relaciona la nota con el producto
• Si existe un ciclo vigente, lo asigna automáticamente.
• Si una nota de envío no tiene producto ciclico asociado se muestra la suscripcion asociada.
• Las suscripciones pausadas no generan notas de envío, por lo tanto no "consumen" ciclos
• Al reactivar una suscripción, se asigna el ciclo vigente en el momento de reactivación,
  • Caso Borde: Si una suscripcion se pausa y se reactiva durante el mismo ciclo, al reactivarse se debe asignar el siguiente ciclo.
• Si un pago falla y se recupera más tarde, se asigna el ciclo vigente a la fecha de cobro original.

Reglas de Edición Manual de Notas de Envío

• Los administradores pueden cambiar el ciclo asignado a cualquier nota de envío pendiente
• Solo se pueden asignar ciclos del mismo producto cíclico
• Al editar manualmente, el tipo cambia a "Automatico" a "Editada"
• No se pueden editar notas de envío ya procesadas o enviadas (si aplica en el futuro)

Reglas de Visualización en Dashboard

• La columna "Producto Cíclico" en shipping notes SOLO es visible si el tenant tiene la feature flag activa
• Si una nota no tiene producto ciclico asignado, se muestra la suscripción asociada
• El badge de tipo (Auto/Manual/Editada) ayuda a identificar el origen de la asignación

---

PARTE 2: DESGLOSE DE TICKETS PROPUESTOS

1. Creación de Feature Flag (enable_cyclic_products)
2. Gestión de Productos Cíclicos
3. Gestion de ciclos en
4. Integración con Shipping Notes
5. Documentación