View Real-Time Reimbursement Amount Before Submitting
Transparency in reimbursement calculations builds trust between peer mentors and their organizations. As the mentor enters or adjusts the distance value, the reimbursement display should recalculate instantly using the org-specific rate fetched from the rate config repository. This removes uncertainty and prevents under- or over-claiming. The display should clearly show the rate applied (e.g., 'NOK 4.90/km × 23 km = NOK 112.70') so the mentor understands the basis of the figure.
User Story
Audience Summaries
Real-time reimbursement calculation directly addresses one of the highest-friction points in peer mentor expense workflows: uncertainty about whether a submitted claim is accurate. By showing the breakdown — rate × distance = total — before submission, the organization eliminates a significant share of coordinator correction overhead and dispute cycles. For HLF and similar organizations relying on peer mentors who span a wide range of digital literacy levels, this transparency is a trust-building feature that supports adoption and retention. Mentors who feel confident in the system submit claims faster and more consistently, which improves data quality for financial reporting.
This story also enforces org-specific rate application, ensuring each organization's configured rate is always honored — a critical compliance feature that protects the organization from systematic over- or under-payment at scale.
This is a high-priority story with moderate delivery complexity. The core requirement is a reactive UI component that recalculates reimbursement as the distance field changes, pulling the org-specific rate from the rate config repository. A key dependency is story-mileage-reimbursement-entry-peer-mentor-1, which must be complete before this story can be validated end-to-end. Testing must cover: valid input recalculation, empty/invalid input edge cases, offline fallback to cached rate, and rate breakdown display accuracy.
Stakeholders in finance and coordinator roles should review the rate breakdown format before sign-off. The offline caching behavior introduces a subtle UX decision — how to communicate stale rate data — which warrants early alignment with product and design. UAT should include users with varying digital literacy to confirm the breakdown label is clear.
Implementation requires a reactive distance input handler that triggers reimbursement recalculation on every change event without debounce delays that would feel sluggish. The org rate must be fetched from the rate config repository on form load and stored in local state; the distance cache should serve as fallback with a flag indicating cache usage. Calculation logic: `amount = rate * distance`, guarded against NaN, null, empty string, and negative values — all of which must render as zero or a neutral placeholder. The rate breakdown string (e.g., 'NOK 4.90/km × 23 km = NOK 112.70') must be rendered as formatted output, not raw values.
Consider extracting the calculation into a pure utility function for unit testability. The cache-hit indicator should be a non-blocking UI element (e.g., a subtle icon or tooltip). Dependency on the rate config repository interface must be confirmed before work begins.
Acceptance Criteria
- Given I am on the mileage entry form and the org rate has been loaded, When I type or adjust the distance value, Then the reimbursement amount updates in real time without requiring a separate action
- Given the organization uses a custom per-km rate configured in the org rate config repository, When the calculation runs, Then the displayed amount reflects that organization's specific rate, not a hardcoded default
- Given the distance field is empty or contains an invalid value, When the calculation would produce NaN or a negative result, Then the reimbursement display shows zero or a clear placeholder rather than an error
- Given the rate data cannot be fetched (e.g., offline), When the form loads, Then a cached rate from the local distance cache is used and a subtle indicator informs the user the rate may be from cache
- Given the calculated amount is displayed, When the user reviews the form, Then the rate breakdown (rate × distance = total) is visible to confirm the calculation basis
Business Value
Real-time feedback eliminates the most common source of reimbursement errors — mentors submitting incorrect distances because they could not verify the total before submission. This reduces coordinator correction overhead and increases mentor confidence in the system, supporting adoption among the target demographic which includes users with varying digital literacy levels.