Articulos / Productos - Resource

DOCUMENTACION RETROSPECTIVA - Generada a partir de codigo implementado el 2026-02-09

Modulo: ventas Tipo: Resource Estado: Implementado Fecha: 2026-02-09

---

Descripcion

El recurso Articulos (tambien referido como "Productos") es la entidad central del catalogo comercial del Sistema Bautista. Permite gestionar la informacion de todos los articulos que la empresa comercializa, incluyendo sus datos basicos, clasificacion, precios, parametros fiscales, control de stock y configuracion de membresias.

Los articulos se utilizan en procesos de facturacion, gestion de stock, compras y membresias. Cada articulo tiene un codigo numerico auto-generado, un codigo comercial opcional (codigo de barras), y una clasificacion por rubro/agrupacion y linea.

---

Frontend (Perspectiva de Usuario)

Vistas

1. Listado de Articulos (?loc=mvp): Vista principal que muestra una tabla paginada con columnas Codigo, Nombre, Codigo Comercial y Estado (Activo/Inactivo). Incluye filtrado por columna, ordenamiento y paginacion del lado del servidor.

2. Formulario de Alta/Modificacion (?loc=mvfp): Formulario completo para crear o editar un articulo. Si se pasa un parametro id, opera en modo modificacion; sin id, opera en modo alta.

Interacciones del usuario

En el listado:

• Ver listado paginado de articulos con ordenamiento y filtrado por columna
• Navegar entre paginas de resultados
• Editar un articulo haciendo clic en el boton de edicion de la fila (redirige al formulario)
• Crear un nuevo articulo mediante boton "Nvo. Articulo | Alt+A"

En el formulario:

• Ingresar codigo comercial (opcional, maximo 14 caracteres)
• Ingresar nombre del articulo (obligatorio, maximo 50 caracteres)
• Ingresar descripcion extendida (opcional, maximo 400 caracteres)
• Ingresar costo inicial (solo editable en alta, no en modificacion)
• Ingresar porcentaje de ganancia (para generar listas de precios basadas en costo)
• Seleccionar agrupacion/rubro mediante busqueda por nombre o codigo (autocomplete)
• Seleccionar linea dentro del rubro elegido (autocomplete, habilitado tras seleccionar rubro)
• Seleccionar proveedor (autocomplete, visible si modulo Compras habilitado)
• Seleccionar ubicacion (hasta 5 niveles jerarquicos, con Select2 y soporte para crear nuevas)
• Elegir si maneja stock (Si/No, visible si modulo Control de Stock habilitado)
• Ingresar punto de pedido (stock minimo, visible si modulo Compras habilitado)
• Configurar impuestos internos (porcentaje o fijo)
• Ingresar comision por articulo (porcentaje, 0-100%)
• Seleccionar categoria de IVA
• Configurar si maneja precios en facturacion (visible segun configuracion de empresa)
• Seleccionar referencia contable (autocomplete, visible si modulo Contabilidad habilitado)
• Activar/desactivar el articulo (solo en modificacion)
• Gestionar listas de precios mediante modal:
  • Agregar nueva lista con: numero de lista, costo, porcentaje de utilidad, precio, tipo de precio (Neto/Final)
  • Modificar precio de una lista existente
  • Eliminar una lista de precios
• Configurar membresia (visible si modulo Membresias habilitado):
  • Seleccionar meses de disponibilidad (multi-seleccion de los 12 meses)
  • Ingresar anio especifico (opcional)
  • Ingresar observaciones

Permisos

• Los campos visibles en el formulario dependen de los modulos habilitados para la empresa:
  • Contabilidad: Referencia Contable
  • Compras: Proveedor, Punto de Pedido
  • Control de Stock: Manejo de Stock
  • Membresias: Seccion completa de Membresia
  • Configuracion de Precios de Empresa: Checkbox "Maneja precios"

Estados de UI

• Carga: Indicador de carga al obtener datos del producto (SweetAlert "Cargando datos")
• Exito en alta: Modal de confirmacion con el codigo asignado al producto ("Producto creado con el codigo: X")
• Exito en modificacion: Modal de confirmacion ("El producto fue modificado exitosamente")
• Error de duplicidad: Alerta si ya existe un producto con el mismo codigo comercial
• Error de comision: Mensaje si el porcentaje esta fuera de rango (0-100%)
• Listado vacio: Estado vacio manejado por DataTable
• Error de carga: Mensaje de error en rojo si falla la carga del listado

---

Backend (Perspectiva de Datos de Negocio)

Entidades de negocio

