View and Replace Attached Receipt Before Submission
After attaching a receipt, the peer mentor can tap the thumbnail to open a full-screen preview modal. From the preview, they can choose to retake the photo, select a different image from the gallery, or remove the attachment entirely. If the expense threshold requires a receipt, removing it triggers a validation warning. The BLoC state correctly reflects the attachment status and the form submission button is disabled if a required receipt is missing. This ensures data quality at point of entry rather than requiring coordinator follow-up.
User Story
Audience Summaries
This story directly addresses volunteer satisfaction and operational efficiency for peer mentors submitting expense claims. By enabling receipt preview, replacement, and removal before submission, the organization eliminates a costly back-and-forth approval loop between peer mentors and coordinators caused by unreadable or incorrect receipt images. Higher-quality submissions at point of entry translate to increased auto-approval rates, faster reimbursement cycles, and stronger volunteer retention — a critical metric for NHF and partner organizations. Reducing coordinator follow-up overhead also lowers administrative costs per claim processed, supporting the platform's value proposition across all partner organizations.
This high-priority story requires close collaboration between Flutter developers and backend/BLoC state management specialists. The full-screen preview modal, replacement flow, and conditional validation logic introduce moderate UI complexity and several distinct acceptance criteria that must be verified through both automated widget tests and manual accessibility testing. Dependencies on the receipt capture story (story-receipt-capture-and-attachment-peer-mentor-001) mean this work cannot begin until that story is complete and stable. Rollout planning should include regression testing of the expense form submission flow end-to-end, with screen reader compatibility verified on both iOS and Android.
Validation warning behavior and submit button disabling logic require explicit UAT sign-off from a coordinator or product owner.
Implementation requires extending the existing BLoC state to track attachment presence, validity, and replacement lifecycle. The preview modal should be a dedicated widget receiving the current attachment state and emitting replacement or removal events back to the BLoC. Camera sheet reuse from the capture story should be abstracted into a reusable service to avoid duplication. Conditional form submission disabling must observe BLoC stream state reactively — avoid imperative checks.
The inline validation error for missing required receipts must use a semantics live region (Flutter Semantics widget with liveRegion: true) for screen reader announcements. Edge cases include handling in-progress image replacement (user cancels camera), memory management for replaced images (ensure old file references are disposed), and form state persistence across navigator stack pops.
Acceptance Criteria
- Given a receipt is attached to my expense, When I tap the thumbnail preview, Then a full-screen preview modal opens showing the receipt image
- Given the preview modal is open, When I tap 'Replace', Then the camera sheet reopens and I can capture a new image that replaces the previous one
- Given the preview modal is open, When I tap 'Remove', Then the attachment is cleared and the thumbnail indicator is removed from the form
- Given I remove a receipt from a claim that requires one, When the form is validated, Then a visible inline error message informs me that a receipt is required for this amount
- Given a receipt is removed when required, When I attempt to submit, Then the submit button remains disabled and the validation error is announced to screen readers via live region
- Given I replace a receipt, When the new image is confirmed, Then the old image is discarded from local state and the new thumbnail is shown
Business Value
Allowing review and replacement before submission prevents claim rejections caused by unreadable receipts, which would otherwise create a back-and-forth approval loop costing coordinator and peer mentor time. Clean data at submission means higher auto-approval rates and faster reimbursement for the peer mentor, directly improving volunteer satisfaction.
Components
- Receipt Camera Sheet ui
- Receipt Thumbnail Preview Widget ui
- Receipt Attachment Indicator ui
- Receipt Attachment Service service
- Receipt Image Compressor service
- Receipt Image Picker Integration infrastructure
- Expense Form BLoC service
- Expense Validation Service service
- Plain Language Error Display ui