SRV-22 — Invitations & attribution module
Invitation codes, signed links and QR payloads, share texts, Play install-referrer attribution, funnel events up to the first order.
| Field | Details |
|---|---|
| Task code | SRV-22 |
| Phase | P1 — V1 build & integration |
| Product scope | V1 |
| Status | Done (Mon 19 Oct 2026) |
| Start | Mon 19 Oct 2026 |
| Due | Mon 19 Oct 2026 |
| Responsible | Anis — Full-stack developer |
| Co-responsible | — |
| Effort | 0.5 person-day(s) planned · 3 from scratch · size XS |
| Area · app | Server · server |
| Depends on | SRV-14 |
| Unblocks | — |
| Milestones | — |
Summary
Invitation codes, signed links and QR payloads, share texts, Play install-referrer attribution, funnel events up to the first order.
Description
Delegates convert prospects by inviting them to install the app; the cahier asks for a unique, secure link and QR code, sharing by WhatsApp/SMS/link and automatic tracking of activation steps up to the first order (§6.6, §12; IVT-01…IVT-04). This task implements Invitation codes (8 characters, uppercase, no ambiguous letters, displayed AB12-CD34, link https://app.hoco.dz/i/AB12CD34), QR payloads, localised share texts per ShareChannel, delegate.invitations.create/get/markShared, the public invitations.resolve and the landing GET /i/{code} that routes Android users to the Play Store with an install referrer, and other devices to the reseller web sign-up with the code prefilled, invitations.attribute fed by the Play Install Referrer, and InvitationEvent funnel steps (SENT → APP_INSTALLED → ACCOUNT_CREATED → PHONE_VERIFIED → CATALOG_VIEWED → FIRST_ORDER) updated from identity, catalog and order events. Out of scope: the web landing page design (WEB-01) and mobile referrer reading (Imad).
Subtasks
| # | Subtask | Owner |
|---|---|---|
| 1 | Code generator (8 chars from an unambiguous alphabet, collision retry) and Invitation model service with validity invitations.validityDays | Anis |
| 2 | delegate.invitations.create for a reseller/prospect (one active code per reseller, reuse), get, markShared with ShareChannel | Anis |
| 3 | Share texts fr/ar for WhatsApp and SMS with the link, and QR payload (the link) | Anis |
| 4 | Public invitations.resolve returning minimal data (inviter first name, store name prefill, validity) with anti-enumeration rate limit | Anis |
| 5 | Landing GET /i/{code}: user-agent routing to Play Store with referrer=code, otherwise reseller web sign-up with the code | Anis |
| 6 | invitations.attribute (public, idempotent): install referrer → APP_INSTALLED step and device link | Anis |
| 7 | Funnel consumers: account.created, phone verified, first catalog view, first order → InvitationEvent steps and reseller lifecycle updates | Anis |
| 8 | admin.invitations.list with funnel per delegate for reports | Anis |
| 9 | Play Install Referrer handling and deep-link opening of the code in the reseller app | Imad |
Deliverables
- apps/server/src/modules/invitations/{codes.ts,invitations.service.ts,landing.ts,attribution.ts,consumers.ts,router.ts}
- packages/contracts/src/{invitations.ts,delegate/invitations.ts}
- Share text templates in apps/server/src/modules/notifications/templates/invitations.*
Acceptance criteria
- Generated codes never contain 0, O, 1, I or L and are unique; display format is AB12-CD34 (IVT-01)
- Opening https://app.hoco.dz/i/AB12CD34 on Android redirects to the Play Store listing with the referrer; on desktop it opens the web sign-up with the code prefilled (IVT-04)
- A sign-up with the code attributes the reseller to the inviting delegate and records ACCOUNT_CREATED (IVT-03, IVT-04)
- The first order of an invited reseller records FIRST_ORDER on the funnel (IVT-03)
- More than 30 resolve calls per minute from one IP return 429 RATE_LIMITED
Requirements covered
| Requirement | Title | Release |
|---|---|---|
| IVT-01 | Unique, secure invitation link and QR code per reseller and delegate | V1 |
| IVT-02 | Share by WhatsApp, SMS or link; copyable referral code | V1 |
| IVT-03 | Activation steps updated automatically: app installed, account created, phone verified, catalog viewed, first order | V1 |
| IVT-04 | The link opens the right app or store and attributes the sign-up to the inviting delegate | V1 |
API surface
| Endpoint group | Operations |
|---|---|
| Invitations & attribution (public + reseller) | 3 |
| Prospects, points of sale, follow-ups & invitations | 13 |
Test measures
- Unit tests for the code alphabet, format and collision handling
- Integration test of the funnel from SENT to FIRST_ORDER through emitted events
- Manual check on an Android device: link → Play Store → install → referrer attributed (with Imad)
Risks
- Install referrer missing on some devices or sideloads — fallback: the sign-up form accepts the code manually and attribution then happens at ACCOUNT_CREATED
KPI
- Delivered by Mon 19 Oct 2026 within 0.5 person-day(s).
- Every acceptance criterion above demonstrated before hand-off; linked requirements' acceptance criteria pass.
- Zero open critical defects, permission gaps or data-integrity regressions at sign-off.
Generated from content/plan/tasks.json by scripts/generate-team-tasks.mjs. Dates are computed by the scheduler (Sunday–Thursday weeks, holidays excluded) — change the plan, not this page.
SRV-21 — Field operations module — objectives, tours, visits, reports
Objectives, tour planning and lifecycle, visits with GPS check-in tolerance, checklists, photos, structured reports that create follow-ups, location pings, closing summary/KPIs, recommended visit order.
SRV-23 — Offline sync — batch replay, delta pulls, idempotency
Idempotency records for every mutation, /sync/batch replay with per-item results and conflict codes, /sync/delta cursors for the delegate's offline scopes, occurredAt plausibility rules.