Assist_Design/docs/PRODUCT-CATALOG-ARCHITECTURE.md

# Product Catalog & SKU Architecture - Complete Guide

This document consolidates the complete SKU-based architecture for the catalog and order system, including implementation patterns, edge cases, and migration strategy.

## Core Principles

### 1. **Frontend Responsibility**

- Frontend loads ALL required SKUs from catalog API
- Frontend determines which SKUs to include based on customer selections
- Frontend passes explicit SKU list to backend

### 2. **Backend Simplicity**

- Backend processes provided SKU list without guessing
- No order-type-specific logic for determining products
- Clean validation and error handling

### 3. **Salesforce as Source of Truth**

- All product relationships defined in Salesforce
- Catalog API exposes all necessary product types
- Clear product classification via `Item_Class__c`

## Product Classification

### Item_Class\_\_c Values

```sql
'Service'      -- Main customer-selectable products (Internet plans, SIM plans, VPN)
'Activation'   -- Required one-time activation fees
'Installation' -- Installation options (one-time or monthly)
'Add-on'       -- Optional additional services
```

### Portal Visibility Logic

```sql
Portal_Catalog__c = true     -- Visible in main catalog (customer selects)
Portal_Accessible__c = true  -- Can be used in orders (includes hidden fees/add-ons)
```

## SKU Naming Strategy

### Detailed SKU Format

Use explicit product variants with all relevant attributes:

**Internet SKUs:**

- `INTERNET-SILVER-HOME-1G`
- `INTERNET-GOLD-APT-1G`
- `INTERNET-PLATINUM-APT-100M`
- `INTERNET-INSTALL-SINGLE`
- `INTERNET-INSTALL-WEEKEND`
- `INTERNET-ADDON-HIKARI-DENWA-INSTALL`

**SIM SKUs:**

- `SIM-DATA-ONLY-5GB`
- `SIM-DATA-VOICE-50GB`
- `SIM-DATA-VOICE-50GB-FAMILY`
- `SIM-ACTIVATION-FEE`
- `SIM-ADDON-VOICE-MAIL`

**VPN SKUs:**

- `VPN-REMOTE-ACCESS-USA-SF`
- `VPN-REMOTE-ACCESS-UK-LONDON`
- `VPN-ACTIVATION-FEE`

## New Catalog API Structure

### Main Catalog Endpoint

```typescript
GET /catalog
// Returns only customer-selectable products (Portal_Catalog__c = true)
{
  internet: Array<{
    id: string,
    name: string,
    sku: string, // Detailed format: INTERNET-SILVER-APT-1G
    tier: string,
    offeringType: string,
    monthlyPrice: number
  }>,
  sim: Array<{
    id: string,
    name: string,
    sku: string, // Detailed format: SIM-DATA-VOICE-50GB
    dataSize: string,
    planType: string,
    hasFamilyDiscount: boolean
  }>,
  vpn: Array<{
    id: string,
    name: string,
    sku: string // Detailed format: VPN-REMOTE-ACCESS-USA-SF
  }>
}
```

### Related Products Endpoints

```typescript
GET /catalog/sim/activation-fees
// Returns SIM activation products (Item_Class__c = 'Activation')
Array<{id: string, name: string, sku: string, price: number, isDefault: boolean}>

GET /catalog/vpn/activation-fees?region=<region>
// Returns VPN activation products (Item_Class__c = 'Activation')
Array<{id: string, name: string, sku: string, price: number, isDefault: boolean}>

GET /catalog/internet/installations
// Returns Internet installation options (Item_Class__c = 'Installation')
Array<{id: string, name: string, sku: string, billingCycle: string, price: number, installmentType: string}>

GET /catalog/internet/addons
// Returns Internet add-ons (Item_Class__c = 'Add-on')
Array<{id: string, name: string, sku: string, price: number, billingCycle: string, autoAdd: boolean}>

GET /catalog/sim/addons
// Returns SIM add-ons (Item_Class__c = 'Add-on')
Array<{id: string, name: string, sku: string, price: number, billingCycle: string}>
```

## Frontend Implementation Patterns

### 1. Data Loading Pattern

