Driver honorarium form: confidentiality declaration and acknowledgement
epic-travel-expense-registration-org-extensions-task-004 — Extend the DriverHonorariumForm to present the linked confidentiality declaration text, rendered in a scrollable read-only panel. Add an acknowledgement checkbox with accessible semantics label. Implement submission-blocking logic that prevents the parent expense form from progressing to submit until the checkbox is checked. Record the acknowledgement timestamp via DriverHonorariumService on checkbox activation. Declaration text must be sourced from org configuration, not hardcoded.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 3 - 413 tasks
Can start after Tier 2 completes
Implementation Notes
Use a ScrollController attached to the declaration SingleChildScrollView to detect scroll-to-bottom: listen to controller.position.pixels >= controller.position.maxScrollExtent - 10. Store fullyScrolled as a BLoC state field, not widget local state, so it survives rebuilds. Declaration text should be fetched once when the form is first shown and cached in the BLoC state for the session — avoid re-fetching on every rebuild. Use the flutter_markdown package for rendering declaration text if markdown formatting is required.
The acknowledgement record in declaration_acknowledgement must be inserted via DriverHonorariumService (which calls a Supabase Edge Function) to use server-side timestamps. Do not allow re-use of a previously saved acknowledgement_id across sessions — always create a new record.
Testing Requirements
Widget tests: (1) declaration text renders from mocked service, (2) checkbox unchecked by default, (3) submit button disabled when unchecked, (4) submit button enabled after checkbox checked, (5) acknowledgement event fired with correct data on check, (6) fully_scrolled=false when user has not scrolled to bottom, (7) fully_scrolled=true after full scroll. BLoC unit tests: ExpenseFormBloc blocks submission when declarationAcknowledged=false. Integration test: full flow from form open → scroll declaration → check box → submit enabled. Use flutter_test and mocktail.
Test on both iOS (VoiceOver) and Android (TalkBack) semantic trees.
The Dynamics portal (HLF) and Xledger (Blindeforbundet) APIs have organisation-managed API contracts that may change without notice. Field mapping requirements, authentication flows, and export formats are not fully documented and may only be clarified during integration testing.
Mitigation & Contingency
Mitigation: Engage HLF and Blindeforbundet technical contacts early to obtain API documentation, sandbox credentials, and example payloads before implementation starts. Design the accounting integration client as a thin adapter layer with organisation-specific mappers so that field mapping changes require only mapper updates, not core client changes.
Contingency: If API documentation is unavailable or the API is unstable during Phase 3, implement a CSV/JSON file export as an interim deliverable. Coordinators can manually upload the file to their respective accounting systems until the live API integration is completed.
The confidentiality declaration for Blindeforbundet drivers may have specific legal requirements around content, format, wording, and record-keeping that are not yet specified. Implementing the wrong declaration flow could expose Blindeforbundet to compliance risk.
Mitigation & Contingency
Mitigation: Treat the declaration content and acknowledgement flow as a Blindeforbundet-controlled configuration, not hardcoded text. Implement the declaration as a templated document fetched from Supabase and reviewed by Blindeforbundet before any production deployment. Obtain written sign-off on the declaration text and acknowledgement mechanism before the epic is considered complete.
Contingency: If legal requirements cannot be confirmed in time for the sprint, deliver the driver honorarium form without the confidentiality declaration and gate the entire driver feature behind its feature flag. The declaration can be added in a follow-up sprint once requirements are confirmed, without blocking other feature delivery.
If the accounting export can be triggered multiple times for the same approved claims batch, duplicate records may be created in Dynamics or Xledger, causing accounting reconciliation problems that are difficult to reverse.
Mitigation & Contingency
Mitigation: Implement idempotent export runs: each export batch is assigned a unique run ID stored in the database. The accounting integration client checks for an existing successful export run for the same claim IDs before submitting. Approved claims that have been exported are marked with exported_at timestamp to prevent re-export.
Contingency: If duplicate exports occur despite idempotency checks (e.g. network failure after API success but before local confirmation), provide coordinators with an export history panel showing run IDs and timestamps. Implement a reconciliation endpoint that can query the accounting system for existing records before re-submitting flagged claims.