Imagenes de Producto - Resource

Modulo: ventas Tipo: Resource Estado: En desarrollo Fecha: 2026-04-21

---

Descripcion

El recurso Imagenes de Producto permite asociar un catalogo visual a cada articulo/producto del sistema. Cada producto puede tener multiples imagenes con una imagen marcada como principal y un orden de visualizacion definido por el usuario.

Este recurso complementa al recurso Articulos / Productos aportando la dimension visual necesaria para presentar los productos en interfaces de facturacion, catalogos, portales de clientes y futuras integraciones con e-commerce.

Las imagenes se almacenan en disco procesadas y optimizadas (formato WebP), y se acceden mediante URLs publicas que no requieren autenticacion, de modo que puedan embeberse directamente en vistas, reportes o aplicaciones externas.

---

Frontend (Perspectiva de Usuario)

Vistas

Las imagenes se gestionan como parte de la ficha del articulo. Las interacciones principales son:

• Subir una nueva imagen para un producto
• Marcar una imagen como principal
• Reordenar las imagenes para definir el orden de presentacion
• Eliminar una imagen

Interacciones del usuario

Carga de imagen:

• Seleccionar un archivo desde el dispositivo del usuario (JPEG, PNG o WebP)
• El sistema valida el tipo y tamano antes de aceptar la carga
• Si es la primera imagen del producto, queda automaticamente marcada como principal

Gestion de imagen principal:

• Seleccionar cualquier imagen del producto y marcarla como principal
• La imagen que era principal pasa a no principal de forma automatica

Reordenamiento:

• Asignar un orden numerico a cada imagen del producto
• El listado de imagenes siempre se presenta ordenado de menor a mayor

Eliminacion:

• Eliminar una imagen especifica del producto
• Si la imagen eliminada era la principal y existen otras imagenes, la siguiente por orden pasa a ser la principal automaticamente

Estados de UI

• Carga exitosa: Confirmacion con los datos de la imagen creada (identificador, URL publica, si es principal, orden)
• Error de tipo de archivo: Mensaje indicando que el formato no es soportado (solo JPEG, PNG o WebP)
• Error de tamano: Mensaje indicando que el archivo supera el maximo permitido (10 MB)
• Error de persistencia: Mensaje de error y archivo descartado automaticamente si no pudo registrarse la imagen

Permisos

• La carga, modificacion y eliminacion de imagenes requieren autenticacion (sesion JWT del modulo Ventas)
• El acceso de lectura a las imagenes (URL publica) es abierto y no requiere autenticacion

---

Backend (Perspectiva de Datos de Negocio)

Entidades de negocio

Imagen de Producto (Entidad principal):

• Identificador unico
• Referencia al producto
• URL publica de acceso a la imagen
• Indicador de imagen principal (Si/No)
• Orden de visualizacion
• Ruta de almacenamiento fisico (uso interno)

Datos necesarios

Dato	Obligatorio	Restricciones
Producto	Si	Debe existir en el sistema
Archivo de imagen	Si	JPEG, PNG o WebP, maximo 10 MB
Es principal	Si	Si/No (calculado automaticamente en alta)
Orden	Si	Numero entero (calculado automaticamente en alta)

Relaciones de negocio

• Una imagen pertenece a un unico producto
• Un producto puede tener cero, una o muchas imagenes
• Un producto tiene como maximo una imagen principal a la vez
• Las imagenes se presentan ordenadas por el campo orden ascendente

Validaciones de negocio

1. El producto referenciado debe existir
2. El archivo enviado debe tener un tipo MIME permitido: JPEG, PNG o WebP
3. El archivo no puede superar los 10 MB
4. Solo puede existir una imagen principal por producto (garantizado a nivel de base de datos)
5. Si el registro en base de datos falla despues de haber guardado el archivo en disco, el archivo se elimina para evitar archivos huerfanos
6. Si la eliminacion del archivo fisico falla, la operacion completa se revierte para mantener consistencia entre base de datos y disco

