T. Narantuya 0bf872e249 Refactor code formatting and improve documentation clarity

- Adjusted YAML and JSON files for consistent formatting, including healthcheck commands and package exports.
- Enhanced readability in various TypeScript files by standardizing string quotes and improving line breaks.
- Updated documentation across multiple files to improve clarity and consistency, including address system and logging levels.
- Removed unnecessary package-lock.json from shared package directory to streamline dependencies.

2025-09-09 18:19:54 +09:00

2.9 KiB

Raw Blame History

Clean Salesforce-to-Portal Implementation Summary

✅ What Was Implemented

I've cleanly integrated secure Salesforce-to-Portal communication into your existing codebase:

1. Enhanced SalesforceService

Added: updateOrder() method for direct Salesforce Order updates
Added: getOrder() method for order validation
Integration: Works with your existing Salesforce connection

2. Event-Driven Provisioning

Added: Salesforce Platform Events subscriber (OrderProvisionRequested__e)
Added: BullMQ provisioning queue + processor
Behavior: Subscribes to SF, enqueues job, runs orchestrator, updates SF

3. Updated OrderOrchestrator

Added: provisionOrderFromSalesforce() method for the real provisioning flow
Integration: Uses your existing services and patterns
Features: Idempotency, error handling, direct Salesforce updates
Logging: Comprehensive audit trail without sensitive data

🔄 The Flow (Async)

1. Salesforce Flow sets `Activation_Status__c = Activating` and publishes OrderProvisionRequested__e on approval
2. Portal BFF subscribes → guards on `Activation_Status__c = Activating` → enqueues job → provisions in WHMCS → updates Salesforce Order
3. Customer polls Portal → Gets updated order status

🔒 Security Features

JWT auth to Salesforce (Connected App, private key JWT)
Platform Event permissions (Permission Set) for Platform Events
Idempotency keys (via event field IdemKey__c, safe retries)
Comprehensive logging (no sensitive data exposure)

📝 Next Steps

1. Salesforce Setup

Platform Event: OrderProvisionRequested__e (fields: OrderId__c [Text 18], IdemKey__c [Text 80, optional])
Permission Set: grant Platform Event permissions and PE object read to integration user
Flow (Record‑Triggered): On Order Status = Approved → Set `Activation_Status__c = Activating` → Create OrderProvisionRequested__e

2. Environment Variables

SF_EVENTS_ENABLED=true
SF_PROVISION_EVENT_CHANNEL=/event/OrderProvisionRequested__e
SF_EVENTS_REPLAY=LATEST

3. Complete the TODOs

In OrderOrchestrator.provisionOrderFromSalesforce():

Connect to your WHMCS service for payment validation
Add eSIM activation logic if needed
Implement actual WHMCS provisioning calls
Add email notifications

🎯 Key Benefits

✅ Clean integration with your existing architecture
✅ No inbound SF webhooks - event-driven, durable replay
✅ Production-ready security - JWT to Salesforce; event idempotency
✅ Proper error handling - updates Salesforce on failures
✅ Comprehensive logging - audit trail without sensitive data
✅ Simple customer experience - polling for status updates

This implementation follows your documentation exactly and integrates cleanly with your existing codebase patterns!

2.9 KiB Raw Blame History Unescape Escape