Documentación del Sistema

Appearance

Agrupacion y Linea de Articulos - Resource ​

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

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

Descripcion ​

Las Agrupaciones (Rubros) y Lineas son una estructura jerarquica de dos niveles que permite clasificar los articulos del modulo de ventas. Las Agrupaciones representan la categoria principal (nivel superior) y las Lineas representan sub-categorias dentro de cada Agrupacion (nivel inferior).

Esta clasificacion se utiliza para:

  • Organizar el catalogo de articulos por familias y sub-familias
  • Filtrar productos por agrupacion o linea en otros procesos del sistema (ej: generacion de listas de precios por rango de agrupaciones)
  • Facilitar la busqueda y navegacion del catalogo de articulos

La relacion es: una Agrupacion contiene cero o mas Lineas, y cada Linea pertenece exactamente a una Agrupacion.

Frontend (Perspectiva de Usuario) ​

Vistas ​

  1. Listado de Agrupaciones (?loc=mva): Vista principal que muestra una tabla con todas las agrupaciones existentes. Incluye columnas de codigo y nombre. Desde cada registro se puede acceder a las lineas de esa agrupacion o modificar la agrupacion.

  2. Listado de Lineas (?loc=mvl&rubro={id}): Vista secundaria que muestra las lineas asociadas a una agrupacion especifica. El titulo de la pagina indica a que agrupacion pertenecen las lineas mostradas. Incluye columnas de codigo de linea y descripcion.

Interacciones del usuario ​

Agrupaciones:

  • Visualizar listado completo de agrupaciones en tabla con botones de exportacion (Excel, PDF)
  • Crear nueva agrupacion mediante formulario modal (boton "Nva. Agrupacion" o atajo Alt+A)
  • Modificar una agrupacion existente (boton de edicion en cada fila)
  • Navegar a las lineas de una agrupacion (boton "Lineas" en cada fila)

Lineas:

  • Visualizar listado de lineas de una agrupacion especifica, con exportacion (Excel, PDF)
  • Crear nueva linea dentro de la agrupacion actual (boton "Nva. Linea" o atajo Alt+A)
  • Modificar una linea existente (boton de edicion en cada fila)
  • Navegar de vuelta a la vista de agrupaciones mediante breadcrumb

Permisos ​

  • VENTAS_BASES_AGR-LIN: Acceso al listado, alta y modificaciones de agrupaciones y lineas (nivel 3)

Estados de UI ​

  • Carga: Indicador de carga (popup) mientras se obtienen los datos del servidor
  • Exito en creacion: Notificacion toast indicando el codigo asignado al nuevo registro
  • Exito en modificacion: Notificacion toast indicando modificacion exitosa
  • Error: Modal de error si ocurre un problema en la obtencion de datos
  • Tabla vacia: DataTable sin registros con mensaje estandar del plugin

Backend (Perspectiva de Datos de Negocio) ​

Entidades de negocio ​

1. Agrupacion (Rubro) Categoria principal para clasificar articulos. Cada agrupacion tiene un codigo unico auto-incremental y un nombre descriptivo.

2. Linea Sub-categoria dentro de una agrupacion. Cada linea tiene un codigo auto-incremental dentro de su agrupacion padre, una referencia a la agrupacion, y una descripcion.

Datos necesarios ​

Agrupacion:

  • Codigo unico (auto-generado)
  • Nombre/concepto (obligatorio, maximo 30 caracteres)

Linea:

  • Codigo de linea (auto-generado, unico dentro de la agrupacion)
  • Referencia a la agrupacion padre (obligatorio)
  • Descripcion (obligatorio, maximo 30 caracteres segun DTO, 50 en base de datos)

Relaciones de negocio ​

  • Una Agrupacion contiene cero o mas Lineas
  • Cada Linea pertenece exactamente a una Agrupacion
  • Los Articulos (Productos) del sistema hacen referencia tanto a una Agrupacion como a una Linea para su clasificacion

