Define Bufdir API submission interface contract
epic-bufdir-reporting-export-processing-services-task-011 — Define the abstract Dart interface for the BufdirApiIntegrationService including method signatures for submitting export packages, checking submission status, and handling Bufdir API response codes. Document the expected future Bufdir API endpoints, authentication mechanism, and payload format based on available Bufdir documentation to guide future implementation.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 4 - 323 tasks
Can start after Tier 3 completes
Implementation Notes
Keep the interface file focused: `bufdir_api_integration_service.dart` should contain only the abstract class and the `BufdirApiError` enum — no implementation details. Use triple-slash `///` Dart doc comments throughout so dart doc generates browsable HTML. For the contract markdown document, create it at `docs/bufdir_api_contract.md` relative to the project root — this is a developer reference document, not generated output, so it is safe to commit. Reference the Bufdir contact established in the workshop documentation (Norse Digital Products is initiating dialogue with Bufdir on behalf of all organisations) as the source for future updates to this contract.
Include a table in the markdown listing each method with its endpoint placeholder, auth mechanism, and known gap status. For the `BufdirApiError` enum, add a `description` extension getter so error messages can be logged without a switch statement. Mark the file with `// ignore_for_file: avoid_classes_with_only_static_members` if needed to pass linting on the interface pattern.
Testing Requirements
This is a documentation and interface definition task — runtime test coverage is not applicable. However: (1) the abstract class must compile without errors verified by running `dart analyze` in CI; (2) a simple instantiability test must verify that `BufdirDirectApiService` (the placeholder implementation from task-010) correctly satisfies the interface at compile time; (3) the `BufdirApiError` enum must have a corresponding unit test that maps all defined values to non-null description strings to confirm completeness.
Documentation review checklist: all methods have doc comments, all placeholders are marked, GDPR section is present, no TODO left unacknowledged.
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.