Document column mapping configuration guide
epic-bufdir-reporting-export-core-logic-task-014 — Write developer documentation covering: the ColumnMappingConfig JSON structure, how to add a new organisation's column schema without code changes, the NullValuePolicy options and when to use each, the ExportAuditRecord lifecycle diagram, and the orchestrator step sequence with error propagation table. Include worked examples for NHF, Blindeforbundet, and HLF configurations.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 6 - 158 tasks
Can start after Tier 5 completes
Implementation Notes
Read the actual ColumnMappingConfig and related Dart source files before writing the documentation — do not infer field names. Use a consistent heading hierarchy: H2 for major sections, H3 for subsections, H4 for individual fields in reference tables. For the lifecycle diagram, model all states visible in the ExportAuditRecord status enum including transient states (initiated, processing) and all terminal states (completed, failed, partial_failure). The error propagation table should have one row per distinct exception type the orchestrator handles.
For NHF, Blindeforbundet, and HLF examples, cross-reference the workshop summary document (likeperson.md) to ensure column examples reflect their real-world reporting fields (e.g., activity type, duration, participant count). Keep the tone technical but accessible — this document targets Flutter/Dart developers, not end users.
Testing Requirements
No automated tests for documentation. Manual review checklist: (1) all JSON examples are valid — paste each into a JSON validator; (2) Mermaid diagram renders in GitHub preview; (3) all internal cross-references (anchor links) resolve; (4) peer review sign-off from one other developer who attempts to follow the 'Adding a new organisation' procedure and confirms it works end-to-end against the actual codebase.
Bufdir's column schema may have per-field business rules (conditional required fields, cross-field validation, organisation-specific category taxonomies) that cannot be expressed in a simple key-value mapping configuration. If the configuration model is too simple, supporting NHF's specific requirements will require hardcoded organisation logic, undermining the configuration-driven design.
Mitigation & Contingency
Mitigation: Design the column configuration schema as a full JSON document supporting field-level transformation rules, conditional expressions, and org-specific value enumerations. Validate the design against a real NHF Bufdir Excel template before implementation begins.
Contingency: If the configuration model cannot express all required rules, implement a thin transformation plugin interface where org-specific logic can be added as a named Dart class registered against the organisation ID, with the JSON config covering only the common cases.
For large organisations like NHF with potentially tens of thousands of activity records, the full export pipeline (query + map + generate + bundle + upload) may exceed Supabase Edge Function execution time limits (typically 150s), causing silent timeouts that leave audit records in a pending state indefinitely.
Mitigation & Contingency
Mitigation: Implement the orchestrator as a background Dart isolate with progress streaming rather than a synchronous Edge Function call. Use chunked processing for the query and mapping phases to reduce peak memory usage. Profile against realistic NHF data volumes in a staging environment.
Contingency: If processing time cannot be reduced below the timeout threshold, implement an asynchronous job model where the export is queued, processed in the background, and the user is notified via push notification when the download is ready — treating it as an eventual rather than synchronous operation.