Nota (2026-02-09): No posee FK de momento, sólo FK lógica como muchas de las FK del sistema. Las relaciones se validan en la capa de aplicación.

Validaciones de negocio ​

Agrupacion:

  • El nombre es obligatorio y no puede exceder 30 caracteres

Linea:

  • La descripcion es obligatoria y no puede exceder 30 caracteres (DTO) / 50 caracteres (proxy frontend)
  • La agrupacion padre es obligatoria y debe ser un identificador numerico valido
  • El codigo de la linea es obligatorio y numerico para operaciones de modificacion

Reglas de negocio ​

  • Regla 1: Codigos auto-generados

    • Condicion: Al crear una nueva agrupacion o linea
    • Accion: El sistema asigna automaticamente el siguiente codigo disponible (MAX + 1). Para agrupaciones es global; para lineas es dentro de la agrupacion padre.

  • Regla 2: Clave primaria compuesta en lineas

    • Condicion: Una linea se identifica por la combinacion de su codigo y el codigo de la agrupacion
    • Accion: Dos lineas pueden tener el mismo codigo numerico siempre que pertenezcan a agrupaciones diferentes

  • Regla 3: Navegacion de primer/ultimo registro

    • Condicion: Se solicita obtener el primer o ultimo rubro
    • Accion: El sistema retorna un unico registro ordenado por codigo ascendente (primer) o descendente (ultimo). Esta funcionalidad se utiliza internamente en otros modulos (ej: formulario de productos).

  • Regla 4: Filtrado por autocomplete

    • Condicion: Se proporciona un filtro de busqueda
    • Accion: Se busca por nombre (coincidencia parcial, insensible a mayusculas/minusculas) o por codigo (coincidencia exacta), limitando los resultados a 10 registros.

  • Regla 5: Seed de datos por defecto

    • Condicion: Al inicializar el sistema (migraciones)
    • Accion: Se crea una agrupacion "Varios" con codigo 1, y una linea "Varios" con codigo 1 asociada a dicha agrupacion, como datos minimos del sistema.

  • Regla 6: Datos de agrupacion y linea en articulos

    • Condicion: Al consultar un articulo
    • Accion: Los campos de agrupacion y linea del articulo se expanden para mostrar los datos completos (no solo el codigo numerico), utilizando el servicio de agrupacion/linea.

Casos de uso ​

Caso 1: Crear nueva agrupacion ​

Actor: Usuario con permiso VENTAS_BASES_AGR-LIN

Precondiciones:

  • El usuario esta autenticado y tiene acceso al modulo de ventas
  • El usuario tiene el permiso de agrupaciones y lineas

Flujo principal:

  1. El usuario accede al listado de agrupaciones
  2. Presiona el boton "Nva. Agrupacion" (o Alt+A)
  3. Se muestra un formulario modal con el campo "Concepto"
  4. El usuario ingresa el nombre de la agrupacion
  5. Confirma la operacion
  6. El sistema asigna un codigo automatico y registra la agrupacion
  7. Se muestra notificacion de exito con el codigo asignado
  8. La tabla se actualiza mostrando el nuevo registro

Postcondiciones:

  • La agrupacion queda registrada con codigo auto-generado
  • La tabla del listado refleja el nuevo registro

Flujos alternativos:

  • Nombre vacio: El formulario no permite enviar si el campo esta vacio (requerido por HTML)
  • Error de servidor: Se muestra modal de error

Caso 2: Crear nueva linea dentro de una agrupacion ​

Actor: Usuario con permiso VENTAS_BASES_AGR-LIN

Precondiciones:

  • Existe al menos una agrupacion en el sistema
  • El usuario navego al listado de lineas de una agrupacion especifica

