Assist_Design/docs/FIELD-MAPPING-MIGRATION-GUIDE.md

# Field Mapping Migration Guide

This guide provides step-by-step instructions for migrating services to use the simplified centralized field mapping system.

## Overview

The simplified field mapping system in `apps/bff/src/common/config/field-map.ts` provides essential field coverage for Internet, SIM, and VPN products with a clean, maintainable structure. Complex configuration logic is handled by Salesforce flows rather than product fields.

## What's New

### Simplified Structure
- **Core Product fields**: Essential catalog fields only (StockKeepingUnit, category, visibility, pricing)
- **Service-specific fields**: Minimal fields per product type (Internet tier, SIM data size, etc.)
- **Configuration logic**: Moved to Salesforce flows for Gold/Platinum Internet plans
- **Family discount logic**: Handled in personalized catalog service

### Key Simplifications
- **Removed complex configuration fields**: Access mode, service speed, etc. determined by Salesforce
- **Streamlined VPN products**: Region selection at order time, not product level
- **Clean Internet structure**: Silver (customer configures) vs Gold/Platinum (Salesforce configures)

## Migration Steps

### 1. Update Catalog Service

**Current hardcoded usage:**
```typescript
// In catalog.service.ts
const soql = `SELECT Id, Name, ${skuField}, Product2Categories1__c, Portal_Catalog__c FROM Product2...`
```

**Migrate to:**
```typescript
import { getSalesforceFieldMap, getProductQueryFields } from "../common/config/field-map";

// Option 1: Use helper function (recommended)
const soql = `SELECT ${getProductQueryFields()} FROM Product2 WHERE ${fields.product.portalCatalog} = true`;

// Option 2: Use individual fields
const fields = getSalesforceFieldMap();
const soql = `SELECT Id, Name, ${fields.product.sku}, ${fields.product.portalCategory}, ${fields.product.portalCatalog} FROM Product2...`;
```

### 2. Update Orders Service

**Current mixed usage:**
```typescript
// Some fields use mapping, others are hardcoded
orderFields.Order_Type__c = normalizedType;
orderFields.Activation_Type__c = body.selections.activationType;
orderFields.Internet_Plan_Tier__c = body.selections.tier;
```

**Migrate to:**
```typescript
const fields = getSalesforceFieldMap();

orderFields[fields.order.orderType] = normalizedType;
orderFields[fields.order.activationType] = body.selections.activationType;
orderFields[fields.order.internetPlanTier] = body.selections.tier;
orderFields[fields.order.accessMode] = body.selections.mode;
orderFields[fields.order.serviceSpeed] = body.selections.speed;
orderFields[fields.order.installmentPlan] = body.selections.install;
orderFields[fields.order.weekendInstall] = body.selections.weekend;
```

### 3. Update Account Service

**Current hardcoded usage:**
```typescript
// In salesforce-account.service.ts
WHERE SF_Account_No__c = '${this.safeSoql(customerNumber.trim())}'
```

**Migrate to:**
```typescript
import { getSalesforceFieldMap } from "../../../common/config/field-map";

const fields = getSalesforceFieldMap();
WHERE ${fields.account.customerNumber} = '${this.safeSoql(customerNumber.trim())}'
```

### 4. Add Personalized Catalog Support

**New functionality for Account eligibility:**
```typescript
const fields = getSalesforceFieldMap();

// Query account eligibility
const accountSoql = `SELECT ${fields.account.internetEligibility} FROM Account WHERE Id = '${accountId}'`;

// Filter products by eligibility
const productSoql = `SELECT ${getProductQueryFields()} 
                    FROM Product2 
                    WHERE ${fields.product.portalVisible} = true 
                    AND ${fields.product.portalInternetOffering} = '${eligibility}'`;
```

## Service-by-Service Migration Checklist

### ✅ Catalog Service
- [ ] Replace hardcoded `Product2Categories1__c` with `fields.product.portalCategory`
- [ ] Replace hardcoded `Portal_Catalog__c` with `fields.product.portalCatalog`
- [ ] Replace hardcoded `Portal_Accessible__c` with `fields.product.portalAccessible`
- [ ] Use `getProductQueryFields()` for standard queries
- [ ] Add personalized catalog support using `fields.account.internetEligibility`

### ✅ Orders Service
- [ ] Replace all hardcoded Order fields with field mapping
- [ ] Update Order query to use `getOrderQueryFields()`
- [ ] Replace hardcoded `Activation_Status__c`, `Activation_Type__c`, etc.
- [ ] Update MNP field usage to use `fields.order.mnp.*`
- [ ] Replace `WHMCS_Order_ID__c` with `fields.order.whmcsOrderId`

### ✅ Account Service
- [ ] Replace `SF_Account_No__c` with `fields.account.customerNumber`
- [ ] Add eligibility field queries using `fields.account.internetEligibility`

### ✅ User Service
- [ ] Update buildSalesforceUpdate to use field mapping for custom fields
- [ ] Ensure consistency with Account service field usage

## Environment Variable Support

All field mappings support environment variable overrides:

```bash
# Account fields
ACCOUNT_INTERNET_ELIGIBILITY_FIELD=Custom_Internet_Eligibility__c
ACCOUNT_CUSTOMER_NUMBER_FIELD=Custom_Account_Number__c

# Product fields
PRODUCT_PORTAL_CATALOG_FIELD=Custom_Portal_Catalog__c
PRODUCT_PORTAL_ACCESSIBLE_FIELD=Custom_Portal_Accessible__c
PRODUCT_PORTAL_CATEGORY_FIELD=Custom_Product2Categories1__c

# Order fields  
ORDER_ACTIVATION_TYPE_FIELD=Custom_Activation_Type__c
ORDER_INTERNET_PLAN_TIER_FIELD=Custom_Plan_Tier__c

# And many more...
```

## Testing Strategy

1. **Unit Tests**: Update tests to use field mapping instead of hardcoded values
2. **Integration Tests**: Verify SOQL queries work with mapped fields
3. **Environment Tests**: Test with different field mappings via env vars

## Rollback Plan

If issues arise, you can quickly rollback by:
1. Setting environment variables to original field names
2. The field mapping defaults ensure backward compatibility
3. No database or Salesforce schema changes required

## Benefits After Migration

1. **Single Source of Truth**: All field references in one place
2. **Environment Flexibility**: Easy customization per environment
3. **Documentation Alignment**: Perfect match with portal documentation
4. **Type Safety**: Strong TypeScript typing for all field references
5. **Maintainability**: Changes only needed in field mapping file

## Next Steps

1. Migrate services one by one following this guide
2. Update unit tests to use field mapping
3. Test in development environment
4. Update documentation with new patterns
5. Consider adding field validation at startup