Implement PDF report generator with Bufdir template layout
epic-bufdir-reporting-export-processing-services-task-006 — Build the BufdirPdfGenerator service that renders Bufdir's official report template layout as a PDF document. Implement page structure including organization header, reporting period block, activity summary table, participant counts, and signature fields. Use a server-side Dart PDF library and ensure the output matches Bufdir's required visual formatting.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Use the 'pdf' Dart package (pub.dev) — it is pure Dart, requires no native code, and works on both Flutter mobile and server-side Dart. Combine with 'printing' package only for device share/print UI, keeping the generator itself free of Flutter UI dependencies. Define all layout constants (margins, font sizes, column widths, colors) in a BufdirPdfTheme class so the template can be adjusted without touching generator logic. Use a TtfFont loaded from app assets for Norwegian character support — the default Helvetica built into the pdf package does not include æ/ø/å.
Embed NotoSans or similar open-source font that covers Latin Extended-A. Structure the generator around a BufdirPdfLayout builder that assembles: (1) header widget, (2) period widget, (3) activity table widget (using pdf package's TableHelper or custom table with page break handling), (4) participant counts widget, (5) signature widget. The activity table should aggregate data by activity type rather than listing every individual activity row — confirm this grouping matches Bufdir's expected format. The Bufdir PDF template details must be confirmed with the client by reviewing the actual Word template before finalizing layout implementation.
Testing Requirements
Unit tests using flutter_test with the pdf Dart package. Test cases: (1) output is non-empty Uint8List beginning with '%PDF' magic bytes, (2) generator completes without throwing for a minimal valid input (1 activity, full metadata), (3) generator handles empty activity list — produces PDF with header and period blocks but empty summary table with 'Ingen aktiviteter' message, (4) Norwegian characters (æ, ø, å) are embedded correctly (requires a font that supports the full Latin Extended-A range), (5) metadata object with null optional fields (e.g., no coordinator name) — assert graceful fallback text rather than exception. For visual validation, generate a sample PDF during development and manually review against the actual Bufdir Word template provided by the organizations. Screenshot/golden testing of PDF output is not required for CI but a reference PDF fixture should be stored in test/fixtures/ for manual comparison.
NHF contacts can belong to up to five local chapters simultaneously. If the deduplication logic in the activity query service incorrectly attributes cross-chapter activities, organisations will either under-report or over-report to Bufdir, which could trigger grant clawback or compliance investigations.
Mitigation & Contingency
Mitigation: Implement deduplication using the existing multi-chapter membership service as the source of truth for chapter affiliation. Write test fixtures covering all known multi-chapter edge cases and validate outputs against manually prepared reference exports from NHF.
Contingency: If deduplication cannot be made deterministic for complex hierarchies before release, gate the export behind an org-level feature flag and require NHF to validate a preview export against their manual Excel before enabling in production.
Server-side Dart libraries for Excel generation are less mature than equivalents in Node.js or Python. The chosen library may lack support for Bufdir-required formatting features (merged cells, data validation, specific date formats), requiring significant workaround effort or a library switch mid-implementation.
Mitigation & Contingency
Mitigation: Evaluate the top two Dart xlsx libraries (excel, spreadsheet_decoder) against a Bufdir template sample file before committing. Identify all required formatting features and verify library support in a spike.
Contingency: If no Dart library meets requirements, implement the Excel generation as a Supabase Edge Function in TypeScript using the well-supported ExcelJS library, exposing it to the Dart backend via an internal RPC call.
The attachment bundler must retrieve documents from Supabase Storage that were uploaded by the document attachments feature. If storage paths, RLS policies, or signed URL expiry have not been standardised across features, the bundler may fail to retrieve attachments at export time.
Mitigation & Contingency
Mitigation: Audit the document attachments feature's storage schema and RLS policies before implementing the bundler. Agree on a stable internal service-account access pattern for cross-feature storage reads.
Contingency: If cross-feature storage access cannot be made reliable, implement the bundler to include only attachments that can be retrieved successfully and produce a manifest listing any attachments that could not be bundled, rather than failing the entire export.