Implement BenefitCalculationService pure functions
epic-benefit-calculator-core-logic-task-003 — Implement BenefitCalculationService as a stateless class with a single calculate(ActivityInput input, BenefitMultiplierConfig config) method that returns a BenefitCalculationResult. Compute personal benefit (hours_saved = duration_hours * hourly_value_rate, travel_cost_avoided = km * cost_per_km) and societal benefit (public_health_offset = activities_count * health_offset_factor). No network calls, no side effects — pure function only.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Implementation Notes
Make the class a const-constructible singleton or expose a static calculate() method — either pattern is fine, but be consistent with other service classes in the codebase. Dart's double arithmetic is IEEE 754; for currency display, callers should round to 2 decimal places in the UI layer, not here. Do not introduce package:decimal or similar — the values are estimates, not financial ledger entries. ActivityInput likely already exists in the codebase (it is referenced in the activity wizard); if it lacks duration_hours or distance_km, add those fields in this task.
Document the formula inline with a comment referencing the source (e.g., NAV time-value rate) so future maintainers understand the multiplier semantics.
Testing Requirements
Exhaustive unit tests using flutter_test — no mocks needed. Cover: (1) nominal inputs (e.g., 2 hours, 15 km, 3 activities); (2) all zeros input produces all-zero result; (3) fractional hours (0.25, 0.5, 0.75) produce correct proportional output; (4) large km value (e.g., 500 km) does not overflow; (5) activities_count = 1 with non-zero factor; (6) boundary multiplier config (all rates = 1.0) passes through input values unchanged; (7) negative input throws ArgumentError; (8) total_societal_value == hours_saved + travel_cost_avoided + public_health_offset for every test case. Aim for 100% branch coverage.
The exact formulas for SROI social value (public health system cost offset) may not be agreed upon with the client organisations or Bufdir. If formulas are disputed post-implementation, the service and all downstream tests will need to be revised.
Mitigation & Contingency
Mitigation: Document the two formulas and their multiplier inputs explicitly in the BenefitCalculationService source file and obtain sign-off from the product owner before implementation begins. Store formula multipliers exclusively in the Supabase config table so adjustments require only a config update, not a code deployment.
Contingency: If formulas are revised after implementation, the pure-function architecture means changes are isolated to BenefitCalculationService. Update the service, adjust unit tests, and re-run the test suite. No UI components need modification.
The BLoC must handle the asynchronous config fetch from the multiplier repository during initialisation. Race conditions between the config loading state and the first InputChanged event could result in calculations running against null or stale multiplier values.
Mitigation & Contingency
Mitigation: Guard all InputChanged event handlers in the BLoC with a null check on the loaded config state. Emit BenefitCalculationLoading until config resolves. Write a BLoC test that fires InputChanged before config loads and asserts the state remains BenefitCalculationLoading.
Contingency: If race conditions surface in integration testing, add an explicit config-loaded flag and queue InputChanged events until the flag is set, draining the queue on config resolution.