Assist_Design/docs/CONSOLIDATED-TYPE-SYSTEM.md

# Consolidated Type System - Complete Solution

## Problem Analysis

You identified a critical issue: **order items, catalog items, and product types were all trying to encapsulate the same Salesforce Product2 data**, leading to:

1. **Type duplication** across contexts
2. **Inconsistent pricing models** (sometimes `price`, sometimes `monthlyPrice`/`oneTimePrice`)
3. **Enhanced Order Summary** creating its own conflicting `OrderItem` interface
4. **Missing PricebookEntry representation** in the type system

## Solution: Unified Type Architecture

### Core Principle

**One Salesforce Object = One TypeScript Type Structure**

Since both catalog items and order items ultimately represent Salesforce `Product2` objects (with `PricebookEntry` for pricing), we created a unified type system that directly maps to the Salesforce/WHMCS object structure.

## New Type Hierarchy

### 1. Base Product Structure

```typescript
// packages/domain/src/entities/product.ts

// Maps directly to Salesforce Product2 fields
interface BaseProduct {
  // Standard Salesforce fields
  id: string;                    // Product2.Id
  name: string;                  // Product2.Name
  sku: string;                   // Product2.StockKeepingUnit
  
  // Custom portal fields
  category: ProductCategory;     // Product2Categories1__c
  itemClass: ItemClass;          // Item_Class__c
  billingCycle: BillingCycle;    // Billing_Cycle__c
  portalCatalog: boolean;        // Portal_Catalog__c
  portalAccessible: boolean;     // Portal_Accessible__c
  
  // WHMCS integration
  whmcsProductId: number;        // WH_Product_ID__c
  whmcsProductName: string;      // WH_Product_Name__c
}

// Represents Salesforce PricebookEntry structure
interface PricebookEntry {
  id: string;                    // PricebookEntry.Id
  name: string;                  // PricebookEntry.Name
  unitPrice: number;             // PricebookEntry.UnitPrice
  pricebook2Id: string;          // PricebookEntry.Pricebook2Id
  product2Id: string;            // PricebookEntry.Product2Id
  isActive: boolean;             // PricebookEntry.IsActive
}

// Product with proper pricing structure
interface ProductWithPricing extends BaseProduct {
  pricebookEntry?: PricebookEntry;
  // Convenience fields derived from pricebookEntry and billingCycle
  unitPrice?: number;            // PricebookEntry.UnitPrice
  monthlyPrice?: number;         // UnitPrice if billingCycle === "Monthly"
  oneTimePrice?: number;         // UnitPrice if billingCycle === "Onetime"
}
```

### 2. Specialized Product Types

```typescript
// Category-specific extensions
interface InternetProduct extends ProductWithPricing {
  category: "Internet";
  internetPlanTier?: "Silver" | "Gold" | "Platinum";
  internetOfferingType?: string;
  internetMonthlyPrice?: number;
}

interface SimProduct extends ProductWithPricing {
  category: "SIM";
  simDataSize?: string;
  simPlanType?: "DataOnly" | "DataSmsVoice" | "VoiceOnly";
  simHasFamilyDiscount?: boolean;
}

// Union type for all products
type Product = InternetProduct | SimProduct | VpnProduct | ProductWithPricing;
```

### 3. Order Item Types

```typescript
// For new orders (before Salesforce creation)
interface OrderItemRequest extends ProductWithPricing {
  quantity: number;
  autoAdded?: boolean;
}

// Actual Salesforce OrderItem structure
interface SalesforceOrderItem {
  id: string;                    // OrderItem.Id
  orderId: string;               // OrderItem.OrderId
  quantity: number;              // OrderItem.Quantity
  unitPrice: number;             // OrderItem.UnitPrice
  totalPrice: number;            // OrderItem.TotalPrice
  pricebookEntry: PricebookEntry & {
    product2: Product;           // Full product data
  };
  whmcsServiceId?: string;       // WHMCS_Service_ID__c
  billingCycle?: BillingCycle;   // Derived from Product2
}
```

### 4. Order Types

```typescript
// Salesforce Order structure
interface SalesforceOrder {
  id: string;                    // Order.Id
  orderNumber: string;           // Order.OrderNumber
  status: string;                // Order.Status
  type: string;                  // Order.Type
  effectiveDate: string;         // Order.EffectiveDate
  totalAmount: number;           // Order.TotalAmount
  accountId: string;             // Order.AccountId
  pricebook2Id: string;          // Order.Pricebook2Id
  
  // Custom fields
  orderType?: string;            // Order_Type__c
  activationStatus?: string;     // Activation_Status__c
  whmcsOrderId?: string;         // WHMCS_Order_ID__c
  
  orderItems?: SalesforceOrderItem[];
}

// WHMCS Order structure (separate for existing orders)
interface WhmcsOrder extends WhmcsEntity {
  orderNumber: string;
  status: OrderStatus;
  items: WhmcsOrderItem[];
}

// Union types for different contexts
type Order = WhmcsOrder | SalesforceOrder;
type OrderItem = WhmcsOrderItem | OrderItemRequest | SalesforceOrderItem;
```

## Key Benefits

### 1. **Single Source of Truth**
- All types map directly to Salesforce object structure
- No more guessing which type to use in which context
- Consistent field names across the application

### 2. **Proper PricebookEntry Representation**
- Pricing is now properly modeled as PricebookEntry structure
- Convenience fields (`monthlyPrice`, `oneTimePrice`) derived from `unitPrice` and `billingCycle`
- No more confusion between `price` vs `monthlyPrice` vs `unitPrice`

