Assist_Design/docs/PORTAL-FLOW.md

# Portal Ordering & Provisioning – Flow

This document explains the end-to-end customer and operator flow, systems involved, and the request/response choreography. For data model and field-level details, see `PORTAL-DATA-MODEL.md`.

## Architecture at a Glance

- Salesforce: Product2 + PricebookEntry (catalog & eligibility), Order/OrderItem (review/trigger), reporting
- WHMCS: customer profile (authoritative), payment methods, invoices, subscriptions, provisioning
- Portal BFF: orchestration and ID mappings; centralized logging (dino)

## Customer Flow

1. Signup

- Inputs: email, confirm email, password, confirm password, first/last name, optional company/phone, Customer Number (SF Number)
- Actions: create portal user, create WHMCS client with Customer Number custom field, create mapping (userId ↔ whmcsClientId ↔ sfAccountId)
- Email: Welcome (customer, CC support)

2. Add payment method (required)

- UI: CTA opens WHMCS payment methods via SSO
- API: BFF checks hasPaymentMethod via WHMCS GetPayMethods; gate checkout until true

3. Browse catalog and configure

- BFF serves Product2 catalog (portal-visible only), with personalization for Internet based on Account eligibility fields
- Product detail collects configurable options

4. Checkout (create Order)

- BFF: `POST /orders` → create Salesforce Order (Pending Review) + OrderItems (snapshots: Quantity, UnitPrice, Billing_Cycle, optional ConfigOptions)
- Portal shows “Awaiting review”

5. Review & Provision (operator)

- Operator approves in Salesforce and clicks “Provision in WHMCS” (Quick Action)
- Salesforce calls BFF `POST /orders/{sfOrderId}/provision` (signed & idempotent)
- BFF:
  - Re-check hasPaymentMethod in WHMCS; if missing, set SF status Failed (Payment Required)
  - eSIM: activate if applicable
  - WHMCS: AddOrder → AcceptOrder
  - Update Salesforce Order with WHMCS IDs and status (Provisioned or Failed)
  - Emails: Activation/Provisioned

5a) Immediate vs Scheduled activation (eSIM example)

- Ops selects Activation Type on the Order:
  - Immediate: BFF runs activation and WHMCS order right after approval.
  - Scheduled: set Activation_Scheduled_At\_\_c; BFF runs at that time.
- BFF enqueues delayed jobs:
  - Preflight (e.g., T-3 days): verify WHMCS payment method; notify if missing.
  - Execute (at scheduled date): set Activation status → Activating; run eSIM activation; on success run WHMCS AddOrder → AcceptOrder; write back IDs and set Activation → Activated; on error set Activation → Failed and log error fields.
- Manual override “Activate Now” can trigger the same execute path immediately.

Scheduling options

- Option A: Salesforce Flow (no portal job)
  - Record-Triggered Flow on Order with a Scheduled Path at `Activation_Scheduled_At__c` when `Status = Approved`, `Activation_Type__c = Scheduled`, `Activation_Status__c = Not Started`.
  - Action: Flow HTTP Callout (Named Credential) → `POST /orders/{sfOrderId}/provision` with headers `Idempotency-Key`, `X-Timestamp`, `X-Nonce`.
  - Alternative: Scheduled-Triggered Flow (every 15m) querying due Orders (NOW() ≥ Activation_Scheduled_At\_\_c) and invoking the same callout.
- Option B: Portal BFF delayed jobs (BullMQ)
  - Use when you want retry/backoff control and consolidated observability in BFF.

Status interaction (business vs technical)

- Order Status: Pending Review → Approved → (Completed/Cancelled).
- Activation Status: Not Started → Activating → Activated/Failed.
- UI: Show Activation fields only when Order Status is Approved/Completed.

6. Completion

- Subscriptions and invoices show in portal from WHMCS via BFF endpoints
- Order status in portal reflects Salesforce status

## API Surface (BFF)

- Auth: `POST /auth/signup` (requires `sfNumber` = Customer Number)
- Billing: `GET /billing/payment-methods/summary`, `POST /auth/sso-link`
- Catalog: `GET /catalog`, `GET /catalog/personalized`
- Orders: `POST /orders`, `GET /orders/:sfOrderId`, `POST /orders/:sfOrderId/provision`
- eSIM actions: `POST /subscriptions/:id/reissue-esim`, `POST /subscriptions/:id/topup`

## Security & Reliability

- Salesforce → BFF: Named Credentials + HMAC headers; IP allowlisting; 5m TTL; Idempotency-Key
- WHMCS: timeouts, retries, circuit breakers; redact sensitive data in logs
- Idempotency: checkout keyed by cart hash; provisioning keyed by Idempotency-Key; include `sfOrderId` in WHMCS notes
- Observability: correlation IDs, metrics, alerts on failures/latency

## Business Rules

- Home Internet: billing address equals service address.
  - Capture once after signup and save to WHMCS; at checkout only verify.
  - Snapshot the same address onto the Salesforce Order (Bill To). No separate service address UI.

- Single Internet per account: disallow a second Home Internet order.
  - Backend: `POST /orders` checks WHMCS client services (active/pending/suspended) for Internet; if present, return 409 and a manage link.
  - Frontend: hide/disable Internet products when such a service exists; show “Manage/Upgrade” CTA.
  - Salesforce (optional): validation/Flow to prevent Internet lines when the account already has an Internet service.

- One service per Order (1:1 with Opportunity)
- Cart is split so each selected service becomes its own Salesforce Order containing exactly one OrderItem.
- Each Order links to exactly one `Opportunity` (1 opportunity represents 1 service).
- Activation fields (`Activation_Type__c`, `Activation_Scheduled_At__c`, `Activation_Status__c`) apply to that single service.
- Result: for two eSIMs (even same date), we create two Orders, two Opportunities, two WHMCS Orders/Invoices/Services.