Producto/Articulo (Entidad principal):

• Identificador unico numerico (auto-generado)
• Codigo comercial/barras (opcional)
• Nombre
• Descripcion extendida
• Costo
• Porcentaje de ganancia
• Agrupacion/Rubro (referencia)
• Linea dentro del rubro (referencia)
• Proveedor (referencia, opcional)
• Ubicacion (referencia jerarquica, opcional)
• Manejo de stock (Si/No)
• Punto de pedido (stock minimo)
• Impuesto interno (porcentaje o monto fijo)
• Comision por articulo (porcentaje)
• Categoria de IVA (referencia)
• Referencia contable (referencia, opcional)
• Manejo de precios en facturacion (Si/No)
• Sincroniza con e-commerce (Si/No)
• Stock web
• Estado activo/inactivo
• Bonificacion fija

Lista de Precios (Entidad asociada):

• Numero de lista
• Precio
• Tipo de precio (Neto / Final)
• Referencia al producto

Extension de Membresia (Entidad asociada, opcional):

• Meses de disponibilidad (12 caracteres, cada posicion indica disponibilidad del mes)
• Anio
• Observacion
• Referencia al producto

Datos necesarios

Dato	Obligatorio	Restricciones
Nombre	Si	Maximo 50 caracteres
Codigo comercial	No	Maximo 14 caracteres, unico
Descripcion	No	Maximo 400 caracteres
Costo	No	Numerico, mayor o igual a 0
Porcentaje de ganancia	No	Numerico
Rubro/Agrupacion	Si	Debe existir en el sistema
Linea	Si	Debe existir dentro del rubro seleccionado
Categoria IVA	Si	Debe existir en el sistema
Manejo de stock	Si	S o N
Punto de pedido	No	Numerico entero
Impuesto interno	No	Numerico
Tipo de impuesto	No	P (porcentaje) o F (fijo)
Comision	No	0 a 100 (porcentaje)
Proveedor	No	Debe existir en el sistema
Referencia contable	No	Maximo 3 caracteres, debe existir
Manejo precios facturacion	Si	Si/No
Sincroniza web	Si	Si/No (default: No)
Stock web	No	Numerico entero
Activo	Si	Si/No (default: Si)
Ubicacion	No	Hasta 5 niveles jerarquicos
Listas de precios	No	Array de listas con numero, precio y tipo
Membresia	No	Meses, anio y observacion (si modulo habilitado)

Relaciones de negocio

• Un articulo pertenece a un rubro/agrupacion
• Un articulo pertenece a una linea dentro de su rubro
• Un articulo puede tener un proveedor
• Un articulo puede tener una referencia contable
• Un articulo puede tener una ubicacion jerarquica (hasta 5 niveles)
• Un articulo tiene una categoria de IVA
• Un articulo puede tener multiples listas de precios
• Un articulo puede tener una extension de membresia (si el modulo esta habilitado)
• Un articulo se utiliza en facturas, movimientos de stock y procesos de compras

Validaciones de negocio

1. El nombre es obligatorio y no puede exceder 50 caracteres
2. El codigo comercial debe ser unico entre todos los productos
3. El rubro y la linea son obligatorios
4. La categoria de IVA es obligatoria
5. La comision no puede ser menor a 0% ni mayor a 100%
6. El costo solo se carga en el alta (restriccion de frontend)
7. El impuesto interno se trunca a dos decimales
8. Si se cambia el rubro, se limpia la linea seleccionada
9. Para listas de precios, no se permite duplicar el numero de lista
10. Si el modulo de membresias esta habilitado, se validan los datos de membresia al insertar/actualizar

---

Reglas de negocio

• Regla 1: Generacion automatica de codigo

  • Condicion: Al crear un nuevo articulo
  • Accion: Se asigna automaticamente el proximo codigo disponible (MAX + 1). Si no se proporciona codigo comercial, se usa el codigo numerico como codigo comercial.

• Regla 2: Unicidad de codigo comercial

  • Condicion: Al crear o modificar un articulo
  • Accion: Se verifica que no exista otro producto con el mismo codigo comercial. Si existe, se rechaza la operacion.

• Regla 3: Desactivacion en vez de eliminacion

  • Condicion: Cuando se desea dar de baja un articulo
  • Accion: No existe operacion de eliminacion. Los articulos se desactivan cambiando el campo activo a falso.

• Regla 4: Filtrado por estado activo

  • Condicion: En consultas y listados
  • Accion: Por defecto se muestran solo los productos activos. Se puede especificar si se desean ver todos, solo activos o solo inactivos.

