Mava.Reporting 0.1.0-alpha.1

Mava.Reporting

Libreria .NET para generacion dinamica de reportes PDF a partir de definiciones declarativas en JSON.

Estado actual del paquete: 0.1.0-alpha

Estado de roadmap:

• Alpha Hardening: cerrada
• Consumption Expansion: cerrada
• siguiente fase recomendada: Engine Semantics

Objetivo

Permitir que multiples aplicaciones consuman un motor de reportes reutilizable, extensible y publicable en NuGet, capaz de renderizar:

• Header de reporte
• Page header
• Content dinamico
• Footer
• Tablas
• Graficos
• Estilos y layout reutilizable

Principios

• Contrato del reporte controlado por nosotros, no por un vendor externo.
• Arquitectura limpia y extensible.
• Render declarativo basado en JSON.
• Separacion estricta entre definicion, validacion, render y exportacion.
• Preparado para publicarse como paquete NuGet.

Documentacion interna

• docs/01-goals-and-scope.md
• docs/02-architecture.md
• docs/03-development-rules.md
• docs/04-json-contract-v1.md
• docs/05-testing-strategy.md
• docs/06-release-versioning-and-publishing.md
• docs/07-roadmap.md
• docs/08-vscode-ai-collaboration.md
• docs/09-alpha-hardening-phase.md
• docs/10-consumption-expansion-phase.md
• docs/11-section-decorative-backgrounds-phase.md
• docs/12-nuget-publication-guide.md
• AGENTS.md
• CONTRIBUTING.md

Sample recomendado

El repositorio mantiene un sample ejecutable en samples/Mava.Reporting.SampleConsole/. Ese sample ya no es una demo minima: representa un escenario de negocio realista de monthly sales performance para un backend que necesita generar un PDF operativo con:

• logo SVG embebido por sourceSvgBase64
• section con fondo degradado decorativo
• section con fondo SVG decorativo
• box como primitiva decorativa sin contenido para segmentos y bloques visuales
• salto de pagina explicito con pageBreak
• layout horizontal relativo en row mediante weight
• styles nombrados
• placeholders {{param.*}}
• table con format
• progressRing como indicador circular SVG de progreso
• segmentedProgress como indicador lineal segmentado para distribuciones por estado
• chart tipo Bar multiserie con modo inline o dataset-backed
• header, pageHeader, content y footer
• multiples datasets en un mismo reporte

Consumo esperado desde NuGet:

using Microsoft.Extensions.DependencyInjection;
using Mava.Reporting;

var services = new ServiceCollection();
services.AddMavaReporting();

using var provider = services.BuildServiceProvider();
var reporting = provider.GetRequiredService<IReportingService>();

var report = await reporting.GenerateDocumentAsync(
    definitionJson,
    cultureName: "es-ES",
    parameters: new Dictionary<string, object?> {
        ["reportTitle"] = "Sales Summary"
    },
    datasets: new Dictionary<string, IReadOnlyCollection<IDictionary<string, object?>>> {
        ["sales"] = rows
    });

La ruta publica recomendada devuelve ReportDocument desde Mava.Reporting, para evitar que el caso comun de consumo dependa de Application.Models.

La cultura visible del reporte se controla desde ReportRequest.CultureName o mediante el overload publico con cultureName. Si no se informa, el motor usa CultureInfo.CurrentCulture.

El contrato JSON soporta styles nombrados con efecto real en elementos text. La precedencia actual es:

• propiedades inline del elemento sobre el estilo nombrado
• estilo nombrado sobre los defaults del renderer

Las columnas de table tambien soportan format con efecto real para:

• currency
• date
• datetime

Comportamiento cultural actual:

• currency usa la cultura efectiva del request
• placeholders convierten valores visibles usando la cultura efectiva del request
• date y datetime se mantienen con formato estable para preservar el contrato actual

El elemento chart soporta hoy:

• Bar, Line y Pie
• Bar multiserie agrupado por categoria
• color por serie
• frame.visible y frame.color
• legend.visible y legend.position
• legend.fontSize y legend.fontColor
• xAxis.visible, xAxis.labelFontSize, xAxis.labelColor
• yAxis.visible, yAxis.labelFontSize, yAxis.labelColor
• grid.visible, grid.direction, grid.color y grid.lineWidth
• barLayout.mode, barLayout.groupSpacing, barLayout.barSpacing y barLayout.barWidth
• dos modos de datos para Bar: inline y dataset-backed

Reglas actuales de Bar:

• usa exactamente uno entre modo inline (data.labels + data.series) y modo dataset-backed (dataset + categoryField + series)
• series[].valueField aplica solo al modo dataset-backed
• data.series[].values aplica solo al modo inline
• el mapping concreto a ScottPlot vive solo en Infrastructure

El elemento image soporta hoy:

• sourceBase64 para raster
• sourceSvgBase64 para SVG
• width
• height

Regla de validacion actual para image:

