Documentación del Sistema

Appearance

Vendedores - Resource ​

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

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

Descripcion General ​

El recurso Vendedores permite gestionar el catalogo de vendedores de la empresa. Los vendedores son personas o entidades responsables de las operaciones comerciales de venta, y se asocian a comprobantes (facturas, notas de credito, notas de debito) y a clientes. Cada vendedor tiene un porcentaje de comision que se aplica a los items de los comprobantes que genera.

El recurso esta disponible dentro del modulo de Ventas, en la seccion "Bases", y es compartido con los modulos de Cuenta Corriente y CRM.

Frontend (Perspectiva de Usuario) ​

Vistas ​

  1. Listado de Vendedores (vista principal): Tabla con todos los vendedores activos mostrando codigo y nombre. Incluye botones de accion para consultar, modificar y eliminar. Permite exportar a Excel y PDF.
  2. Formulario de Vendedor (modal): Formulario de alta y modificacion que se presenta en ventana modal. En modo consulta, los campos se deshabilitan y solo se muestra el boton "Aceptar" para cerrar.
  3. Informe de Vendedores (vista de reporte): Formulario para generar un informe PDF con rango de vendedores (desde/hasta), con autocomplete para seleccionar vendedores.

Interacciones del usuario ​

  • Crear vendedor: Boton "Nvo. Vendedor" (atajo Alt+A) en la vista principal abre el formulario vacio.
  • Consultar vendedor: Boton de "ojo" en la tabla abre el formulario en modo solo lectura.
  • Modificar vendedor: Boton de "lapiz" en la tabla abre el formulario con los datos cargados y habilitados para edicion.
  • Eliminar vendedor: Boton de "basura" en la tabla solicita confirmacion antes de eliminar.
  • Buscar localidad: Autocomplete en el campo localidad que busca por codigo postal, nombre de localidad o provincia.
  • Generar informe: Seleccionar rango de vendedores (desde/hasta) y generar PDF (atajo Alt+I).

Permisos ​

  • VENTAS_BASES_VENDEDORES: Acceso al listado, alta y modificaciones de vendedores.
  • VENTAS_INF_VENDEDORES: Generacion de informe de listado de vendedores.

Estados de UI ​

  • Cargando: Indicador de carga mientras se obtienen los datos de la tabla.
  • Registrando cambios: Indicador de carga durante alta o modificacion.
  • Eliminando vendedor: Indicador de carga durante eliminacion.
  • Confirmacion de eliminacion: Modal de confirmacion antes de eliminar.
  • Exito en alta: Toast de confirmacion con el codigo asignado al nuevo vendedor.
  • Exito en modificacion: Toast de confirmacion de modificacion exitosa.
  • Exito en eliminacion: Modal de confirmacion de eliminacion exitosa.
  • Error de comision: Mensaje de error si el porcentaje de comision supera 100.
  • Error en informe: Mensaje de error si el vendedor "desde" es mayor que el vendedor "hasta".

Backend (Perspectiva de Datos de Negocio) ​

Entidades de negocio ​

Vendedor: Persona o entidad comercial responsable de las operaciones de venta.

Datos necesarios ​

DatoObligatoriedadDescripcion
CodigoAutomatico (solo lectura)Identificador numerico unico, asignado automaticamente
NombreObligatorioNombre del vendedor (3 a 35 caracteres)
DocumentoOpcionalDocumento de identidad (DNI/CUIL/CUIT), formato validado
ComisionObligatorioPorcentaje de comision sobre ventas (0 a 100)
DomicilioOpcionalDireccion del vendedor (3 a 25 caracteres)
LocalidadOpcionalLocalidad del vendedor, seleccionada por autocomplete
TelefonoOpcionalNumero de telefono, formato validado

Relaciones de negocio ​

  • Un vendedor puede estar asociado a multiples comprobantes de venta (facturas, notas de credito, notas de debito).
  • Un vendedor puede estar asociado a multiples clientes como vendedor asignado.
  • Un vendedor puede estar asociado a multiples pedidos.
  • La localidad del vendedor referencia al catalogo general de localidades del sistema.
  • El porcentaje de comision del vendedor se traslada a los items de los comprobantes que genera.

Validaciones de negocio ​

  • El nombre es obligatorio y debe tener entre 3 y 35 caracteres.
  • La comision es obligatoria y no puede superar el 100%.
  • El documento, si se ingresa, debe cumplir el formato de DNI/CUIL/CUIT argentino.
  • El telefono, si se ingresa, debe cumplir el formato de telefono valido.
  • El domicilio, si se ingresa, debe tener entre 3 y 25 caracteres.
  • El codigo se genera automaticamente al crear (proximo numero disponible).

Reglas de negocio ​

  • Regla 1: Asignacion automatica de codigo

    • Condicion: Al crear un nuevo vendedor
    • Accion: El sistema asigna automaticamente el proximo codigo disponible (maximo existente + 1)

  • Regla 2: Eliminacion logica (soft delete)

    • Condicion: Al eliminar un vendedor
    • Accion: El vendedor no se elimina fisicamente, se marca como eliminado. Los vendedores eliminados no aparecen en listados ni busquedas.

  • Regla 3: Vendedor por defecto

    • Condicion: Al inicializar el sistema
    • Accion: Se crea automaticamente un vendedor con codigo 1 y nombre "CASA CENTRAL" como registro por defecto.

  • Regla 4: Comision maxima

    • Condicion: Al ingresar la comision
    • Accion: Si el porcentaje ingresado supera 100, se ajusta automaticamente a 100 y se muestra un mensaje de error.

  • Regla 5: Comision en comprobantes

    • Condicion: Al generar un comprobante de venta
    • Accion: El porcentaje de comision del vendedor se registra en cada item del comprobante para el calculo posterior de comisiones.

