Build ScenarioDeepLinkHandler URI translation service
epic-scenario-based-follow-up-prompts-core-logic-task-007 — Implement ScenarioDeepLinkHandler that converts a triggered ScenarioContext (activityId, contactId, activityType, prefillDate, prefillDuration) into a go_router URI string targeting the activity registration wizard with pre-filled route arguments. Implement buildDeepLinkUri(context) and navigateToWizard(context, router). Support both cold-start (notification tap from terminated app) and warm-start (app in background) navigation paths.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Implementation Notes
Implement ScenarioDeepLinkHandler as a Riverpod StateNotifier or plain Provider class. Keep buildDeepLinkUri() strictly pure — it should be a static method or a method with no instance state. For the cold-start flow, maintain a StateProvider
This avoids platform channel complexity and works reliably with go_router. Encode the URI using Uri(path: ..., queryParameters: {...}).toString() to ensure correct percent-encoding. Use the route path string constants defined in the existing go_router configuration — do not hardcode path strings in this handler. Document the cold-start lifecycle clearly: push notification received → app launched → pendingDeepLink stored → app init (Supabase auth) completes → root widget consumes pending link → navigateToWizard() called.
Testing Requirements
Write unit tests using flutter_test for buildDeepLinkUri(): verify URI structure for standard inputs, verify ISO 8601 date encoding, verify URL encoding of special characters in activityType, verify all five context fields appear in the output. For navigateToWizard(): use a GoRouter mock to verify router.go() is called with the correct URI. Write widget tests for the cold-start path: simulate app termination state by calling the pending deep link store before initialization, then trigger the post-init hook and assert the router mock received the correct navigation call. Test that a second cold-start deep link overwrites the first (max 1 pending item).
Test that the pending link is null after consumption.
The Rule Engine must support a flexible JSON rule schema that can express compound conditions (e.g., contact_type AND wellbeing_flag AND delay_days). Underestimating schema expressiveness may require breaking changes to the rule format after coordinators have already configured rules.
Mitigation & Contingency
Mitigation: Define and freeze the rule JSON schema (trigger_type enum, metadata_conditions structure, delay logic) before any implementation begins; validate schema against all known HLF scenarios documented in the feature spec.
Contingency: If schema changes are needed after deployment, implement a schema version field and a migration utility that upgrades stored rules to the new format without coordinator intervention.
Deep-link navigation to the activity wizard with pre-filled arguments may fail if the user's session has expired or if the wizard route is not yet mounted in the navigator stack, causing unhandled navigation exceptions.
Mitigation & Contingency
Mitigation: Implement session state check before navigation; if session is expired, redirect to biometric/login screen and store the pending deep-link URI for post-auth redirect using go_router's redirect mechanism.
Contingency: If post-auth redirect proves unreliable, fall back to navigating to the home screen with a visible action banner that re-triggers the wizard with pre-filled arguments.