```typescript
const ConfigurePage = () => {
  const [serviceProducts, setServiceProducts] = useState([]);
  const [activationFees, setActivationFees] = useState([]);
  const [addons, setAddons] = useState([]);

  useEffect(() => {
    const loadCatalogData = async () => {
      try {
        // Load all required data in parallel
        const [catalog, activation, addonsData] = await Promise.all([
          authenticatedApi.get("/catalog"),
          authenticatedApi.get("/catalog/sim/activation-fees"),
          authenticatedApi.get("/catalog/sim/addons"),
        ]);

        setServiceProducts(catalog.sim);
        setActivationFees(activation);
        setAddons(addonsData);
      } catch (error) {
        console.error("Failed to load catalog data:", error);
        // Handle error - show fallback or redirect
      }
    };

    loadCatalogData();
  }, []);
};
```

### 2. SKU Building Pattern

```typescript
const buildOrderSKUs = () => {
  const skus = [];

  // Always add service SKU (detailed format)
  if (selectedPlan?.sku) {
    skus.push(selectedPlan.sku); // e.g., "SIM-DATA-VOICE-50GB"
  }

  // Add required activation fee
  const defaultActivation = activationFees.find(f => f.isDefault || f.autoAdd);
  if (defaultActivation) {
    skus.push(defaultActivation.sku); // e.g., "SIM-ACTIVATION-FEE"
  }

  // Add selected add-ons
  selectedAddons.forEach(addon => {
    skus.push(addon.sku); // e.g., "SIM-ADDON-VOICE-MAIL"

    // Add dependent products if needed
    if (addon.requiredProducts) {
      skus.push(...addon.requiredProducts);
    }
  });

  return [...new Set(skus)]; // Remove duplicates
};
```

### 3. Order Submission Pattern

```typescript
const submitOrder = () => {
  const skus = buildOrderSKUs();

  const params = new URLSearchParams({
    orderType: "SIM",
    skus: JSON.stringify(skus), // Pass complete SKU array
    simType: selectedSimType,
    // ... other customer selections for order header
  });

  router.push(`/checkout?${params.toString()}`);
};
```

## SIM Configure Page - Complete Implementation

