186 lines
9.2 KiB
Markdown
186 lines
9.2 KiB
Markdown
# 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.
|