Casos de uso ​

Caso 1: Alta de vendedor ​

Actor: Usuario con permiso VENTAS_BASES_VENDEDORES

Precondiciones:

  • El usuario debe estar autenticado en el sistema
  • El usuario debe tener acceso al modulo de Ventas y al submenu Bases > Vendedores

Flujo principal:

  1. El usuario accede al listado de vendedores
  2. El usuario presiona el boton "Nvo. Vendedor" (o Alt+A)
  3. El sistema muestra el formulario de vendedor en modo alta (sin codigo visible)
  4. El usuario ingresa el nombre del vendedor (obligatorio)
  5. El usuario ingresa la comision (obligatorio, valor por defecto 0)
  6. Opcionalmente, el usuario ingresa domicilio, localidad (por autocomplete), documento y telefono
  7. El usuario presiona "Aceptar"
  8. El sistema valida los datos ingresados
  9. El sistema asigna automaticamente el proximo codigo disponible
  10. El sistema registra el vendedor y muestra confirmacion con el codigo asignado
  11. El nuevo vendedor aparece en la tabla del listado

Postcondiciones:

  • El vendedor queda registrado con un codigo unico
  • El vendedor aparece en la tabla del listado

Flujos alternativos:

  • Error de validacion: Si los datos no cumplen las validaciones, el formulario muestra el error y permite corregir.
  • Comision mayor a 100: El sistema ajusta automaticamente a 100 y muestra advertencia.

Caso 2: Modificacion de vendedor ​

Actor: Usuario con permiso VENTAS_BASES_VENDEDORES

Precondiciones:

  • Debe existir al menos un vendedor registrado

Flujo principal:

  1. El usuario accede al listado de vendedores
  2. El usuario presiona el boton de edicion (lapiz) en la fila del vendedor deseado
  3. El sistema muestra el formulario con los datos actuales del vendedor, incluyendo el codigo (solo lectura)
  4. El usuario modifica los campos deseados
  5. El usuario presiona "Aceptar"
  6. El sistema valida y actualiza los datos
  7. La tabla del listado se actualiza con los nuevos datos

Postcondiciones:

  • Los datos del vendedor quedan actualizados en el sistema

Caso 3: Eliminacion de vendedor ​

Actor: Usuario con permiso VENTAS_BASES_VENDEDORES

Precondiciones:

  • Debe existir al menos un vendedor registrado

Flujo principal:

  1. El usuario accede al listado de vendedores
  2. El usuario presiona el boton de eliminacion (basura) en la fila del vendedor deseado
  3. El sistema muestra un modal de confirmacion
  4. El usuario confirma la eliminacion
  5. El sistema marca el vendedor como eliminado (soft delete)
  6. El vendedor desaparece de la tabla del listado

Postcondiciones:

  • El vendedor queda marcado como eliminado y no aparece en busquedas ni listados
  • Los comprobantes historicos que referencian al vendedor mantienen su referencia

Flujos alternativos:

  • Cancelacion: El usuario cancela y el vendedor permanece sin cambios.

Consideraciones ​

Seguridad ​

  • El acceso al mantenimiento de vendedores esta protegido por el permiso VENTAS_BASES_VENDEDORES.
  • La generacion de informes requiere el permiso VENTAS_INF_VENDEDORES.
  • Todas las operaciones requieren autenticacion previa (sesion activa).

Auditoria ​

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

Rendimiento ​

  • La busqueda por filtro (autocomplete) limita los resultados a 10 registros para mantener respuesta rapida.
  • El listado principal carga todos los vendedores activos (filtrados por soft delete).

Dependencias ​

Funcionalidades relacionadas ​

  • Facturacion (Ventas): Los comprobantes de venta (facturas, notas de credito, notas de debito) requieren un vendedor asignado.
  • Clientes (Ventas): Los clientes pueden tener un vendedor asignado.
  • Pedidos (Ventas): Los pedidos referencian un vendedor.
  • Localidades (General): El campo localidad del vendedor referencia al catalogo de localidades.
  • Informe de Comisiones (Ventas): Utiliza la comision del vendedor registrada en los items de comprobantes.

Servicios externos ​

  • Ninguno identificado.

Criterios de aceptacion ​

  • [x] AC-001: El sistema permite listar todos los vendedores activos con codigo y nombre.
  • [x] AC-002: El sistema permite crear un nuevo vendedor con asignacion automatica de codigo.
  • [x] AC-003: El sistema permite modificar los datos de un vendedor existente.
  • [x] AC-004: El sistema permite eliminar un vendedor (eliminacion logica).
  • [x] AC-005: El sistema permite consultar los datos completos de un vendedor en modo solo lectura.
  • [x] AC-006: El sistema valida el nombre (obligatorio, 3-35 caracteres) y la comision (obligatoria, 0-100%).
  • [x] AC-007: El sistema valida el formato de documento y telefono cuando se ingresan.
  • [x] AC-008: El campo localidad permite busqueda por autocomplete (codigo postal, nombre, provincia).
  • [x] AC-009: El sistema permite generar un informe PDF de vendedores por rango.
  • [x] AC-010: El sistema permite exportar el listado de vendedores a Excel y PDF.

Preguntas Pendientes ​

Informacion Faltante: Hay preguntas sobre esta funcionalidad que requieren validacion. Ver: Preguntas sobre Vendedores

Referencias Tecnicas ​

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.