111bbc8c91
- Introduced email configuration for both development and production environments in `.env.dev.example` and `.env.production.example`. - Added SendGrid API key and email settings to support password reset and welcome emails. - Implemented password reset and request password reset endpoints in the AuthController. - Enhanced signup form to include additional fields such as Customer Number, address, nationality, date of birth, and gender. - Updated various services and controllers to integrate email functionality and handle new user data. - Refactored logging and error handling for improved clarity and maintainability. - Adjusted Docker configuration for production deployment.
106 lines
5.5 KiB
Markdown
106 lines
5.5 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
|
||
- 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.
|