```typescript
// apps/portal/src/app/catalog/sim/configure/page.tsx
"use client";

import { useEffect, useState } from "react";
import { useRouter, useSearchParams } from "next/navigation";
import { authenticatedApi } from "@/lib/api";

interface SimPlan {
  id: string;
  name: string;
  sku: string; // Detailed format: SIM-DATA-VOICE-50GB
  dataSize: string;
  planType: string;
  hasFamilyDiscount: boolean;
  monthlyPrice: number;
}

interface ActivationFee {
  id: string;
  name: string;
  sku: string; // SIM-ACTIVATION-FEE
  price: number;
  isDefault: boolean;
  autoAdd: boolean;
}

interface SimAddon {
  id: string;
  name: string;
  sku: string; // SIM-ADDON-VOICE-MAIL
  price: number;
  billingCycle: string;
  description?: string;
}

export default function SimConfigurePage() {
  const router = useRouter();
  const params = useSearchParams();
  const planSku = params.get("sku"); // Detailed SKU from catalog

  // State
  const [loading, setLoading] = useState(true);
  const [selectedPlan, setSelectedPlan] = useState<SimPlan | null>(null);
  const [activationFees, setActivationFees] = useState<ActivationFee[]>([]);
  const [addons, setAddons] = useState<SimAddon[]>([]);

  // Customer selections
  const [simType, setSimType] = useState<"eSIM" | "Physical SIM" | null>(null);
  const [selectedAddons, setSelectedAddons] = useState<string[]>([]);
  const [eid, setEid] = useState("");

  // Load catalog data
  useEffect(() => {
    let mounted = true;

    const loadCatalogData = async () => {
      if (!planSku) {
        router.push('/catalog/sim');
        return;
      }

      try {
        // Load all required data in parallel
        const [catalog, activation, addonsData] = await Promise.all([
          authenticatedApi.get<{sim: SimPlan[]}>("/catalog"),
          authenticatedApi.get<ActivationFee[]>("/catalog/sim/activation-fees"),
          authenticatedApi.get<SimAddon[]>("/catalog/sim/addons")
        ]);

        if (mounted) {
          const plan = catalog.sim.find(p => p.sku === planSku);
          if (plan) {
            setSelectedPlan(plan);
            setActivationFees(activation);
            setAddons(addonsData);
          } else {
            router.push('/catalog/sim');
          }
        }
      } catch (error) {
        console.error("Failed to load catalog data:", error);
        if (mounted) router.push('/catalog/sim');
      } finally {
        if (mounted) setLoading(false);
      }
    };

    loadCatalogData();
    return () => { mounted = false; };
  }, [planSku, router]);

  // Build complete SKU list based on selections
  const buildOrderSKUs = (): string[] => {
    const skus: string[] = [];

    // Always add service SKU (detailed format)
    if (selectedPlan?.sku) {
      skus.push(selectedPlan.sku); // e.g., "SIM-DATA-VOICE-50GB"
    }

    // Add required activation fee (auto-add or default)
    const requiredActivation = activationFees.find(f => f.autoAdd || f.isDefault);
    if (requiredActivation) {
      skus.push(requiredActivation.sku); // "SIM-ACTIVATION-FEE"
    }

    // Add selected add-ons
    selectedAddons.forEach(addonSku => {
      skus.push(addonSku); // e.g., "SIM-ADDON-VOICE-MAIL"
    });

    // Remove duplicates
    return [...new Set(skus)];
  };

  // Calculate pricing
  const calculatePricing = () => {
    let monthlyTotal = 0;
    let oneTimeTotal = 0;

    // Service plan (monthly)
    if (selectedPlan) {
      monthlyTotal += selectedPlan.monthlyPrice || 0;
    }

    // Activation fee (one-time)
    const requiredActivation = activationFees.find(f => f.autoAdd || f.isDefault);
    if (requiredActivation) {
      oneTimeTotal += requiredActivation.price;
    }

    // Add-ons (monthly)
    selectedAddons.forEach(addonSku => {
      const addon = addons.find(a => a.sku === addonSku);
      if (addon && addon.billingCycle === 'Monthly') {
        monthlyTotal += addon.price;
      }
    });

    return { monthlyTotal, oneTimeTotal };
  };

  // Submit order
  const handleSubmit = () => {
    if (!selectedPlan || !simType) return;

    const skus = buildOrderSKUs();
    const { monthlyTotal, oneTimeTotal } = calculatePricing();

    const params = new URLSearchParams({
      orderType: "SIM", // Always "SIM", not "eSIM"
      skus: JSON.stringify(skus), // Complete SKU array

      // Customer selections (for order header)
      planName: selectedPlan.name,
      simType: simType,
      ...(eid && { eid }),

      // Pricing (for display)
      monthlyPrice: monthlyTotal.toString(),
      oneTimePrice: oneTimeTotal.toString(),
    });

    router.push(`/checkout?${params.toString()}`);
  };

  if (loading) {
    return <div>Loading...</div>;
  }

  if (!selectedPlan) {
    return <div>Plan not found</div>;
  }

  return (
    <div className="max-w-4xl mx-auto p-6">
      <h1 className="text-2xl font-bold mb-6">Configure {selectedPlan.name}</h1>

      {/* SIM Type Selection */}
      <section className="mb-8">
        <h2 className="text-xl font-semibold mb-4">SIM Type</h2>
        <div className="grid grid-cols-2 gap-4">
          <label className="border rounded-lg p-4 cursor-pointer hover:bg-gray-50">
            <input
              type="radio"
              name="simType"
              value="Physical SIM"
              checked={simType === "Physical SIM"}
              onChange={(e) => setSimType(e.target.value as "Physical SIM")}
              className="mr-3"
            />
            <div>
              <div className="font-medium">Physical SIM</div>
              <div className="text-sm text-gray-600">Traditional SIM card</div>
            </div>
          </label>

          <label className="border rounded-lg p-4 cursor-pointer hover:bg-gray-50">
            <input
              type="radio"
              name="simType"
              value="eSIM"
              checked={simType === "eSIM"}
              onChange={(e) => setSimType(e.target.value as "eSIM")}
              className="mr-3"
            />
            <div>
              <div className="font-medium">eSIM</div>
              <div className="text-sm text-gray-600">Digital SIM</div>
            </div>
          </label>
        </div>

        {/* EID input for eSIM */}
        {simType === "eSIM" && (
          <div className="mt-4">
            <label className="block text-sm font-medium mb-2">
              EID (Required for eSIM)
            </label>
            <input
              type="text"
              value={eid}
              onChange={(e) => setEid(e.target.value)}
              className="w-full border rounded-lg px-3 py-2"
              placeholder="Enter your device EID"
            />
          </div>
        )}
      </section>

      {/* Add-ons Selection */}
      <section className="mb-8">
        <h2 className="text-xl font-semibold mb-4">Add-ons (Optional)</h2>
        <div className="space-y-3">
          {addons.map(addon => (
            <label key={addon.id} className="flex items-center border rounded-lg p-4 cursor-pointer hover:bg-gray-50">
              <input
                type="checkbox"
                checked={selectedAddons.includes(addon.sku)}
                onChange={(e) => {
                  if (e.target.checked) {
                    setSelectedAddons([...selectedAddons, addon.sku]);
                  } else {
                    setSelectedAddons(selectedAddons.filter(sku => sku !== addon.sku));
                  }
                }}
                className="mr-3"
              />
              <div className="flex-1">
                <div className="font-medium">{addon.name}</div>
                {addon.description && (
                  <div className="text-sm text-gray-600">{addon.description}</div>
                )}
              </div>
              <div className="text-right">
                <div className="font-medium">¥{addon.price.toLocaleString()}</div>
                <div className="text-sm text-gray-600">{addon.billingCycle}</div>
              </div>
            </label>
          ))}
        </div>
      </section>

      {/* Pricing Summary */}
      <section className="mb-8">
        <div className="bg-gray-50 rounded-lg p-4">
          <h3 className="font-semibold mb-3">Order Summary</h3>

          {/* Service */}
          <div className="flex justify-between mb-2">
            <span>{selectedPlan.name}</span>
            <span>¥{(selectedPlan.monthlyPrice || 0).toLocaleString()}/month</span>
          </div>

          {/* Activation Fee */}
          {activationFees.find(f => f.autoAdd || f.isDefault) && (
            <div className="flex justify-between mb-2">
              <span>Activation Fee</span>
              <span>¥{activationFees.find(f => f.autoAdd || f.isDefault)!.price.toLocaleString()} (one-time)</span>
            </div>
          )}

          {/* Add-ons */}
          {selectedAddons.map(addonSku => {
            const addon = addons.find(a => a.sku === addonSku);
            return addon ? (
              <div key={addonSku} className="flex justify-between mb-2">
                <span>{addon.name}</span>
                <span>¥{addon.price.toLocaleString()}/{addon.billingCycle.toLowerCase()}</span>
              </div>
            ) : null;
          })}

          {/* Totals */}
          <hr className="my-3" />
          <div className="flex justify-between font-semibold">
            <span>Monthly Total</span>
            <span>¥{calculatePricing().monthlyTotal.toLocaleString()}</span>
          </div>
          <div className="flex justify-between font-semibold">
            <span>One-time Total</span>
            <span>¥{calculatePricing().oneTimeTotal.toLocaleString()}</span>
          </div>
        </div>
      </section>

      {/* Submit Button */}
      <button
        onClick={handleSubmit}
        disabled={!selectedPlan || !simType || (simType === "eSIM" && !eid)}
        className="w-full bg-blue-600 text-white font-bold py-3 px-6 rounded-lg hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed"
      >
        Continue to Checkout
      </button>
    </div>
  );
}
```

