Receipt Upload & Management
Feature Detail
Description
This feature provides peer mentors with the ability to attach photographic receipt evidence to individual expense items by capturing images directly via device camera or selecting from the photo library. Receipts are required for expense items exceeding a configurable monetary threshold (HLF specifies 100 kr). The system stores receipt images securely in cloud object storage, generates thumbnails for inline preview within the expense form, and links each image to its parent expense item record. Receipt status is tracked and surfaced to approvers during the attestation workflow.
Analysis
Receipt documentation is a mandatory compliance requirement for organisational auditing and Bufdir grant reporting. Without a seamless in-app capture flow, peer mentors resort to paper receipts that are lost or submitted late, causing reimbursement delays and audit failures. Integrating camera capture directly into the expense registration flow eliminates the friction of external photo management and ensures receipts are attached at the point of registration rather than forgotten. For coordinators and accountants, having receipts digitally attached to each expense item dramatically reduces manual follow-up and accelerates approval cycles. This feature directly supports integration with accounting systems like Xledger and Dynamics by providing the documentation trail required for automated expense sync.
Use the `image_picker` Flutter package to provide both camera capture and gallery selection. Images should be compressed client-side before upload using `flutter_image_compress` to reduce storage costs and upload time. Upload to Supabase Storage with a bucket policy restricting read access to the owning user and their organisation's coordinators. Store the storage path and a generated thumbnail URL in the `receipts` table linked to the parent `expense_items` record. The UI renders a thumbnail grid within the expense detail view with a tap-to-fullscreen viewer. Threshold-based requirement enforcement (e.g., mandatory above 100 kr) is driven by organisation configuration retrieved from Supabase at session start. Handle upload failures gracefully with retry logic and offline queue support.
Dependencies
Definition of Done
Components (6)
User Stories (12)
As a As a Peer Mentor (Likeperson)
I want I want to delete a receipt thumbnail from the expense item if I attached the wrong image
So that So that I can correct mistakes before submitting the expense claim without having to discard the entire expense registration
- Given a receipt thumbnail is displayed, when the user taps the delete affordance on the thumbnail, then a confirmation prompt is shown to prevent accidental deletion
- Given the user confirms deletion, when the delete action completes, then the thumbnail is removed from the grid and the receipt record is deleted from the database
- Given the user dismisses the confirmation prompt without confirming, when the prompt closes, then the receipt remains attached and unchanged
- +1 more
As a As a user
I want I want to select an existing photo from my device's photo library to attach as a receipt
So that So that I can still attach a receipt when I photographed it earlier or prefer to use an image already saved on my device
- Given the Camera Capture Widget action sheet is shown, when the user selects 'Choose from Library', then the native device photo picker opens
- Given the user selects an image from their library, when they confirm, then the image is processed and uploaded using the same pipeline as a camera capture
- Given a library image is selected, when the upload succeeds, then a thumbnail is shown in the receipt grid identical in appearance to a camera-captured receipt
- +1 more
As a As a user
I want I want to see thumbnail previews of all attached receipts and tap any thumbnail to open it full screen
So that So that I can verify the correct receipt image has been attached and review its legibility before submitting the expense claim
- Given an expense item has attached receipts, when the Receipt Upload Screen is opened, then all attached receipt thumbnails are displayed in a grid layout
- Given a thumbnail is displayed, when the user taps it, then the receipt image opens in a full-screen viewer
- Given an image is uploading, when the thumbnail is rendered, then a spinner or pending indicator is visible on the thumbnail
- +2 more
As a As a Peer Mentor (Likeperson)
I want I want failed receipt uploads to be queued and automatically retried when connectivity is restored
So that So that I can register expenses and attach receipts in areas with poor network coverage without losing my images or having to repeat the upload manually
- Given the device is offline, when the user attaches a receipt image, then the thumbnail is added to the grid with a pending indicator showing the upload is queued
- Given an upload is queued and the device comes back online, when connectivity is restored, then the pending upload is retried automatically without requiring user action
- Given a queued upload succeeds after retry, when the upload completes, then the thumbnail transitions from a pending state to a confirmed state
- +2 more
As a As a user
I want I want to select an existing photo from my device's photo library to attach as a receipt
So that So that I can still attach a receipt when I photographed it earlier or prefer to use an image already saved on my device
- Given the Camera Capture Widget action sheet is shown, when the user selects 'Choose from Library', then the native device photo picker opens
- Given the user selects an image from their library, when they confirm, then the image is processed and uploaded using the same pipeline as a camera capture
- Given a library image is selected, when the upload succeeds, then a thumbnail is shown in the receipt grid identical in appearance to a camera-captured receipt
- +1 more
As a As a user
I want I want to see thumbnail previews of all attached receipts and tap any thumbnail to open it full screen
So that So that I can verify the correct receipt image has been attached and review its legibility before submitting the expense claim
- Given an expense item has attached receipts, when the Receipt Upload Screen is opened, then all attached receipt thumbnails are displayed in a grid layout
- Given a thumbnail is displayed, when the user taps it, then the receipt image opens in a full-screen viewer
- Given an image is uploading, when the thumbnail is rendered, then a spinner or pending indicator is visible on the thumbnail
- +2 more
As a As a Coordinator
I want I want to view the receipt images attached to an expense item when reviewing a reimbursement claim in the approval queue
So that So that I can verify the validity and legibility of submitted receipts before approving or rejecting the reimbursement claim, and to fulfil my attestation obligations
- Given a coordinator opens a reimbursement claim containing expense items with attached receipts, when the detail view loads, then receipt thumbnails are displayed for each qualifying expense item
- Given a receipt thumbnail is visible in the approval view, when the coordinator taps it, then the full-resolution receipt image opens in the full-screen viewer
- Given the expense item has no receipts, when the approval detail view loads, then a clear indicator shows that no receipt is attached for that item
- +2 more
As a As a user
I want I want to take a photo of a receipt using my device camera from within the expense registration screen
So that So that I can capture proof of an expense immediately at the point of payment without having to manage files separately or switch to another app
- Given the Receipt Upload Screen is open, when the user taps the camera action button, then a bottom sheet appears with 'Take Photo' and 'Choose from Library' options
- Given the action sheet is shown, when the user selects 'Take Photo', then the device native camera is launched
- Given the user captures a photo, when they confirm it, then the image is returned to the app and the upload process begins immediately
- +2 more
As a As a Peer Mentor (Likeperson)
I want I want to be prompted to attach a receipt when my expense item exceeds the organisation-configured monetary threshold
So that So that I am reminded of the receipt requirement at the right moment and cannot accidentally submit a non-compliant expense claim
- Given an expense item's amount is at or above the configured threshold, when the user attempts to proceed without a receipt, then a validation message clearly states that a receipt is required
- Given the threshold enforcement is active, when the user tries to submit the expense, then submission is blocked until at least one receipt is successfully attached
- Given the organisation threshold is 100 kr and the expense amount is 99 kr, when the user proceeds without a receipt, then no mandatory receipt prompt is shown
- +2 more
As a As a user
I want I want to attach a receipt image to an individual expense item directly within the expense registration flow
So that So that the receipt is linked to the correct expense at the point of entry, satisfying audit and Bufdir grant reporting requirements without relying on paper submission
- Given an expense item is open for editing, when the user taps the attach receipt action, then the Receipt Upload Screen opens and displays any previously attached receipt thumbnails
- Given the Receipt Upload Screen is open, when a new image is successfully uploaded, then it appears as a thumbnail in the grid with a confirmation indicator
- Given an image is uploading, when the upload completes, then the thumbnail transitions from a pending state to a confirmed state without requiring user interaction
- +2 more
As a As a user
I want I want to take a photo of a receipt using my device camera from within the expense registration screen
So that So that I can capture proof of an expense immediately at the point of payment without having to manage files separately or switch to another app
- Given the Receipt Upload Screen is open, when the user taps the camera action button, then a bottom sheet appears with 'Take Photo' and 'Choose from Library' options
- Given the action sheet is shown, when the user selects 'Take Photo', then the device native camera is launched
- Given the user captures a photo, when they confirm it, then the image is returned to the app and the upload process begins immediately
- +2 more
As a As a user
I want I want to attach a receipt image to an individual expense item directly within the expense registration flow
So that So that the receipt is linked to the correct expense at the point of entry, satisfying audit and Bufdir grant reporting requirements without relying on paper submission
- Given an expense item is open for editing, when the user taps the attach receipt action, then the Receipt Upload Screen opens and displays any previously attached receipt thumbnails
- Given the Receipt Upload Screen is open, when a new image is successfully uploaded, then it appears as a thumbnail in the grid with a confirmation indicator
- Given an image is uploading, when the upload completes, then the thumbnail transitions from a pending state to a confirmed state without requiring user interaction
- +2 more