Flujo principal:

  1. El usuario esta en la vista de lineas de una agrupacion (titulo muestra nombre de la agrupacion)
  2. Presiona el boton "Nva. Linea" (o Alt+A)
  3. Se muestra un formulario modal con el campo "Descripcion"
  4. El usuario ingresa la descripcion de la linea
  5. Confirma la operacion
  6. El sistema asigna un codigo de linea auto-incremental dentro de la agrupacion
  7. Se muestra notificacion de exito con el codigo asignado
  8. La tabla se actualiza mostrando el nuevo registro

Postcondiciones:

  • La linea queda registrada asociada a la agrupacion
  • El codigo es unico dentro de esa agrupacion

Caso 3: Modificar nombre de agrupacion o descripcion de linea ​

Actor: Usuario con permiso VENTAS_BASES_AGR-LIN

Precondiciones:

  • El registro a modificar existe en el sistema

Flujo principal:

  1. El usuario presiona el boton de edicion en la fila correspondiente
  2. Se muestra el formulario modal con el dato actual pre-cargado
  3. El usuario modifica el nombre/descripcion
  4. Confirma la operacion
  5. Se muestra notificacion de exito
  6. La tabla actualiza el registro en su lugar (sin recargar toda la pagina)

Postcondiciones:

  • El campo modificado queda actualizado en la base de datos

Consideraciones ​

Operaciones Disponibles ​

No existe operación DELETE: Este recurso no implementa eliminación de agrupaciones ni líneas. No existe deleted_at en casi ningún legacy resource. Los registros permanecen en el sistema de forma permanente para mantener la integridad referencial con los artículos que los utilizan.

Campos Sin Uso ​

Los formularios incluyen campos para "Sincroniza con web" que actualmente están deshabilitados. Estos campos (urlimg, activoweb en tabla linea) no se les dio uso de momento y están disponibles para funcionalidad futura.

Atajos de Teclado ​

Los botones de alta muestran "Alt+A" como atajo de teclado. Esta funcionalidad existe en un key-events.js importado global que maneja los atajos en toda la aplicación.

Seguridad ​

  • Solo usuarios autenticados con el permiso VENTAS_BASES_AGR-LIN pueden acceder
  • El permiso cubre listado, alta y modificacion de ambas entidades
  • Los datos se transmiten via JSON autenticado con JWT

Auditoria ​

Nota (2026-02-09): No implementado en recursos legacy. Se agregará en refactorización futura a 5-layer DDD.

Rendimiento ​

  • El filtrado de autocomplete limita a 10 resultados para mantener tiempos de respuesta rapidos
  • Los listados principales no tienen paginacion implementada (cargan todos los registros)
  • Estas tablas son tipicamente de bajo volumen de datos

Dependencias ​

Funcionalidades relacionadas ​

  • Articulos/Productos: Los articulos utilizan agrupacion y linea para su clasificacion. Los campos rubro y linea del articulo son obligatorios.
  • Listas de Precios: El proceso de generacion de lista por margen de ganancia permite filtrar productos por rango de agrupaciones.
  • Informes de Ventas: Existen informes que agrupan datos por agrupacion (ventas-provincias-rubros).

Criterios de aceptacion ​

  • [x] AC-001: El usuario puede visualizar el listado completo de agrupaciones con codigo y nombre
  • [x] AC-002: El usuario puede crear una nueva agrupacion ingresando solo el nombre
  • [x] AC-003: El codigo de la agrupacion se asigna automaticamente
  • [x] AC-004: El usuario puede modificar el nombre de una agrupacion existente
  • [x] AC-005: El usuario puede navegar desde una agrupacion al listado de sus lineas
  • [x] AC-006: El usuario puede crear una nueva linea dentro de una agrupacion
  • [x] AC-007: El codigo de la linea se asigna automaticamente, unico dentro de la agrupacion
  • [x] AC-008: El usuario puede modificar la descripcion de una linea existente
  • [x] AC-009: Ambas tablas permiten exportar a Excel y PDF
  • [x] AC-010: El formulario valida que los campos obligatorios esten completos

Referencias Técnicas ​

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.