# Phase 2: Product API for Vendors

## Objective
Provide vendor-facing product endpoints with search, barcode lookup, active/inactive toggle, and product detail pages with sales stats.

---

## Tasks

### 2.1 Barcode Field on Product/ProductVariation

Check if `barcode` already exists on `Product` or `ProductVariation`. From the screenshots, the product detail shows a barcode (e.g., `5391029384757`).

**If missing, create migration:**
```
database/migrations/YYYY_MM_DD_HHMMSS_add_barcode_to_product_variations_table.php
```

Add:
- `barcode` (string, nullable, indexed) on `product_variations` table

### 2.2 Active Toggle on Product

Check if `is_active` exists on Product. If not:

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

Add:
- `is_active` (boolean, default true) on `products` table

### 2.3 List Products Controller (Vendor-facing)

**File:** `app/Http/Controllers/Api/Employee/ShopManager/ListProductsController.php`

Features:
- Paginated list of products for the place
- Search by name (existing pattern)
- Filter by category
- Include: stock count, total sold, active status
- Sort by name, price, sold count

**Response fields per product (from screenshots):**
```json
{
  "id": "public_id",
  "name": "Champion Spirit Cap",
  "category": { "id": "...", "name": "GEAR" },
  "price": { "amount": 2800, "currency": "EUR" },
  "total_sold": 1200,
  "stock_remaining": 24,
  "is_active": true,
  "image_url": "..."
}
```

### 2.4 Product Detail Controller

**File:** `app/Http/Controllers/Api/Employee/ShopManager/ShowProductController.php`

Returns detailed product info with stats:
```json
{
  "id": "public_id",
  "name": "Club Hoodie",
  "sku": "WP-DRK-02-57",
  "category": { "name": "Apparel" },
  "badge": "TOP PERFORMER",
  "stock": 18,
  "total_sold": 500,
  "total_revenue": { "amount": 2930000, "currency": "USD" },
  "sales_performance": {
    "weekly_units": 144,
    "daily_breakdown": [
      { "day": "MON", "units": 5 },
      { "day": "TUE", "units": 7 }
    ]
  },
  "inventory_snapshot": {
    "current_stock": 18,
    "reorder_status": "healthy",
    "barcode": "5391029384757",
    "rating": 4.6
  },
  "latest_feedback": {
    "text": "Great quality...",
    "author": "James K.",
    "badge": "Verified Buyer",
    "total_comments": 58
  }
}
```

### 2.5 Barcode Lookup Controller

**File:** `app/Http/Controllers/Api/Employee/ShopManager/LookupProductByBarcodeController.php`

- `GET /v1/places/{place}/shop/products/barcode/{code}`
- Lookup `ProductVariation` by barcode within the place
- Return product + variation details
- Return 404 if not found

### 2.6 Toggle Product Active Controller

**File:** `app/Http/Controllers/Api/Employee/ShopManager/ToggleProductActiveController.php`

- `PATCH /v1/places/{place}/shop/products/{product}/toggle`
- Toggle `is_active` boolean
- Return updated product

### 2.7 Vendor Product Resource

**File:** `app/Http/Resources/ShopManager/VendorProductResource.php`

Extends or wraps `ProductResource` with additional vendor-specific fields:
- `total_sold`, `stock_remaining`, `is_active`, `sales_performance`

### 2.8 Tests

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

Test cases:
- [ ] List products returns paginated results for the place
- [ ] Search by name works
- [ ] Filter by category works
- [ ] Barcode lookup returns correct product
- [ ] Barcode lookup returns 404 for unknown barcode
- [ ] Toggle active/inactive works
- [ ] Product detail includes sales stats
- [ ] Non-shop-manager gets 403

---

## Files Created/Modified

| Action | File |
|---|---|
| Create | `database/migrations/..._add_barcode_to_product_variations_table.php` (if needed) |
| Create | `database/migrations/..._add_is_active_to_products_table.php` (if needed) |
| Create | `app/Http/Controllers/Api/Employee/ShopManager/ListProductsController.php` |
| Create | `app/Http/Controllers/Api/Employee/ShopManager/ShowProductController.php` |
| Create | `app/Http/Controllers/Api/Employee/ShopManager/LookupProductByBarcodeController.php` |
| Create | `app/Http/Controllers/Api/Employee/ShopManager/ToggleProductActiveController.php` |
| Create | `app/Http/Resources/ShopManager/VendorProductResource.php` |
| Modify | `routes/api.php` |
| Create | `tests/Feature/Controllers/ShopManager/ProductsTest.php` |

---

## Acceptance Criteria

- [ ] Products are listed with stock and sales data
- [ ] Barcode scan resolves to the correct product
- [ ] Toggle active/inactive persists
- [ ] Product detail page data matches screenshot requirements
- [ ] Swagger annotations on all controllers
- [ ] All tests pass
- [ ] `./gitCheck.sh` passes