Appearance
ABM de Clientes
Modulo: ventas Tipo: Resource Estado: Implementado Fecha: 2026-02-09
DOCUMENTACION RETROSPECTIVA - Generada a partir de codigo implementado el 2026-02-09. Esta documentacion fue extraida analizando el codigo fuente existente, no a partir de requisitos de negocio originales.
Descripcion
El ABM (Alta, Modificacion) de Clientes permite gestionar el registro maestro de clientes del sistema de ventas. Cada cliente almacena datos de identificacion fiscal (DNI/CUIT), datos de contacto, domicilios, condicion ante el IVA e Ingresos Brutos, vendedor asignado, y configuracion de cuenta corriente. Es una entidad central que se utiliza en facturacion, cuentas corrientes y reportes de ventas.
La entidad Cliente es un recurso cross-module compartido entre los modulos de Ventas y Cuentas Corrientes. La tabla base tambien es utilizada por el modulo de Membresias, donde el modelo Miembro actua como un wrapper de Cliente extendiendo datos adicionales pero manteniendo la misma tabla base.
Nota: Actualmente no se permite eliminar clientes debido a restricciones de integridad referencial con otros modulos del sistema.
Frontend (Perspectiva de Usuario)
Vistas
- Listado de clientes: Tabla con busqueda server-side (DataTables SSR) que muestra codigo, nombre, identificacion, domicilio, telefono, email y marca de cliente por defecto
- Formulario de alta/modificacion: Formulario completo en vanilla JS para crear o editar un cliente con todos sus datos fiscales, de contacto y configuracion comercial. El formulario es un componente reutilizable (
createFormCliente) que se monta dinamicamente en la pagina, soportando modo alta y modo modificacion segun se proporcione un ID de cliente - Informe de lista de clientes: Formulario React para generar reportes de clientes con filtros por cartera, cuenta corriente y opciones de ordenamiento
Interacciones del usuario
- Buscar clientes por nombre, codigo o identificacion (busqueda SSR con paginacion)
- Crear un nuevo cliente con datos completos
- Editar un cliente existente
- Marcar/desmarcar un cliente como "cliente por defecto" (actualizacion parcial con logica exclusiva: solo un cliente puede ser defecto a la vez)
- Consultar si un cliente tiene pendientes (pedidos pendientes)
- Obtener el primer o ultimo cliente por codigo
- Obtener el cliente por defecto
- Generar informe de lista de clientes con filtros
Permisos
- Acceso al modulo de ventas: controla visibilidad de la opcion de clientes en el menu
- Acceso al modulo de cuentas corrientes (modulo_ctacte): controla visibilidad de campos de cuenta corriente en el formulario
- Nota: Los permisos se aplican unicamente en el frontend (client-side). No existe validacion de permisos a nivel backend; cualquier usuario autenticado puede acceder a los endpoints de clientes
Estados de UI
- Carga de datos: indicador de carga mientras se obtienen clientes
- Error: mensajes de error al fallar la carga de datos
- Formulario de informe: indicador "Generando..." durante la creacion del reporte
- Validacion: mensajes de error en campos invalidos del formulario de informe
Backend (Perspectiva de Datos de Negocio)
Entidades de negocio
Cliente: Entidad principal que representa a un cliente comercial del sistema.
Datos necesarios
| Dato | Requerido | Descripcion |
|---|---|---|
| Codigo (id) | Auto-generado | Numero unico secuencial del cliente |
| Nombre | Si | Nombre o razon social (3 a 55 caracteres) |
| Identificacion | No | DNI o CUIT del cliente (validacion de formato) |
| Domicilio principal | No | Direccion principal (hasta 35 caracteres) |
| Domicilio secundario | No | Direccion alternativa (hasta 35 caracteres) |
| Telefono principal | No | Numero de telefono (numerico) |
| Telefono secundario | No | Numero de telefono alternativo (numerico) |
| No | Direccion de correo electronico (formato valido, hasta 50 caracteres) | |
| Localidad | Si | Localidad del cliente (referencia a tabla de localidades) |
| Condicion IVA | Si | Condicion ante el IVA (Responsable Inscripto, Monotributista, Consumidor Final, Exento) |
| Tipo Ingresos Brutos | Si | Condicion ante IIBB |
| Numero Ingresos Brutos | No | Numero de inscripcion IIBB (hasta 13 caracteres) |
| Vendedor asignado | Si | Vendedor responsable de la cuenta |
| Comision | No | Porcentaje de comision del vendedor (numerico) |
| Cartera | No | Cartera comercial a la que pertenece el cliente |
| Tiene cuenta corriente | No | Indica si el cliente opera con cuenta corriente |
| Margen de credito | No | Limite de credito en cuenta corriente (solo si tiene cuenta corriente) |
| Facturas impagas permitidas | No | Cantidad maxima de facturas impagas (solo si tiene cuenta corriente) |
| Relacion lista de precios | No | Tipo de relacion con lista de precios |
| Numero de lista | No | Lista de precios asignada |
| Cliente por defecto | No | Marca si es el cliente predeterminado del sistema (solo uno puede serlo). Se utiliza como valor inicial en formularios que requieren un cliente (ej: facturacion electronica) para que el campo no quede vacio |
| Fecha de alta | Auto-generado | Fecha en que se dio de alta el cliente |
| Ultimo movimiento | Solo lectura | Fecha del ultimo movimiento registrado |
Relaciones de negocio
- Un cliente pertenece a una localidad
- Un cliente tiene una condicion de IVA
- Un cliente tiene una condicion de Ingresos Brutos (IIBB)
- Un cliente tiene un vendedor asignado
- Un cliente puede pertenecer a una cartera comercial
- Un cliente puede tener cuentas corrientes asociadas
- Un cliente puede tener pendientes (pedidos) si la empresa tiene habilitado el modulo de pedidos
Validaciones de negocio
- El nombre es obligatorio, debe tener entre 3 y 55 caracteres
- La identificacion (DNI/CUIT) debe tener formato valido si se proporciona
- La identificacion debe ser unica: no pueden existir dos clientes con el mismo DNI/CUIT
- El email debe tener formato valido si se proporciona
- Los domicilios no pueden exceder 35 caracteres
- El numero de IIBB no puede exceder 13 caracteres
- La localidad, condicion de IVA, tipo IIBB y vendedor son obligatorios
- El margen de credito y facturas impagas solo se actualizan si el cliente tiene cuenta corriente
- Solo un cliente puede ser marcado como "cliente por defecto" a la vez; al marcar uno, se desmarca el anterior automaticamente
Reglas de negocio
Regla 1: Unicidad de identificacion fiscal
- Condicion: Al crear o editar un cliente con identificacion (DNI/CUIT)
- Accion: El sistema valida que no exista otro cliente con el mismo numero de identificacion. Si existe, rechaza la operacion con error "Ya existe un cliente con ese numero de identificacion"
Regla 2: Cliente por defecto exclusivo
- Condicion: Al marcar un cliente como "por defecto"
- Accion: El sistema desmarca automaticamente cualquier otro cliente que estuviera marcado como defecto, y luego marca al cliente seleccionado. Solo puede existir un cliente por defecto en todo el sistema. El cliente por defecto se usa como valor inicial en formularios que requieren un cliente (por ejemplo, facturacion electronica) para evitar campos vacios
Regla 3: Campos de cuenta corriente condicionales
- Condicion: Al actualizar un cliente
- Accion: Los campos de margen de credito y facturas impagas solo se actualizan si el cliente tiene cuenta corriente habilitada (tiene_ctacte = 1). Si no tiene cuenta corriente, estos campos conservan su valor anterior
Regla 4: Generacion automatica de codigo
- Condicion: Al crear un nuevo cliente
- Accion: El sistema asigna automaticamente el siguiente numero disponible (MAX(codigo) + 1)
Regla 5: Fecha de alta automatica
- Condicion: Al crear un nuevo cliente
- Accion: La fecha de alta se establece automaticamente como la fecha actual (CURRENT_DATE)
Regla 6: Verificacion de pendientes
- Condicion: Al consultar un cliente, si la empresa tiene habilitado el modulo de pedidos
- Accion: El sistema verifica si el cliente tiene pedidos pendientes y devuelve esta informacion como un flag adicional
Regla 7: Busqueda de clientes
- Condicion: En el listado de clientes (autocomplete)
- Accion: La busqueda filtra por nombre (busqueda parcial insensible a mayusculas), codigo (busqueda exacta) o identificacion (busqueda por prefijo). Se limita a 10 resultados para el autocomplete
Casos de uso
Caso 1: Crear un nuevo cliente
Actor: Usuario del modulo de ventas
Precondiciones:
- El usuario debe estar autenticado y tener acceso al modulo de ventas
- Deben existir localidades, condiciones de IVA, tipos de IIBB y vendedores configurados
Flujo principal:
- El usuario accede al formulario de alta de cliente
- El usuario completa los datos obligatorios: nombre, localidad, condicion IVA, tipo IIBB y vendedor
- El usuario opcionalmente completa datos adicionales: identificacion, domicilios, telefonos, email, cartera, comision, configuracion de cuenta corriente
- El sistema valida el formato de los datos ingresados
- Si se proporciona identificacion, el sistema verifica que no exista otro cliente con el mismo DNI/CUIT
- El sistema genera automaticamente el codigo del cliente y registra la fecha de alta
- El sistema confirma la creacion y devuelve el codigo asignado
Postcondiciones:
- El cliente queda registrado en el sistema con su codigo unico
- La fecha de alta queda registrada
Flujos alternativos:
- Identificacion duplicada: El sistema muestra error "Ya existe un cliente con ese numero de identificacion" y no crea el registro
- Datos invalidos: El sistema muestra errores de validacion especificos por cada campo
Caso 2: Editar un cliente existente
Actor: Usuario del modulo de ventas
Precondiciones:
- El cliente debe existir en el sistema
- El usuario debe estar autenticado
Flujo principal:
- El usuario busca y selecciona el cliente a modificar
- El sistema carga todos los datos del cliente con sus relaciones (localidad, condicion IVA, IIBB, vendedor)
- El usuario modifica los datos necesarios
- El sistema valida los datos modificados
- Si se modifico la identificacion, el sistema verifica unicidad
- El sistema actualiza los datos del cliente
Postcondiciones:
- Los datos del cliente quedan actualizados
- Los campos de cuenta corriente solo se actualizan si el cliente tiene cuenta corriente habilitada
Flujos alternativos:
- Identificacion duplicada: El sistema rechaza la modificacion
- Datos invalidos: El sistema muestra errores de validacion
Caso 3: Marcar cliente como predeterminado
Actor: Usuario del modulo de ventas
Precondiciones:
- El cliente debe existir en el sistema
Flujo principal:
- El usuario selecciona la opcion de marcar un cliente como predeterminado
- El sistema desmarca cualquier cliente que estuviera marcado como defecto
- El sistema marca al cliente seleccionado como defecto
Postcondiciones:
- Solo el cliente seleccionado queda marcado como predeterminado
- El cliente anterior (si existia) queda desmarcado
Caso 4: Generar informe de lista de clientes
Actor: Usuario del modulo de ventas
Precondiciones:
- El usuario debe tener acceso al modulo de ventas
- Si usa filtro de cuenta corriente, debe tener acceso al modulo de cuentas corrientes
- Si usa filtro de cartera, la empresa debe tener habilitada la funcionalidad de carteras
Flujo principal:
- El usuario accede al formulario de informe de lista de clientes
- El usuario opcionalmente configura filtros: rango de carteras, filtro de cuenta corriente (tiene/no tiene/todos)
- El usuario selecciona el ordenamiento: por codigo, alfabetico o por vendedor
- El usuario opcionalmente activa "Ordenar por localidad"
- El sistema genera el informe con los parametros seleccionados
Postcondiciones:
- Se genera el informe en formato PDF/impresion
Flujos alternativos:
- Cartera desde mayor que hasta: El sistema muestra error de validacion
- Error de generacion: El sistema muestra mensaje de error
Consideraciones
Seguridad
- Los datos fiscales de los clientes (CUIT/DNI) requieren proteccion
- El acceso al ABM de clientes debe estar controlado por permisos del modulo de ventas
- Las operaciones de escritura (crear, editar) se ejecutan dentro de transacciones
Auditoria
- No existe auditoria implementada para las operaciones de clientes. Las operaciones de alta y modificacion no se registran en el log de auditoria del sistema
Rendimiento
- La busqueda de clientes para DataTables utiliza Server-Side Rendering (SSR) para manejar grandes volumenes de datos
- Las busquedas de autocomplete se limitan a 10 resultados
- El sistema utiliza scopes (min/max) para obtener solo los campos necesarios segun el contexto, optimizando las consultas
Limitaciones Actuales
- Eliminacion no implementada: No se permite eliminar clientes del sistema. Esto se debe a restricciones de integridad referencial con comprobantes de venta, cuentas corrientes, y otros modulos que referencian al cliente. No existe endpoint DELETE ni funcionalidad de baja
- Sin auditoria: Las operaciones de alta y modificacion de clientes no se registran en el sistema de auditoria
- Sin permisos backend: No hay validacion de permisos a nivel de API. Los permisos son unicamente client-side (el frontend oculta opciones segun configuracion de modulos)
- Concurrencia en alta: La generacion del codigo de cliente (MAX+1) podria generar conflictos en inserciones simultaneas. No se han reportado problemas, pero es una mejora pendiente
Dependencias
Funcionalidades relacionadas
- Modulo de Cuentas Corrientes: Clientes con cuenta corriente habilitada se integran con el sistema de cuentas corrientes
- Modulo de Ventas - Facturacion: Los clientes son referenciados en comprobantes de venta
- Modulo de Ventas - Pedidos: Verificacion de pendientes del cliente (si la empresa tiene pedidos habilitados)
- Informes de Ventas: El cliente es una dimension de agrupacion en reportes
- Localidades: Tabla maestra de localidades
- Condiciones de IVA: Tabla maestra de categorias fiscales
- Ingresos Brutos: Tabla maestra de condiciones IIBB
- Vendedores: Tabla maestra de vendedores
- Carteras: Tabla maestra de carteras comerciales (si la empresa las tiene habilitadas)
Servicios externos
- Ninguno identificado en el codigo analizado
Criterios de aceptacion
- [x] AC-001: El sistema permite crear un cliente con datos obligatorios (nombre, localidad, condicion IVA, IIBB, vendedor) y genera un codigo unico automaticamente
- [x] AC-002: El sistema valida la unicidad del numero de identificacion (DNI/CUIT) al crear y editar clientes
- [x] AC-003: El sistema permite buscar clientes por nombre, codigo o identificacion con paginacion server-side
- [x] AC-004: El sistema permite editar todos los datos de un cliente existente
- [x] AC-005: El sistema permite marcar un unico cliente como "cliente por defecto", desmarcando automaticamente el anterior
- [x] AC-006: Los campos de margen de credito y facturas impagas solo se actualizan si el cliente tiene cuenta corriente
- [x] AC-007: El sistema permite generar un informe de lista de clientes con filtros por cartera, cuenta corriente y opciones de ordenamiento
- [x] AC-008: Las validaciones de formato (email, DNI/CUIT, longitudes maximas) funcionan correctamente
Notas adicionales
- La tabla base de clientes (
ordcon) es compartida entre los modulos de Ventas, Cuentas Corrientes y Membresias. El modulo de Membresias usa un modelo Miembro que actua como wrapper de la tabla base, extendiendo datos en tablas adicionales pero la entidad subyacente sigue siendo un cliente - El recurso Cliente es cross-module: se accede tanto desde Ventas como desde Cuentas Corrientes, donde clientes (ordcon) y proveedores (cpdprov) comparten logica estandarizada en un modelo unico de cuenta corriente
- El endpoint principal opera desde un archivo legacy con switch por metodo HTTP
- El formulario CRUD es vanilla JS (no React), implementado como componente reutilizable
createFormClienteque se monta dinamicamente - Solo el informe de lista de clientes y el hook de datos estan migrados a React/TypeScript
- Existe una migracion formal:
20240823200741_new_table_ordcon.phpcon configuracion dinamica de niveles multi-tenant - La tabla soporta configuracion personalizable por empresa: puede estar a nivel EMPRESA (clientes compartidos entre sucursales) o EMPRESA+SUCURSAL (clientes separados por sucursal)
Referencias Tecnicas
Actualizaciones Post-Generacion
Fecha: 2026-02-09
Informacion Validada:
- [x] Eliminacion de clientes: No implementada (integridad referencial)
- [x] Tabla compartida: ordcon usada por clientes (ventas) y miembros (membresias)
- [x] Formulario CRUD: Vanilla JS legacy (form-cliente.php + form-cliente.js + cliente.js)
- [x] Campo defecto: Valor inicial en formularios (ej: facturacion electronica)
- [x] Validacion: Legacy (proxy frontend, backend, model/DTO), no middleware
- [x] Concurrencia: Sin problemas actuales, mejora pendiente
- [x] Permisos: Client-side only, no backend
- [x] Ruta cross-module: Compartida Ventas + CtaCte
- [x] Schema: Actualizado con migracion 20240823200741
NOTA IMPORTANTE: Esta documentacion fue generada automaticamente analizando el codigo implementado y validada parcialmente con stakeholders el 2026-02-09. Las secciones actualizadas reflejan informacion confirmada por el equipo de desarrollo.