## Backend Implementation

### Enhanced Catalog Controller

```typescript
@Controller("catalog")
export class CatalogController {
  @Get("sim/activation-fees")
  @ApiOperation({ summary: "Get SIM activation fee options" })
  async getSimActivationFees() {
    return this.catalogService.getSimActivationFees();
  }

  @Get("vpn/activation-fees")
  @ApiOperation({ summary: "Get VPN activation fee options" })
  async getVpnActivationFees(@Query("region") region?: string) {
    return this.catalogService.getVpnActivationFees(region);
  }

  @Get("internet/installations")
  @ApiOperation({ summary: "Get Internet installation options" })
  async getInternetInstallations() {
    return this.catalogService.getInternetInstallations();
  }

  @Get("internet/addons")
  @ApiOperation({ summary: "Get Internet add-on options" })
  async getInternetAddons() {
    return this.catalogService.getInternetAddons();
  }

  @Get("sim/addons")
  @ApiOperation({ summary: "Get SIM add-on options" })
  async getSimAddons() {
    return this.catalogService.getSimAddons();
  }
}
```

### Simplified Order Processing

```typescript
private async createOrderItems(orderId: string, body: CreateOrderBody): Promise<void> {
  // Parse SKUs from selections (detailed format)
  let skus: string[] = [];

  if (body.selections.skus && typeof body.selections.skus === 'string') {
    try {
      skus = JSON.parse(body.selections.skus);
    } catch (e) {
      this.logger.warn("Failed to parse SKUs JSON, falling back to individual fields");
    }
  }

  // Fallback to individual SKU fields for backward compatibility
  if (skus.length === 0) {
    if (body.selections.skuService) skus.push(body.selections.skuService as string);
    if (body.selections.skuActivation) skus.push(body.selections.skuActivation as string);
    if (body.selections.skuInstall) skus.push(body.selections.skuInstall as string);
    if (body.selections.skuAddons) {
      const addons = Array.isArray(body.selections.skuAddons)
        ? body.selections.skuAddons
        : [body.selections.skuAddons];
      skus.push(...addons.map(String));
    }
  }

  // Remove duplicates and empty values
  skus = [...new Set(skus.filter(Boolean))];

  if (skus.length === 0) {
    throw new BadRequestException("No products specified for order");
  }

  // Create OrderItems for each detailed SKU
  const pricebookId = await this.findPortalPricebookId();

  for (const sku of skus) {
    const meta = await this.getProductMetaBySku(pricebookId, sku);

    if (!meta?.pbeId) {
      this.logger.error({ sku }, "PricebookEntry not found for SKU");
      throw new NotFoundException(`Product not found: ${sku}`);
    }

    await this.sf.sobject("OrderItem").create({
      OrderId: orderId,
      PricebookEntryId: meta.pbeId,
      Quantity: 1,
      UnitPrice: null, // Use pricebook price
    });

    this.logger.log({ orderId, sku, pbeId: meta.pbeId }, "OrderItem created");
  }
}
```