---

Reglas de negocio

• Regla 1: Asignacion automatica de imagen principal en alta

  • Condicion: Al subir la primera imagen de un producto sin imagenes previas
  • Accion: La imagen se registra automaticamente como principal

• Regla 2: Unicidad de imagen principal

  • Condicion: En todo momento para un producto dado
  • Accion: Solo puede haber una imagen principal. Al marcar una nueva como principal, la anterior deja de serlo automaticamente

• Regla 3: Reasignacion automatica tras eliminar la principal

  • Condicion: Al eliminar la imagen principal de un producto que posee otras imagenes
  • Accion: La siguiente imagen segun el orden ascendente pasa automaticamente a ser la principal

• Regla 4: Procesamiento y optimizacion de imagenes

  • Condicion: Al cargar una imagen
  • Accion: El sistema redimensiona la imagen a un maximo de 1920 pixeles manteniendo la relacion de aspecto y la convierte a formato WebP con calidad optimizada antes de almacenarla

• Regla 5: Integridad entre base de datos y almacenamiento

  • Condicion: En todas las operaciones de alta y baja de imagenes
  • Accion: Si ocurre una falla en cualquier paso (registro en base de datos o manipulacion del archivo), se revierte la operacion completa para evitar inconsistencias (archivos huerfanos o registros sin archivo)

• Regla 6: Acceso publico a imagenes

  • Condicion: Al consultar la URL publica de una imagen
  • Accion: La imagen se sirve directamente sin requerir autenticacion, habilitando su uso embebido en interfaces, reportes y sistemas externos

• Regla 7: Aislamiento por empresa y sucursal

  • Condicion: En el almacenamiento de imagenes
  • Accion: Las imagenes se organizan fisicamente por numero de sistema, sucursal/schema y producto, garantizando la separacion de datos entre empresas y sucursales (multi-tenant)

• Regla 8: Orden de presentacion controlado por el usuario

  • Condicion: Al listar las imagenes de un producto
  • Accion: Las imagenes se devuelven siempre ordenadas por el campo orden ascendente, permitiendo al usuario definir la secuencia de presentacion

• Regla 9: Inclusion condicional en consulta de productos

  • Condicion: Al consultar un producto
  • Accion: Las imagenes solo se incluyen en la respuesta cuando la consulta se realiza con el detalle maximo (scope max). En consultas resumidas (scope min) o de facturacion (scope facturacion) no se incluyen, para optimizar el trafico de datos

---

Casos de uso

Caso 1: Subir la primera imagen de un producto

Actor: Usuario del modulo de Ventas

Precondiciones:

• El producto debe existir en el sistema
• El usuario debe estar autenticado
• El archivo debe ser JPEG, PNG o WebP menor a 10 MB

Flujo principal:

1. El usuario selecciona un producto sin imagenes y carga un archivo valido
2. El sistema valida el tipo de archivo y el tamano
3. El sistema procesa la imagen (redimensionado y conversion a WebP)
4. El sistema almacena el archivo en la ubicacion correspondiente al producto
5. El sistema registra la imagen marcandola automaticamente como principal
6. El sistema devuelve los datos de la imagen creada (identificador, URL publica, es principal, orden)

Postcondiciones:

• El producto tiene una imagen registrada
• Esa imagen queda marcada como principal

Flujos alternativos:

• Tipo de archivo no permitido: El sistema rechaza la carga e informa al usuario
• Archivo mayor a 10 MB: El sistema rechaza la carga e informa al usuario
• Fallo en el registro posterior al guardado: El sistema elimina el archivo del disco y reporta error

Caso 2: Subir una imagen adicional

Actor: Usuario del modulo de Ventas

Precondiciones:

• El producto ya tiene al menos una imagen principal

Flujo principal:

1. El usuario carga un nuevo archivo valido para el producto
2. El sistema valida, procesa y almacena la imagen
3. El sistema registra la imagen como no principal
4. La imagen principal existente no cambia
5. El sistema devuelve los datos de la nueva imagen