• debe existir exactamente una fuente soportada
• no puede definir sourceBase64 y sourceSvgBase64 al mismo tiempo

Los hijos de row pueden declarar weight para repartir ancho relativo. Regla actual:

• si un hijo no define weight, su peso relativo es 1
• si un hijo define width, width gana y ese hijo pasa a ancho fijo

Los placeholders en texto soportan hoy:

• {{name}} por compatibilidad
• {{param.name}} como forma explicita recomendada

Los tokens {{engine.*}} y {{fn.*}} quedan reservados para una futura capa de expresiones y hoy se conservan sin cambios. En particular, {{engine.pageNumber}} y {{engine.totalPages}} quedan reservados para una futura iteracion relacionada con paginacion.

El contrato tambien soporta ahora un elemento section para agrupar hijos en flujo vertical y aplicar presentacion visual simple al bloque con:

• items
• spacing
• padding
• backgroundColor
• backgroundGradient
• backgroundImage
• borderColor
• borderWidth
• borderRadius

El contrato soporta tambien box como primitiva decorativa sin contenido, con:

• height requerida
• width o weight opcionales segun el layout
• backgroundColor
• borderColor
• borderWidth
• borderRadius

Regla semantica actual:

• box es un bloque visual sin hijos
• section sigue siendo el contenedor visual con contenido

El contrato soporta tambien progressRing como indicador visual de un unico valor, separado de chart, con:

• value numerico directo o valueFrom como referencia explicita a param.<name>
• max opcional con default 100
• color, trackColor y thickness
• label opcional o porcentaje automatico en el centro
• render SVG directo para mantener nitidez en PDF

Reglas actuales de progressRing:

• debe definir exactamente uno entre value y valueFrom
• valueFrom usa la forma explicita param.<name>
• si el parametro no existe o no es numerico, el motor falla con error claro

El contrato soporta tambien segmentedProgress como indicador lineal segmentado, separado de row + box, con:

• height requerida
• borderRadius, trackColor y gap
• modo inline mediante segments[] con value, color y label opcional
• modo dataset-backed mediante dataset, valueField, labelField y colorField
• calculo proporcional basado en la suma real de segments[].value, sin exigir que sumen 100
• colorField opcional con fallback estable #94A3B8 por fila cuando no hay color usable
• render SVG directo; label queda como metadato y no se renderiza dentro de la barra en esta iteracion

Reglas actuales para fondos de section:

• backgroundColor, backgroundGradient y backgroundImage son mutuamente excluyentes
• backgroundImage soporta raster por sourceBase64 y SVG por sourceSvgBase64
• backgroundImage.fit soporta Contain, Cover y Stretch
• backgroundImage.horizontalAlign y backgroundImage.verticalAlign controlan la alineacion interna del fondo
• el fondo decorativo se renderiza detras del contenido sin afectar el flujo interno del bloque

Para generar un PDF de prueba:

dotnet run --project .\samples\Mava.Reporting.SampleConsole\Mava.Reporting.SampleConsole.csproj

El archivo PDF se genera en:

samples/Mava.Reporting.SampleConsole/bin/Debug/net10.0/generated/

El reporte generado muestra:

• logo SVG vectorial embebido sin rasterizacion manual
• bloque ejecutivo con fondo degradado decorativo
• bloque documental con fondo SVG decorativo
• resumen ejecutivo del periodo
• facturas liquidadas del mes
• receivables pendientes de cobro

Es la referencia recomendada para entender como integrar Mava.Reporting desde un backend.

Preparacion de pre-release

Validacion local recomendada antes de empaquetar:

dotnet test .\tests\Mava.Reporting.UnitTests\Mava.Reporting.UnitTests.csproj -m:1 -nr:false --disable-build-servers
dotnet test .\tests\Mava.Reporting.IntegrationTests\Mava.Reporting.IntegrationTests.csproj -m:1 -nr:false --disable-build-servers
dotnet pack .\src\Mava.Reporting\Mava.Reporting.csproj -c Debug -p:ContinuousIntegrationBuild=false

Pendientes de metadata antes de una publicacion final:

• Authors y Company: no definidos por falta de dato confirmado
• licencia del paquete: no declarada todavia
• flujo automatizado de publicacion: fuera del alcance actual

Estructura esperada de la solucion

src/
  Mava.Reporting.Domain/
  Mava.Reporting.Application/
  Mava.Reporting.Infrastructure/
  Mava.Reporting/
samples/
  Mava.Reporting.SampleConsole/
tests/
  Mava.Reporting.UnitTests/
  Mava.Reporting.IntegrationTests/
docs/
.github/

Estado inicial sugerido

• v0.1.x: base del motor, parser, text, line, spacer, header/footer, table simple
• v0.2.x: chart bar, line, pie
• v0.3.x: estilos, parametros, expresiones simples
• v0.4.x: layout compuesto, repeticion, page breaks, reglas de visibilidad