Mi Documentación

Appearance

Arquitectura de acceso a datos por API ​

Este documento describe el diseno aplicado para permitir que la aplicacion VB6 acceda a datos de clientes mediante una API REST, manteniendo como alternativa el acceso directo a la base de datos.

Objetivo ​

La meta es desacoplar los formularios del origen real de los datos. El formulario no deberia decidir si consulta MySQL directamente o si consume HTTP. Esa decision queda centralizada en la clase de dominio, en este caso cCliente.

Con este enfoque se puede migrar funcionalidad gradualmente:

  • Cuando la API esta habilitada, cCliente usa cClienteApiGateway.
  • Cuando la API no esta habilitada, cCliente conserva el comportamiento historico contra menu.conn.
  • Los formularios siguen trabajando con propiedades, metodos y ADODB.Recordset, reduciendo cambios en la UI.

Componentes ​

Formularios ​

Los formularios deben delegar la lectura y escritura de clientes en cCliente.

Ejemplos:

  • frmCliente.frm: ABM de un cliente individual.
  • frmClientes.frm: listado, busqueda y paginado de clientes.

El formulario puede seguir construyendo filtros visuales o validando datos de pantalla, pero no deberia abrir directamente consultas principales contra menu.conn cuando existe una operacion equivalente en la clase.

Clase de dominio cCliente ​

cCliente actua como capa de acceso compatible con VB6. Expone metodos como:

  • SeleccionarXId
  • Listar
  • ListarParametrizado
  • ListarHojaRutaP
  • ListarFiltrado
  • Ingresar
  • Modificar
  • Eliminar

Cada metodo decide internamente que camino usar:

vb
If ClienteApiHabilitada Then
    ' Acceso via API
Else
    ' Acceso directo a BD
End If

La funcion ClienteApiHabilitada valida dos condiciones:

  • que la API de clientes este habilitada;
  • que exista una BaseUrl configurada.

Gateway REST cClienteApiGateway ​

cClienteApiGateway encapsula los detalles HTTP:

  • construccion del recurso REST;
  • envio de requests con cRestClient;
  • parseo de JSON;
  • validacion de respuestas HTTP;
  • extraccion de colecciones, objetos y totales.

La clase de dominio no deberia armar HTTP manualmente. Solo llama al gateway.

Cliente HTTP cRestClient ​

cRestClient contiene la infraestructura generica para consumir REST:

  • BaseUrl;
  • token bearer;
  • timeout;
  • headers;
  • serializacion/deserializacion JSON.

Este componente es reutilizable por otros dominios si se migran mas entidades.

Configuracion modRestApi ​

La configuracion se lee desde settings de la aplicacion o variables de entorno:

  • ClientesHabilitada / MG_API_CLIENTES_HABILITADA
  • BaseUrl / MG_API_BASE_URL
  • Token / MG_API_TOKEN
  • TimeoutMs / MG_API_TIMEOUT_MS

Tambien puede configurarse por codigo con ConfigurarApiClientes.

Flujo de lectura ​

Para un listado filtrado de clientes:

  1. frmClientes toma los valores de los controles de busqueda.
  2. Arma los filtros historicos SQL para compatibilidad con BD directa.
  3. Arma tambien un query string REST equivalente.
  4. Llama a cCliente.ListarFiltrado.
  5. cCliente decide:
    • si la API esta habilitada, llama a cClienteApiGateway.ListarConTotal;
    • si no, ejecuta el SQL historico contra menu.conn.
  6. En ambos casos devuelve un ADODB.Recordset compatible con la grilla.

La UI queda aislada del origen de datos real.

Flujo de escritura ​

Para alta, modificacion o baja:

  1. frmCliente carga los datos en una instancia de cCliente.
  2. Llama a Ingresar, Modificar o Eliminar.
  3. cCliente decide si usar API o BD directa.
  4. Si usa API, transforma el objeto cliente en JSON mediante cClienteApiGateway.
  5. Si usa BD directa, ejecuta el SQL historico y mantiene las novedades locales existentes.

Compatibilidad con VB6 ​

Para minimizar impacto en formularios existentes, la capa mantiene estas decisiones:

  • Las lecturas de listados devuelven ADODB.Recordset.
  • Las propiedades publicas de cCliente siguen siendo la interfaz principal del ABM.
  • Los formularios no consumen JSON directamente.
  • El parseo de alias JSON se concentra en cCliente, por ejemplo idCliente, idcliente, nroCliente, nrocliente.

Ventajas del diseno ​

  • Migracion gradual por entidad o metodo.
  • Fallback inmediato a BD directa si la API no esta configurada.
  • Menos cambios en formularios VB6.
  • Un solo punto para manejar errores HTTP.
  • Un solo contrato REST documentado en docs/cliente-rest-api.md.
  • Permite reutilizar el patron en otras clases de dominio.

Consideraciones ​

El listado de frmClientes tiene filtros avanzados que originalmente estaban expresados como SQL dinamico. Para soportar API, esos filtros deben tener equivalente como parametros REST.

Los filtros simples ya se envian como parametros estructurados. Los filtros de atributos especiales actualmente se envian como filtrosAtributos en forma descriptiva. Si la API debe aplicarlos realmente, conviene definir un contrato estructurado para atributos especiales.

Regla recomendada para nuevas migraciones ​

Al migrar otra pantalla:

  1. Crear o completar una clase de dominio.
  2. Mover ahi el acceso principal a datos.
  3. Crear un gateway REST especifico si la entidad consume API.
  4. Mantener fallback directo a BD dentro de la clase de dominio.
  5. Hacer que el formulario invoque solo metodos de la clase.
  6. Documentar el contrato REST esperado.

El criterio central es que la UI no debe saber si los datos vienen de HTTP o de SQL.