Postcondiciones:

• El producto tiene una imagen adicional
• La imagen principal previa se mantiene sin cambios

Caso 3: Cambiar la imagen principal

Actor: Usuario del modulo de Ventas

Precondiciones:

• El producto tiene al menos dos imagenes (una principal y otra no principal)

Flujo principal:

1. El usuario solicita marcar como principal una imagen que hoy no lo es
2. El sistema cambia esa imagen a principal
3. El sistema cambia la imagen que era principal a no principal
4. El sistema confirma la operacion

Postcondiciones:

• La imagen seleccionada es la nueva principal
• La anterior imagen principal deja de serlo
• Sigue existiendo una unica imagen principal para el producto

Caso 4: Reordenar imagenes

Actor: Usuario del modulo de Ventas

Precondiciones:

• El producto tiene al menos una imagen

Flujo principal:

1. El usuario asigna un nuevo orden a una imagen
2. El sistema actualiza el orden de la imagen
3. En consultas posteriores, las imagenes se devuelven ordenadas ascendentemente segun el nuevo valor

Postcondiciones:

• El orden de la imagen queda actualizado

Caso 5: Eliminar una imagen no principal

Actor: Usuario del modulo de Ventas

Precondiciones:

• La imagen existe y no es la principal

Flujo principal:

1. El usuario solicita eliminar la imagen
2. El sistema elimina el registro en base de datos
3. El sistema elimina el archivo fisico del disco
4. El sistema confirma la operacion

Postcondiciones:

• El producto ya no tiene esa imagen
• La imagen principal del producto no cambia

Caso 6: Eliminar la imagen principal cuando existen otras imagenes

Actor: Usuario del modulo de Ventas

Precondiciones:

• La imagen a eliminar es la principal
• Existe al menos otra imagen asociada al producto

Flujo principal:

1. El usuario solicita eliminar la imagen principal
2. El sistema elimina el registro y el archivo de la imagen
3. El sistema reasigna automaticamente la siguiente imagen (por orden ascendente) como nueva principal
4. El sistema confirma la operacion

Postcondiciones:

• La imagen eliminada ya no existe
• El producto continua teniendo una imagen principal

Flujos alternativos:

• Fallo al eliminar el archivo fisico: El sistema revierte la eliminacion en base de datos para mantener la consistencia y reporta error

Caso 7: Consultar un producto con sus imagenes

Actor: Usuario del modulo de Ventas (o sistemas integrados)

Precondiciones:

• El producto existe

Flujo principal:

1. El usuario consulta un producto solicitando el detalle maximo
2. El sistema devuelve los datos del producto incluyendo el listado de imagenes ordenadas ascendentemente, cada una con su identificador, URL publica, si es principal y su orden

Flujos alternativos:

• Consulta resumida o de facturacion: Si el scope solicitado es min o facturacion, la respuesta no incluye el listado de imagenes

Caso 8: Acceso publico a una imagen

Actor: Cualquier consumidor con la URL publica (navegador, reporte, portal, e-commerce)

Precondiciones:

• La imagen existe y la URL publica es conocida

Flujo principal:

1. El consumidor accede a la URL publica de la imagen
2. El sistema entrega el archivo directamente sin requerir autenticacion

Postcondiciones:

• La imagen se presenta al consumidor

---

Consideraciones

Seguridad

• Las operaciones de escritura (alta, cambio de principal, reordenamiento, eliminacion) requieren autenticacion JWT
• El acceso de lectura a la URL publica es abierto por diseno, de manera que las imagenes puedan consumirse desde reportes, portales y sistemas externos sin inyectar credenciales
• Los parametros que componen la ruta fisica de almacenamiento (numero de sistema y schema) se validan estrictamente para evitar intentos de manipulacion de ruta (path traversal). Cualquier valor con caracteres no permitidos es rechazado antes de realizar cualquier operacion sobre el filesystem

