Cayaqui.MPS.ExcelExport 0.9.1

Cayaqui.MPS.ExcelExport

Exporta colecciones de DTOs a .xlsx usando los atributos del paquete Cayaqui.MPS.Metadata. Simétrico a Cayaqui.MPS.ExcelImport — decorás tu DTO una sola vez y se importa/exporta con formato consistente.

Distribución propietaria — requiere contrato comercial con Cayaqui. Ver LICENSE.txt.

Dependencias: Cayaqui.MPS.Metadata (se registra automáticamente con AddMpsExcelExport) + licencia Syncfusion XlsIO.

v0.9.0 — CoverSheetSection: logo Cayaqui en footer

CoverSheetSection agrega un área de footer al final de la portada con el logo corporativo Cayaqui (izquierda) y el texto "Powered by Cayaqui · MPS Project Suite" (derecha). Se activa pasando LogoOptions.MpsCompanyLogo en ExcelExportOptions.Logos.

var logos = new LogoOptions
{
    OwnerLogo      = new BytesLogo { Bytes = ownerLogoBytes },
    MpsCompanyLogo = new BytesLogo { Bytes = cayaquiLogoBytes }  // nuevo
};

var opts = new ExcelExportOptions
{
    Theme = theme,
    Logos = logos
};

v0.8.0 — Template corporativo: CoverSheetSection + ReportTheme

Sistema de branding unificado para workbooks profesionales. Un solo ReportTheme configura la portada, footer y tab color de todas las hojas.

var theme = new ReportTheme
{
    ReportTitle          = "Monthly Project Report",
    ProjectName          = "Talara U3 — Expansion",
    CompanyName          = "Cayaqui S.A.",
    PreparedBy           = "Project Controls Team",
    Version              = "1.0",
    ReportDate           = new DateTime(2026, 4, 30),
    ConfidentialityLabel = "CONFIDENCIAL",
    PrimaryColorHex      = "#0F2044",   // deep navy
    AccentColorHex       = "#C9961A",   // amber gold
    TitleFont            = "Calibri Light",
    BodyFont             = "Calibri"
};

var report = new ExcelReport()
    .AddCoverSheet()                    // portada corporativa oscura
    .AddEvmKpiStrip(new EvmKpiStripSection { Snapshot = kpiSnapshot })
    .AddEvmSCurveChart(new EvmSCurveChartSection { Points = sCurve, Bac = 10_000_000m })
    .AddCashflowChart(new CashflowChartSection { Points = cashflow });

var stream = await exporter.ExportAsync(report, new ExcelExportOptions { Theme = theme });

CoverSheetSection genera un sheet con:

• Banda superior oscura (primary color) con logos cliente/Cayaqui
• Título del reporte (26pt, Calibri Light) + nombre del proyecto + fecha
• Franja de acento ámbar superior e inferior
• Tabla de información: Proyecto / Empresa / Preparado por / Fecha / Versión / Clasificación

Footer automático aplicado a todas las hojas cuando Theme está configurado:

• Izquierda: fecha del reporte (formato dd-MMM-yy)
• Centro: ConfidentialityLabel (ej. "CONFIDENCIAL")
• Derecha: "Página &P de &N"

Tab color: todas las hojas (excepto Cover) reciben PrimaryColorHex como color de pestaña.

