# Phase 3: Cart & Customers — Completion Log

## Date Completed
2026-03-12

## Files Created
| File | Purpose |
|---|---|
| `app/Http/Controllers/Api/Employee/ShopManager/ListCartsController.php` | List active carts (WAITING_PAYMENT) for this employee |
| `app/Http/Controllers/Api/Employee/ShopManager/CreateCartController.php` | Create new cart for a customer |
| `app/Http/Controllers/Api/Employee/ShopManager/ShowCartController.php` | Show cart detail with all items |
| `app/Http/Controllers/Api/Employee/ShopManager/UpdateCartController.php` | Full replace of all cart items |
| `app/Http/Controllers/Api/Employee/ShopManager/DeleteCartController.php` | Delete cart and all items (WAITING_PAYMENT only) |
| `app/Http/Controllers/Api/Employee/ShopManager/AddCartItemController.php` | Add item by product_id/variation_id or barcode, auto-increments duplicates |
| `app/Http/Controllers/Api/Employee/ShopManager/RemoveCartItemController.php` | Remove a single item from cart |
| `app/Http/Controllers/Api/Employee/ShopManager/UpdateCartItemQuantityController.php` | Update item quantity (0 removes item) |
| `app/Http/Controllers/Api/Employee/ShopManager/ChangeCartCustomerController.php` | Change customer on existing cart |
| `app/Http/Controllers/Api/Employee/ShopManager/SearchCustomersController.php` | Search customers by name/email/phone |
| `app/Http/Controllers/Api/Employee/ShopManager/CreateCustomerController.php` | Create customer on the spot with wallet |
| `app/Http/Resources/ShopManager/CartResource.php` | Cart resource (customer info, items_count, total) |
| `app/Http/Resources/ShopManager/CartItemResource.php` | Cart item resource (product, variation, quantity, prices) |
| `app/Http/Requests/ShopManager/CreateCartRequest.php` | Validates customer_id |
| `app/Http/Requests/ShopManager/UpdateCartRequest.php` | Validates items array with product_id, variation_id, quantity |
| `app/Http/Requests/ShopManager/AddCartItemRequest.php` | Validates product_id+variation_id or barcode |
| `app/Http/Requests/ShopManager/UpdateCartItemQuantityRequest.php` | Validates quantity (min:0) |
| `app/Http/Requests/ShopManager/ChangeCartCustomerRequest.php` | Validates customer_id |
| `app/Http/Requests/ShopManager/CreateCustomerRequest.php` | Validates firstname, lastname, email (unique), phone |
| `app/Actions/ShopManager/CreateQuickCustomerAction.php` | Creates User + Wallet in transaction |
| `tests/Feature/Controllers/ShopManager/CartTest.php` | 20 tests for cart CRUD and item management |
| `tests/Feature/Controllers/ShopManager/CustomerTest.php` | 7 tests for search and create customer |

## Files Modified
| File | Change |
|---|---|
| `routes/api.php` | Added 11 cart/customer routes under shop manager group |

## Migrations
No new migrations (Order already has employee_id, place_id, status fields).

## Tests Written
| Test File | Test Count | All Pass? |
|---|---|---|
| `tests/Feature/Controllers/ShopManager/CartTest.php` | 20 | Yes |
| `tests/Feature/Controllers/ShopManager/CustomerTest.php` | 7 | Yes |

## Swagger Docs
- [x] All new controllers have @OA\ annotations

## Quality Checks
- [x] All 52 Shop Manager tests pass (130 assertions)
- [x] No dd(), dump(), var_dump() in code
- [x] All classes are final
- [x] All files have declare(strict_types=1)
- [x] public_id used in API (never id)

## API Endpoints
| Method | Path | Controller |
|---|---|---|
| GET | `/v1/places/{place}/shop/carts` | ListCartsController |
| POST | `/v1/places/{place}/shop/carts` | CreateCartController |
| GET | `/v1/places/{place}/shop/carts/{order}` | ShowCartController |
| PUT | `/v1/places/{place}/shop/carts/{order}` | UpdateCartController |
| DELETE | `/v1/places/{place}/shop/carts/{order}` | DeleteCartController |
| POST | `/v1/places/{place}/shop/carts/{order}/items` | AddCartItemController |
| PATCH | `/v1/places/{place}/shop/carts/{order}/items/{item}` | UpdateCartItemQuantityController |
| DELETE | `/v1/places/{place}/shop/carts/{order}/items/{item}` | RemoveCartItemController |
| POST | `/v1/places/{place}/shop/carts/{order}/customer` | ChangeCartCustomerController |
| GET | `/v1/places/{place}/shop/customers` | SearchCustomersController |
| POST | `/v1/places/{place}/shop/customers` | CreateCustomerController |

## Commits
Not yet committed — user requested no commits.

## Notes / Deviations from Plan
- Cart items use `OrderItem::makeFor()` for price calculation, reusing existing orderable pricing logic.
- Adding a duplicate product+variation to cart auto-increments quantity rather than creating a new item.
- Quantity=0 on update removes the item (as specified in test plan).
- ListCarts returns a flat `data` array (not paginated) since active carts are typically few.
- SearchCustomers returns paginated results using `items` wrapper (project convention via `ResourceCollection::wrap('items')`).
- CreateQuickCustomerAction sets `lang: 'fr'` as required by users table schema.

## Bugs Fixed During Phase 3
- Fixed `.env.testing` DB port (3307 -> 3306) and created missing `tests` database.
- Fixed `ListProductsController::computeTotalSold()` — was referencing non-existent `order_items.quantity` column, changed to `JSON_EXTRACT(metadata, '$.quantity')`.
- Fixed `ShowProductController` — same `quantity` column issue in sales/weekly breakdown queries.
- Fixed `ProductsTest` — used `'data'` wrapper but project uses `'items'` (via `ResourceCollection::wrap('items')` in AppServiceProvider).
- Created missing `ProductFactory` and `ProductVariationStockFactory`.

## Blockers / Open Questions
None. Ready for Phase 7 (Inventory) + Phase 8 (Orders History) per build order.