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
- **Silver Internet**: Customer configures access mode (IPoE-BYOR vs PPPoE), standard pricing
- **Gold Internet**: Customer selects tier only, premium pricing, shows operator review message
- **Platinum Internet**: Customer selects tier only, premium pricing + additional fees message:
  ```
  *IMPORTANT* For PLATINUM subscribers
  * Additional fees are incurred for the PLATINUM service. Please refer to the
    information from our tech team for details.
  * Will appear on the invoice as "Platinum Base Plan". Device subscriptions
    will be added later.
  ```
- **SIM**: Personalized catalog shows regular or family discount products based on existing services
- **VPN**: Customer selects region at order time

4. Checkout (create Order)

- **All Internet plans**: `POST /orders` → create Salesforce Order (Pending Review)
- **All plans**: OrderItem created with customer's selected product and its default WHMCS_Product_Id__c
- **Silver**: Customer selections saved (access mode, installment, etc.)
- **Gold/Platinum**: Customer tier selection saved, operator can modify WHMCS Product ID during review
- Portal shows "Awaiting review" for all orders

5. Review & Provision (operator)

- **Silver Orders**: Operator reviews customer configuration, approves as-is or makes adjustments
- **Gold/Platinum Orders**: Operator reviews customer location/requirements and may:
  - Change WHMCS Product ID on OrderItem if different product needed based on infrastructure
  - Set `Access_Mode__c` (IPoE-BYOR, IPoE-HGW, PPPoE) based on technical assessment
  - Add additional fees or services as needed
  - Update order with final configuration
- **Default behavior**: If no changes needed, order provisions with customer's selected product
- Operator 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 (uses WHMCS Product ID set by operator)
  - 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

## Simplified Internet Plan Process

### Overview
All Internet plans (Silver, Gold, Platinum) are separate products with manual operator review. No complex configuration flows needed.

### Process Flow

1. **Customer Selection**
   ```typescript
   POST /orders {
     orderType: "Internet",
     selections: {
       planTier: "Platinum",           // Customer choice
       installmentType: "24-month",    // Customer choice
       weekendInstall: true,           // Customer choice
       accessMode: null                // Silver: customer sets, Gold/Platinum: operator sets
     }
   }
   ```

2. **Order Creation (BFF)**
   - Creates Salesforce Order with `Status = "Pending Review"`
   - All customer selections saved to Order fields
   - OrderItem created with customer's selected product and its default `WHMCS_Product_Id__c`
   - Operator can change `WHMCS_Product_Id__c` during review if needed

3. **Operator Review**
   - **Silver**: Operator reviews customer configuration, approves or adjusts
   - **Gold/Platinum**: Operator reviews and may:
     - Change WHMCS Product ID if different product needed
     - Set `Access_Mode__c` based on technical assessment
     - Add additional services/fees as needed
   - **Default**: If no changes needed, uses customer's selected product

4. **Provision**
   - Operator clicks "Provision in WHMCS"
   - BFF uses WHMCS Product ID set by operator
   - Standard provisioning flow

### Status Progression
```
Draft → Pending Review → Approved → Provisioned
```

### Product Structure
```sql
-- All visible to customers with default WHMCS Product IDs
"Internet Silver Plan" → SKU: "INTERNET-SILVER" → WHMCS_Product_Id__c: 184
"Internet Gold Plan" → SKU: "INTERNET-GOLD" → WHMCS_Product_Id__c: 188 (default, operator can change)
"Internet Platinum Plan" → SKU: "INTERNET-PLATINUM" → WHMCS_Product_Id__c: 183 (default, operator can change)
```

## 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`

Salesforce prerequisites for Catalog:

- Enable Products and Price Books (Setup → Product Settings)
- Product2 required fields for portal queries: `SKU__c`, `Portal_Visible__c`, `Portal_Category__c`
- Ensure integration user has Read on `Product2` and field-level read access to those fields
- Create a `Portal` price book and ensure `PricebookEntry` exists for each visible product
- 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.