Assist_Design/docs/ADDON-INSTALLATION-LOGIC.md

# Addon and Installation Logic - Clear Business Rules

## Product Classification in Salesforce

### Item_Class\_\_c Values

- **Service**: Main customer-selectable products (Internet plans, SIM plans, VPN)
- **Installation**: Installation options for services (one-time or monthly)
- **Add-on**: Optional additional services that can be standalone or bundled
- **Activation**: Required one-time activation fees

## Addon Logic

### Standalone Addons

Addons can exist independently without bundling:

```typescript
// Example: Voice Mail addon for SIM
{
  sku: "SIM-ADDON-VOICE-MAIL",
  itemClass: "Add-on",
  billingCycle: "Monthly",
  isBundledAddon: false,
  bundledAddonId: null
}
```

### Bundled Addons

Addons can be bundled with their installation/setup:

```typescript
// Monthly service addon
{
  sku: "INTERNET-ADDON-HIKARI-DENWA",
  itemClass: "Add-on",
  billingCycle: "Monthly",
  isBundledAddon: true,
  bundledAddonId: "a0X4x000000INSTALL123" // Points to installation product
}

// Installation for the addon
{
  sku: "INTERNET-ADDON-HIKARI-DENWA-INSTALL",
  itemClass: "Add-on", // Note: Installation for addon is still classified as Add-on
  billingCycle: "Onetime",
  isBundledAddon: true,
  bundledAddonId: "a0X4x000000SERVICE456" // Points back to monthly service
}
```

## Installation Logic

### Service Installations

Main service installations are classified as "Installation":

```typescript
// Internet service installation
{
  sku: "INTERNET-INSTALL-SINGLE",
  itemClass: "Installation", // Classified as Installation
  billingCycle: "Onetime",
  isBundledAddon: false,
  bundledAddonId: null
}
```

### Addon Installations

Addon installations remain classified as "Add-on":

```typescript
// Addon installation (not classified as Installation)
{
  sku: "INTERNET-ADDON-HIKARI-DENWA-INSTALL",
  itemClass: "Add-on", // Still Add-on, not Installation
  billingCycle: "Onetime",
  isBundledAddon: true,
  bundledAddonId: "a0X4x000000SERVICE456"
}
```

## Frontend Bundle Display Logic

The `AddonGroup.tsx` component handles bundling:

1. **Identifies bundled pairs**: Looks for products with `isBundledAddon: true` and matching `bundledAddonId`
2. **Groups by billing cycle**:
   - Monthly addon + Onetime installation = Bundle
   - Standalone addon = Individual item
3. **Display logic**:
   - Bundle: Shows combined name, monthly price + activation price
   - Standalone: Shows individual addon with its price

## Business Rules

### Bundling Rules

- Only addons can be bundled (Item_Class\_\_c = "Add-on")
- Service installations are separate (Item_Class\_\_c = "Installation")
- Bundled addons must have matching `bundledAddonId` references
- Bundle pairs: One Monthly + One Onetime with same bundle relationship

### SKU Patterns

- Service installations: `*-INSTALL-*` with Item_Class\_\_c = "Installation"
- Addon installations: `*-ADDON-*-INSTALL` with Item_Class\_\_c = "Add-on"
- Monthly addons: `*-ADDON-*` (no INSTALL suffix) with Item_Class\_\_c = "Add-on"

### Validation Logic

```typescript
// Service vs Addon installation detection
function isServiceInstallation(product) {
  return product.itemClass === "Installation";
}

function isAddonInstallation(product) {
  return (
    product.itemClass === "Add-on" &&
    product.sku.includes("INSTALL") &&
    product.billingCycle === "Onetime"
  );
}

function isMonthlyAddon(product) {
  return product.itemClass === "Add-on" && product.billingCycle === "Monthly";
}
```

This clarifies that:

1. **No featureList/featureSet fields** - removed from field mapping
2. **Addons can be standalone or bundled** with their installations
3. **Service installations** use Item_Class\_\_c = "Installation"
4. **Addon installations** use Item_Class\_\_c = "Add-on" (not "Installation")
5. **Bundle logic** is based on `isBundledAddon` + `bundledAddonId` fields, not SKU patterns