Conceptos de Notas - Documentacion Tecnica Frontend

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

Modulo: Ventas Feature: Conceptos de Notas de Credito y Debito (ABM) Fecha: 2026-02-09 Documento de Negocio: conceptos-notas-resource.md

---

Arquitectura Implementada

Estado actual: Frontend legacy (vanilla JavaScript + jQuery + PHP templates)

No es una aplicacion React. Todo el frontend esta implementado con:

• PHP para el template HTML (server-side rendering)
• Vanilla JavaScript (ES Modules) para logica del cliente
• jQuery para DataTables y manipulacion del DOM
• Bootstrap 4 para estilos y modales
• SweetAlert2 para notificaciones y confirmaciones
• API.js (legacy) para comunicacion con el backend

Componente	Archivo	Tecnologia
Vista principal	public/view/mod-ventas/conceptos-notas.php	PHP + HTML
Logica principal	public/js/view/mod-ventas/conceptos-notas.js	Vanilla JS (ES Module)
Template formulario	public/php/components/mod-venta/forms/form-conceptos-notas.html	HTML puro
Logica formulario	public/js/components/forms/ventas/form-conceptos-notas.js	Vanilla JS (ES Module)

---

Componentes Implementados

Vista Principal (conceptos-notas.php)

Ubicacion: /var/www/Bautista/public/view/mod-ventas/conceptos-notas.php

Estructura:

