# Phase 7 + 8: Inventory & Orders History — Completion Log

## Date Completed
2026-03-12

## Files Created
| File | Purpose |
|---|---|
| `app/Http/Controllers/Api/Employee/ShopManager/Dashboard/InventoryAlertsController.php` | Low-stock/out-of-stock product alerts endpoint |
| `app/Http/Controllers/Api/Employee/ShopManager/AdjustStockController.php` | Stock adjustment endpoint (refill/correction/return/damaged) |
| `app/Http/Requests/ShopManager/AdjustStockRequest.php` | Validation for stock adjustment (variation_id, type, quantity, note) |
| `app/Actions/ShopManager/AdjustStockAction.php` | Creates ProductVariationStock entry + activity log on Product |
| `app/Http/Controllers/Api/Employee/ShopManager/ListOrdersController.php` | Paginated vendor order list with period/customer/status/type filters |
| `app/Http/Controllers/Api/Employee/ShopManager/ShowOrderController.php` | Full order detail with 403 guard for other employees' orders |
| `app/Http/Resources/ShopManager/VendorOrderResource.php` | List resource (order_number, type_label, customer, total) |
| `app/Http/Resources/ShopManager/VendorOrderDetailResource.php` | Detail resource (items, payment info, invoice status, notes, refund info) |
| `tests/Feature/Controllers/ShopManager/InventoryTest.php` | 14 tests for inventory alerts, reorder status, stock adjustments |
| `tests/Feature/Controllers/ShopManager/OrdersHistoryTest.php` | 13 tests for order listing, filtering, detail, access control |

## Files Modified
| File | Change |
|---|---|
| `app/Models/ProductVariation.php` | Added `currentStock()` method, `current_stock` attribute, `reorder_status` accessor (out_of_stock/low/warning/healthy), `@property-read` docblocks |
| `routes/api.php` | Added 4 routes: stock adjust, inventory alerts, list orders, show order + 3 new use statements |

## Migrations
No new migrations (low_stock_threshold already created in Phase 10 migration).

## Tests Written
| Test File | Test Count | All Pass? |
|---|---|---|
| `tests/Feature/Controllers/ShopManager/InventoryTest.php` | 14 | Yes |
| `tests/Feature/Controllers/ShopManager/OrdersHistoryTest.php` | 13 | Yes |
| **All Shop Manager tests combined** | **79** | **Yes (221 assertions)** |

## Swagger Docs
- [x] All new controllers have @OA\ annotations (InventoryAlertsController, AdjustStockController, ListOrdersController, ShowOrderController)

## Quality Checks
- [ ] `./gitCheck.sh` — NOT run (crashes server due to system load)
- [x] All 79 Shop Manager tests pass (221 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/dashboard/inventory-alerts` | InventoryAlertsController |
| POST | `/v1/places/{place}/shop/products/{product}/stock` | AdjustStockController |
| GET | `/v1/places/{place}/shop/orders` | ListOrdersController |
| GET | `/v1/places/{place}/shop/orders/{order}` | ShowOrderController |

## Commits
Not yet committed — awaiting user instruction.

## Notes / Deviations from Plan
- Phase 7 doc suggested a migration for `low_stock_threshold` but it was already created in Phase 10 (`2026_07_01_000002_add_shop_manager_product_fields.php`).
- `AdjustStockAction` logs activity on the `Product` model (not `ProductVariation`) because `ProductVariation` has no morph map entry. The variation_id is stored in the activity properties.
- `ListOrdersController` uses `items` wrapper via project's `ResourceCollection::wrap('items')` convention.
- `VendorOrderResource.type_label` computed from dominant orderable type in order items (e.g. "Product", "Service").
- `ShowOrderController` returns 403 (not 404) when accessing another employee's order at the same place, to distinguish from "order not found".
- `PaymentProvider` enum values are lowercase (`pos`, `cash`, etc.) — tests assert accordingly.
- Reorder status levels: `out_of_stock` (stock <= 0), `low` (stock <= threshold), `warning` (stock <= threshold*2), `healthy` (stock > threshold*2).

## Blockers / Open Questions
None. Ready for Phase 4 (Payments) per build order.