## Edge Case Handling

### 1. Multiple Activation Fees Found

**Solution**: Add `Is_Default__c` field to Product2

```sql
-- Product2 fields for disambiguation
Is_Default__c           Checkbox    -- Default choice when multiple options exist
Display_Order__c        Number      -- Ordering for UI selection
Auto_Add__c            Checkbox    -- Automatically add to orders (required fees)
```

**Implementation**:

```typescript
// Catalog service - return default activation fee
const activationFees = records
  .filter(r => r.Item_Class__c === "Activation")
  .map(r => ({
    id: r.Id,
    sku: r.StockKeepingUnit, // Correct field name
    name: r.Name,
    price: r.PricebookEntries?.records?.[0]?.UnitPrice || 0,
    isDefault: r.Is_Default__c === true,
    autoAdd: r.Auto_Add__c === true,
  }))
  .sort((a, b) => (b.isDefault ? 1 : 0) - (a.isDefault ? 1 : 0));
```

### 2. Missing Required Products

**Solution**: Validation in catalog service with fallback

```typescript
async getSimActivationFees(): Promise<ActivationFee[]> {
  const fees = await this.queryActivationFees('SIM');

  if (fees.length === 0) {
    this.logger.warn("No SIM activation fees found in catalog");
    return [];
  }

  if (!fees.some(f => f.isDefault)) {
    this.logger.warn("No default SIM activation fee, marking first as default");
    fees[0].isDefault = true;
  }

  return fees;
}
```

### 3. Product Relationships

**Solution**: Add relationship fields to Product2

```sql
-- Product2 relationship fields
Required_Products__c    Text(1000)  -- JSON array of required SKUs
Dependent_Products__c   Text(1000)  -- JSON array of auto-added SKUs
Mutually_Exclusive__c   Text(1000)  -- JSON array of conflicting SKUs
```

**Example Usage**:

```sql
-- Hikari Denwa service
Required_Products__c = '["INTERNET-ADDON-HIKARI-DENWA-INSTALL"]'

-- Weekend installation
Mutually_Exclusive__c = '["INTERNET-INSTALL-WEEKDAY"]'
```

