305 lines
10 KiB
Markdown
305 lines
10 KiB
Markdown
|
# Freebit SIM Management - Implementation Guide
|
||
|
|
|
||
|
|
*Complete implementation of Freebit SIM management functionality for the Customer Portal.*
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
This document outlines the complete implementation of Freebit SIM management features, including backend API integration, frontend UI components, and Salesforce data tracking requirements.
|
||
|
|
|
||
|
|
## 🏗️ Implementation Summary
|
||
|
|
|
||
|
|
### ✅ Completed Features
|
||
|
|
|
||
|
|
1. **Backend (BFF) Integration**
|
||
|
|
- Freebit API service with all endpoints
|
||
|
|
- SIM management service layer
|
||
|
|
- REST API endpoints for portal consumption
|
||
|
|
- Authentication and error handling
|
||
|
|
|
||
|
|
2. **Frontend (Portal) Components**
|
||
|
|
- SIM details card with status and information
|
||
|
|
- Data usage chart with visual progress tracking
|
||
|
|
- SIM management actions (top-up, cancel, reissue)
|
||
|
|
- Interactive top-up modal with presets and scheduling
|
||
|
|
- Integrated into subscription detail page
|
||
|
|
|
||
|
|
3. **Features Implemented**
|
||
|
|
- View SIM details (ICCID, MSISDN, plan, status)
|
||
|
|
- Real-time data usage monitoring
|
||
|
|
- Data quota top-up (immediate and scheduled)
|
||
|
|
- eSIM profile reissue
|
||
|
|
- SIM service cancellation
|
||
|
|
- Plan change functionality
|
||
|
|
- Usage history tracking
|
||
|
|
|
||
|
|
## 🔧 API Endpoints
|
||
|
|
|
||
|
|
### Backend (BFF) Endpoints
|
||
|
|
|
||
|
|
All endpoints are prefixed with `/api/subscriptions/{id}/sim/`
|
||
|
|
|
||
|
|
- `GET /` - Get comprehensive SIM info (details + usage)
|
||
|
|
- `GET /details` - Get SIM details only
|
||
|
|
- `GET /usage` - Get data usage information
|
||
|
|
- `GET /top-up-history?fromDate=&toDate=` - Get top-up history
|
||
|
|
- `POST /top-up` - Add data quota
|
||
|
|
- `POST /change-plan` - Change SIM plan
|
||
|
|
- `POST /cancel` - Cancel SIM service
|
||
|
|
- `POST /reissue-esim` - Reissue eSIM profile (eSIM only)
|
||
|
|
|
||
|
|
### Freebit API Integration
|
||
|
|
|
||
|
|
**Implemented Freebit APIs:**
|
||
|
|
- PA01-01: OEM Authentication (`/authOem/`)
|
||
|
|
- PA03-02: Get Account Details (`/mvno/getDetail/`)
|
||
|
|
- PA04-04: Add Specs & Quota (`/master/addSpec/`)
|
||
|
|
- PA05-0: MVNO Communication Information Retrieval (`/mvno/getTrafficInfo/`)
|
||
|
|
- PA05-02: MVNO Quota Addition History (`/mvno/getQuotaHistory/`)
|
||
|
|
- PA05-04: MVNO Plan Cancellation (`/mvno/releasePlan/`)
|
||
|
|
- PA05-21: MVNO Plan Change (`/mvno/changePlan/`)
|
||
|
|
- PA05-22: MVNO Quota Settings (`/mvno/eachQuota/`)
|
||
|
|
- PA05-42: eSIM Profile Reissue (`/esim/reissueProfile/`)
|
||
|
|
- **Enhanced**: eSIM Add Account/Reissue (`/mvno/esim/addAcnt/`) - Based on Salesforce implementation
|
||
|
|
|
||
|
|
**Note**: The implementation includes both the simple reissue endpoint and the enhanced addAcnt method for more complex eSIM reissue scenarios, matching your existing Salesforce integration patterns.
|
||
|
|
|
||
|
|
## 🎨 Frontend Components
|
||
|
|
|
||
|
|
### Component Structure
|
||
|
|
```
|
||
|
|
apps/portal/src/features/sim-management/
|
||
|
|
├── components/
|
||
|
|
│ ├── SimManagementSection.tsx # Main container component
|
||
|
|
│ ├── SimDetailsCard.tsx # SIM information display
|
||
|
|
│ ├── DataUsageChart.tsx # Usage visualization
|
||
|
|
│ ├── SimActions.tsx # Action buttons and confirmations
|
||
|
|
│ └── TopUpModal.tsx # Data top-up interface
|
||
|
|
└── index.ts # Exports
|
||
|
|
```
|
||
|
|
|
||
|
|
### Features
|
||
|
|
- **Responsive Design**: Works on desktop and mobile
|
||
|
|
- **Real-time Updates**: Automatic refresh after actions
|
||
|
|
- **Visual Feedback**: Progress bars, status indicators, loading states
|
||
|
|
- **Error Handling**: Comprehensive error messages and recovery
|
||
|
|
- **Accessibility**: Proper ARIA labels and keyboard navigation
|
||
|
|
|
||
|
|
## 🗄️ Required Salesforce Custom Fields
|
||
|
|
|
||
|
|
To enable proper SIM data tracking in Salesforce, add these custom fields:
|
||
|
|
|
||
|
|
### On Service/Product Object
|
||
|
|
|
||
|
|
```sql
|
||
|
|
-- Core SIM Identifiers
|
||
|
|
Freebit_Account__c (Text, 15) - Freebit account identifier (phone number)
|
||
|
|
Freebit_MSISDN__c (Text, 15) - Phone number/MSISDN
|
||
|
|
Freebit_ICCID__c (Text, 22) - SIM card identifier (physical SIMs)
|
||
|
|
Freebit_EID__c (Text, 32) - eSIM identifier (eSIMs only)
|
||
|
|
Freebit_IMSI__c (Text, 15) - International Mobile Subscriber Identity
|
||
|
|
|
||
|
|
-- Service Information
|
||
|
|
Freebit_Plan_Code__c (Text, 20) - Current Freebit plan code
|
||
|
|
Freebit_Status__c (Picklist) - active, suspended, cancelled, pending
|
||
|
|
Freebit_SIM_Type__c (Picklist) - physical, esim
|
||
|
|
Freebit_SIM_Size__c (Picklist) - standard, nano, micro, esim
|
||
|
|
|
||
|
|
-- Service Features
|
||
|
|
Freebit_Has_Voice__c (Checkbox) - Voice service enabled
|
||
|
|
Freebit_Has_SMS__c (Checkbox) - SMS service enabled
|
||
|
|
Freebit_IPv4__c (Text, 15) - Assigned IPv4 address
|
||
|
|
Freebit_IPv6__c (Text, 39) - Assigned IPv6 address
|
||
|
|
|
||
|
|
-- Data Tracking
|
||
|
|
Freebit_Remaining_Quota_KB__c (Number) - Current remaining data in KB
|
||
|
|
Freebit_Remaining_Quota_MB__c (Formula) - Freebit_Remaining_Quota_KB__c / 1024
|
||
|
|
Freebit_Last_Usage_Sync__c (DateTime) - Last usage data sync
|
||
|
|
Freebit_Is_Blacklisted__c (Checkbox) - Service restriction status
|
||
|
|
|
||
|
|
-- Service Dates
|
||
|
|
Freebit_Service_Start__c (Date) - Service activation date
|
||
|
|
Freebit_Last_Sync__c (DateTime) - Last sync with Freebit API
|
||
|
|
|
||
|
|
-- Pending Operations
|
||
|
|
Freebit_Pending_Operation__c (Text, 50) - Scheduled operation type
|
||
|
|
Freebit_Operation_Date__c (Date) - Scheduled operation date
|
||
|
|
```
|
||
|
|
|
||
|
|
### Optional: Dedicated SIM Management Object
|
||
|
|
|
||
|
|
For detailed tracking, create a custom object `SIM_Management__c`:
|
||
|
|
|
||
|
|
```sql
|
||
|
|
SIM_Management__c
|
||
|
|
├── Service__c (Lookup to Service) - Related service record
|
||
|
|
├── Freebit_Account__c (Text, 15) - Freebit account identifier
|
||
|
|
├── Action_Type__c (Picklist) - topup, cancel, reissue, plan_change
|
||
|
|
├── Action_Date__c (DateTime) - When action was performed
|
||
|
|
├── Amount_MB__c (Number) - Data amount (for top-ups)
|
||
|
|
├── Previous_Plan__c (Text, 20) - Previous plan (for plan changes)
|
||
|
|
├── New_Plan__c (Text, 20) - New plan (for plan changes)
|
||
|
|
├── Status__c (Picklist) - success, failed, pending
|
||
|
|
├── Error_Message__c (Long Text) - Error details if failed
|
||
|
|
├── Scheduled_Date__c (Date) - For scheduled operations
|
||
|
|
├── Campaign_Code__c (Text, 20) - Campaign code used
|
||
|
|
└── Notes__c (Long Text) - Additional notes
|
||
|
|
```
|
||
|
|
|
||
|
|
## 🚀 Deployment Configuration
|
||
|
|
|
||
|
|
### Environment Variables (BFF)
|
||
|
|
|
||
|
|
Add these to your `.env` file:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Freebit API Configuration
|
||
|
|
# Production URL
|
||
|
|
FREEBIT_BASE_URL=https://i1.mvno.net/emptool/api
|
||
|
|
# Test URL (for development/testing)
|
||
|
|
# FREEBIT_BASE_URL=https://i1-q.mvno.net/emptool/api
|
||
|
|
|
||
|
|
FREEBIT_OEM_ID=PASI
|
||
|
|
FREEBIT_OEM_KEY=your_32_char_oem_key_from_freebit
|
||
|
|
FREEBIT_TIMEOUT=30000
|
||
|
|
FREEBIT_RETRY_ATTEMPTS=3
|
||
|
|
```
|
||
|
|
|
||
|
|
### Module Registration
|
||
|
|
|
||
|
|
Ensure the Freebit module is imported in your main app module:
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
// apps/bff/src/app.module.ts
|
||
|
|
import { FreebititModule } from './vendors/freebit/freebit.module';
|
||
|
|
|
||
|
|
@Module({
|
||
|
|
imports: [
|
||
|
|
// ... other modules
|
||
|
|
FreebititModule,
|
||
|
|
],
|
||
|
|
})
|
||
|
|
export class AppModule {}
|
||
|
|
```
|
||
|
|
|
||
|
|
## 🧪 Testing
|
||
|
|
|
||
|
|
### Backend Testing
|
||
|
|
```bash
|
||
|
|
# Test Freebit API connectivity
|
||
|
|
curl -X POST http://localhost:3001/api/subscriptions/{id}/sim/details \
|
||
|
|
-H "Authorization: Bearer {token}"
|
||
|
|
|
||
|
|
# Test data top-up
|
||
|
|
curl -X POST http://localhost:3001/api/subscriptions/{id}/sim/top-up \
|
||
|
|
-H "Content-Type: application/json" \
|
||
|
|
-H "Authorization: Bearer {token}" \
|
||
|
|
-d '{"quotaMb": 1024}'
|
||
|
|
```
|
||
|
|
|
||
|
|
### Frontend Testing
|
||
|
|
1. Navigate to a SIM subscription detail page
|
||
|
|
2. Verify SIM management section appears
|
||
|
|
3. Test top-up modal with different amounts
|
||
|
|
4. Test eSIM reissue (if applicable)
|
||
|
|
5. Verify error handling with invalid inputs
|
||
|
|
|
||
|
|
## 🔒 Security Considerations
|
||
|
|
|
||
|
|
1. **API Authentication**: Freebit auth keys are securely cached and refreshed
|
||
|
|
2. **Input Validation**: All user inputs are validated on both frontend and backend
|
||
|
|
3. **Rate Limiting**: Implement rate limiting for SIM management operations
|
||
|
|
4. **Audit Logging**: All SIM actions are logged with user context
|
||
|
|
5. **Error Handling**: Sensitive error details are not exposed to users
|
||
|
|
|
||
|
|
## 📊 Monitoring & Analytics
|
||
|
|
|
||
|
|
### Key Metrics to Track
|
||
|
|
- SIM management API response times
|
||
|
|
- Top-up success/failure rates
|
||
|
|
- Most popular data amounts
|
||
|
|
- Error rates by operation type
|
||
|
|
- Usage by SIM type (physical vs eSIM)
|
||
|
|
|
||
|
|
### Recommended Dashboards
|
||
|
|
1. **SIM Operations Dashboard**
|
||
|
|
- Daily/weekly top-up volumes
|
||
|
|
- Plan change requests
|
||
|
|
- Cancellation rates
|
||
|
|
- Error tracking
|
||
|
|
|
||
|
|
2. **User Engagement Dashboard**
|
||
|
|
- SIM management feature usage
|
||
|
|
- Self-service vs support ticket ratio
|
||
|
|
- User satisfaction metrics
|
||
|
|
|
||
|
|
## 🆘 Troubleshooting
|
||
|
|
|
||
|
|
### Common Issues
|
||
|
|
|
||
|
|
**1. "This subscription is not a SIM service"**
|
||
|
|
- Check if subscription product name contains "sim"
|
||
|
|
- Verify subscription has proper SIM identifiers
|
||
|
|
|
||
|
|
**2. "SIM account identifier not found"**
|
||
|
|
- Ensure subscription.domain contains valid phone number
|
||
|
|
- Check WHMCS service configuration
|
||
|
|
|
||
|
|
**3. Freebit API authentication failures**
|
||
|
|
- Verify OEM ID and key configuration
|
||
|
|
- Check Freebit API endpoint accessibility
|
||
|
|
- Review authentication token expiry
|
||
|
|
|
||
|
|
**4. Data usage not updating**
|
||
|
|
- Check Freebit API rate limits
|
||
|
|
- Verify account identifier format
|
||
|
|
- Review sync job logs
|
||
|
|
|
||
|
|
### Support Contacts
|
||
|
|
- **Freebit API Issues**: Contact Freebit technical support
|
||
|
|
- **Portal Issues**: Check application logs and error tracking
|
||
|
|
- **Salesforce Integration**: Review field mapping and data sync jobs
|
||
|
|
|
||
|
|
## 🔄 Future Enhancements
|
||
|
|
|
||
|
|
### Planned Features
|
||
|
|
1. **Voice Options Management**
|
||
|
|
- Enable/disable voicemail
|
||
|
|
- Configure call forwarding
|
||
|
|
- International calling settings
|
||
|
|
|
||
|
|
2. **Usage Analytics**
|
||
|
|
- Monthly usage trends
|
||
|
|
- Cost optimization recommendations
|
||
|
|
- Usage prediction and alerts
|
||
|
|
|
||
|
|
3. **Bulk Operations**
|
||
|
|
- Multi-SIM management for business accounts
|
||
|
|
- Bulk data top-ups
|
||
|
|
- Group plan management
|
||
|
|
|
||
|
|
4. **Advanced Notifications**
|
||
|
|
- Low data alerts
|
||
|
|
- Usage milestone notifications
|
||
|
|
- Plan recommendation engine
|
||
|
|
|
||
|
|
### Integration Opportunities
|
||
|
|
1. **Payment Integration**: Direct payment for top-ups
|
||
|
|
2. **Support Integration**: Create support cases from SIM issues
|
||
|
|
3. **Billing Integration**: Usage-based billing reconciliation
|
||
|
|
4. **Analytics Integration**: Usage data for business intelligence
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## ✅ Implementation Complete
|
||
|
|
|
||
|
|
The Freebit SIM management system is now fully implemented and ready for deployment. The system provides customers with complete self-service SIM management capabilities while maintaining proper data tracking and security standards.
|
||
|
|
|
||
|
|
**Next Steps:**
|
||
|
|
1. Configure Freebit API credentials
|
||
|
|
2. Add Salesforce custom fields
|
||
|
|
3. Test with sample SIM subscriptions
|
||
|
|
4. Train customer support team
|
||
|
|
5. Deploy to production
|
||
|
|
|
||
|
|
For technical support or questions about this implementation, refer to the troubleshooting section above or contact the development team.
|