Add referral programme and promo-code client

[JonnyLuca]

Summary / Zusammenfassung

EN. RealUnit referral programme and promo-code client (Offerte 24.08.2026 + mail Dani 17:42). The DFX API is the decision authority; this app is a rendering layer for eligibility, terms, invites, overview, frozen-CHF prizes, KYC invite/promo, and App Links.

DE. RealUnit-Empfehlungsprogramm und Promo-Code in der App (Offerte 24.08.2026 + Mail Dani 17:42). Die DFX-API entscheidet; die App rendert Kachel, Teilnahmebedingungen, Einladungen, Übersicht, Prämien mit eingefrorenem Frankenwert, KYC-Schritt Invite/Promo und App Links.

Scope, measurements, blockers

Scope

• Dashboard and settings tiles gated on GET /v1/realunit/referral/summary eligible (KYC-verified, ≥ 70 REALU, not an employee). Subtitle Erhalte 20 REALU pro Weiterempfehlung.
• Teilnahmebedingungen from authenticated GET /v1/realunit/referral/terms (version, markdown, markdownEn), with bundled assets only as an outage fallback; create-invite only after checkbox Ich habe die Teilnahmebedingungen gelesen und akzeptiert. Acceptance posts the exact rendered version so a newer server version reopens the gate.
• Server-generated share text, copy and send; invite URL always https://realunit.app/invite/{code}.
• Overview: Open / Credited only (TB Ziff. 7). Bound/Review folded to Open; defensive client parsing drops Deleted/expired rows if an older backend returns them. Total tile may show running value; label Aktienkurs. History uses CHF frozen at credit (TB Ziff. 6).
• KYC registration step for invite and promo (promo Aktionstext in its own dialog). No stacking with an invite prize (API rejects).
• Universal Links / App Links; Play Install Referrer on Android; iOS re-tap / paste.
• Prize rows: whole REALU, date, frozen CHF. getPayouts drops Pending. History watch includes referralPayout (type 5).
• DE/EN, handbook #spec-referral.
• integration_test/: entry card, terms checkbox gate, named invite, copy/share, overview (open/credited, sum, Aktienkurs), history prize, registration invite+promo, deeplinks /invite/* /promo/*, errors (invalid, not eligible, limit).
• Referral/promo goldens: 28 baselines (eligible/not eligible, empty/filled, loading, error, quota, creating, promo window, KYC invite/promo states). PNGs only via golden-regenerate.yaml.
• iOS/macOS build migrations are committed, including macOS CocoaPods wiring and iOS project/lock/scheme updates. Generated swiftpm/ caches are ignored and not committed.

The app targets the live DFXswiss/backend contract. Public lookup uses GET /v1/realunit/referral/code/:code with inviterName / inviteeName; invite creation sends the exact guestName-only request (terms acceptance is versioned separately) and create/list responses consume server-generated copyText / copyTextEn plus inviterName, pinned against backend draft #5290. Summary openCount is contract-tested against the same visible Open/Credited invite projection; sharePrice and sharePriceLabel: Aktienkurs drive the running “Insgesamt erhalten” valuation while payout history keeps frozen CHF values. Live terms consume version, markdown, and markdownEn 1:1 from backend #5290, select the app language, take precedence over the bundled outage fallback, and pass the rendered version through page → cubit → POST /terms/accept. The separate stand-in repository is not a ship path.

Measured 2026-08-30 (native host checkout; signed current PR head 7ce9d355)

Check	Result
flutter test --coverage --exclude-tags=golden --concurrency=4	5923/5923 passed
Line coverage total (non-golden run)	82.74% (16854/20371)
Line coverage referral|promo|invite under lib/**	100.00% (2352/2352)
Authoritative Golden workflow on this exact head	Run 33316259027 succeeded; baselines already matched, so no bot commit was needed
Android AVD pixel_jonny / emulator-5554	25/25 passed in 2:22
iPhone Air simulator, iOS 26.5	25/25 passed in 3:01
macOS desktop, 9 isolated native invocations	25/25 passed, 9/9 files
Host/platform hygiene	checkout clean after generated plist restoration; 0 tracked swiftpm/ cache files

The macOS files run as isolated flutter test <file> -d macos invocations because Flutter’s combined desktop run lost the debug log connection after 3 passes even though every bundle built. Every integration file and assertion is green in isolated runs. The 66 local pixel differences (including 3 referral surfaces) are host-render differences: the authoritative CI workflow succeeded on this exact head without changing a baseline. No PNG was committed or regenerated locally.

Golden runs (golden-regenerate.yaml on RealUnitCH/app)

• 33316259027 success on current head 7ce9d355; all CI baselines matched, no bot commit needed
• 33285410091 success on d2fa474 → bot commit 566ff5e (ancestor of this head)
• 33283621847 success on 300dd5a
• 33282696234 success on 8457ee8e
• 33284500943 failure on 454c93e (no bot commit)
• 33281775686 failure on 3c273a7d

Post-merge / operator actions

• Backend rollout: draft DFXswiss/backend#5290 implements and tests the matching route and inviterName / inviteeName response; merge/deploy remains human-owned.
• Human: merge RealUnitCH/web#27 so production AASA / assetlinks / /invite/* are HTTP 200.
• Human: Play App Signing SHA-256 if it differs from GitHub APK 7F:8B:14:54:E2:91:E9:DB:56:21:69:0A:64:23:7C:34:80:78:C6:5B:B4:86:31:CA:02:9D:14:20:E6:3C:7B:40.
• Human: PRIZE_WALLET_KEY for settled 20 REALU transfers.

Related: RealUnitCH/intern#3 (do not auto-close).

[JonnyLuca]

Fixes RealUnitCH/intern#3

Branch rebased onto current staging and updated:

• Reduced overview: only open/credited counts plus total REALU with label Aktienkurs (no invitee status).
• Invite and promo App Links (/invite/*, /promo/*).
• DTO, service, cubit and sticky-CTA matrix tests.

Draft against staging. DFX server routes remain API-owned (DFXswiss/api is not reachable from this worker).

[JonnyLuca]

Fixes RealUnitCH/intern#3

Android now reads Play Install Referrer once per install (invite=<code> from the website Play URL) and stashes the code for post-unlock bind. iOS remains re-tap or manual entry.