# Shop Manager — Agent Initialization Script

## How to Use This

Copy-paste this entire document as the first prompt when starting a new agent session to work on the Shop Manager feature.

---

## Context

You are working on the **Shop Manager** feature for Champion Spirit API (Laravel 10 / PHP 8.2). This is a vendor-facing mobile profile that enables employees with the `shop_manager` role to sell products, manage carts, process payments, and view a sales dashboard.

**Read these files first (in order):**
1. `docs/AGENT_INIT.md` — Project-wide coding rules (strict_types, final classes, public_id, etc.)0
---

## Architecture Decisions (LOCKED)

These decisions have been validated and must NOT be changed:

| Decision | Detail |
|---|---|
| **OrderStatus** | Do NOT add new values. Order stays PAID after refund. |
| **Refunds** | Wallet credit-back transaction (WalletPaymentType::REFUND). No OrderStatus change. |
| **DESK** | Do NOT touch. It's admin-only for pack grants. |
| **POS/CASH** | New PaymentProvider enum values. POS needs receipt photo. CASH needs amounts + photo. |
| **Stock validation** | Only for Product orderables (not bookable services). Soft failure on race condition. |
| **Stock decrement** | On OrderPaid listener. If stock=0 race condition → auto-refund wallet credits, log warning. NEVER break listener chain. |
| **Cart cleanup** | 24h TTL, vendor carts only (employee_id IS NOT NULL). |
| **Invoice** | Queued Job, not synchronous. Customer gets instant payment confirmation. |
| **Dashboard cache** | Redis. Pre-compute at midnight. Delta calculation during the day. |
| **Pagination** | Laravel standard format (data/links/meta), NOT custom format. |
| **is_active** | Filter on BOTH vendor and customer product lists. Always visible in Filament. |
| **WalletPaymentType mapping** | POS → CREDIT_CARD, CASH → CASH on wallet transactions. |

---

## Phase Tracking

When you complete a phase, you MUST create a work log file:

```
docs/implementation/shop-manager/logs/PHASE-{N}-DONE.md
```

Use this template:

```markdown
# Phase {N}: {Name} — Completion Log

## Date Completed
YYYY-MM-DD

## Files Created
| File | Purpose |
|---|---|
| `path/to/file.php` | Brief description |

## Files Modified
| File | Change |
|---|---|
| `path/to/file.php` | What changed |

## Migrations
| Migration | Tables/Columns |
|---|---|
| `YYYY_MM_DD_HHMMSS_name.php` | What it creates/modifies |

## Tests Written
| Test File | Test Count | All Pass? |
|---|---|---|
| `tests/Feature/.../SomeTest.php` | N | Yes/No |

## Swagger Docs
- [ ] All new controllers have @OA\ annotations
- [ ] `php artisan l5-swagger:generate` runs without errors

## Quality Checks
- [ ] `./gitCheck.sh` passes (lint + PHPStan)
- [ ] `composer test` passes
- [ ] No dd(), dump(), var_dump() in code
- [ ] All classes are final
- [ ] All files have declare(strict_types=1)
- [ ] public_id used in API (never id)

## Commits
| Hash | Message |
|---|---|
| `abc1234` | `feat(shop-manager): description` |

## Notes / Deviations from Plan
Any decisions made during implementation that differ from the phase doc.

## Blockers / Open Questions
Anything that needs resolution before the next phase.
```

---

## Current Progress

Check `docs/implementation/shop-manager/logs/` to see which phases are done. If the folder doesn't exist, start from Phase 1.

**Build order:**
1. Phase 1 (Foundation) + Phase 10 (Schema/Migrations) — do these first together
2. Phase 2 (Products) + Phase 3 (Cart) — can be parallelized
3. Phase 7 (Inventory) + Phase 8 (Orders History)
4. Phase 4 (Payments)
5. Phase 5 (Invoices)
6. Phase 6 (Dashboard)
7. Phase 9 (Filament) — do incrementally alongside each phase, or at the end

---

## Quick Reference

### Existing patterns to follow
- **Controller pattern:** Single-action `__invoke()` controllers in `app/Http/Controllers/Api/Employee/ShopManager/`
- **Action pattern:** `app/Actions/ShopManager/{Verb}{Subject}Action.php`
- **Request pattern:** `app/Http/Requests/ShopManager/{Action}{Subject}Request.php`
- **Resource pattern:** `app/Http/Resources/ShopManager/{Name}Resource.php`
- **Test pattern:** `tests/Feature/Controllers/ShopManager/{Domain}Test.php`

### Key existing files to reference
| What | File |
|---|---|
| Order model | `app/Models/Order.php` |
| Product model | `app/Models/Product.php` |
| ProductVariation model | `app/Models/ProductVariation.php` |
| UpsertOrderAction | `app/Actions/UpsertOrderAction.php` |
| WalletPayOrderController | `app/Http/Controllers/Api/Orders/WalletPayOrderController.php` |
| StripePayOrderController | `app/Http/Controllers/Api/Orders/StripePayOrderController.php` |
| Employee order controllers | `app/Http/Controllers/Api/Employee/Orders/` |
| EnsureEmployeeOfPlace middleware | `app/Http/Middleware/EnsureEmployeeOfPlace.php` |
| PaymentProvider enum | `app/Enums/PaymentProvider.php` |
| WalletPaymentType enum | `app/Enums/WalletPaymentType.php` |
| AdminRole enum | `app/Enums/AdminRole.php` |
| OrderStatus enum | `app/Enums/OrderStatus.php` |
| API routes | `routes/api.php` |

### New route group prefix
All shop manager endpoints go under:
```
/v1/places/{place}/shop/*
```
With middleware: `auth:sanctum` + `EnsureShopManagerMiddleware`