Assist_Design/docs/portal-guides/eligibility-and-verification.md

Eligibility & Verification (Salesforce-Driven)

This guide describes the intended “Salesforce is the source of truth” model for:

• Internet eligibility (address/serviceability review)
• SIM ID verification (residence card / identity document)

It also explains how these checks gate checkout and where the portal should display their status.

Goals

• Make eligibility/verification account-level so repeat orders are frictionless.
• Use Salesforce workflow + audit trail (Cases + Account fields + Files) instead of portal-only tables.
• Keep checkout clean: show one canonical status and a single next action.

Concepts & Ownership

Concept	Source of truth	Why
Products + pricing	Salesforce pricebook	Single catalog truth
Payment methods	WHMCS	No card storage in portal
Orders + fulfillment	Salesforce Order (and downstream WHMCS)	Operational workflow
Internet eligibility status	Salesforce Account (with Case for workflow)	Reuse for future internet orders
SIM ID verification status	Salesforce Account (with Files)	Reuse for future SIM orders

Internet Eligibility (Address Review)

Target UX

• On /account/shop/internet:
  • Show current eligibility status (e.g. “Checking”, “Eligible for …”, “Not available”, “Action needed”).
  • If not requested yet: show a single CTA (“Request eligibility review”).
• In checkout (Internet orders):
  • If eligibility is PENDING/REQUIRED, the submit CTA is disabled and we guide the user to the next action.
  • If ELIGIBLE, proceed normally.

Target Salesforce Model

Account fields (canonical, cached by portal):

• InternetEligibilityStatus__c (picklist)
  • Suggested values:
    • REQUIRED (no check requested / missing address)
    • PENDING (case open, awaiting review)
    • ELIGIBLE (approved)
    • INELIGIBLE (rejected)
• InternetEligibilityResult__c (text/picklist; optional)
  • Example: Home, Apartment, or a more structured code that maps to portal offerings.
• InternetEligibilityCheckedAt__c (datetime; optional)
• InternetEligibilityNotes__c (long text; optional)

Case (workflow + audit trail):

• Record type: “Internet Eligibility”
• Fields populated from portal:
  • Account, contact, service address snapshot, desired product (SKU), notes
• SLA/review handled by internal team; a Flow/Trigger updates Account fields above.

Portal/BFF Flow (proposed)

1. Portal calls POST /api/eligibility/internet/request (or reuse existing hook behavior).
2. BFF validates:
   • account has a service address (or includes the address in request)
   • throttling/rate limits
3. BFF creates Salesforce Case and sets InternetEligibilityStatus__c = PENDING.
4. Portal reads GET /api/eligibility/internet and shows:
   • PENDING → “Review in progress”
   • ELIGIBLE → “Eligible for …”
   • INELIGIBLE → “Not available” + next steps (support/contact)
5. When Salesforce updates the Account fields:
   • Portal cache invalidates via CDC/eventing (preferred), or via polling fallback.

Recommended status → UI mapping

Status	Shop page	Checkout gating
REQUIRED	Show “Add/confirm address” then “Request review”	Block submit
PENDING	Show “Review in progress”	Block submit
ELIGIBLE	Show “Eligible for: …”	Allow submit
INELIGIBLE	Show “Not available” + support CTA	Block submit

SIM ID Verification (Residence Card / Identity Document)

Target UX

• In SIM checkout (and any future SIM order flow):
  • If status is VERIFIED: show “Verified” and no upload/change UI.
  • If SUBMITTED: show what was submitted (filename + submitted time) and optionally allow “Replace file”.
  • If REQUIRED: require upload before order submission.
• In order detail pages:
  • Show a simple “ID verification: Required / Submitted / Verified” row.

Target Salesforce Model

Account fields (canonical):

• IdVerificationStatus__c (picklist)
  • Suggested values (3-state):
    • REQUIRED
    • SUBMITTED
    • VERIFIED
• IdVerificationSubmittedAt__c (datetime; optional)
• IdVerificationVerifiedAt__c (datetime; optional)
• IdVerificationNotes__c (long text; optional)

Files (document storage):

• Upload as Salesforce Files (ContentVersion)
• Link to Account (ContentDocumentLink)
• Optionally keep a reference field on Account (e.g. IdVerificationContentDocumentId__c) for fast lookup.

Portal/BFF Flow (proposed)

1. Portal calls GET /api/verification/id to read the Account’s canonical status.
2. If user uploads a file:
   • Portal calls POST /api/verification/id with multipart file.
   • BFF uploads File to Salesforce Account and sets:
     • IdVerificationStatus__c = SUBMITTED
     • IdVerificationSubmittedAt__c = now()
3. Internal review updates status to VERIFIED (and sets verified timestamp/notes).
4. Portal displays:
   • VERIFIED → no edit, no upload
   • SUBMITTED → show file metadata + optional replace
   • REQUIRED → upload required before SIM activation

Gating rules (SIM checkout)

Status	Can submit order?	What portal shows
REQUIRED	No	Upload required
SUBMITTED	Yes	Submitted summary + (optional) replace
VERIFIED	Yes	Verified badge only

Where to show status (recommended)

• Shop pages
  • Internet: eligibility banner/status on /account/shop/internet
  • SIM: verification requirement banner/status on /account/shop/sim (optional)
• Checkout
  • Show the relevant status inline in the “Checkout requirements” section.
• Orders
  • Show “Eligibility / ID verification” status on the order detail page so users can track progress after submitting.
• Dashboard
  • Task tiles like “Internet availability review in progress” or “Submit ID to activate SIM”.

Notes on transitioning from current implementation

Current portal code uses a portal-side residence_card_submissions table for the uploaded file and status. The target model moves canonical status to Salesforce Account fields and stores the file in Salesforce Files.

Recommended migration approach:

1. Add Salesforce Account fields for eligibility and ID verification.
2. Dual-write (temporary): when portal receives an upload, store in both DB and Salesforce.
3. Switch reads to Salesforce status.
4. Backfill existing DB submissions into Salesforce Files.
5. Remove DB storage once operationally safe.