# Phase 3: Customer & Cart Management

## Objective
Enable vendors to manage multiple simultaneous carts for different customers, add/remove products (manually or via barcode), and create new customers on the spot.

---

## Context from Screenshots

The Cart screen shows:
- **Tab bar** at top with customer names + item count per cart (e.g., "Fabrice AFUTA - 2 items", "Staging User 1001 - 7 items")
- **Active cart** shows customer avatar, name, email
- **"Change customer"** and **"Edit products"** buttons
- **Product list** with name, description, quantity controls (+/-), price per item
- **"Remove"** button per item
- **Bottom bar** with total amount + total items count + "Checkout" button

---

## Tasks

### 3.1 List Active Carts

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

- `GET /v1/places/{place}/shop/carts`
- Returns all orders with `status = WAITING_PAYMENT` created by this employee at this place
- Each cart includes: customer info, item count, total amount

**Response:**
```json
{
  "data": [
    {
      "id": "cart_public_id",
      "customer": {
        "id": "user_public_id",
        "name": "Fabrice AFUTA",
        "email": "fabrice@example.com",
        "avatar_url": "..."
      },
      "items_count": 2,
      "total": { "amount": 4000, "currency": "USD" }
    }
  ]
}
```

### 3.2 Create Cart

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

- `POST /v1/places/{place}/shop/carts`
- Body: `{ "customer_id": "user_public_id" }`
- Creates a new Order with `status = WAITING_PAYMENT`, `employee_id`, `place_id`, `user_id`
- Returns the new cart

**Request:** `app/Http/Requests/ShopManager/CreateCartRequest.php`

### 3.3 Show Cart

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

- `GET /v1/places/{place}/shop/carts/{order}`
- Returns full cart with all items, quantities, prices, customer info

**Response per item:**
```json
{
  "id": "order_item_public_id",
  "product": {
    "id": "product_public_id",
    "name": "Kore PVC 16 Kg Home Gym Set...",
    "description": "16 kg of PVC weight...",
    "image_url": "..."
  },
  "variation": {
    "id": "variation_public_id",
    "name": "Black"
  },
  "quantity": 4,
  "unit_price": { "amount": 1000, "currency": "USD" },
  "total_price": { "amount": 4000, "currency": "USD" }
}
```

### 3.4 Update Cart (Add/Remove/Update Items)

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

- `PUT /v1/places/{place}/shop/carts/{order}`
- Reuses existing `UpsertOrderAction` pattern
- Body contains full item list:
```json
{
  "items": [
    {
      "product_id": "product_public_id",
      "variation_id": "variation_public_id",
      "quantity": 4
    },
    {
      "product_id": "another_product_public_id",
      "variation_id": "variation_public_id",
      "quantity": 3
    }
  ]
}
```

**Request:** `app/Http/Requests/ShopManager/UpdateCartRequest.php`

### 3.5 Add Single Item to Cart

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

- `POST /v1/places/{place}/shop/carts/{order}/items`
- Quick-add a product (by ID or barcode scan)
- If product already in cart, increment quantity
- Body:
```json
{
  "product_id": "product_public_id",
  "variation_id": "variation_public_id",
  "quantity": 1
}
```

**Alternative barcode flow:**
```json
{
  "barcode": "5391029384757",
  "quantity": 1
}
```

### 3.6 Remove Cart Item

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

- `DELETE /v1/places/{place}/shop/carts/{order}/items/{item}`
- Removes the OrderItem from the cart

### 3.7 Update Item Quantity

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

- `PATCH /v1/places/{place}/shop/carts/{order}/items/{item}`
- Body: `{ "quantity": 5 }`
- Updates the quantity in metadata and recalculates price

### 3.8 Change Cart Customer

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

- `POST /v1/places/{place}/shop/carts/{order}/customer`
- Body: `{ "customer_id": "user_public_id" }`
- Updates `order.user_id`
- Validates the order is still in WAITING_PAYMENT

### 3.9 Delete Cart

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

