Assist_Design/sim-manager-migration/README.md

SIM Manager Migration Package

This folder contains all the code, logic, and rules for the SIM Manager feature and Freebit API integration. Use this package when migrating SIM Manager functionality to a different branch.

📁 Folder Structure

sim-manager-migration/
├── backend/
│   ├── freebit-integration/          # Freebit API integration layer
│   │   ├── services/                 # Freebit API service implementations
│   │   ├── interfaces/               # TypeScript interfaces and types
│   │   └── freebit.module.ts         # NestJS module
│   ├── sim-management/               # SIM management business logic
│   │   ├── services/                 # SIM management services
│   │   ├── types/                    # Request/response types
│   │   ├── interfaces/               # Business logic interfaces
│   │   ├── sim-management.module.ts  # NestJS module
│   │   └── sim-management.service.ts # Main service facade
│   └── controllers/                  # API endpoint definitions
│       └── sim-endpoints.controller.ts
├── frontend/                         # React/Next.js components
│   ├── components/                   # SIM management UI components
│   ├── utils/                        # Frontend utilities
│   └── index.ts                      # Exports
└── docs/                             # Documentation
    ├── FREEBIT-SIM-MANAGEMENT.md     # Complete implementation guide
    └── SIM-MANAGEMENT-API-DATA-FLOW.md # API data flow documentation

🚀 Migration Steps

1. Backend Setup

Step 1.1: Copy Freebit Integration

Copy the entire backend/freebit-integration/ folder to:

apps/bff/src/integrations/freebit/

Step 1.2: Copy SIM Management Module

Copy the entire backend/sim-management/ folder to:

apps/bff/src/modules/subscriptions/sim-management/

Also copy:

backend/sim-management/sim-management.service.ts

to:

apps/bff/src/modules/subscriptions/sim-management.service.ts

Step 1.3: Add Controller Endpoints

The file backend/controllers/sim-endpoints.controller.ts contains all SIM-related endpoints. You need to:

1. Option A: Add these methods to your existing SubscriptionsController
2. Option B: Create a separate SimManagementController and register it

The endpoints are:

• GET /api/subscriptions/:id/sim - Get comprehensive SIM info
• GET /api/subscriptions/:id/sim/details - Get SIM details
• GET /api/subscriptions/:id/sim/usage - Get usage data
• GET /api/subscriptions/:id/sim/top-up-history - Get top-up history
• POST /api/subscriptions/:id/sim/top-up - Top up data quota
• POST /api/subscriptions/:id/sim/change-plan - Change plan
• POST /api/subscriptions/:id/sim/cancel - Cancel SIM
• POST /api/subscriptions/:id/sim/reissue-esim - Reissue eSIM
• POST /api/subscriptions/:id/sim/features - Update features
• GET /api/subscriptions/:id/sim/debug - Debug endpoint

Step 1.4: Register Modules

Ensure your main app module imports both modules:

// apps/bff/src/app.module.ts or subscriptions.module.ts
import { FreebitModule } from "@bff/integrations/freebit/freebit.module";
import { SimManagementModule } from "@bff/modules/subscriptions/sim-management/sim-management.module";

@Module({
  imports: [
    // ... other modules
    FreebitModule,
    SimManagementModule,
  ],
  // ...
})

2. Frontend Setup

Step 2.1: Copy Frontend Components

Copy the entire frontend/ folder to:

apps/portal/src/features/sim-management/

Step 2.2: Integrate into Subscription Page

The main component is SimManagementSection.tsx. Import and use it in your subscription detail page:

import { SimManagementSection } from "@/features/sim-management";

// In your subscription detail component:
<SimManagementSection subscriptionId={subscriptionId} />

3. Environment Configuration

Add these environment variables to your .env file:

# Freebit API Configuration
FREEBIT_BASE_URL=https://i1-q.mvno.net/emptool/api/
# Production: FREEBIT_BASE_URL=https://i1.mvno.net/emptool/api

FREEBIT_OEM_ID=PASI
FREEBIT_OEM_KEY=your_oem_key_here
FREEBIT_TIMEOUT=30000
FREEBIT_RETRY_ATTEMPTS=3

4. Dependencies

Required NestJS Modules

• @nestjs/common
• @nestjs/config
• nestjs-pino (for logging)

Required Services

The SIM Manager depends on these services (ensure they exist in your branch):