### 4. Regional/Conditional Products

**Solution**: Use personalization logic

```typescript
GET /catalog/personalized
// Already filters by account eligibility
// Extend to include conditional activation fees

GET /catalog/vpn/activation-fees?region=USA-SF
// Filter activation fees by region if needed
```

## Key Changes Summary

### 1. Field Name Corrections

```typescript
// OLD: Inconsistent field names
(Portal_Catalog__c, StockKeepingUnit, Product2Categories1__c);

// NEW: Correct Salesforce field names
(Portal_Catalog__c, Portal_Accessible__c, StockKeepingUnit, Product2Categories1__c);
```

### 2. SKU Strategy Change

```typescript
// OLD: Simple SKUs
("SIM-DATA-VOICE-50GB", "INTERNET-SILVER");

// NEW: Detailed SKUs with all attributes
("SIM-DATA-VOICE-50GB-FAMILY", "INTERNET-SILVER-APT-1G");
```

### 3. Order Type Normalization

```typescript
// OLD: Separate eSIM and SIM types
orderType: simType === "eSIM" ? "eSIM" : "SIM"

// NEW: Always use "SIM", differentiate with simType field
orderType: "SIM",
simType: selectedSimType, // "eSIM" or "Physical SIM"
```

### 4. Complete SKU Control

```typescript
// OLD: Incomplete product coverage
const params = new URLSearchParams({
  orderType: "SIM",
  skuService: plan.sku,
  // Missing activation fee!
});

// NEW: Complete SKU coverage
const skus = [
  selectedPlan.sku, // Service: "SIM-DATA-VOICE-50GB"
  activationFees.find(f => f.isDefault).sku, // Activation: "SIM-ACTIVATION-FEE"
  ...selectedAddons, // Add-ons: ["SIM-ADDON-VOICE-MAIL"]
];

const params = new URLSearchParams({
  orderType: "SIM",
  skus: JSON.stringify(skus),
  simType: selectedSimType,
});
```

## Migration Strategy

### Phase 1: ✅ Backend Infrastructure (Completed)

- ✅ New catalog endpoints
- ✅ Enhanced order processing with backward compatibility
- ✅ Comprehensive validation and error handling

### Phase 2: 🔄 Salesforce Configuration (Next)

```sql
-- Add edge case handling fields to Product2
ALTER TABLE Product2 ADD COLUMN Is_Default__c BOOLEAN DEFAULT false;
ALTER TABLE Product2 ADD COLUMN Display_Order__c NUMBER(18,0);
ALTER TABLE Product2 ADD COLUMN Auto_Add__c BOOLEAN DEFAULT false;

-- Mark existing activation fees as default
UPDATE Product2
SET Is_Default__c = true, Auto_Add__c = true
WHERE Item_Class__c = 'Activation'
AND StockKeepingUnit IN ('SIM-ACTIVATION-FEE', 'VPN-ACTIVATION-FEE');
```

### Phase 3: 🔄 Frontend Updates (Next)

- Update SIM configure page to use new endpoints
- Update VPN page to load activation fees
- Update Internet page to use installation/addon endpoints
- Test with both old and new SKU formats

### Phase 4: 🔄 Cleanup (Final)

- Remove legacy individual SKU field support
- Remove order-type-specific validation
- Clean up deprecated frontend code

## Benefits Achieved

### 1. **Eliminated Guessing Logic**

- ❌ No more hint-based product resolution
- ✅ Explicit SKU arrays from frontend
- ✅ Clear validation and error messages

### 2. **Fixed Missing Activation Fees**

- ❌ SIM orders were missing activation fees
- ✅ All order types now include required fees
- ✅ Configurable via Salesforce Product2 fields

### 3. **Improved Maintainability**

- ❌ Complex order-type-specific logic
- ✅ Generic SKU processing
- ✅ Easy to add new product types

### 4. **Enhanced Flexibility**

- ❌ Hard-coded product relationships
- ✅ Configurable product dependencies
- ✅ Regional and conditional products

### 5. **Better Error Handling**

- ❌ Cryptic "product not found" errors
- ✅ Specific SKU validation messages
- ✅ Business rule validation

This architecture provides **complete SKU control**, **predictable behavior**, and **easy debugging** while maintaining **backward compatibility** during the migration period.