ankhbayar/Assist_Design
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity
Assist_Design/docs/_archive/planning/portal-roadmap.md
barsa 7c929eb4dc Update Customer Portal Documentation and Remove Deprecated Files 
- Streamlined the README.md for clarity and conciseness.
- Deleted outdated documentation files related to Freebit SIM management, SIM management API data flow, and various architectural guides to reduce clutter and improve maintainability.
- Updated the last modified date in the README to reflect the latest changes.
2025-12-23 15:43:36 +09:00

4.6 KiB
Raw Blame History

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

  1. 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).

  2. 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

  1. 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.

  2. 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

  1. 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.

  2. Salesforce: Record-Triggered Flow

    • On Order status = Approved, publish OrderProvisionRequested__e with OrderId__c and optional IdemKey__c.

  3. 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

  1. 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.
  1. Email templates & jobs
  • Implement EmailService (SendGrid or SMTP) and queue jobs for: Signup Welcome, eSIM Activation, Order Provisioned.

Phase 6 – Observability & Hardening

  1. Observability
  • Add correlation IDs across BFF, Salesforce calls, WHMCS calls.
  • Metrics: provisioning latency, error rates, retries; alerts on anomalies.
  1. 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.
  1. 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