- `DELETE /v1/places/{place}/shop/carts/{order}`
- Deletes order and all order items
- Only if status is WAITING_PAYMENT

### 3.10 Search Customers

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

- `GET /v1/places/{place}/shop/customers?search=john`
- Search by name, email, phone
- Returns paginated customer list with avatar

### 3.11 Create Customer On-the-Spot

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

- `POST /v1/places/{place}/shop/customers`
- Body:
```json
{
  "firstname": "John",
  "lastname": "Doe",
  "email": "john@example.com",
  "phone": "+33612345678"
}
```
- Creates a new User with `UserType::CUSTOMER`
- Creates a Wallet for the user
- Returns customer info

**Action:** `app/Actions/ShopManager/CreateQuickCustomerAction.php`

**Request:** `app/Http/Requests/ShopManager/CreateCustomerRequest.php`

### 3.12 Cart Resource

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

Wraps the Order model with vendor-specific presentation.

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

Wraps OrderItem with product details, quantity, pricing.

### 3.13 Tests

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

Test cases:
- [ ] Create cart for a customer
- [ ] List active carts shows only WAITING_PAYMENT orders for this employee
- [ ] Show cart returns full item details
- [ ] Add item to cart (by product ID)
- [ ] Add item to cart (by barcode)
- [ ] Adding duplicate product increments quantity
- [ ] Remove item from cart
- [ ] Update item quantity
- [ ] Change cart customer
- [ ] Delete cart removes order and items
- [ ] Cannot modify a PAID order
- [ ] Cart total is calculated correctly

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

Test cases:
- [ ] Search customers by name
- [ ] Search customers by email
- [ ] Create new customer returns user with wallet
- [ ] Cannot create customer with duplicate email

---

## Files Created/Modified

| Action | File |
|---|---|
| Create | `app/Http/Controllers/Api/Employee/ShopManager/ListCartsController.php` |
| Create | `app/Http/Controllers/Api/Employee/ShopManager/CreateCartController.php` |
| Create | `app/Http/Controllers/Api/Employee/ShopManager/ShowCartController.php` |
| Create | `app/Http/Controllers/Api/Employee/ShopManager/UpdateCartController.php` |
| Create | `app/Http/Controllers/Api/Employee/ShopManager/AddCartItemController.php` |
| Create | `app/Http/Controllers/Api/Employee/ShopManager/RemoveCartItemController.php` |
| Create | `app/Http/Controllers/Api/Employee/ShopManager/UpdateCartItemQuantityController.php` |
| Create | `app/Http/Controllers/Api/Employee/ShopManager/ChangeCartCustomerController.php` |
| Create | `app/Http/Controllers/Api/Employee/ShopManager/DeleteCartController.php` |
| Create | `app/Http/Controllers/Api/Employee/ShopManager/SearchCustomersController.php` |
| Create | `app/Http/Controllers/Api/Employee/ShopManager/CreateCustomerController.php` |
| Create | `app/Actions/ShopManager/CreateQuickCustomerAction.php` |
| Create | `app/Http/Requests/ShopManager/CreateCartRequest.php` |
| Create | `app/Http/Requests/ShopManager/UpdateCartRequest.php` |
| Create | `app/Http/Requests/ShopManager/CreateCustomerRequest.php` |
| Create | `app/Http/Resources/ShopManager/CartResource.php` |
| Create | `app/Http/Resources/ShopManager/CartItemResource.php` |
| Modify | `routes/api.php` |
| Create | `tests/Feature/Controllers/ShopManager/CartTest.php` |
| Create | `tests/Feature/Controllers/ShopManager/CustomerTest.php` |

---

## Acceptance Criteria

- [ ] Vendor can manage multiple carts simultaneously
- [ ] Products can be added by ID or barcode
- [ ] Quantity controls work (+/- and direct set)
- [ ] Customer can be changed on an existing cart
- [ ] New customers can be created inline
- [ ] Cart totals are accurate
- [ ] Swagger annotations on all controllers
- [ ] All tests pass
- [ ] `./gitCheck.sh` passes