• Carga el layout estandar de AdminLTE (preloader, navbar, sidebar de ventas, footer)
• Contiene un boton "Nva. Concepto de Nota | Alt+A" en el header
• Radio buttons para alternar entre "Nota Credito" y "Nota Debito"
• Tabla vacia (#tablaNotas) que se llena dinamicamente
• Carga el script principal como ES Module

URL de acceso: ?loc=mvcn

Navegacion en sidebar: Se activa idNavMainSideBarBases > idMainSideBarConceptosNotas

Nota: El breadcrumb muestra incorrectamente "Home > Modulo Tesoreria > Valores de Terceros" (deberia ser Ventas > Bases > Conceptos Notas).

---

Logica Principal (conceptos-notas.js)

Ubicacion: /var/www/Bautista/public/js/view/mod-ventas/conceptos-notas.js

Responsabilidades:

1. Inicializar DataTable con columnas dinamicas
2. Cargar ambos catalogos (credito y debito) al inicio
3. Gestionar eventos de alta, modificacion y eliminacion
4. Mantener estado local de datos en variables datosTablaCredito y datosTablaDebito
5. Alternar la tabla entre ambos catalogos segun seleccion del usuario

Estado local (variables de modulo):

Variable	Tipo	Descripcion
opcionConceptoNota	string	Catalogo activo: 'credito' o 'debito'
datosTablaCredito	array	Cache local de conceptos de credito
datosTablaDebito	array	Cache local de conceptos de debito
permisos	object	Permisos de la empresa (modulos habilitados)

Columnas de la tabla:

Columna	Campo	Condicion
Codigo	id	Siempre
Nombre	nombre	Siempre
Cuenta	cuentasFormat	Solo si permisos.modulo_contabilidad es true
Acciones	(botones)	Siempre: Modificar + Eliminar

Funciones implementadas:

• cargarTabla(tipo): Limpia la DataTable y carga datos del catalogo seleccionado.
• agregarElementoTabla(data): Agrega un nuevo registro a la tabla y al cache local.
• editarElementoTabla(data): Busca y reemplaza un registro en el cache local, recarga la tabla.
• eliminarNota(data): Llama al endpoint DELETE, elimina del cache local y recarga la tabla.
• formatearDatosTabla(): Si contabilidad esta habilitada, genera campo cuentasFormat con formato "numero | nombre" para cada concepto.

Eventos registrados:

Evento	Elemento	Accion
click	#btn_alta	Abre formulario de alta
click	#btnModificar (delegado en tabla)	Abre formulario de edicion
click	#btnEliminar (delegado en tabla)	Muestra confirmacion y elimina
input	#optionNotaCredito	Cambia catalogo a credito
input	#optionNotaDebito	Cambia catalogo a debito

---

Formulario (form-conceptos-notas.js + form-conceptos-notas.html)

Ubicacion JS: /var/www/Bautista/public/js/components/forms/ventas/form-conceptos-notas.jsUbicacion HTML: /var/www/Bautista/public/php/components/mod-venta/forms/form-conceptos-notas.html

Patron: Formulario modal reutilizable para alta y modificacion.

Funcion exportada: createFormConceptoNotas(codigo, onSubmitCallback, permisoContabilidad, notaEditar)

Parametros:

Parametro	Tipo	Default	Descripcion
codigo	number	3	Codigo ARCA del tipo de comprobante
onSubmitCallback	Function	-	Callback ejecutado tras submit exitoso con los datos del concepto
permisoContabilidad	boolean	false	Si el modulo de contabilidad esta habilitado
notaEditar	object|null	null	Datos del concepto a editar. null = modo alta

Campos del formulario:

Campo	Tipo	ID	Requerido	Descripcion
Detalle	text input	idInputDetalle	Si	Nombre/descripcion del concepto
Tipo	select	idSelectTipo	Si	Tipo de concepto: S(Sin detalle), D(Con articulos), C(Cancelacion)
Cuenta	text input (autocomplete)	idInputCuenta	Si (si visible)	Cuenta contable. Visible solo si permisoContabilidad=true

Comportamiento condicional:

• Si codigo === 2 (nota de debito): Se elimina la opcion "D" (Con articulos) del select de tipo.
• Si permisoContabilidad === false: Se oculta el campo de cuenta contable y se desactiva su required.
• Si notaEditar !== null: El titulo cambia a "Modificacion de conceptos de notas" y los campos se precargan.

Estructura del objeto conceptoNota (estado local del formulario):

{
    id: null,           // ID del concepto (null para alta, int para edicion)
    codigo: null,       // Codigo ARCA del tipo de comprobante
    nombre: null,       // Descripcion ingresada
    cuenta_contable: null, // Numero de cuenta contable seleccionada
    tipo: 'S',          // Tipo seleccionado (default: 'S')
    cuentasFormat: null  // String formateado "numero | nombre" para display
}

Autocompletado de cuentas contables:

• Usa setAutocomplete() de util/inputs.js (jQuery UI Autocomplete)
• Endpoint: GET mod-contabilidad/cuenta?filter={term}&scope=min
• Formato de opciones: "numero | nombre"
• Al seleccionar: guarda numero en cuenta_contable y formato en cuentasFormat
• Al borrar: limpia ambos campos

Flujo de submit:

1. Valida formulario con isValidForm(form) (validacion HTML5 nativa)
2. Si es edicion (notaEditar !== null): PUT mod-ventas/concepto-comprobante con el objeto completo
3. Si es alta: POST mod-ventas/concepto-comprobante con el objeto completo
4. En alta, actualiza conceptoNota.id con el ID retornado por el backend
5. Ejecuta onSubmitCallback(conceptoNota) para actualizar la vista padre
6. Cierra el modal

---

Integracion con Backend (API)

Endpoints Consumidos

Metodo	Endpoint	Proposito	Parametros
GET	mod-ventas/concepto-comprobante	Listar conceptos	{codigo: 3|2}
POST	mod-ventas/concepto-comprobante	Crear concepto	{codigo, nombre, tipo, cuenta_contable}
PUT	mod-ventas/concepto-comprobante	Actualizar concepto	{codigo, id, nombre, tipo, cuenta_contable}
DELETE	mod-ventas/concepto-comprobante	Eliminar concepto	{id, codigo}
GET	mod-contabilidad/cuenta	Buscar cuentas contables	{filter, scope:'min'}

Comunicacion: Via ApiRequest class (legacy, js/middleware/API.js). Usa FormData + fetch internamente con propagacion automatica de X-Schema header desde localStorage.

Mapeo de codigos:

• Frontend envia codigo: 3 para nota de credito, codigo: 2 para nota de debito.
• Estos corresponden a los codigos ARCA para comprobantes tipo "A" (Nota de Credito A = 3, Nota de Debito A = 2).

---

Routing

URL: ?loc=mvcn

Este recurso utiliza el sistema de routing legacy basado en parametro GET loc. No utiliza React Router ni ningun sistema de routing SPA.

El archivo index.php del frontend mapea mvcn al template view/mod-ventas/conceptos-notas.php.

---

Permisos en Frontend

• Acceso a la vista: Controlado por el sidebar. El link solo se renderiza si el usuario tiene el permiso VENTAS_BASES_CONCEPTOS-NOTAS (verificado en PHP server-side en main-sidebar-venta.php).
• Columna de cuenta contable: Controlada por permisos.modulo_contabilidad obtenido via getPermisosModulos() (verificacion client-side).

---

Bibliotecas y Dependencias Frontend

Dependencia	Version	Uso
jQuery	3.x	Manipulacion DOM, DataTables, modales
DataTables	BS4	Tabla con paginacion, busqueda, ordenamiento
Bootstrap 4	4.x	Layout, modales, botones, formularios
SweetAlert2	-	Notificaciones toast, confirmaciones, loading
jQuery UI	-	Autocomplete de cuentas contables
Font Awesome	6.x	Iconos en botones
AdminLTE	3.x	Template de interfaz de administracion

---

Estado de Migracion

No migrado a React/TypeScript. Todo el frontend es legacy.

Componentes que necesitarian migracion a React si se moderniza:

• Vista principal -> React component con TanStack Query
• DataTable -> Componente de tabla React (posiblemente TanStack Table)
• Formulario modal -> React Hook Form + Zod schema + Modal component
• Autocomplete de cuentas -> Componente ControlledAutoComplete
• Estado local -> TanStack Query cache + useState

---

Tests Existentes

No se encontraron tests frontend para este recurso (ni Vitest ni otro framework).

---

Preguntas Tecnicas Pendientes

Aclaraciones Requeridas: Hay aspectos tecnicos que requieren validacion. Ver: Preguntas sobre Conceptos de Notas

---

Referencias

• Requisitos de Negocio
• Documentacion Backend

---

NOTA IMPORTANTE: Esta documentacion fue generada automaticamente analizando el codigo implementado. Validar cambios futuros contra este baseline.