Referencias Contables - Documentacion Tecnica Frontend

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

Modulo: Ventas Feature: Referencias Contables Fecha: 2026-02-09 Requisitos de negocio: referencias-contables-resource.md

---

Estado de la Implementacion

Tecnologia: Legacy (vanilla JavaScript + jQuery + jQuery UI + DataTables + Bootstrap 4)

Este recurso NO ha sido migrado a React/TypeScript. Utiliza exclusivamente el stack legacy del frontend.

Aspecto	Tecnologia
Componentes UI	HTML templates + jQuery DOM manipulation
Tabla de datos	jQuery DataTables
Modales	Bootstrap 4 modals via <template> cloning
Formularios	HTML forms con validacion nativa
Autocompletado	jQuery UI Autocomplete
API Client	ApiRequest (legacy API.js con FormData/fetch)
State Management	Variables locales + closure scope
Routing	URL con parametro ?loc=mvrc

---

Archivos Implementados

Archivo	Tipo	Descripcion
public/view/mod-ventas/ref-contables.php	Vista PHP	Template HTML con tabla, modal y scripts
public/js/view/mod-ventas/ref-contables.js	JavaScript (ES Module)	Logica de interaccion, DataTable, formulario
public/php/backend/referencia-contable.php	Proxy PHP	Proxy entre frontend y backend con validacion basica

---

Componente: Vista Principal (ref-contables.php)

Estructura HTML

body.hold-transition.sidebar-mini.sidebar-collapse.layout-fixed
  div.wrapper
    [Preloader]
    [Navbar]
    [Sidebar - mod-venta/main-sidebar-venta.php]
    div.content-wrapper
      section.content-header
        h1 "Listado de referencias contables"
        button#btn_alta "Nva. Ref. Cont. | Alt+A"
        ol.breadcrumb (Home > Ventas > Ref. Cont.)
      section.content
        div.card
          div.card-header "Ref. Cont. registradas en el sistema"
          div.card-body
            table#tablaRefCont
    [Footer]
    template#modalReferencias (modal de alta/modificacion)

