f305ee6e1a
- Added support for Salesforce Platform Events, specifically subscribing to `OrderProvisionRequested__e` to trigger provisioning jobs. - Introduced new environment variables for Salesforce event configuration, including SF_EVENTS_ENABLED, SF_PROVISION_EVENT_CHANNEL, and SF_PUBSUB_ENDPOINT. - Refactored order fulfillment process to utilize event-driven architecture, enhancing reliability and scalability. - Updated documentation to reflect changes in the provisioning workflow and environment variable requirements. - Removed deprecated webhook handling code to streamline the integration.
97 lines
4.6 KiB
Markdown
97 lines
4.6 KiB
Markdown
# Portal – Development Roadmap (Step-by-Step)
|
||
|
||
This roadmap references `PORTAL-ORDERING-PROVISIONING.md` (complete flows and architecture) and `PORTAL-DATA-MODEL.md` (objects/fields/mappings).
|
||
|
||
## Phase 1 – Foundations
|
||
|
||
1. Salesforce setup (Admin)
|
||
- Product2 custom fields: create all fields listed in `SALESFORCE-PRODUCTS.md` (core fields: `StockKeepingUnit`, `Product2Categories1__c`, `Portal_Catalog__c`, `Portal_Accessible__c`, `Item_Class__c`, plus service-specific fields)
|
||
- Pricebook: create "Portal" pricebook; add `PricebookEntry` records for visible Product2 items
|
||
- Order fields: add `Provisioning_*`, `WHMCS_*`, `ESIM_ICCID__c`, `Attempt_Count__c`, `Last_Provisioning_At__c`
|
||
- OrderItem fields: add `Billing_Cycle__c`, `ConfigOptions_JSON__c`, `WHMCS_Service_ID__c`
|
||
- Platform Event: `OrderProvisionRequested__e`; Flow publishes on Order approval
|
||
|
||
2. WHMCS setup (Admin)
|
||
- Create custom field on Client for Customer Number (note id/name).
|
||
- Confirm product IDs for Internet/eSIM/VPN and required config options.
|
||
- Confirm gateway system name for `paymentmethod`.
|
||
|
||
3. Portal BFF env & security
|
||
- Ensure env vars for Salesforce/WHMCS and logging are set; rotate secrets.
|
||
- Enable Platform Events subscriber (`SF_EVENTS_ENABLED=true`); no inbound SF allowlisting required.
|
||
|
||
## Phase 2 – Identity & Billing
|
||
|
||
4. BFF: Signup requires SF Number
|
||
- Update `SignupDto` to require `sfNumber`.
|
||
- Flow: create portal user → create WHMCS User + Client → set Customer Number custom field → create mapping (userId, whmcsClientId, sfAccountId).
|
||
- On email discrepancy with Salesforce Account: create Salesforce Case (no block).
|
||
- Send Welcome email (EmailService via jobs).
|
||
|
||
5. Portal UI: Address & payment method
|
||
- Address step after signup; `PATCH /api/me/billing` to update WHMCS address fields.
|
||
- Payment methods page/button: `POST /auth/sso-link` to WHMCS payment methods; show banner on dashboard until `GET /billing/payment-methods/summary` is true.
|
||
|
||
## Phase 3 – Catalog
|
||
|
||
6. BFF: Catalog endpoints
|
||
- `GET /catalog`: read Product2 (Portal_Catalog__c & validity), price via PricebookEntry
|
||
- `GET /catalog/personalized`: filter Product2 using Account eligibility fields
|
||
- Additional endpoints: `/catalog/sim/activation-fees`, `/catalog/vpn/activation-fees`, `/catalog/sim/addons`, etc.
|
||
|
||
7. Portal UI: Catalog & product detail
|
||
- Build `/catalog` listing; product detail pages for Internet/eSIM/VPN.
|
||
- Support configurable options via Product2 `Portal_ConfigOptions_JSON__c`.
|
||
|
||
## Phase 4 – Orders & Provisioning
|
||
|
||
8. BFF: Orders API
|
||
- `POST /orders`: create SF Order + OrderItems (snapshots: Quantity, UnitPrice, Billing_Cycle, ConfigOptions), status Pending Review; return `sfOrderId`.
|
||
- `GET /orders/:sfOrderId`: return orchestration status.
|
||
- Async Provisioning: triggered by Platform Event `OrderProvisionRequested__e`; worker rechecks payment method; (eSIM) activate; WHMCS AddOrder → AcceptOrder; update SF with IDs/status; send emails.
|
||
|
||
9. Salesforce: Record-Triggered Flow
|
||
- On Order status = Approved, publish `OrderProvisionRequested__e` with `OrderId__c` and optional `IdemKey__c`.
|
||
|
||
10. Portal UI: Checkout & status
|
||
|
||
- Build checkout button gating on `hasPaymentMethod`; after order, show status page that polls `GET /orders/:sfOrderId`.
|
||
|
||
## Phase 5 – eSIM Extras & Emails
|
||
|
||
11. BFF: eSIM actions
|
||
|
||
- `POST /subscriptions/:id/reissue-esim`: call provider API; update WHMCS service notes/custom fields; email customer.
|
||
- `POST /subscriptions/:id/topup`: call provider API; create add-on or invoice in WHMCS; email customer.
|
||
|
||
12. Email templates & jobs
|
||
|
||
- Implement EmailService (SendGrid or SMTP) and queue jobs for: Signup Welcome, eSIM Activation, Order Provisioned.
|
||
|
||
## Phase 6 – Observability & Hardening
|
||
|
||
13. Observability
|
||
|
||
- Add correlation IDs across BFF, Salesforce calls, WHMCS calls.
|
||
- Metrics: provisioning latency, error rates, retries; alerts on anomalies.
|
||
|
||
14. Idempotency & resilience
|
||
|
||
- Cart hash idempotency for `POST /orders`.
|
||
- Idempotency on Platform Event (`IdemKey__c`); dedupe in worker.
|
||
- Include `sfOrderId` in WHMCS `notes` for duplicate protection.
|
||
|
||
15. Security reviews
|
||
|
||
- Confirm no PAN/PII leakage in logs; confirm TLS and secrets; rate limits on auth endpoints.
|
||
|
||
## Deliverables Checklist
|
||
|
||
- Salesforce fields created and secured (FLS/profiles)
|
||
- WHMCS Client custom field created; product IDs confirmed
|
||
- BFF endpoints implemented (auth/billing/catalog/orders/esim)
|
||
- Portal pages implemented (signup/address/catalog/detail/checkout/status)
|
||
- Platform Event Flow wired and tested end-to-end
|
||
- Emails tested in dev/staging
|
||
- Monitoring and alerts configured
|