Multi-tenant

• Las imagenes se almacenan fisicamente separadas por empresa (numero de sistema) y sucursal/schema, siguiendo la convencion multi-tenant del sistema
• Cada sucursal gestiona sus propias imagenes sin interferir con las de otras sucursales o empresas

Rendimiento

• Las imagenes se redimensionan al subirse (maximo 1920 px manteniendo aspecto) y se convierten a WebP para reducir peso y tiempos de transferencia
• Las imagenes se sirven directamente desde el servidor web, sin intermediacion del backend de aplicacion, evitando sobrecarga en las operaciones de lectura
• Las imagenes no se incluyen en las consultas resumidas de productos (scope=min) ni en las de facturacion (scope=facturacion), para no penalizar los flujos de alta frecuencia

Extensibilidad

• El almacenamiento esta disenado para soportar distintos destinos fisicos (disco local hoy, servicios en la nube como S3 o GCS en el futuro) sin cambios en la interfaz de negocio. La migracion a otro proveedor no impactara las reglas de negocio descriptas en este documento

Integridad de datos

• Todas las operaciones que involucran tanto base de datos como filesystem estan disenadas para ser consistentes: ante cualquier falla, se revierte la operacion completa (sea eliminando el archivo recien subido o restaurando el registro que no pudo eliminarse) para evitar estados inconsistentes entre ambos soportes

---

Dependencias

Funcionalidades relacionadas

• Articulos / Productos: Entidad propietaria de las imagenes. Las imagenes se enriquecen en la consulta de producto con detalle maximo
• Modulo Ventas: Contexto de autenticacion y permisos del recurso

Servicios externos

• Servidor web (Apache): Responsable de servir directamente los archivos de imagen en las URLs publicas, sin pasar por el backend de aplicacion

---

Criterios de aceptacion

• [ ] AC-001: Se puede subir una imagen JPEG, PNG o WebP menor a 10 MB asociada a un producto existente y el sistema devuelve su identificador, URL publica, indicador de principal y orden
• [ ] AC-002: La primera imagen cargada para un producto queda automaticamente marcada como principal
• [ ] AC-003: Las imagenes posteriores al primer upload quedan registradas como no principales sin afectar a la principal existente
• [ ] AC-004: Archivos con tipo MIME no permitido (por ejemplo PDF) son rechazados con error descriptivo
• [ ] AC-005: Archivos mayores a 10 MB son rechazados con error descriptivo
• [ ] AC-006: Si falla el registro posterior al guardado del archivo, el archivo no queda huerfano en disco
• [ ] AC-007: Un producto no puede tener mas de una imagen principal en ningun momento
• [ ] AC-008: Se puede cambiar la imagen principal de un producto y la anterior deja de serlo automaticamente
• [ ] AC-009: Se puede modificar el orden de una imagen y los listados reflejan el nuevo orden ascendente
• [ ] AC-010: Al eliminar una imagen no principal, el registro y el archivo fisico se eliminan
• [ ] AC-011: Al eliminar la imagen principal existiendo otras imagenes, la siguiente por orden pasa automaticamente a ser la principal
• [ ] AC-012: Si falla la eliminacion del archivo fisico, el registro de base de datos se preserva y la operacion reporta error
• [ ] AC-013: La consulta de producto con detalle maximo incluye la lista de imagenes ordenadas ascendentemente
• [ ] AC-014: La consulta de producto con detalle resumido o de facturacion no incluye imagenes
• [ ] AC-015: La URL publica de una imagen es accesible sin autenticacion
• [ ] AC-016: Identificadores de empresa o sucursal con caracteres no permitidos son rechazados antes de realizar operaciones sobre el filesystem

---

Notas adicionales

Las imagenes almacenadas bajo esta funcionalidad habilitan futuros usos en catalogos visuales, portal de clientes, integraciones con e-commerce y presentaciones comerciales, aprovechando que su acceso publico permite embebido directo en interfaces internas y externas del sistema.