Mava.Reporting 0.1.0-alpha.2

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
• docs/13-fastreport-evaluation.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(options => {
  options.QuestPdfLicenseType = MavaQuestPdfLicenseType.Community;
});

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
    });

Licenciamiento de QuestPDF en consumo:

• Mava.Reporting no define automaticamente una licencia por el consumidor.
• La app consumidora debe definir la licencia en startup con AddMavaReporting(options => ...).
• Si no se configura QuestPdfLicenseType, se lanza una excepcion en el registro de servicios.
• La responsabilidad de cumplimiento de licencias de terceros recae en la aplicacion consumidora.
• Para uso comercial, valida elegibilidad y tier (Community/Professional/Enterprise) segun los terminos oficiales de QuestPDF.

Texto sugerido para documentacion del consumidor:

El uso de Mava.Reporting implica la aceptacion y cumplimiento de las licencias de dependencias de terceros incluidas o transitivas (por ejemplo, QuestPDF y ScottPlot). La aplicacion consumidora es la responsable de evaluar su contexto legal/comercial y seleccionar o adquirir las licencias que correspondan.

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

padding puede declararse como numero uniforme o por lado:

{ "padding": 8 }

{
  "padding": {
    "top": 8,
    "right": 12,
    "bottom": 8,
    "left": 12
  }
}

styles nombrados aplican hoy a un subconjunto explicito:

• text: tipografia basica, backgroundColor, alignment y padding
• section: padding, backgroundColor, borderColor, borderWidth y borderRadius
• box: backgroundColor, borderColor, borderWidth y borderRadius
• table: padding, colores, borde, alineacion y tipografia basica
• table.columns[]: padding, align, colores y tipografia basica

Regla de precedencia: propiedad inline del elemento > styles.<name> > default del renderer.

Para tablas, la precedencia efectiva es mas especifica:

• celdas de datos: columna inline > columna style > table.cellStyle > table inline > table style > default
• encabezado: table inline header* > table.headerStyle > table style > default

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
• flujo automatizado de publicacion: fuera del alcance actual
• THIRD-PARTY-NOTICES.md: incluir y mantener avisos/licencias de dependencias redistribuidas

Metadata ya definida:

• licencia del paquete: MIT (via PackageLicenseExpression en src/Mava.Reporting/Mava.Reporting.csproj)

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