# Phase 7: Inventory & Alerts

## Objective
Provide inventory visibility: current stock levels, low-stock alerts, reorder status. Powers the "Inventory Alerts" section on the dashboard and the product detail's Inventory Snapshot.

---

## Context from Screenshots

**Dashboard - Inventory Alerts banner:**
- "4 Low-Stock Items" with warning icon

**Product Detail - Inventory Snapshot:**
- Current stock: 18 units
- Reorder status: Healthy
- Barcode: 5391029384757
- Rating: 4.6

---

## Existing Infrastructure

The codebase already has:
- `ProductVariation` model with pricing
- `ProductVariationStock` model with `quantity`, `start_at`, `end_at` (time-bound inventory)
- Product → ProductVariation → ProductVariationStock chain

---

## Tasks

### 7.1 Low-Stock Threshold Configuration

**Option A:** Add to Place model/config:
```php
// On Place or a new place_settings JSON
'low_stock_threshold' => 5,  // Default
```

**Option B:** Add to Product/ProductVariation:
```php
$table->integer('low_stock_threshold')->default(5);
```

Recommendation: **Per-product threshold** stored on `ProductVariation` (Option B) with a Place-level default fallback.

**Migration:** `database/migrations/YYYY_MM_DD_HHMMSS_add_low_stock_threshold_to_product_variations.php`

### 7.2 Reorder Status Logic

Computed attribute on ProductVariation:

```php
public function getReorderStatusAttribute(): string
{
    $stock = $this->currentStock();
    $threshold = $this->low_stock_threshold;

    if ($stock <= 0) return 'out_of_stock';
    if ($stock <= $threshold) return 'low';
    if ($stock <= $threshold * 2) return 'warning';
    return 'healthy';
}
```

### 7.3 Inventory Alerts Endpoint

**Controller:** `app/Http/Controllers/Api/Employee/ShopManager/Dashboard/InventoryAlertsController.php`

- `GET /v1/places/{place}/shop/dashboard/inventory-alerts`
- Returns low-stock and out-of-stock products:
```json
{
  "low_stock_count": 4,
  "items": [
    {
      "id": "product_public_id",
      "name": "Grip Socks",
      "variation": "Default",
      "category": "Supplement",
      "current_stock": 4,
      "threshold": 5,
      "reorder_status": "low",
      "image_url": "..."
    }
  ]
}
```

**Logic:**
- Query all ProductVariations for the place
- Filter where current stock <= low_stock_threshold
- Order by stock ASC (most critical first)

### 7.4 Product Stock Summary (used by Phase 2)

Add helper methods to Product model:
```php
public function getTotalStockAttribute(): int
{
    return $this->variations->sum(fn ($v) => $v->currentStock());
}

public function getTotalSoldAttribute(): int
{
    // Count OrderItems where orderable = this product, order = PAID
}
```

### 7.5 Tests

**File:** `tests/Feature/Controllers/ShopManager/InventoryTest.php`

Test cases:
- [ ] Inventory alerts returns only low-stock products
- [ ] Out-of-stock products are included
- [ ] Products above threshold are not included
- [ ] Reorder status is computed correctly for each level
- [ ] Empty inventory returns zero count, empty array
- [ ] Custom threshold per product is respected

---

## Files Created/Modified

| Action | File |
|---|---|
| Create | `database/migrations/..._add_low_stock_threshold_to_product_variations.php` |
| Modify | `app/Models/ProductVariation.php` (reorder status accessor) |
| Modify | `app/Models/Product.php` (total stock/sold accessors) |
| Create | `app/Http/Controllers/Api/Employee/ShopManager/Dashboard/InventoryAlertsController.php` |
| Modify | `routes/api.php` |
| Create | `tests/Feature/Controllers/ShopManager/InventoryTest.php` |

---

## Acceptance Criteria

- [ ] Low-stock items are detected based on threshold
- [ ] Reorder status is computed correctly (out_of_stock, low, warning, healthy)
- [ ] Dashboard banner shows correct count
- [ ] Product detail shows inventory snapshot
- [ ] Swagger annotations on controller
- [ ] All tests pass
- [ ] `./gitCheck.sh` passes