# 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/address` to update address fields.
   - Payment methods page/button: `POST /api/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