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/Not Requested, 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):

• Internet Eligibility Status (picklist)
  • Suggested values:
    • Not Requested (no check requested yet; address may be missing or unconfirmed)
    • Pending (case open, awaiting review)
    • Eligible (approved)
    • Ineligible (rejected)
• Internet Eligibility (text/picklist; optional result)
  • Example: Home, Apartment, or a more structured code that maps to portal offerings.
• Recommended supporting fields (optional but strongly recommended):
  • Internet Eligibility Request Date Time (datetime)
    • Set by the portal/BFF when the customer requests an eligibility check.
    • Useful for UX (“Requested on …”) and for internal SLAs/reporting.
  • Internet Eligibility Checked Date Time (datetime)
    • Updated by Salesforce automation when the review completes (approved or rejected).
  • Internet Eligibility_Notes (long text)
  • Internet Eligibility_Case_Id (text / lookup, if you want fast linking to the case from the portal)

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 Internet Eligibility Status = Pending.
   • Also sets Internet Eligibility Request Date Time = now() (first request timestamp).
4. Portal reads GET /api/eligibility/internet and shows:
   • Pending → “Review in progress”
   • Eligible → “Eligible for: {Internet Eligibility}”
   • 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
Not Requested	Show “Add/confirm address” then “Request review”	Block submit
Pending	Show “Review in progress”	Block submit
Eligible	Show “Eligible for: {Internet Eligibility}”	Allow submit
INEligible	Show “Not available” + support CTA	Block submit

Notes on “Not Requested” vs “Pending”

• Use Not Requested when the customer has never requested a check (or their address is missing).
• Use Pending immediately after creating the Salesforce Case.
• The portal should treat both as “blocked for ordering” but with different next actions:
  • Not Requested: show CTA to request review (and/or prompt to add address).
  • Pending: show status only (no repeated CTA spam), plus optional “View case” link if you expose it.

Recommended UI details:

• If Internet Eligibility Request Date Time is present, show “Requested on {date}”.
• If Internet Eligibility Checked Date Time is present, show “Last checked on {date}”.

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 Not Submitted: require upload before order submission.
  • If Rejected: show rejection message and require resubmission.
• In order detail pages:
  • Show a simple “ID verification: Not submitted / Submitted / Verified” row.

Target Salesforce Model

Account fields (canonical):

• Id Verification Status (picklist)
  • Values:
    • Not Submitted
    • Submitted
    • Verified
    • Rejected
• Id Verification Submitted Date Time (datetime; optional)
• Id Verification Verified Date Time (datetime; optional)
• Id Verification Note (long text; optional)
• Id Verification Rejection Message (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:
     • Id Verification Status = Submitted
     • Id Verification Submitted Date Time = 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
   • Not Submitted → upload required before SIM activation
   • Rejected → show rejection message and require resubmission

Order-first review model (recommended)

For operational convenience, it can be better to review ID from the specific SIM order, then roll that result up to the Account so future SIM orders are frictionless.

How it works:

1. Customer uploads the ID document during SIM checkout.
2. BFF attaches the file to the Salesforce Order (or an Order-related Case) as the review target.
3. BFF sets Account Id Verification Status = Submitted immediately (so the portal can show progress).
4. A Salesforce Flow (or automation) is triggered when the order’s “ID review” is approved:
   • sets Account Id Verification Status = Verified
   • sets Id Verification Verified Date Time
   • links (or copies) the approved File to the Account (so it’s “on file” for future orders)
   • optionally writes a note to Id Verification Note

Portal implications:

• Current order detail page can show: “ID verification: Submitted/Verified” sourced from the Account, plus (optionally) a link to the specific file attached to the Order.
• SIM checkout becomes very simple:
  • Not Submitted: upload required
  • Submitted: allow order submission, show “Submitted”
  • Verified: no upload UI, no “change” UI

Rejections + resubmission (recommended UX)

Even if you keep a 3-state Account field, the portal can still display “rejected” as a derived UI state using notes/timestamps.

Recommended approach:

• Use Id Verification Note and Id Verification Rejection Message for reviewer feedback.
• When a document is not acceptable, set:
  • Id Verification Status = Rejected (so the portal blocks future SIM submissions until a new file is provided)
  • Id Verification Rejection Message = rejection reason (“image too blurry”, “expired”, etc.)

Portal UI behavior:

• If Id Verification Status = Rejected and Id Verification Rejection Message is non-empty:
  • show “ID verification rejected” + “Rejection note”
  • show an “Id Verification Rejection Message” block that tells the customer what to do next
    • Example content:
      • “Your ID verification was rejected. Please upload a new, clear photo/scan of your residence card.”
      • “Make sure all corners are visible, the text is readable, and the document is not expired.”
      • “After you resubmit, review will restart.”
• When the user uploads again:
  • overwrite the prior file (or create a new version) and set status back to Submitted
  • clear/replace the notes so the UI doesn’t keep showing stale rejection reasons

Gating rules (SIM checkout)

Status	Can submit order?	What portal shows
Not Submitted	No	Upload required
Submitted	Yes	Submitted summary + (optional) replace
Verified	Yes	Verified badge only
Rejected	No	Rejection message + resubmission required

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 near the confirm/requirements cards.
• 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.