Zones Models - Zone-Driven Inventory Architecture

Store
  │
  ├─ Zone (Dairy Cooler)
  │   │
  │   ├─ ZoneInventory (count frequency, par levels)
  │   │   │
  │   │   └─ ParLevelItem (Product A, SKU-123, Qty: 24)
  │   │       └─ Creates/Ensures InventoryLevel exists
  │   │
  │   ├─ ZoneCompliance (daily checklist, photo required)
  │   │
  │   └─ ZoneMerchandising (display standards, required categories)
  │
  └─ Planogram (Holiday Display 2025)
      │
      ├─ PlanogramProduct (Product A, SKU-123, Qty: 12, "Top shelf left")
      │
      └─ Target Zones (apply to specific zones)

# From models.py:9-64

class Zone(SanityIntegratedModel, AuditableMixin):
    """
    Zone model that exactly mirrors Sanity's zone.js schema.
    Zones act as the product assignment layer between catalog and stores.
    """
    zone_name = models.CharField(
        max_length=255,
        help_text='Zone Name'
    )
    store_location = models.ForeignKey(
        'stores.Store',
        on_delete=models.CASCADE,
        related_name='zones',
        help_text='Store Location reference'
    )
    is_shown = models.BooleanField(
        default=True,
        help_text='Show in Compliance Dashboard'
    )
    display_order = models.IntegerField(
        null=True,
        blank=True,
        help_text='Order zones appear in compliance checklists'
    )

    # Zone type configuration - stores the zone configuration data from Sanity
    zone_type = models.JSONField(
        default=list,
        help_text='Zone type configuration from Sanity (array of zone type objects with compliance, merchandising, inventory settings)'
    )

    def get_par_levels(self):
        """Get all par level items for this zone if it has inventory configuration."""
        if isinstance(self.zone_type, list):
            has_inventory = any(
                item.get('_type') == 'zoneInventory'
                for item in self.zone_type
                if isinstance(item, dict)
            )
            if has_inventory:
                return self.zone_inventory.par_levels.all() if hasattr(self, 'zone_inventory') else []
        return []

def get_par_levels(self):
    """Get all par level items for this zone if it has inventory configuration."""
    if isinstance(self.zone_type, list):
        has_inventory = any(
            item.get('_type') == 'zoneInventory'
            for item in self.zone_type
            if isinstance(item, dict)
        )
        if has_inventory:
            return self.zone_inventory.par_levels.all() if hasattr(self, 'zone_inventory') else []
    return []

# From models.py:67-104

class ZoneCompliance(SanityIntegratedModel, AuditableMixin):
    """
    ZoneCompliance model that mirrors Sanity's zoneCompliance.js schema.
    Defines compliance checklist requirements for zones.
    """
    zone = models.OneToOneField(
        Zone,
        on_delete=models.CASCADE,
        related_name='zone_compliance',
        help_text='Associated zone'
    )
    checklist_items = models.JSONField(
        default=list,
        help_text='Array of checklist item strings'
    )
    requires_photo = models.BooleanField(
        default=True,
        help_text='Photo Required'
    )
    frequency = models.CharField(
        max_length=20,
        choices=[
            ('Daily', 'Daily'),
            ('Weekly', 'Weekly'),
            ('Monthly', 'Monthly'),
        ],
        null=True,
        blank=True,
        help_text='Check Frequency'
    )

{
  "checklist_items": [
    "Temperature check (35-38°F)",
    "No expired products",
    "Shelves clean and organized",
    "Products properly rotated (FIFO)"
  ],
  "requires_photo": true,
  "frequency": "Daily"
}

# From models.py:107-129

class ZoneMerchandising(SanityIntegratedModel, AuditableMixin):
    """
    ZoneMerchandising model that mirrors Sanity's zoneMerchandising.js schema.
    Defines merchandising standards for zones.
    """
    zone = models.OneToOneField(
        Zone,
        on_delete=models.CASCADE,
        related_name='zone_merchandising',
        help_text='Associated zone'
    )
    display_standards = models.JSONField(
        default=list,
        help_text='Array of display standard strings'
    )

