Implement QrCodeGenerator widget
epic-membership-recruitment-foundation-task-005 — Implement the QrCodeGenerator Flutter widget wrapping the qr_flutter package. The widget accepts a data string (referral URL), size (double), errorCorrectionLevel (QrErrorCorrectLevel), foregroundColor, and backgroundColor (for organisation branding). Expose a static helper generateBytes(data, size) → Uint8List for use by the share sheet. Ensure the widget degrades gracefully when the data string is empty and renders accessibly with a semantic label describing the QR code purpose.
Acceptance Criteria
Technical Requirements
Implementation Notes
Use QrImageView for the rendered widget (handles its own canvas) and QrPainter directly for generateBytes (paint to ui.Image, then toByteData). Be aware that QrPainter requires a version parameter — pass QrVersions.auto and let the library pick the minimum version for the data length. For generateBytes, run inside a compute isolate if called frequently to avoid blocking the UI thread, though for one-off share operations synchronous execution is acceptable. Keep the widget file small (< 80 lines) — resist adding business logic.
Document the generateBytes method with a dartdoc comment explaining it is intended for share-sheet usage only.
Testing Requirements
Widget tests using flutter_test: (1) renders QrImageView when data is non-empty; (2) renders placeholder when data is empty string; (3) renders placeholder when data is whitespace-only; (4) Semantics label is present and correct; (5) foregroundColor and backgroundColor are passed through to QrImageView. Unit test for generateBytes: (1) returns non-empty Uint8List for valid data; (2) throws ArgumentError for empty data; (3) output is valid PNG bytes (check magic bytes FF D8 or 89 50 4E 47). Golden tests at three sizes to catch rendering regressions. Run with `flutter test --update-goldens` when intentional changes are made.
iOS Universal Links and Android App Links have distinct configuration requirements (apple-app-site-association, assetlinks.json, entitlements). A misconfiguration causes the OS to open the referral URL in a browser instead of the app, completely breaking the onboarding funnel for new members on one platform.
Mitigation & Contingency
Mitigation: Configure both Universal Links and App Links from the start of this epic using the project's existing Supabase-hosted domain. Write an E2E test on both simulators that taps a referral URL and asserts the onboarding screen is reached. Document the required server-side JSON files alongside the migration.
Contingency: If platform deep-link configuration cannot be resolved before the UI epics need the handler, implement a fallback custom-scheme URI (e.g., likeperson://referral?code=XYZ) that works unconditionally, and schedule Universal/App Link fix as a follow-up task.
Referral click events must be writable without an authenticated session (a new member who has not yet registered is tapping the link). Standard Supabase RLS cannot grant anonymous inserts without opening a security hole. If this is not solved early it blocks the entire attribution pipeline.
Mitigation & Contingency
Mitigation: Design referral_events writes to go exclusively through a Supabase Edge Function that validates the referral code exists and is active before inserting. The Edge Function uses the service-role key server-side; the client only calls the function endpoint. This is documented in the feature spec.
Contingency: If the Edge Function approach is delayed, temporarily allow anon inserts restricted by a CHECK constraint that event_type = 'click' and new_member_id IS NULL, then tighten to Edge Function writes in a follow-up migration before the feature goes to production.
The qr_flutter package version pinned in pubspec may conflict with the current Flutter SDK version or with other packages in the monorepo, causing build failures that block QR code delivery.
Mitigation & Contingency
Mitigation: Verify qr_flutter compatibility against the project's Flutter SDK version as the very first task in this epic. If a conflict exists, resolve it before any other work proceeds.
Contingency: If qr_flutter cannot be made compatible, evaluate mobile_scanner (already likely in pubspec for QR scanning) which also supports generation, or implement QR generation via a lightweight Dart port as a last resort.