• Regla 5: Dependencia rubro-linea

  • Condicion: Al seleccionar o cambiar el rubro
  • Accion: La linea se habilita/deshabilita segun la seleccion de rubro. Si se cambia el rubro, se limpia la linea previamente seleccionada.

• Regla 6: Gestion transaccional de precios

  • Condicion: Al guardar un producto con listas de precios
  • Accion: En la actualizacion se sincronizan las listas: se crean las nuevas, se modifican las existentes y se eliminan las que fueron removidas. Todo dentro de una transaccion.

• Regla 7: Campos condicionales por modulos

  • Condicion: Segun los modulos habilitados en la empresa
  • Accion: Los campos de referencia contable, proveedor, punto de pedido, manejo de stock y membresia se muestran u ocultan segun la configuracion de la empresa.

• Regla 8: Limpieza de ubicaciones no utilizadas

  • Condicion: Al actualizar un producto que cambia su ubicacion
  • Accion: Se ejecuta un proceso de limpieza que elimina ubicaciones sin hijos y sin productos asignados.

• Regla 9: Enriquecimiento con datos de membresia

  • Condicion: Al consultar un producto con scope 'max' y modulo de membresias habilitado
  • Accion: Se agrega automaticamente la informacion de membresia al producto retornado. Para listados, se usa una consulta bulk para optimizar.

Gestión de Costos

El campo costo solo es editable durante el alta del artículo desde este formulario. El costo se actualiza desde el cambio en lista de precios o desde compras si se posee el módulo. Esto garantiza que el costo refleje siempre el último precio de adquisición o el definido por estrategia de precios.

Integración con Módulo de Membresías

Los productos pueden tener asociada una extensión de membresía que define en qué meses del año se pueden facturar. Se puede designar en qué momento se facturan algunos productos mediante un string de 12 caracteres donde cada posición representa un mes (ej: "111000000000" = enero, febrero, marzo). Esta configuración se usa para productos de facturación estacional o periódica.

Campos Condicionales por Módulos

La visibilidad de ciertos campos depende de los módulos habilitados en la empresa:

• Módulo Contabilidad: Referencia Contable
• Módulo Compras: Punto de pedido, Proveedor
• Módulo Control Stock: Manejo de Stock
• Módulo Membresías: Sección de membresía (meses, año, observación)
• Empresa con precios: Maneja precios (facturación)

La falta de datos por módulos no se valida en backend sino que suelen tener campos por defecto como deshabilitación (Null, 0, N, false, etc...). Cuando un módulo no está habilitado, los campos se eliminan del DOM frontend.

---

Casos de uso

Caso 1: Alta de un nuevo articulo

Actor: Usuario del modulo de Ventas

Precondiciones:

• El usuario debe estar autenticado
• Deben existir rubros/agrupaciones y lineas configuradas
• Deben existir categorias de IVA registradas

Flujo principal:

1. El usuario accede al listado de articulos y presiona "Nvo. Articulo"
2. El sistema muestra el formulario de alta con los campos disponibles segun los modulos habilitados
3. El usuario completa los campos obligatorios: nombre, rubro, linea y categoria de IVA
4. Opcionalmente, el usuario ingresa codigo comercial, costo, descripcion y demas campos
5. Opcionalmente, el usuario agrega listas de precios mediante el modal
6. El usuario presiona "Aceptar"
7. El sistema genera un codigo numerico automatico
8. El sistema valida la unicidad del codigo comercial (si fue proporcionado)
9. El sistema procesa la ubicacion seleccionada
10. El sistema registra el producto y sus listas de precios en una transaccion
11. El sistema muestra el codigo asignado y redirige al listado

Postcondiciones:

• El articulo queda registrado con estado activo
• Las listas de precios quedan asociadas al producto
• Si aplica, la extension de membresia queda registrada

Flujos alternativos:

• Error de duplicidad: Si el codigo comercial ya existe, el sistema informa al usuario durante la edicion del campo
• Error de validacion: Si faltan campos obligatorios, el formulario no se envia

Caso 2: Modificacion de un articulo existente

Actor: Usuario del modulo de Ventas

Precondiciones:

• El articulo debe existir en el sistema
• El usuario debe estar autenticado

Flujo principal:

1. El usuario accede al listado y presiona editar en un articulo
2. El sistema carga los datos del articulo en el formulario
3. El usuario modifica los campos deseados (excepto costo, que es solo lectura)
4. El usuario puede modificar el estado activo/inactivo
5. El usuario puede agregar, modificar o eliminar listas de precios
6. El usuario presiona "Aceptar"
7. El sistema valida la unicidad del codigo comercial
8. El sistema actualiza el producto, sincroniza las listas de precios (inserta nuevas, actualiza existentes, elimina las removidas) y limpia ubicaciones no utilizadas
9. El sistema muestra confirmacion y redirige al listado