{
  "display_standards": [
    "Products faced forward",
    "Price tags visible and accurate",
    "No gaps or holes in display",
    "Promotional signage at eye level"
  ]
}

# From models.py:132-167

class ZoneInventory(SanityIntegratedModel, AuditableMixin):
    """
    ZoneInventory model that mirrors Sanity's zoneInventory.js schema.
    Defines inventory management configuration for zones.
    """
    zone = models.OneToOneField(
        Zone,
        on_delete=models.CASCADE,
        related_name='zone_inventory',
        help_text='Associated zone'
    )
    count_frequency = models.CharField(
        max_length=20,
        choices=[
            ('Daily', 'Daily'),
            ('Weekly', 'Weekly'),
            ('Bi-Weekly', 'Bi-Weekly'),
            ('Monthly', 'Monthly'),
        ],
        null=True,
        blank=True,
        help_text='How often should inventory in this zone be counted?'
    )
    last_count_date = models.DateField(
        null=True,
        blank=True,
        help_text='Last Count Date'
    )

# From models.py:170-267

class ParLevelItem(SanityIntegratedModel, AuditableMixin):
    """
    ParLevelItem model that mirrors Sanity's parLevelItem.js schema.
    Defines which products belong in physical spaces with ideal quantities.
    This is the core of the zone-driven inventory architecture.
    """
    zone_inventory = models.ForeignKey(
        ZoneInventory,
        on_delete=models.CASCADE,
        related_name='par_levels',
        help_text='Associated zone inventory configuration'
    )
    product = models.ForeignKey(
        'products.Product',
        on_delete=models.CASCADE,
        related_name='par_level_items',
        help_text='Product reference'
    )
    variant_sku = models.CharField(
        max_length=100,
        db_index=True,
        help_text='SKU of the specific product variant'
    )
    quantity = models.IntegerField(
        help_text='Ideal Quantity for this variant in this zone'
    )

    def get_product_variant(self):
        """Get the ProductVariant record that matches this par level item's SKU."""
        try:
            from django.apps import apps
            ProductVariant = apps.get_model('products', 'ProductVariant')
            return ProductVariant.objects.filter(
                product=self.product,
                sku=self.variant_sku
            ).first()
        except Exception as e:
            logger.error(f"Failed to get ProductVariant for SKU {self.variant_sku}: {e}")
            return None

    def ensure_inventory_level_exists(self):
        """
        Ensure an InventoryLevel record exists for this par level item.
        This creates the inventory tracking infrastructure based on zone assignments.
        """
        try:
            from django.apps import apps
            InventoryLevel = apps.get_model('products', 'InventoryLevel')

            # Get the store from the zone
            store = self.zone_inventory.zone.store_location

            # Check if InventoryLevel already exists
            inventory_level, created = InventoryLevel.objects.get_or_create(
                product=self.product,
                variant_sku=self.variant_sku,
                store=store,
                defaults={
                    'quantity_on_hand': 0,
                    'quantity_reserved': 0,
                    'cost_per_unit': None
                }
            )

            if created:
                logger.info(f"Created InventoryLevel for {self.variant_sku} at {store.name} based on par level")

            return inventory_level
        except Exception as e:
            logger.error(f"Failed to ensure InventoryLevel exists for par level {self.pk}: {e}")
            return None

    def clean(self):
        """Validate that the variant_sku exists for the selected product."""
        super().clean()
        if self.product and self.variant_sku:
            variant = self.get_product_variant()
            if not variant:
                raise ValidationError(
                    f"No ProductVariant with SKU '{self.variant_sku}' found for product '{self.product.name}'"
                )

# Admin creates par level in Sanity or Django
par_level = ParLevelItem.objects.create(
    zone_inventory=dairy_zone.zone_inventory,
    product=milk_product,
    variant_sku='MILK-GAL-WHOLE',
    quantity=24  # Should have 24 gallons in dairy cooler
)

# Par level automatically ensures inventory tracking exists
inventory_level = par_level.ensure_inventory_level_exists()

# Now inventory system knows:
# - This product/variant should be tracked at this store
# - Ideal quantity is 24 units in the dairy cooler zone
# - Can trigger reorders when actual < par level

# From models.py:270-319

