prepare<T> method

Future<PreparedReport> prepare<T>({
  1. required ReportDefinition<T> definition,
  2. required List<T> records,
})

Prepares, validates, aggregates, and calculates a report from a definition and records.

Implementation

Future<PreparedReport> prepare<T>({
  required ReportDefinition<T> definition,
  required List<T> records,
}) async {
  _log.info(
    'Preparing report: "${definition.title}" with ${records.length} records',
  );

  // 1. Validate definition
  final validationErrors = definition.validate();
  if (validationErrors.isNotEmpty) {
    throw ArgumentError(
      'Invalid ReportDefinition:\n${validationErrors.join('\n')}',
    );
  }

  final List<String> warnings = [];

  // 2. Map records to normalized maps
  final List<Map<String, dynamic>> rawRecords = [];
  for (int i = 0; i < records.length; i++) {
    final item = records[i];
    final Map<String, dynamic> rowMap = {};
    for (final col in definition.columns) {
      final dynamic rawVal = col.extractValue(item);
      rowMap[col.id] = _normalizeValue(rawVal, col, i, warnings);
    }
    rawRecords.add(rowMap);
  }

  // 3. Process analyses
  final List<PreparedAnalysis> preparedAnalyses = [];
  final Map<String, num> detailTotals = {};
  final Map<String, num> groupTotals = {};
  final Map<String, num> grandTotals = {};
  final List<String> discrepancies = [];

  int maxFilteredRecords = 0;

  for (final analysis in definition.analyses) {
    // Filter records
    final List<Map<String, dynamic>> filteredRecords = rawRecords.where((
      row,
    ) {
      for (final filter in analysis.filters) {
        final val = row[filter.fieldId];
        if (!filter.matches(val, row)) return false;
      }
      return true;
    }).toList();

    if (filteredRecords.length > maxFilteredRecords) {
      maxFilteredRecords = filteredRecords.length;
    }

    PreparedAnalysis prepAnalysis;
    switch (analysis.type) {
      case ReportAnalysisType.detail:
        prepAnalysis = _prepareDetailAnalysis(
          definition,
          analysis,
          filteredRecords,
          detailTotals,
          grandTotals,
        );
        break;
      case ReportAnalysisType.grouped:
        prepAnalysis = _prepareGroupedAnalysis(
          definition,
          analysis,
          filteredRecords,
          groupTotals,
          grandTotals,
        );
        break;
      case ReportAnalysisType.crossTab:
        prepAnalysis = _prepareCrossTabAnalysis(
          definition,
          analysis,
          filteredRecords,
        );
        break;
      case ReportAnalysisType.summary:
        prepAnalysis = _prepareSummaryAnalysis(
          definition,
          analysis,
          filteredRecords,
        );
        break;
    }
    preparedAnalyses.add(prepAnalysis);
  }

  // 4. Reconciliation audit
  bool isReconciled = true;
  for (final colKey in detailTotals.keys) {
    final dTotal = detailTotals[colKey] ?? 0;
    final gTotal = groupTotals[colKey];
    if (gTotal != null) {
      final diff = (dTotal - gTotal).abs();
      if (diff > 0.001) {
        isReconciled = false;
        discrepancies.add(
          'Detail total ($dTotal) does not match group total ($gTotal) for column "$colKey" (diff: $diff)',
        );
      }
    }
  }

  final reconciliation = ReconciliationSummary(
    isReconciled: isReconciled,
    detailTotals: detailTotals,
    groupTotals: groupTotals,
    grandTotals: grandTotals,
    discrepancies: discrepancies,
  );

  if (!isReconciled) {
    warnings.addAll(discrepancies);
  }

  return PreparedReport(
    title: definition.title,
    subtitle: definition.subtitle,
    branding: definition.branding,
    theme: definition.theme ?? ReportTheme.classicBlue(),
    settings:
        definition.settings ??
        ReportSettings(
          pageSize: definition.pdfOptions?.pageSize ?? 'A4',
          orientation: definition.pdfOptions?.orientation ?? 'portrait',
          pageOrientation: definition.pdfOptions?.pageOrientation,
        ),
    analyses: preparedAnalyses,
    totalRecordCount: records.length,
    filteredRecordCount: maxFilteredRecords,
    warnings: warnings,
    reconciliation: reconciliation,
    metadata: definition.metadata ?? {},
    summaryItems: definition.summaryItems,
    paymentDetails: definition.paymentDetails,
  );
}