7c929eb4dc
- 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.
45 lines
2.5 KiB
Markdown
45 lines
2.5 KiB
Markdown
# Catalog & Checkout
|
||
|
||
Where product data comes from, what we validate, and how we keep it fresh.
|
||
|
||
## Product Source
|
||
|
||
- Products and pricing come from the Salesforce portal pricebook (`PORTAL_PRICEBOOK_ID`), not WHMCS.
|
||
- Categories covered: Internet, VPN, SIM/mobile. Each SKU is a Salesforce Product2 + PricebookEntry record.
|
||
- The portal pulls only products marked for the portal category; Salesforce is the source of truth for names, SKUs, and prices.
|
||
|
||
### SIM family plans
|
||
|
||
- If a user already has an active SIM service in WHMCS, we also show SIM family/discount plans.
|
||
- If they do not have a SIM yet, we hide family plans and show regular plans only.
|
||
|
||
## Eligibility & Validation
|
||
|
||
- Internet orders check account-specific eligibility stored in Salesforce; the eligibility result is cached per account and invalidated when Salesforce signals a change.
|
||
- During checkout we confirm:
|
||
- The user has a WHMCS client mapping and at least one payment method on file in WHMCS.
|
||
- SKUs selected exist in the Salesforce pricebook.
|
||
- For Internet orders, we block duplicates when WHMCS already shows an active Internet service (in production).
|
||
|
||
For the intended Salesforce-driven workflow model (Cases + Account fields + portal UX), see `docs/portal-guides/eligibility-and-verification.md`.
|
||
|
||
## Checkout Data Captured
|
||
|
||
- Address snapshot: we copy the customer’s address (or the one they update during checkout) into the Salesforce Order billing fields so the order shows the exact data used.
|
||
- Activation preferences: stored on the Salesforce Order (activation type/schedule, SIM specifics, MNP details when applicable).
|
||
- No card data is stored in the portal; we only verify that WHMCS already has a payment method.
|
||
|
||
## Caching for Catalog Calls
|
||
|
||
- Catalog data uses Salesforce Change Data Capture (CDC) events; there is no time-based expiry. When Salesforce signals a product change, the cache is cleared.
|
||
- Volatile catalog bits (e.g., fast-changing reference data) use a 60s TTL.
|
||
- Eligibility per account is cached with no TTL and cleared when Salesforce changes.
|
||
- Request coalescing is used so multiple users hitting the same catalog do not spam Salesforce.
|
||
|
||
## If something goes wrong
|
||
|
||
- Missing payment method: checkout is blocked with a clear “add a payment method” message.
|
||
- Ineligible address or duplicate Internet: we stop the order and explain why (eligibility failed or active Internet already exists).
|
||
- Salesforce pricebook issues: we return a friendly “catalog unavailable, please try again later.”
|
||
- Cache failures: we fall back to live Salesforce reads to avoid empty screens.
|