class Planogram(SanityIntegratedModel, AuditableMixin):
    """
    Planogram model that mirrors Sanity's planogram.js schema.
    Provides merchandising guidance for zone product arrangements.
    """
    planogram_name = models.CharField(
        max_length=255,
        help_text='Planogram Name'
    )
    version = models.CharField(
        max_length=50,
        null=True,
        blank=True,
        help_text='Version (e.g., 1.0, 2.1)'
    )
    effective_date = models.DateField(
        null=True,
        blank=True,
        help_text='Effective Date'
    )
    campaign = models.ForeignKey(
        'promotions.PromotionalCampaign',
        on_delete=models.SET_NULL,
        null=True,
        blank=True,
        related_name='planograms',
        help_text='Associated Campaign'
    )
    instructions = models.TextField(
        blank=True,
        help_text='Instructions (from bodyPortableText)'
    )
    diagram_url = models.URLField(
        null=True,
        blank=True,
        help_text='URL to planogram diagram image'
    )

# From models.py:322-387

class PlanogramProduct(SanityIntegratedModel, AuditableMixin):
    """
    PlanogramProduct model that mirrors Sanity's planogramProduct.js schema.
    Defines specific product placements within planograms.
    """
    planogram = models.ForeignKey(
        Planogram,
        on_delete=models.CASCADE,
        related_name='planogram_products',
        help_text='Associated planogram'
    )
    product = models.ForeignKey(
        'products.Product',
        on_delete=models.CASCADE,
        related_name='planogram_products',
        help_text='Product reference'
    )
    variant_sku = models.CharField(
        max_length=100,
        db_index=True,
        help_text='SKU of the specific product variant'
    )
    quantity = models.IntegerField(
        help_text='Initial Quantity for Product Variant'
    )
    position_notes = models.CharField(
        max_length=255,
        blank=True,
        help_text='Positioning Notes (e.g., "Top shelf, left corner")'
    )

    def get_product_variant(self):
        """Get the ProductVariant record that matches this planogram product's SKU."""
        # Similar to ParLevelItem.get_product_variant()
        ...

    def clean(self):
        """Validate that the variant_sku exists for the selected product."""
        # Similar to ParLevelItem.clean()
        ...

# From models.py:391-407

class PlanogramTargetStore(models.Model):
    """Junction table for planogram target stores."""
    planogram = models.ForeignKey(
        Planogram,
        on_delete=models.CASCADE,
        related_name='target_stores'
    )
    store = models.ForeignKey(
        'stores.Store',
        on_delete=models.CASCADE,
        related_name='targeted_planograms'
    )

    unique_together = [['planogram', 'store']]

# From models.py:409-424

class PlanogramTargetZone(models.Model):
    """Junction table for planogram target zones."""
    planogram = models.ForeignKey(
        Planogram,
        on_delete=models.CASCADE,
        related_name='target_zones'
    )
    zone = models.ForeignKey(
        Zone,
        on_delete=models.CASCADE,
        related_name='targeted_planograms'
    )

    unique_together = [['planogram', 'zone']]

# From models.py:427-442

class ZoneMerchandisingRequiredProduct(models.Model):
    """Junction table for zone merchandising required product categories."""
    zone_merchandising = models.ForeignKey(
        ZoneMerchandising,
        on_delete=models.CASCADE,
        related_name='required_products'
    )
    product_type = models.ForeignKey(
        'products.ProductType',
        on_delete=models.CASCADE,
        related_name='required_in_zones'
    )

    unique_together = [['zone_merchandising', 'product_type']]

1. Create Zone (Dairy Cooler at Store A)
   │
2. Create ZoneInventory (count daily)
   │
3. Create ParLevelItem (Milk SKU-123, Qty: 24)
   │
   ├─ Validates SKU exists
   ├─ ensure_inventory_level_exists() called
   │   │
   │   └─ Creates InventoryLevel (Store A, Milk SKU-123)
   │
4. Inventory System Now Knows:
   ├─ Track Milk SKU-123 at Store A
   ├─ Ideal quantity is 24 in Dairy Cooler
   ├─ Count daily (from zone_inventory.count_frequency)
   └─ Trigger reorder when actual < 24