HQS.DataBridge.Foundation 2.1.0

HQS.DataBridge.Foundation

Biblioteca de contratos compartidos para la integración con el ERP a través de DataBridge. Define los DTOs (*Contract) y las interfaces de controlador (I*Controller) que consumidores e implementaciones del wrapper deben usar para mantener un acoplamiento desacoplado y versionable.

Este repositorio no contiene lógica de negocio ni acceso a datos: solo la superficie de tipos que garantiza compatibilidad entre clientes (APIs, servicios, integraciones) y la implementación concreta del DB Wrapper.

Características

• Target .NET Standard 2.0 (compatible con .NET Framework y .NET moderno).
• Empaquetado como NuGet en cada build (GeneratePackageOnBuild).
• Patrón uniforme List / Search / Save en todos los controladores.
• Contratos de maestros (catálogos) y comprobantes (transacciones).

Requisitos

• .NET SDK compatible con netstandard2.0
• Dependencia transitiva: DS.Foundation.WebApi (tipos ResponseContract<T> y SearchContract)

Instalación

dotnet add package HQS.DataBridge.Foundation

O agregar la referencia en el .csproj:

<PackageReference Include="HQS.DataBridge.Foundation" Version="2.1.0" />

Estructura del proyecto

src/
└── HQS.DataBridge.Foundation/
    ├── HQS.DataBridge.Foundation.csproj
    └── HQS.DataBridge.ERP.Interfaces/
        ├── Contracts/                  # DTOs de maestros
        │   ├── AbstractElementContract.cs
        │   ├── AbstractObjectContract.cs
        │   ├── ClienteContract.cs
        │   ├── ArticuloContract.cs
        │   ├── DepositoContract.cs
        │   ├── ...
        │   └── Comprobantes/           # DTOs transaccionales
        │       ├── ComprobanteContractBase.cs
        │       ├── ComprobanteItemContract.cs
        │       ├── OrdenDeCompraContract.cs
        │       ├── OrdenDeCompraItemContract.cs
        │       ├── OrdenDeVentaContract.cs
        │       ├── OrdenDeVentaItemContract.cs
        │       └── TipoDeComprobante.cs  # códigos canónicos de tipo
        └── Controllers/                # Interfaces de controlador
            ├── IClienteController.cs
            ├── IDepositoController.cs
            ├── IImpuestoController.cs
            ├── IOrdenDeCompraController.cs
            └── ...

Namespaces

Todo el paquete vive bajo el namespace común HQS.DataBridge.ERP.Interfaces, y la ruta de carpetas es el namespace:

El build lo hace cumplir: el RootNamespace del proyecto está vacío y la regla IDE0130 (src/HQS.DataBridge.Foundation/.editorconfig) falla con error si el namespace de un archivo no coincide con su carpeta. Comprobantes/ es la única excepción: es una subcarpeta organizativa y sus tipos comparten HQS.DataBridge.ERP.Interfaces.Contracts.

Jerarquía de contratos (maestros)

AbstractElementContract
├── Codigo, Nombre
├── UsuarioContract
└── AbstractObjectContract
    ├── Descripcion, EstaDeshabilitado, EstaEliminado
    └── ClienteContract, ArticuloContract, ProveedorContract, ImpuestoContract, ...

Jerarquía de comprobantes

ComprobanteContractBase          (cabecera común: tipo, fechas, CAI, empresa, condición de pago, ...)
├── OrdenDeCompraContract        (+ proveedor, tipo de proveedor, EsGasto, CuentaDeuda, Items)
└── OrdenDeVentaContract         (+ cliente, Items)

ComprobanteItemContract          (línea común: artículo, cantidad, precios, impuestos, depósito, ...)
├── OrdenDeCompraItemContract
└── OrdenDeVentaItemContract

Los comprobantes son DTOs planos (cabecera + ítems) y no heredan de la jerarquía de maestros. Las referencias a otras entidades son siempre códigos de negocio (el Codigo del contrato referenciado), nunca ids internos del ERP.

Tipos e identificación de comprobantes

Tipo lleva siempre un código canónico de 2 letras de TipoDeComprobante, nunca un código numérico ni un valor propio del ERP. Cada comprobante concreto lo inicializa (OrdenDeCompraContract = OC, OrdenDeVentaContract = OV).

Campos de identificación (todos string, en formato canónico):

