96 lines
4.2 KiB
Markdown
96 lines
4.2 KiB
Markdown
|
# Portal – Development Roadmap (Step-by-Step)
|
|||
|
|
|
|||
|
|
This roadmap references `PORTAL-FLOW.md` (flows) and `PORTAL-DATA-MODEL.md` (objects/fields/mappings).
|
|||
|
|
|
|||
|
|
## Phase 1 – Foundations
|
|||
|
|
|
|||
|
|
1. Salesforce setup (Admin)
|
|||
|
|
- Product2 custom fields: create all `Portal_*` and `WHMCS_*` fields listed in DATA MODEL.
|
|||
|
|
- 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`.
|
|||
|
|
- Quick Action: “Provision in WHMCS” to call BFF; configure Named Credentials + HMAC headers.
|
|||
|
|
|
|||
|
|
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 IP allowlisting for Salesforce → BFF; implement HMAC shared secret.
|
|||
|
|
|
|||
|
|
## 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_Visible\_\_c & validity), price via PricebookEntry.
|
|||
|
|
- `GET /catalog/personalized`: filter Product2 using Account eligibility fields.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
- `POST /orders/:sfOrderId/provision`: SF-only; recheck payment method; (eSIM) activate; WHMCS AddOrder → AcceptOrder; update SF with IDs/status; send emails.
|
|||
|
|
|
|||
|
|
9. Salesforce: Quick Action/Flow
|
|||
|
|
- Implement button action to call BFF with Named Credentials + HMAC; pass Idempotency-Key.
|
|||
|
|
|
|||
|
|
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-Key for `POST /orders/:sfOrderId/provision`.
|
|||
|
|
- 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)
|
|||
|
|
- Quick Action wired and tested end-to-end
|
|||
|
|
- Emails tested in dev/staging
|
|||
|
|
- Monitoring and alerts configured
|