ReportTheme.MpsCorporateDark es el preset default (deep navy #0F2044 + amber #C9961A). Se activa automáticamente cuando Theme = null en CoverSheetSection.

Logos se configuran en ExcelExportOptions.Logos:

var options = new ExcelExportOptions
{
    Theme = theme,
    Logos = new LogoOptions
    {
        OwnerLogo  = new BytesLogo(ownerLogoBytes),
        CayaquiLogo = new BytesLogo(cayaquiLogoBytes)
    }
};

Sin breaking changes. Requiere Cayaqui.MPS.ReportModels ≥ 0.4.0.

v0.7.4 — R9C esquema actualizado

R9cReportSection ahora usa el nuevo esquema R9C: PO / CO / PC / Comprometido / Incurrido / Pagado / Trends / EAC / %Ejec. La columna Varianza fue eliminada. Totals row calcula %Ejec = sumIncurrido / sumEAC. Requiere Cayaqui.MPS.ReportModels ≥ 0.3.5.

v0.7.3 — 6 nuevas secciones EPC

6 nuevas secciones de project controls para ingeniería/procura:

var report = new ExcelReport()
    .AddTitle("Talara U3 · Cut-off 2026-04-30")
    .AddWbsBudgetTable(new WbsBudgetTableSection
    {
        Title = "Presupuesto WBS",
        Rows = new[]
        {
            new WbsBudgetRow("1.0",   "Ingeniería",       Level: 0, Bac: 5_000_000m, Ev: 4_200_000m, Ac: 4_500_000m, Eac: 5_357_143m, PercentComplete: 0.84m, Currency: "USD"),
            new WbsBudgetRow("1.1",   "Diseño básico",    Level: 1, Bac: 2_000_000m, Ev: 2_000_000m, Ac: 2_100_000m, Eac: 2_100_000m, PercentComplete: 1.00m, Currency: "USD"),
            new WbsBudgetRow("1.2",   "Diseño detalle",   Level: 1, Bac: 3_000_000m, Ev: 2_200_000m, Ac: 2_400_000m, Eac: 3_272_727m, PercentComplete: 0.73m, Currency: "USD"),
        }
    })
    .AddEngProgressTable(new EngProgressTableSection
    {
        Title = "Avance Ingeniería",
        Rows = new[]
        {
            new EngProgressRow("ENG-001", "Plano P&ID", "Proceso",
                PlanPct: 0.90m, ActualPct: 0.85m,
                PlannedCompletion: new DateTime(2026, 5, 15),
                ForecastCompletion: new DateTime(2026, 5, 22)),
        }
    })
    .AddLookaheadTable(new LookaheadTableSection
    {
        Title = "Lookahead 3 Semanas",
        Rows = new[]
        {
            new LookaheadRow("1.2.1", "Rev. planos estructurales", "J. Pérez",
                new DateTime(2026, 5, 19), new DateTime(2026, 5, 23),
                LookaheadStatus.InProgress),
        }
    })
    .AddEvmControlChart(new EvmControlChartSection
    {
        Title = "Control Chart SV/CV",
        Points = controlChartPoints   // IEnumerable<ControlChartPoint>
    })
    .AddRaciMatrix(new RaciMatrixSection
    {
        Title = "Matriz RACI",
        Items = new[]
        {
            new RaciEntry("Diseño básico", "Ing. Jefe",    RaciRole.Responsible),
            new RaciEntry("Diseño básico", "Gerente Proy", RaciRole.Accountable),
            new RaciEntry("Diseño básico", "Cliente",      RaciRole.Consulted),
        }
    })
    .AddPoRegister(new PoRegisterSection
    {
        Title = "Registro de Órdenes de Compra",
        Items = new[]
        {
            new PoEntry("PO-001", "Aceros del Sur", "Estructuras metálicas",
                450_000m, "USD", "Approved",
                IssueDate: new DateTime(2026, 3, 1),
                DeliveryDate: new DateTime(2026, 6, 30)),
        }
    });

Requiere Cayaqui.MPS.ReportModels ≥ 0.3.3. Sin breaking changes.

v0.6.0 — Migración a ReportModels + 8 secciones Fase 2

Migración de DTOs a Cayaqui.MPS.ReportModels (nuevo peer-dependency, zero-dep): EvmKpiSnapshot, EvmSCurvePoint, CashflowPoint, BurndownPoint, R9cEntry, RiskItem+RiskView, VarianceRow, PhysicalProgressPoint, ProductionPoint. Los namespaces se mantienen via global using — sin breaking changes para consumers existentes. SemaforoColors y EvmChartPalette conservan sus APIs públicas y delegan internamente a ReportModels.

8 nuevas secciones Fase 2:

var report = new ExcelReport()
    .AddTitle("Talara U3 · Cut-off 2026-04-30")
    .AddContingencyDrawdown(new ContingencyDrawdownSection
    {
        Points = contingencyPoints, ControlDate = controlDate
    })
    .AddWaterfall(new WaterfallSection
    {
        Steps = new[]
        {
            new WaterfallStep("BAC", WaterfallStepKind.Total, 10_000_000m),
            new WaterfallStep("Contingencia usada", WaterfallStepKind.Subtract, 500_000m),
            new WaterfallStep("Reserva gestión", WaterfallStepKind.Subtract, 200_000m),
            new WaterfallStep("EAC pendiente", WaterfallStepKind.Forecast, 9_300_000m),
        }
    })
    .AddResourceHistogram(new ResourceHistogramSection
    {
        Buckets = resourceBuckets, CapacityLimit = 40m, CapacityUnit = "HH/mes"
    })
    .AddManagementReserveTracker(new ManagementReserveTrackerSection
    {
        Events = mrEvents, InitialReserve = 500_000m, Currency = "USD"
    })
    .AddTornadoChart(new TornadoChartSection { Items = tornadoItems, Currency = "USD" })
    .AddMilestoneStrip(new MilestoneStripSection { Milestones = milestones })
    .AddRiskRegisterTable(new RiskRegisterTableSection { Entries = riskRegister })
    .AddChangeOrderLog(new ChangeOrderLogSection { Entries = changeOrders, Currency = "USD" });

149 tests en MPS.Infrastructure.ExcelExport.Tests (todos passing). Sin breaking changes. Requiere Cayaqui.MPS.ReportModels ≥ 0.2.0.

v0.5.1 — Patch: paleta de curvas alineada con design system MPS

Fix de paleta en PhysicalProgressCurveSection y ProductionCurveSection. v0.5.0 publicaba con colores invertidos respecto al componente Blazor real (MPS.Components.Evm.PhysicalProgressCurve/ProductionCurve):

EvmChartPalette agrega 2 constantes públicas: Baseline (#44403C) y Cyan (#0086C9). +2 tests de regresión por sección. Sin breaking changes en API — solo cambia el output visual.

v0.5.0 — Mining + Risk extensions (3 secciones nuevas + sparklines inline)

3 nuevas secciones para los verticals mining production + risk QRA, plus sparklines opcionales inline en R9C / Schedule Variance:

var report = new ExcelReport()
    .AddTitle("Talara U3 · Mining cut-off 2026-04-30")
    .AddR9cReport(new R9cReportSection
    {
        Rows = r9c, Currency = "USD",
        TrendData = cpiHistory     // 👈 NEW v0.5 — agrega columna "Trend" con sparkline nativo
    })
    .AddMonteCarloHistogram(new MonteCarloHistogramSection
    {
        Samples = qraSamples, Bins = 30, Percentiles = new[] { 50, 80, 90 }
    })
    .AddPhysicalProgressCurve(new PhysicalProgressCurveSection
    {
        Points = progressPoints, ControlDate = controlDate, ShowGoalLine = true
    })
    .AddProductionCurve(new ProductionCurveSection
    {
        Points = production, NameplateRate = 5_000m, Unit = "t/día"
    });

DTOs nuevos: PhysicalProgressPoint, ProductionPoint. Helper público: MonteCarloHistogramSection.Percentile(sortedSamples, p) (linear-interpolation NIST C=R7 — mismo método que numpy.percentile default).

Sin breaking changes. Sparklines son opcionales (TrendData = null mantiene el output v0.4.0 idéntico). +27 tests xUnit (120 total). Ver scripts/migrate-to-excelexport-0.5.0.md.

Out of scope (v0.6.0+): WaterfallChartSection — ExcelChartType.Waterfall no existe en XlsIO 33.2.3 (solo Histogram / BoxAndWhisker / Funnel); el workaround con Column_Stacked queda para iteración futura.

v0.4.0 — Executive cut-off report completo (5 secciones nuevas + TableSection<T>)

Suma 5 secciones EVM y desbloquea TableSection<T> (refactor mínimo de ExcelExporter<T>). Ahora un cut-off mensual completo entra en un solo workbook:

var report = new ExcelReport()
    .AddTitle("Talara U3 · Cut-off 2026-04-30")
    .AddEvmKpiStrip(new EvmKpiStripSection { Snapshot = evmSnapshot })
    .AddEvmSCurveChart(new EvmSCurveChartSection { Points = evmPoints, Bac = 10_000_000m })
    .AddCashflowChart(new CashflowChartSection { Points = cashflow, CutOffDate = controlDate })
    .AddR9cReport(new R9cReportSection { Rows = r9c, Currency = "USD" })
    .AddRiskHeatmap(new RiskHeatmapSection { Risks = risks, View = RiskView.Inherente })
    .AddScheduleVariance(new ScheduleVarianceTableSection { Rows = variance, WarnThreshold = 5 })
    .AddBurndownChart(new BurndownChartSection { Points = burndown, TargetDate = goLive })
    .AddTable(controlAccounts, new TableSectionOptions { SheetName = "CAs" });

await using var stream = await ReportExporter.ExportAsync(report);

DTOs nuevos (sin dep en MPS.Components): EvmKpiSnapshot, R9cEntry, RiskItem + RiskView, VarianceRow, BurndownPoint, EvmThresholds, SemaforoColors.

ExcelExporter<T>.ExportAsync (v0.2.0) sigue intacto — el refactor extrajo RenderToSheetAsync interno reusable. Sin breaking changes. +44 tests xUnit (93 total). Ver scripts/migrate-to-excelexport-0.4.0.md.

v0.3.0 — Reportes con secciones + charts EVM nativos

Nueva API IExcelReportExporter para componer reportes multi-sheet con la Curva S de EVM y el Cashflow mensual + acumulado como IChart Excel nativos (no imágenes — refrescables y editables in-Excel):

@inject IExcelReportExporter ReportExporter

var report = new ExcelReport()
    .AddTitle("Talara U3 · Cut-off 2026-04-30")
    .AddEvmSCurveChart(new EvmSCurveChartSection
    {
        Points      = evmPoints,                  // PV, EV, AC, Forecast por mes
        Bac         = 10_000_000m,                // stripline horizontal
        ControlDate = new DateTime(2026, 4, 30),  // stripline vertical
        Currency    = "USD"
    })
    .AddCashflowChart(new CashflowChartSection
    {
        Points         = cashflowPoints,          // Plan, Actual, Forecast por mes
        CutOffDate     = new DateTime(2026, 4, 30),
        Currency       = "USD",
        ShowCumulative = true                     // 3 columnas + 3 líneas acumuladas (dual-axis)
    });

await using var stream = await ReportExporter.ExportAsync(report);

Output: workbook con sheet "Cover" (título + branding logos) + "Curva S" (4 series + striplines BAC/ControlDate) + "Cashflow" (combo dual-axis con 6 series + stripline CutOffDate).

DTOs propios del package (sin dependencia con MPS.Components):

public sealed record EvmSCurvePoint(DateTime Date, decimal? Pv, decimal? Ev, decimal? Ac, decimal? Forecast);
public sealed record CashflowPoint(DateTime Date, decimal Plan, decimal Actual, decimal Forecast);

Si tu data layer ya construye los del componente Blazor, mappeás con un LINQ (mismo shape, distinto namespace).

EvmChartPalette expone los colores canónicos (Plan, Earned, Actual, Forecast, Bac, CutOff) como Syncfusion.Drawing.Color reutilizables — paleta #2E5BFF Plan, #7F56D9 EV, #D92D20 Actual, #039855 Forecast. Forecast/EAC siempre dashed para indicar proyección. Las acumuladas las computa CumulativeBuilder con paridad tested vs MPS.Components.Evm.CashflowChart.BuildDisplayPoints — los valores que ves en Excel son los mismos que los del componente Blazor.

AddTable<T> queda para v0.4.0 (out of scope este release; los reportes que requieran tablas combinan IExcelExporter<T>.ExportAsync con IExcelReportExporter.ExportAsync por ahora).

Sin breaking changes. El IExcelExporter<T>.ExportAsync v0.2.0 sigue idéntico. Ver scripts/migrate-to-excelexport-0.3.0.md. +35 tests xUnit (49 total).

Instalación

dotnet add package Cayaqui.MPS.ExcelExport

builder.Services.AddMpsExcelExport();

Atributos consumidos

[Mask] NO se aplica al export — exportar datos enmascarados sería un bug (pierde el valor original para ediciones). Se respeta el valor sin máscara para que Excel edite bien.

Convenciones importantes

[Percentage] — almacenar ratio 0.0–1.0

Excel interpreta el formato 0.0% multiplicando el valor por 100. Almacenar 75.6 en el DTO produciría 7560% en la celda. Convención correcta:

[Percentage(1)]
public decimal Cpi { get; set; }   // ← almacenar 0.756, NO 75.6

Al exportar, la celda se ve 75.6%. Al importar (round-trip), se recupera 0.756.

[Badge] con enum values — color por fila

Sobre una propiedad enum con [BadgeColor] en cada valor, cada fila recibe el color correspondiente al valor de esa fila:

public enum Status
{
    [BadgeColor(BadgeKind.Success)] Approved,
    [BadgeColor(BadgeKind.Error)]   Rejected
}

[Badge] public Status RowStatus { get; set; }
// En Excel: filas con Approved → verde, filas con Rejected → rojo

[Badge(BadgeKind.Success)] (FixedKind) → toda la columna del mismo color.

Uso

public sealed class InvoiceRow
{
    [Display(Name = "N°", Order = 1)]
    public int InvoiceNumber { get; set; }

    [Label("Cliente")] [Display(Order = 2)]
    public string CustomerName { get; set; } = "";

    [Currency("USD", 2)] [Align(TextAlign.Right)] [ColumnWidth(120)] [Display(Order = 3)]
    public decimal Amount { get; set; }

    [Date("dd-MMM-yyyy")] [Display(Order = 4)]
    public DateTime IssueDate { get; set; }

    [Badge(BadgeKind.Success)] [Display(Order = 5)]
    public bool IsPaid { get; set; }

    [Hidden]
    public int InternalId { get; set; }
}

public class InvoiceExportService(IExcelExporter<InvoiceRow> exporter)
{
    public async Task<Stream> GenerateAsync(IEnumerable<InvoiceRow> rows)
    {
        return await exporter.ExportAsync(rows, new ExcelExportOptions
        {
            SheetName = "Invoices",
            FreezeHeaderRow = true,
            AutoFilter = true,
            HeaderBackgroundColor = "#D9E1F2"
        });
    }
}

ExcelExportOptions

public sealed class ExcelExportOptions
{
    string SheetName = "Data";
    bool IncludeHeader = true;
    bool StyleHeader = true;                           // bold + background
    string HeaderBackgroundColor = "#D9E1F2";
    bool FreezeHeaderRow = true;
    bool AutoFilter = true;
    bool AutoFitColumns = false;                       // usa [ColumnWidth] cuando se declara
    CultureInfo Culture = CultureInfo.InvariantCulture;
}

Tipos nativos vs texto

El exporter respeta el tipo de .NET para que Excel los trate como datos reales (números son sumables, fechas son filtrables):

Round-trip Export → Import

var rows = new[] { new InvoiceRow { ... } };

await using var exported = await exporter.ExportAsync(rows);    // DTO → xlsx
var result = await importer.ImportAsync(exported);              // xlsx → DTO
// result.Rows[0] === rows[0] (values preserved)

Este roundtrip está cubierto por tests.

Tests

Proyecto MPS.Infrastructure.ExcelExport.Tests — 9 tests ✅:

• Header + row values con types nativos (number, text, bool)
• [Hidden] excluye columna
• [Display(Order)] respeta orden declarado
• [VisibleIn(Web)] (sin Excel flag) omite columna
• [Currency] aplica number format a celdas
• Header styled bold + freeze pane activa
• Empty collection produce output sólo con header
• Round-trip: Export → Import preserva valores (int, string, decimal)

Requisitos

• .NET 10.0 o superior
• Cayaqui.MPS.Metadata (auto-registrado con AddMpsExcelExport)
• Licencia Syncfusion Essential Studio (XlsIO)