Postcondiciones:

• Los datos del articulo quedan actualizados
• Las listas de precios reflejan los cambios realizados
• Las ubicaciones huerfanas son eliminadas

Caso 3: Consulta y listado de articulos

Actor: Usuario del modulo de Ventas

Precondiciones:

• El usuario debe estar autenticado

Flujo principal:

1. El usuario accede al listado de articulos
2. El sistema muestra la tabla paginada con codigo, nombre, codigo comercial y estado
3. El usuario puede ordenar por cualquier columna haciendo clic en el encabezado
4. El usuario puede filtrar por codigo, nombre o codigo comercial escribiendo en los campos de filtro
5. El usuario puede navegar entre paginas

Postcondiciones:

• Se muestran los articulos segun los filtros y paginacion seleccionados

---

Consideraciones

Seguridad

• El acceso al recurso requiere autenticacion JWT
• El formulario valida la sesion del usuario antes de mostrar contenido
• Los datos se envian por HTTPS con token de autorizacion
• El contexto de tenant (esquema) se inyecta automaticamente en cada peticion

Auditoria

• [REQUIERE VALIDACION] No se encontro implementacion de auditoria para operaciones de alta y modificacion de productos. Esto contrasta con el patron estandar del sistema.

Rendimiento

• El listado usa paginacion del lado del servidor para manejar grandes catalogos
• Las consultas con scope 'min' devuelven solo campos basicos (id, nombre, codigo_comercial, activo) para optimizar los listados
• El enriquecimiento con membresia usa consultas bulk para evitar el problema N+1 en listados

Patrón Legacy de Valores Booleanos

Varios campos booleanos usan el patrón VARCHAR(1) con valores 'S'/'N' en lugar de tipo BOOLEAN nativo de PostgreSQL. Muchos valores booleanos mapeados en base de datos manejan los S o N por migración de FoxPro. Ejemplos:

• maneja_stock: 'S' o 'N'
• Otros campos similares en recursos legacy

Este patrón es heredado del sistema anterior y se mantiene por compatibilidad.

---

Dependencias

Funcionalidades relacionadas

• Rubros/Agrupaciones: Clasificacion primaria de articulos
• Lineas: Subclasificacion dentro de cada rubro
• Categorias de IVA: Configuracion fiscal obligatoria
• Listas de Precios: Gestion de precios multiples por articulo
• Ubicaciones: Sistema jerarquico de ubicacion fisica (hasta 5 niveles)
• Proveedores (modulo Compras): Proveedor del articulo
• Referencias Contables (modulo Contabilidad): Imputacion contable
• Membresias (modulo Membresias): Extension de disponibilidad por meses
• Control de Stock: Manejo de existencias y movimientos
• Facturacion: Consumo de articulos al facturar

Servicios externos

• No se detectaron integraciones con servicios externos directos. La sincronizacion web (activo_web, stock_web) sugiere integracion con un sistema e-commerce, pero los detalles no estan en el codigo analizado.

---

Criterios de aceptacion

• [x] AC-001: Se puede crear un articulo nuevo con campos obligatorios (nombre, rubro, linea, categoria IVA) y el sistema asigna un codigo automatico
• [x] AC-002: Se puede modificar cualquier campo de un articulo existente (excepto costo)
• [x] AC-003: No se puede crear un articulo con un codigo comercial ya existente
• [x] AC-004: El listado muestra articulos paginados con filtrado por columna y ordenamiento
• [x] AC-005: Se pueden gestionar multiples listas de precios por articulo
• [x] AC-006: Los campos del formulario se muestran u ocultan segun los modulos habilitados
• [x] AC-007: Se puede activar o desactivar un articulo desde la modificacion
• [x] AC-008: Las ubicaciones se gestionan de forma jerarquica hasta 5 niveles
• [x] AC-009: Si el modulo de membresias esta habilitado, se pueden configurar meses de disponibilidad
• [x] AC-010: El listado por defecto muestra solo articulos activos

---

---

Referencias Tecnicas

• Documentacion Tecnica Backend
• Documentacion Tecnica Frontend

---

NOTA IMPORTANTE: Esta documentacion fue generada automaticamente analizando el codigo implementado. Se recomienda validar con stakeholders de negocio para confirmar que refleja fielmente los requisitos originales.