Travel Reimbursement Registration
Feature Detail
Description
This feature enables peer mentors and coordinators to register all forms of travel reimbursement expenses including mileage, toll fees, parking costs, and public transit fares through a structured, guided interface. The system enforces mutually exclusive expense type selections to prevent invalid combinations such as simultaneously claiming both kilometre allowance and a bus ticket for the same journey. Fixed dropdown choices replace free-text input to ensure data integrity and downstream accounting compatibility. Default values and smart validation reduce input errors and registration time significantly for high-volume users.
Analysis
Travel reimbursement is a core operational need for both HLF and Blindeforbundet, where peer mentors routinely travel to visit members and attend events. Without a streamlined registration flow, reimbursements go unclaimed or are submitted incorrectly, creating administrative burden and volunteer frustration. Accurate expense capture also feeds directly into Bufdir reporting requirements, making it strategically critical. The enforced expense type logic eliminates a major source of accounting errors that currently require manual correction by coordinators, saving significant back-office time and ensuring compliance with organisational reimbursement policies. Automating this reduces the barrier for volunteers to claim what they are entitled to, supporting volunteer retention.
Implement as a multi-step Flutter wizard using BLoC for state management, with expense type selection as the first mandatory step that drives conditional field rendering. Expense types are sourced from a configuration store in Supabase to allow per-organisation customisation. Mileage calculation integrates with a distance validation utility, while toll, parking, and transit entries require amount input with optional receipt linking. Riverpod providers expose organisation-specific reimbursement rules including per-kilometre rates. Validation is enforced client-side with server-side confirmation on submission. The repository layer writes to `travel_expense_reports` and `expense_items` tables in Supabase with appropriate RLS policies scoped to the submitting user.
Dependencies
Definition of Done
User Stories (13)
As a As a user
I want I want to view a list of my previously submitted travel expense reports, including their submission date, total amount, and current approval status
So that So that I can track whether my claims have been approved, identify any that require additional action, and verify the amounts that will be reimbursed to me
- Given the user navigates to their expense history, when the repository query executes, then all of their previously submitted expense reports are listed in descending submission date order
- Given a submitted expense report exists, when the user views the history list, then each item shows the submission date, total reimbursement amount, and an approval status badge
- Given the user has no previous submissions, when the history screen loads, then an empty state message is displayed prompting them to submit their first claim
- +2 more
As a As a user
I want I want to view a list of my previously submitted travel expense reports, including their submission date, total amount, and current approval status
So that So that I can track whether my claims have been approved, identify any that require additional action, and verify the amounts that will be reimbursed to me
- Given the user navigates to their expense history, when the repository query executes, then all of their previously submitted expense reports are listed in descending submission date order
- Given a submitted expense report exists, when the user views the history list, then each item shows the submission date, total reimbursement amount, and an approval status badge
- Given the user has no previous submissions, when the history screen loads, then an empty state message is displayed prompting them to submit their first claim
- +2 more
As a As a Coordinator
I want I want to open the expense registration wizard in proxy mode, select a peer mentor from my organisation's active roster, and submit a travel expense report attributed to that mentor rather than myself
So that So that peer mentors who lack the technical ability or device access to use the app are not excluded from receiving reimbursements they are entitled to, ensuring equitable access to expense claims
- Given the coordinator opens the expense registration wizard, when they activate proxy mode, then a peer mentor selection step is presented before the expense type step
- Given the coordinator selects a peer mentor, when the wizard advances, then the organisation-specific reimbursement rules for the selected mentor's organisation are loaded
- Given the coordinator completes and submits the wizard in proxy mode, when the record is written to Supabase, then the expense report owner is set to the selected mentor's user ID and the proxy submitter field records the coordinator's ID
- +2 more
As a As a user
I want I want to enter a monetary amount for a toll fee, parking cost, or public transit fare using a structured input widget that enforces currency formatting and optionally links an uploaded receipt
So that So that fixed-cost travel expenses are captured accurately and linked to supporting documentation where required by the organisation's reimbursement policy
- Given the user has selected 'Toll fee', 'Parking', or 'Public transit' as the expense type, when the wizard advances, then the Expense Amount Input Widget is displayed with a currency-formatted number field
- Given the user enters a non-numeric value or zero, when they attempt to advance, then a validation error is shown and progression is blocked
- Given the organisation has a receipt requirement threshold of NOK 100 and the user enters an amount exceeding this, when the field loses focus, then a prompt to attach a receipt is displayed with a link to the receipt upload flow
- +2 more
As a As a user
I want I want to see the reimbursement rules applicable to my organisation — including the per-kilometre rate, auto-approval distance threshold, and receipt requirement threshold — before or during the expense registration process
So that So that I can make informed decisions about which expense type to claim and whether I need to attach a receipt, without having to consult external documentation or contact a coordinator
- Given the user opens the expense registration wizard, when the rules provider initialises, then it fetches the organisation-specific rules from Supabase within 2 seconds
- Given the rules have been fetched, when the user is on the mileage entry step, then the current per-kilometre rate is displayed as helper text below the distance input field
- Given the rules have been fetched, when the user is on a fixed-amount entry step, then the receipt requirement threshold is shown as helper text indicating when a receipt is required
- +2 more
As a As a user
I want I want to enter a monetary amount for a toll fee, parking cost, or public transit fare using a structured input widget that enforces currency formatting and optionally links an uploaded receipt
So that So that fixed-cost travel expenses are captured accurately and linked to supporting documentation where required by the organisation's reimbursement policy
- Given the user has selected 'Toll fee', 'Parking', or 'Public transit' as the expense type, when the wizard advances, then the Expense Amount Input Widget is displayed with a currency-formatted number field
- Given the user enters a non-numeric value or zero, when they attempt to advance, then a validation error is shown and progression is blocked
- Given the organisation has a receipt requirement threshold of NOK 100 and the user enters an amount exceeding this, when the field loses focus, then a prompt to attach a receipt is displayed with a link to the receipt upload flow
- +2 more
As a As a user
I want I want to see the reimbursement rules applicable to my organisation — including the per-kilometre rate, auto-approval distance threshold, and receipt requirement threshold — before or during the expense registration process
So that So that I can make informed decisions about which expense type to claim and whether I need to attach a receipt, without having to consult external documentation or contact a coordinator
- Given the user opens the expense registration wizard, when the rules provider initialises, then it fetches the organisation-specific rules from Supabase within 2 seconds
- Given the rules have been fetched, when the user is on the mileage entry step, then the current per-kilometre rate is displayed as helper text below the distance input field
- Given the rules have been fetched, when the user is on a fixed-amount entry step, then the receipt requirement threshold is shown as helper text indicating when a receipt is required
- +2 more
As a As a user
I want I want to select an expense type from a fixed dropdown list at the start of a reimbursement registration, with the system preventing invalid type combinations such as kilometre allowance and public transit for the same journey
So that So that I cannot accidentally submit an inconsistent claim that would require manual correction by an administrator and cause downstream accounting errors
- Given the expense registration wizard is open, when the user lands on step one, then the expense type selector is displayed with all types permitted for their organisation loaded from the configuration store
- Given the user selects 'Kilometre allowance', when the selector re-renders, then 'Public transit' and any other mutually exclusive types are disabled and visually indicated as unavailable
- Given the user selects a fixed-amount type (toll, parking, or transit), when the selector re-renders, then 'Kilometre allowance' is disabled to prevent combination claims
- +2 more
As a As a user
I want I want to enter a kilometre distance and have the system automatically calculate my reimbursement amount using my organisation's configured per-kilometre rate, with a live preview of the calculated sum before I submit
So that So that I can quickly register mileage claims without needing to know the current rate or perform manual calculations, reducing input errors and increasing claim accuracy
- Given the user has selected 'Kilometre allowance' and entered a distance, when the distance field value changes, then the calculated reimbursement amount updates immediately using the organisation's configured per-kilometre rate
- Given the organisation has a per-kilometre rate of NOK 4.90, when the user enters 25 km, then the preview shows NOK 122.50 before any user action to proceed
- Given the user enters a distance below the configured minimum or above the configured maximum, when they attempt to advance in the wizard, then a validation error message specifying the allowed range is shown and progression is blocked
- +2 more
As a As a user
I want I want to progress through a multi-step expense registration wizard that collects all required information for my reimbursement claim and submits it to Supabase with client-side and server-side validation before confirming success
So that So that my expense claim is recorded completely and accurately in a single guided session, minimising the risk of incomplete submissions that would require follow-up
- Given the user opens the expense registration wizard and completes all required steps, when they tap 'Submit', then client-side validation runs first and any errors are shown inline before a server request is made
- Given client-side validation passes, when the submission request is sent, then server-side validation runs and the response either confirms success or returns specific field-level errors
- Given submission succeeds, when the confirmation screen is shown, then it displays the report reference number, total reimbursement amount, and a timestamp
- +3 more
As a As a user
I want I want to select an expense type from a fixed dropdown list at the start of a reimbursement registration, with the system preventing invalid type combinations such as kilometre allowance and public transit for the same journey
So that So that I cannot accidentally submit an inconsistent claim that would require manual correction by an administrator and cause downstream accounting errors
- Given the expense registration wizard is open, when the user lands on step one, then the expense type selector is displayed with all types permitted for their organisation loaded from the configuration store
- Given the user selects 'Kilometre allowance', when the selector re-renders, then 'Public transit' and any other mutually exclusive types are disabled and visually indicated as unavailable
- Given the user selects a fixed-amount type (toll, parking, or transit), when the selector re-renders, then 'Kilometre allowance' is disabled to prevent combination claims
- +2 more
As a As a user
I want I want to enter a kilometre distance and have the system automatically calculate my reimbursement amount using my organisation's configured per-kilometre rate, with a live preview of the calculated sum before I submit
So that So that I can quickly register mileage claims without needing to know the current rate or perform manual calculations, reducing input errors and increasing claim accuracy
- Given the user has selected 'Kilometre allowance' and entered a distance, when the distance field value changes, then the calculated reimbursement amount updates immediately using the organisation's configured per-kilometre rate
- Given the organisation has a per-kilometre rate of NOK 4.90, when the user enters 25 km, then the preview shows NOK 122.50 before any user action to proceed
- Given the user enters a distance below the configured minimum or above the configured maximum, when they attempt to advance in the wizard, then a validation error message specifying the allowed range is shown and progression is blocked
- +2 more
As a As a user
I want I want to progress through a multi-step expense registration wizard that collects all required information for my reimbursement claim and submits it to Supabase with client-side and server-side validation before confirming success
So that So that my expense claim is recorded completely and accurately in a single guided session, minimising the risk of incomplete submissions that would require follow-up
- Given the user opens the expense registration wizard and completes all required steps, when they tap 'Submit', then client-side validation runs first and any errors are shown inline before a server request is made
- Given client-side validation passes, when the submission request is sent, then server-side validation runs and the response either confirms success or returns specific field-level errors
- Given submission succeeds, when the confirmation screen is shown, then it displays the report reference number, total reimbursement amount, and a timestamp
- +3 more