Template Modal (#modalReferencias)

Campos del formulario:

Campo	ID	Tipo HTML	Atributos	Descripcion
Codigo	idInputCodigo	text	maxlength="3", required	Codigo alfanumerico
Denominacion	idInputDenominacion	text	maxlength="20", required	Nombre descriptivo
Imputacion de ventas	inputImpVentas	text	required	Autocompletado de cuentas contables
Imputacion de compras	inputImpCompras	text	required (condicional)	Autocompletado de cuentas contables

Botones:

• Cancelar (dismiss modal)
• Aceptar (submit form)

---

Componente: Logica JavaScript (ref-contables.js)

Importaciones

import { getPermisosModulos } from '../../auth/permisos.js'
import { ApiRequest } from '../../middleware/API.js'
import { LANG_TABLE } from '../../util/constantes.js'
import { reemplazarFila } from '../../util/datatable-methods.js'
import { isValidForm } from '../../util/form-methods.js'
import { validateType } from '../../util/input-functions.js'
import { setAutocomplete } from '../../util/inputs.js'

DataTable - Configuracion

Selector: #tablaRefCont

Columnas:

Columna	Data	Render	Orderable
Codigo	codigo	Texto directo	Si
Nombre	nombre	Texto directo	Si
Imp. Ventas	impVentas	${data.numero} | ${data.nombre} (si existe)	Si
Imp. Compras	impCompras	${data.numero} | ${data.nombre} (si existe)	Si
Acciones	null	Boton de edicion (icono lapiz)	No

Opciones: responsive: true, lengthChange: false, autoWidth: false

Botones de exportacion: ['excel', 'pdf']

Idioma: LANG_TABLE (espanol)

Carga Inicial

1. GET 'referencia-contable' con { scope: 'max' }
2. tabla.rows.add(referencias).draw()
3. Carga permisos del usuario
4. Registra evento click en btn_alta
5. Registra evento click delegado para #btnModificar

Funcion: modalFormReferencia(referencia?)

Proposito: Crea y muestra el modal de formulario para alta o modificacion.

Parametros opcionales (modo edicion):

• id: ID de la referencia
• codigo: Codigo actual
• nombre: Nombre actual
• impCompras: Objeto cuenta de compras
• impVentas: Objeto cuenta de ventas

Comportamiento:

1. Clona template #modalReferencias y obtiene elementos del DOM.
2. Inicializa estructura newData con valores recibidos o null.
3. Manejo condicional de compras: Si permisos.modulo_compras es false, deshabilita inputImpCompras.
4. Evento input en codigo: Convierte a mayusculas en tiempo real.
5. Eventos blur: Validacion de tipo en codigo y denominacion.
6. Autocompletado (on modal shown):
   • inputImpVentas: Busca cuentas contables via GET mod-contabilidad/cuenta con { filter, saldo_propio: true }.
   • inputImpCompras: Solo si permisos.modulo_compras. Misma busqueda de cuentas.
   • Formato label: ${numero} | ${nombre}
   • setSelectedData: Asigna objeto cuenta a newData.impVentas o newData.impCompras.
   • deleteSelectedData: Limpia a null.
7. Modo edicion: Si newData.id existe, precarga valores en inputs y cambia titulo a "Modificacion de referencia contable".
8. Modo alta: Titulo "Nueva referencia contable".
9. Submit:
   • Valida formulario con isValidForm().
   • Muestra popup de carga.
   • Extrae valores de inputs.
   • Si id existe: PUT 'referencia-contable' -> actualiza fila en tabla con reemplazarFila().
   • Si no existe: POST 'referencia-contable' -> agrega fila a tabla con tabla.row.add().
   • Cierra modal.
10. Focus inicial: Al abrir modal, focus en campo codigo.
11. Limpieza: Al cerrar modal, elimina elemento del DOM.

---

Integracion con Backend

Endpoints Consumidos

Accion	Metodo HTTP	URL Proxy	Parametros
Listar (con cuentas)	GET	referencia-contable	{ scope: 'max' }
Crear	POST	referencia-contable	{ codigo, nombre, impVentas, impCompras }
Modificar	PUT	referencia-contable	{ id, codigo, nombre, impVentas, impCompras }
Buscar cuentas	GET	mod-contabilidad/cuenta	{ filter: term, saldo_propio: true }

Proxy Frontend (referencia-contable.php)

Ubicacion: public/php/backend/referencia-contable.php

Responsabilidades:

1. Validacion de sesion PHP ($_SESSION['SD_USER']).
2. Validacion de parametros GET (tipo integer para id, longitud para codigo).
3. Proxying de request hacia server/backend/ref_con.php via Request service.
4. Transformacion de respuesta (extrae data del JSON de respuesta del backend).

Metodos soportados: GET, POST, PUT (no DELETE).

Patron de Comunicacion API

Frontend JS (ApiRequest)
  -> AJAX/fetch a /php/backend/referencia-contable.php
    -> PHP Request service a /backend/ref_con.php
      -> RefContableController

El ApiRequest legacy utiliza la URL base configurada + nombre del recurso ('referencia-contable'). El proxy agrega autenticacion de sesion y reenvaa al backend.

---

State Management

Estado Local (Variables de Scope)

Variable	Tipo	Scope	Descripcion
tabla	DataTable instance	Modulo	Instancia de DataTable con datos
permisos	Object	Modulo	Permisos del usuario (cargados async)
newData	Object	Closure (modalFormReferencia)	Datos del formulario en edicion

Flujo de Datos

Carga inicial:
  API GET (scope=max) -> tabla.rows.add() -> render DataTable

Alta:
  Form submit -> API POST -> tabla.row.add() -> render nueva fila

Modificacion:
  Click editar -> leer data-row del boton -> modalFormReferencia(data)
  Form submit -> API PUT -> reemplazarFila() -> render fila actualizada

Nota: No hay invalidacion de cache ni recarga desde servidor despues de operaciones CUD. La tabla se actualiza localmente con los datos enviados.

---

Validaciones del Formulario

Validacion HTML Nativa

Campo	Atributo	Efecto
Codigo	required, maxlength="3"	Impide envio si vacio, limita a 3 caracteres
Denominacion	required, maxlength="20"	Impide envio si vacio, limita a 20 caracteres
Imp. Ventas	required	Impide envio si vacio
Imp. Compras	required (condicional)	Solo requerido si modulo compras habilitado

Validacion JavaScript

• isValidForm(form): Valida el formulario antes de enviar.
• validateType: Evento blur en codigo y denominacion (validacion de tipo).
• Conversion a mayusculas en input de codigo (e.target.value.toUpperCase()).
• Trim de valores en submit (convierte strings vacios a null).

Sin Validacion (gaps identificados)

• No hay validacion de que el autocompletado haya seleccionado una cuenta valida (se puede escribir texto libre).
• No hay validacion de tipo en los campos de cuenta contable del lado frontend.
• La validacion de unicidad de codigo solo ocurre en el backend al momento de guardar.

---

Navegacion y Sidebar

URL de Acceso

?loc=mvrc

Breadcrumb

Home > Ventas > Ref. Cont.

Sidebar Activo

// Abre seccion "Bases" en sidebar
navItemBases.classList.add('menu-is-opening', 'menu-open');
navLinkBases.classList.add('active');
// Marca "Ref. Contables" como activo
navLinkActive.classList.add('active');  // id: idMainSideBarRefContables

Ubicacion en menu: Ventas > Bases > Ref. Contables

---

Atajo de Teclado

Atajo	Accion	Implementacion
Alt+A	Abrir modal de alta	Via label del boton btn_alta (no implementado programaticamente, es hint visual)

Nota: El atajo Alt+A aparece como texto en el boton pero no hay un listener de teclado registrado. La funcionalidad depende del comportamiento nativo del navegador con accesskey (no implementado).

---

Dependencias de Librerias

Libreria	Version	Uso
jQuery	N/A	DOM manipulation, eventos, AJAX
Bootstrap 4	N/A	Grid, modals, forms, badges
jQuery DataTables	N/A	Tabla con paginacion, ordenamiento
DataTables Bootstrap 4	N/A	Estilos Bootstrap para DataTables
DataTables Responsive	N/A	Responsividad de tabla
DataTables Buttons	N/A	Exportacion Excel/PDF
jQuery UI	N/A	Autocompletado de cuentas contables
pdfmake	N/A	Generacion de PDF para exportacion
jszip	N/A	Generacion de Excel para exportacion
Font Awesome	N/A	Iconos (plus, pen, exit)
AdminLTE	N/A	Template de administracion
SweetAlert (CSS)	N/A	Estilos de alertas y popups

---

Diagrama de Flujo de Interaccion

sequenceDiagram
    participant U as Usuario
    participant V as Vista (PHP/JS)
    participant P as Proxy (referencia-contable.php)
    participant B as Backend (ref_con.php)
    participant DB as PostgreSQL

    Note over U,V: Carga Inicial
    U->>V: Accede a ?loc=mvrc
    V->>P: GET referencia-contable {scope: max}
    P->>B: GET ref_con {scope: max}
    B->>DB: SELECT ref_con
    DB-->>B: Registros
    B->>DB: SELECT cuentas (por cada ref)
    DB-->>B: Datos de cuentas
    B-->>P: JSON con refs + cuentas
    P-->>V: JSON refs enriquecidas
    V->>V: tabla.rows.add().draw()

    Note over U,V: Alta
    U->>V: Click "Nva. Ref. Cont."
    V->>V: modalFormReferencia()
    U->>V: Completa formulario
    U->>V: Busca cuenta contable
    V->>P: GET mod-contabilidad/cuenta {filter, saldo_propio}
    P-->>V: Lista de cuentas
    V->>V: Muestra autocompletado
    U->>V: Selecciona cuenta
    U->>V: Click "Aceptar"
    V->>P: POST referencia-contable {data}
    P->>B: POST ref_con {data}
    B->>DB: INSERT ref_con
    DB-->>B: ID generado
    B-->>P: RefContableDTO
    P-->>V: {id, codigo, nombre, ...}
    V->>V: tabla.row.add().draw()
    V->>V: Toast "Referencia contable creada"

---

Preguntas Tecnicas Pendientes

Aclaraciones Requeridas: Hay aspectos tecnicos que requieren validacion. Ver: Preguntas sobre Referencias Contables

---

Referencias

• Requisitos de Negocio
• Documentacion Tecnica Backend

---

NOTA IMPORTANTE: Esta documentacion fue generada automaticamente analizando el codigo implementado. Este recurso utiliza exclusivamente tecnologia legacy (vanilla JS, jQuery, Bootstrap 4) y no ha sido migrado a React/TypeScript. Se recomienda considerar su migracion al stack moderno cuando se requieran modificaciones significativas.