### 3. **Type Safety**
- TypeScript discrimination based on `category` field
- Proper type guards for business logic
- Compile-time validation of field access

### 4. **Maintainability**
- Changes to Salesforce fields only need updates in one place
- Clear transformation functions between Salesforce API and TypeScript types
- Backward compatibility through type aliases

## Transformation Functions

```typescript
// Transform Salesforce Product2 + PricebookEntry to unified Product
function fromSalesforceProduct2(sfProduct: any, pricebookEntry?: any): Product {
  const billingCycle = sfProduct.Billing_Cycle__c || "Onetime";
  const unitPrice = pricebookEntry?.UnitPrice;
  
  return {
    id: sfProduct.Id,
    name: sfProduct.Name,
    sku: sfProduct.StockKeepingUnit,
    category: sfProduct.Product2Categories1__c,
    itemClass: sfProduct.Item_Class__c,
    billingCycle: billingCycle,
    portalCatalog: sfProduct.Portal_Catalog__c,
    portalAccessible: sfProduct.Portal_Accessible__c,
    whmcsProductId: sfProduct.WH_Product_ID__c,
    whmcsProductName: sfProduct.WH_Product_Name__c,
    
    // PricebookEntry structure
    pricebookEntry: pricebookEntry ? {
      id: pricebookEntry.Id,
      name: pricebookEntry.Name,
      unitPrice: pricebookEntry.UnitPrice,
      pricebook2Id: pricebookEntry.Pricebook2Id,
      product2Id: sfProduct.Id,
      isActive: pricebookEntry.IsActive !== false
    } : undefined,
    
    // Convenience pricing fields
    unitPrice: unitPrice,
    monthlyPrice: billingCycle === "Monthly" ? unitPrice : undefined,
    oneTimePrice: billingCycle === "Onetime" ? unitPrice : undefined,
    
    // Include all other fields for dynamic access
    ...sfProduct
  };
}

// Transform Salesforce OrderItem to unified structure
function fromSalesforceOrderItem(sfOrderItem: any): SalesforceOrderItem {
  const product = fromSalesforceProduct2(
    sfOrderItem.PricebookEntry?.Product2,
    sfOrderItem.PricebookEntry
  );
  
  return {
    id: sfOrderItem.Id,
    orderId: sfOrderItem.OrderId,
    quantity: sfOrderItem.Quantity,
    unitPrice: sfOrderItem.UnitPrice,
    totalPrice: sfOrderItem.TotalPrice,
    pricebookEntry: {
      ...product.pricebookEntry!,
      product2: product
    },
    whmcsServiceId: sfOrderItem.WHMCS_Service_ID__c,
    billingCycle: product.billingCycle,
    ...sfOrderItem
  };
}
```

## Usage Examples

### Catalog Context
```typescript
const product = fromSalesforceProduct2(salesforceProduct, pricebookEntry);

if (isCatalogVisible(product)) {
  displayInCatalog(product);
}
```

### Order Context
```typescript
const orderItem: OrderItemRequest = {
  ...product,
  quantity: 1,
  autoAdded: false
};
```

### Enhanced Order Summary
```typescript
// Now uses consistent unified types
interface OrderItem extends OrderItemRequest {
  id?: string;
  description?: string;
}

// Access unified pricing fields
const price = item.billingCycle === "Monthly" 
  ? item.monthlyPrice || item.unitPrice || 0
  : item.oneTimePrice || item.unitPrice || 0;
```

## Migration Strategy

1. **Backward Compatibility**: Legacy type aliases maintained
   ```typescript
   export type InternetPlan = InternetProduct;
   export type CatalogItem = Product;
   ```

2. **Gradual Adoption**: Existing code continues to work while new code uses unified types

3. **Clear Documentation**: This document explains the new structure and migration path

## Files Modified

- `packages/domain/src/entities/product.ts` - New unified product types
- `packages/domain/src/entities/order.ts` - Updated order types
- `packages/domain/src/entities/catalog.ts` - Re-exports with legacy aliases
- `apps/portal/src/features/catalog/components/base/EnhancedOrderSummary.tsx` - Updated to use unified types

## Enhanced Order Summary

The **Enhanced Order Summary** was a UI component that created its own `OrderItem` interface, leading to type conflicts. It has been updated to:

1. **Extend unified types**: Now extends `OrderItemRequest` instead of creating conflicting interfaces
2. **Use consistent pricing**: Uses `monthlyPrice`/`oneTimePrice`/`unitPrice` from unified structure
3. **Proper field access**: Uses `itemClass`, `billingCycle` from unified product structure

This eliminates the confusion about "which OrderItem type should I use?" because there's now a clear hierarchy:
- `OrderItemRequest` - for new orders in the portal
- `SalesforceOrderItem` - for existing orders from Salesforce
- `WhmcsOrderItem` - for existing orders from WHMCS

The Enhanced Order Summary now properly represents the unified product structure while adding UI-specific fields like `description` and optional `id`.

## Conclusion

This consolidated type system eliminates the original problem of multiple types trying to represent the same Salesforce data. Now there's **one unified type system** that properly maps to your Salesforce/WHMCS object structure, with clear transformation functions and proper PricebookEntry representation.

The solution maintains backward compatibility while providing a clear path forward for consistent type usage across your entire application.