Agrupacion y Linea - Documentacion Tecnica Frontend

Modulo: ventas Feature: Agrupacion (Rubro) y Linea de articulos Fecha: 2026-02-09

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

---

Enlace a Documentacion de Negocio

• Requisitos de Negocio: Agrupacion y Linea
• Documentacion Tecnica Backend

---

Arquitectura Implementada

Patron: Legacy (vanilla JavaScript + PHP templates). No utiliza React, TypeScript, ni TanStack Query. Se basa en jQuery DataTables, Bootstrap 4 modals, y el middleware API.js.

Archivos Frontend

Tipo	Archivo	Descripcion
Vista PHP (Agrupacion)	public/view/mod-ventas/agrupacion.php	Template HTML principal para listado de agrupaciones
Vista PHP (Linea)	public/view/mod-ventas/linea.php	Template HTML principal para listado de lineas
JS View (Agrupacion)	public/js/view/mod-ventas/agrupacion.js	Logica de la vista de agrupaciones
JS View (Linea)	public/js/view/mod-ventas/linea.js	Logica de la vista de lineas
JS Form (Agrupacion)	public/js/components/forms/ventas/agrupacion.js	Componente de formulario de agrupacion
JS Form (Linea)	public/js/components/forms/ventas/linea.js	Componente de formulario de linea
HTML Form (Agrupacion)	public/php/components/mod-venta/forms/agrupacion.html	Template HTML del formulario modal de agrupacion
HTML Form (Linea)	public/php/components/mod-venta/forms/linea.html	Template HTML del formulario modal de linea
Proxy Backend (Rubro)	public/php/backend/rubro.php	Proxy de validacion y reenvio al backend
Proxy Backend (Linea)	public/php/backend/linea.php	Proxy de validacion y reenvio al backend

---

Componentes Implementados

Vista de Agrupaciones (agrupacion.php + agrupacion.js)

Ubicacion: public/view/mod-ventas/agrupacion.php, public/js/view/mod-ventas/agrupacion.jsURL: ?loc=mvaProposito: Listado CRUD de agrupaciones de articulos

Estructura de la pagina:

• Header con titulo "Listado de agrupaciones" y boton "Nva. Agrupacion | Alt+A"
• Breadcrumb: Home > Ventas > Agrupaciones
• Tabla DataTable con exportacion Excel/PDF
• Sidebar del modulo de ventas con item "Agrupacion" activo dentro de "Bases"

DataTable - Columnas:

Columna	Data	Ordenable	Descripcion
Codigo	id	Si	Codigo numerico del rubro
Nombre	concepto	Si	Nombre de la agrupacion
Acciones	(render)	No	Botones: Modificar, Lineas

Botones de Accion por fila:

• Modificar (btn-success, icono lapiz): Abre formulario modal con datos pre-cargados
• Lineas (btn-info, icono lista): Navega a ?loc=mvl&rubro={id} para ver las lineas de esa agrupacion

Interacciones:

1. Al cargar: ApiRequest.get('rubro') obtiene todos los rubros y los muestra en la tabla
2. Boton alta: Invoca createFormAgrupacion() con callback que agrega la fila a la tabla
3. Boton modificar: Extrae datos de la fila, invoca createFormAgrupacion() con updateData, callback reemplaza la fila
4. Boton lineas: Redirige a la vista de lineas con el ID del rubro en URL

---

Vista de Lineas (linea.php + linea.js)

Ubicacion: public/view/mod-ventas/linea.php, public/js/view/mod-ventas/linea.jsURL: ?loc=mvl&rubro={id}Proposito: Listado CRUD de lineas de una agrupacion especifica

Estructura de la pagina:

• Header con titulo "Lineas de la agrupacion: {nombre}" y boton "Nva. Linea | Alt+A"
• Breadcrumb: Home > Ventas > Agrupacion > Lineas
• Tabla DataTable con exportacion Excel/PDF
• Sidebar con item "Agrupacion" activo dentro de "Bases"

Flujo de inicializacion:

1. Extrae parametro rubro de la URL via getUrlParams()
2. Valida que rubro sea numerico (si no, muestra error)
3. Consulta datos del rubro via ApiRequest.get('rubro', { id: rubro }) para mostrar el nombre
4. Consulta lineas via ApiRequest.get('linea', { rubro }) y las muestra en la tabla

DataTable - Columnas:

Columna	Data	Ordenable	Descripcion
Linea	id	Si	Codigo numerico de la linea
Nombre	descri	Si	Descripcion de la linea
Acciones	(default)	No	Boton: Modificar

Boton de Accion por fila:

• Modificar (btn-success, icono lapiz): Abre formulario modal con datos pre-cargados

---

Formulario de Agrupacion (createFormAgrupacion)

Archivo JS: public/js/components/forms/ventas/agrupacion.jsTemplate HTML: public/php/components/mod-venta/forms/agrupacion.html

Funcion exportada: createFormAgrupacion({ appendTo, onSubmitCallback, updateData })

Parametros:

Parametro	Tipo	Obligatorio	Descripcion
appendTo	HTMLElement	No	Elemento contenedor (null = modal)
onSubmitCallback	Function	Si	Callback al completar operacion
updateData	Object	No	Datos para edicion (vacio = alta)

Campos del formulario:

Campo	ID	Tipo HTML	Validacion HTML	Descripcion
Concepto	idInputConcepto	text	required, maxlength=30	Nombre de la agrupacion
Sincroniza con web	(radios)	radio	disabled	Si/No (deshabilitado, sin funcionalidad)

Campos Deshabilitados:

El formulario incluye un campo "Sincroniza con web" con radio buttons deshabilitados (disabled). No se les dio uso de momento y está disponible para funcionalidad futura.

Flujo de submit:

1. Valida formulario con isValidForm(form)
2. Muestra popup de carga
3. Si newData.id existe (update): ApiRequest.put('rubro', newData) -> toast "Agrupacion modificada exitosamente"
4. Si newData.id es null (insert): ApiRequest.post('rubro', newData) -> toast "Agrupacion creada con el codigo: {id}"
5. Ejecuta onSubmitCallback(newData) con los datos actualizados
6. Cierra el modal

Estructura de datos:

{
  id: null | number,    // null para insert, numero para update
  concepto: string      // trimmed, null si vacio
}

---

Formulario de Linea (createFormLinea)

Archivo JS: public/js/components/forms/ventas/linea.jsTemplate HTML: public/php/components/mod-venta/forms/linea.html

Funcion exportada: createFormLinea({ rubro, updateData, onSubmitCallback, appendTo })

Parametros:

Parametro	Tipo	Obligatorio	Descripcion
rubro	number	Si	ID de la agrupacion padre
updateData	Object	No	Datos para edicion (vacio = alta)
onSubmitCallback	Function	Si	Callback al completar operacion
appendTo	HTMLElement	No	Elemento contenedor (null = modal)

Campos del formulario:

Campo	ID	Tipo HTML	Validacion HTML	Descripcion
Descripcion	idInputDescripcion	text	required	Nombre de la linea
Sincroniza con web	(radios)	radio	disabled	Si/No (deshabilitado, sin funcionalidad)

Campos Deshabilitados:

El formulario incluye un campo "Sincroniza con web" con radio buttons deshabilitados (disabled). No se les dio uso de momento y está disponible para funcionalidad futura. En la tabla linea existen campos urlimg y activoweb que corresponden a esta funcionalidad planificada.

Flujo de submit:

1. Valida formulario con isValidForm(form)
2. Muestra popup de carga
3. Si newData.id existe (update): ApiRequest.put('linea', newData) -> toast "Linea modificada exitosamente"
4. Si newData.id es null (insert): ApiRequest.post('linea', newData) -> toast "Linea creada con el codigo: {id}"
5. Ejecuta onSubmitCallback(newData) con los datos actualizados
6. Cierra el modal

Estructura de datos:

{
  rubro: number,        // siempre presente, del contexto padre
  id: null | number,    // null para insert, numero para update
  descri: string        // trimmed, null si vacio
}

---

Patron de Formularios Modales

Ambos formularios siguen el mismo patron legacy:

1. Carga de template: Se obtiene el HTML del formulario via getContentFile() (fetch de archivo .html)
2. Inyeccion en DOM: Se crea un div contenedor, se parsea el HTML, se extrae el .modal
3. Modo modal o embebido: Si appendTo es null, se muestra como modal Bootstrap; si no, se embebe en el contenedor
4. Focus automatico: Al mostrarse el modal, el input principal recibe foco y seleccion
5. Limpieza: Al cerrar el modal, se elimina del DOM. Si hay otros modals abiertos, se restaura modal-open en body
6. Validacion de tipo: Se agrega listener blur con validateType en el input principal

---

Integracion con Backend

Endpoints Consumidos (via API.js -> php/backend proxy)

Metodo	Recurso API.js	Proxy Frontend	Backend	Proposito
GET	rubro	php/backend/rubro.php	backend/lrubro.php	Listar agrupaciones
GET	rubro (con id)	php/backend/rubro.php	backend/lrubro.php	Obtener agrupacion por ID
POST	rubro	php/backend/rubro.php	backend/lrubro.php	Crear agrupacion
PUT	rubro	php/backend/rubro.php	backend/lrubro.php	Modificar agrupacion
GET	linea (con rubro)	php/backend/linea.php	backend/linea.php	Listar lineas de agrupacion
POST	linea	php/backend/linea.php	backend/linea.php	Crear linea
PUT	linea	php/backend/linea.php	backend/linea.php	Modificar linea

Flujo de comunicacion

Vista JS (agrupacion.js / linea.js)
  -> Componente Form JS (agrupacion.js / linea.js)
    -> ApiRequest (API.js middleware)
      -> Frontend Proxy (php/backend/rubro.php / linea.php)
        -> Backend REST (server/backend/lrubro.php / linea.php)

Nota: La clase ApiRequest de API.js usa FormData y fetch. El nombre del recurso ('rubro', 'linea') se mapea al archivo proxy en php/backend/. El proxy valida datos de entrada, agrega la sesion, y reenvia al backend real.

---

Routing

URL de Agrupaciones: ?loc=mvaURL de Lineas: ?loc=mvl&rubro={id_rubro}

El routing es manejado por el sistema legacy basado en parametro loc de la URL. No hay React Router ni rutas Slim involucradas para estas vistas.

La navegacion entre agrupaciones y lineas se realiza con window.location.href.

---

Dependencias y Librerias

Libreria	Version	Uso
jQuery	(plugins)	Selector DOM, DataTables, Bootstrap modals
DataTables	(BS4)	Tabla interactiva con paginacion, busqueda, exportacion
Bootstrap 4	(bundle)	Layout, modals, formularios, botones
Font Awesome	(free)	Iconos
AdminLTE	(min)	Template de admin (sidebar, layout)
SweetAlert2	(Swal)	Popups de carga y alertas toast
pdfmake + jszip	(plugins)	Exportacion PDF y Excel desde DataTables

---

Sidebar / Navegacion

Ambas vistas activan los elementos del sidebar del modulo de ventas:

• Submenu "Bases" (idNavMainSideBarBases) - abierto
• Link "Agrupacion" (idMainSideBarAgrupacion) - activo

Esto se configura con JavaScript inline al final de cada vista PHP.

---

Atajos de Teclado

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

---

Referencias

• Requisitos de Negocio
• Documentacion Backend

---

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