• Comprobante es el identificador único del comprobante dentro del ERP para la empresa (EmpresaCodigo).
• Search recibe el valor de Comprobante en SearchContract.Id. La empresa se indica con un filtro Field = EmpresaCodigo en SearchContract.Filters; sin ese filtro, el wrapper usa la empresa por defecto de su configuración.
• En Save, quien llama envía siempre Tipo, Letra, Talonario, Numero y Comprobante, y el ERP los respeta.
• Cada wrapper traduce estos valores al formato de su ERP (por ejemplo, Gescom usa un talonario de 4 dígitos).

Referencias y valores null

• Codigo de identidad (AbstractElementContract.Codigo) nunca es null: se inicializa en "" porque es la clave de join entre contratos.
• Un campo *Codigo contiene el código de la entidad referenciada (por ejemplo ArticuloContract.RubroCodigo = RubroContract.Codigo); el campo homónimo sin sufijo contiene su nombre (ArticuloContract.Rubro = nombre del rubro). Para relacionar entidades, usar siempre el *Codigo.
• Un string sin inicializador o una propiedad de valor nullable (int?, decimal?, bool?) en null significa "el ERP no lo informa o no hay relación", nunca "vacío" ni "cero".

Entidades disponibles

Maestros

Comprobantes

Cada comprobante incluye una lista de ítems (OrdenDeCompraItemContract / OrdenDeVentaItemContract), ambos derivados de ComprobanteItemContract.

Patrón de controlador

Todas las interfaces siguen la misma firma:

public interface IClienteController
{
    ResponseContract<List<ClienteContract>> List();
    ResponseContract<List<ClienteContract>> Search(SearchContract search);
    ResponseContract<List<ClienteContract>> Save(ClienteContract contract);
}

Los tipos de respuesta y búsqueda provienen de DS.Foundation.WebApi.Surface.Contracts.

Compilación

dotnet build src/HQS.DataBridge.Foundation.sln

El paquete NuGet se genera en:

src/HQS.DataBridge.Foundation/bin/Debug/HQS.DataBridge.Foundation.{version}.nupkg

Scripts (bash) en src/: clean.sh borra bin/ y obj/ de los proyectos de src/, build.sh compila en Release y push.sh limpia, compila y publica el paquete (requiere NUGET_ORG_API_KEY y GITEA_NUGET_API_KEY).

Versionado

La versión del paquete se define en HQS.DataBridge.Foundation.csproj (AssemblyVersion / FileVersion).

Al actualizar contratos con cambios incompatibles (renombre de namespace, cambio de tipos de propiedades, eliminación de miembros), incrementar la versión mayor según SemVer y documentar la migración para consumidores existentes. Excepción histórica: la 1.1 incluyó cambios incompatibles por decisión del proyecto (ver migración abajo).

La superficie pública se controla con Microsoft.CodeAnalysis.PublicApiAnalyzers: PublicAPI.Shipped.txt (liberado) y PublicAPI.Unshipped.txt (pendiente de liberar; los miembros eliminados figuran con el prefijo *REMOVED*). Ambos archivos, el README y la documentación XML viajan dentro del paquete.

Migración 2.0 → 2.1

La 2.1 no rompe compilación, pero cambia los valores de identificación de los comprobantes (OrdenDeCompraContract, OrdenDeVentaContract). Cada wrapper debe adoptarla para que Search y Save sean consistentes entre ERPs.

Migración 1.x → 2.0

La 2.0 rompe compilación en todos los wrappers (Gescom, Netegia, Odoo, Táctica) y cambia el JSON de comprobantes, artículos, clientes, empresas, impuestos y usuarios. Cada wrapper debe actualizarse en la misma release.

Comprobantes (OrdenDeCompraContract, OrdenDeVentaContract y sus ítems)

Maestros

Migración 1.0.x → 1.1

Relación con otros proyectos

┌─────────────────────┐     referencia      ┌──────────────────────────┐
│  Consumidores       │ ──────────────────► │ HQS.DataBridge.Foundation│
│  (API, servicios)   │                     │  (contratos + interfaces)│
└─────────────────────┘                     └────────────┬─────────────┘
                                                         │ implementa
                                                         ▼
                                              ┌──────────────────────────┐
                                              │  DB Wrapper (ERP)        │
                                              └──────────────────────────┘

Los consumidores referencian este paquete para tipar requests/responses. La implementación concreta de cada I*Controller vive en el proyecto del wrapper ERP.

Plan de evolución

Ver agents/rules/roadmap.md para el roadmap de entidades faltantes hacia un ERP estándar (fases, sprints y deuda técnica), agents/rules/stock-movements.md para la decisión sobre movimientos de stock y agents/rules/voucher-types.md para el catálogo de tipos de comprobante.