1. WHMCS Integration (for top-up payments):

   • WhmcsService with createInvoice() and capturePayment() methods
   • Required for the top-up payment flow

2. Subscriptions Service:

   • SubscriptionsService - for subscription data access

3. Mappings Service:

   • MappingsModule - for ID mapping between systems

4. Email Service:

   • EmailModule - for notifications

5. Sim Usage Store:

   • SimUsageStoreService - for caching usage data

5. Type Definitions

The code uses types from @customer-portal/domain. Ensure these types are available:

• SimTopupRequest
• SimChangePlanRequest
• SimCancelRequest
• SimFeaturesRequest
• SimDetails
• SimUsage
• SimTopUpHistory

If these don't exist in your domain package, they are defined in:

• backend/sim-management/types/sim-requests.types.ts
• backend/freebit-integration/interfaces/freebit.types.ts

📋 Freebit API Endpoints Used

The implementation uses the following Freebit APIs:

1. PA01-01: OEM Authentication (/authOem/)
2. PA03-02: Get Account Details (/mvno/getDetail/)
3. PA04-04: Add Specs & Quota (/master/addSpec/)
4. PA05-01: MVNO Communication Information (/mvno/getTrafficInfo/)
5. PA05-02: MVNO Quota Addition History (/mvno/getQuotaHistory/)
6. PA05-04: MVNO Plan Cancellation (/mvno/releasePlan/)
7. PA05-21: MVNO Plan Change (/mvno/changePlan/)
8. PA05-22: MVNO Quota Settings (/mvno/eachQuota/)
9. PA05-42: eSIM Profile Reissue (/esim/reissueProfile/)
10. Enhanced: eSIM Add Account/Reissue (/mvno/esim/addAcnt/)

🔧 Key Features

SIM Management Operations

• ✅ View SIM details (ICCID, MSISDN, plan, status)
• ✅ Real-time data usage monitoring
• ✅ Data quota top-up with payment processing (1GB = ¥500)
• ✅ eSIM profile reissue
• ✅ SIM service cancellation
• ✅ Plan change functionality
• ✅ Usage history tracking
• ✅ Service options management (Voice Mail, Call Waiting, Roaming)

Payment Flow (Top-Up)

The top-up feature includes a complete payment flow:

1. User requests top-up amount
2. WHMCS invoice created
3. Payment captured automatically
4. Freebit API called to add quota
5. Success/error handling

📚 Documentation

• FREEBIT-SIM-MANAGEMENT.md: Complete implementation guide with all features, API endpoints, and configuration
• SIM-MANAGEMENT-API-DATA-FLOW.md: Detailed API data flow and system architecture documentation

⚠️ Important Notes

1. WHMCS Integration Required: The top-up feature requires WHMCS integration with createInvoice() and capturePayment() methods. If these don't exist in your branch, you'll need to implement them or modify the top-up service.

2. Module Dependencies: The FreebitModule and SimManagementModule have circular dependencies resolved with forwardRef(). Ensure this pattern is maintained.

3. Authentication: All endpoints require authentication. The controller uses @ApiBearerAuth() and expects a JWT token.

4. Validation: Request validation uses Zod schemas. Ensure ZodValidationPipe is available in your validation utilities.

5. Error Handling: The implementation includes comprehensive error handling and user-friendly error messages.

🧪 Testing

After migration, test the following:

1. SIM Details: Verify SIM information displays correctly
2. Usage Data: Check that usage charts and data are accurate
3. Top-Up: Test the complete payment flow
4. Plan Change: Verify plan changes work correctly
5. eSIM Reissue: Test eSIM profile reissue (if applicable)
6. Error Handling: Test error scenarios (invalid subscription, API failures, etc.)

🔍 Troubleshooting

Common Issues

1. "Module not found" errors: Ensure all modules are properly imported in your app module
2. "FREEBIT_OEM_KEY is not configured": Add the environment variable
3. Payment failures: Verify WHMCS integration is working
4. API timeouts: Check Freebit API connectivity and increase timeout if needed

Debug Endpoints

Use the debug endpoint to troubleshoot:

GET /api/subscriptions/:id/sim/debug
GET /api/debug/sim-details/:account

📞 Support

For detailed implementation information, refer to:

• docs/FREEBIT-SIM-MANAGEMENT.md - Complete feature documentation
• docs/SIM-MANAGEMENT-API-DATA-FLOW.md - API integration details

---

Last Updated: January 2025
Migration Package Version: 1.0