# Restaurant 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 Restaurant Manager feature.

---

## Context

You are working on the **Restaurant Manager** feature for Champion Spirit API (Laravel 10 / PHP 8.2). This module enables places to operate one or more restaurants with full menu management, table reservations, dine-in checkout, customer pre-ordering, and analytics dashboards.

**Read these files first (in order):**
1. `docs/AGENT_INIT.md` — Project-wide coding rules (strict_types, final classes, public_id, etc.)
2. `docs/implementation/restaurant-manager/00-MASTER-PLAN.md` — Full scope, models, endpoints

---

## Architecture Decisions (LOCKED)

These decisions have been validated and must NOT be changed:

| Decision | Detail |
|---|---|
| **Restaurant Model** | Standalone model. Place hasMany Restaurant. Each restaurant has its own config, hours, tables, menus. |
| **RestaurantMenuItem** | Implements `Orderable` interface. Polymorphic orderable in OrderItem. 3-tier pricing like Service/Product. |
| **RestaurantReservation** | Standalone model (NOT reusing Booking model). Implements `Orderable` for optional paid reservations. |
| **Cart = Order** | Reuse existing Order model with WAITING_PAYMENT status, same as Shop Manager. |
| **OrderStatus** | Do NOT add new values. Order stays PAID after refund. Same rule as Shop. |
| **Refunds** | Wallet credit-back transaction. No OrderStatus change. Same as Shop. |
| **DESK** | Do NOT touch. Admin-only for pack grants. |
| **POS/CASH** | Reuse existing PaymentProvider values. Same photo requirements as Shop. |
| **Tips** | Stored on Order model (tip_amount + tip_currency). Added at checkout, separate from item total. |
| **Service Periods** | Enum-based. Menus are scoped to service periods. Each restaurant configures its own period time ranges. |
| **Allergens** | EU 14 regulatory allergens as PHP enum. Stored as JSON array on RestaurantMenuItem. |
| **Multi-table** | Pivot table `restaurant_reservation_tables`. No complex floor plan — just number + zone. |
| **Menu Variants** | NO item variants. One item = one price. Keep it simple. |
| **Cover/Service Charge** | NOT implemented. No automatic surcharges. |
| **Kitchen Display** | NOT implemented. Out of scope. |
| **Invoice** | Same as Shop: queued Job, PDF snapshot, not synchronous. |
| **Dashboard cache** | Same as Shop: Redis, pre-compute at midnight, delta calculation during day. |
| **Pagination** | Laravel standard format (data/links/meta), NOT custom format. |
| **Translations** | Name/description fields on Restaurant, Category, MenuItem, Menu, MenuSection use HasDatabaseTranslations. |
| **Existing RestaurantRevenue model** | Legacy model. Mark as `@deprecated`. Remove its Filament RelationManager and ManagementPage from PlaceResource. New restaurant module replaces it entirely. |
| **Filament navigation** | Restaurant gets a `navigationGroup = 'Restaurant'` in Filament sidebar (same pattern as Shop). PlaceResource gets a ManageRestaurants management page and RestaurantWidget (same pattern as Shop's ManageRestaurantRevenues page and ShopSalesWidget). |

---

## Phase Tracking

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

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

Use the same template as Shop Manager (see `docs/implementation/shop-manager/AGENT_INIT.md`).

**IMPORTANT — Quality checks:**
- Do **NOT** run `./gitCheck.sh` (breaks the environment)
- Do **NOT** create commits automatically
- Instead, after each phase, run lint and phpstan **only on new/modified files**:
```bash
# Lint only changed files
vendor/bin/pint path/to/file1.php path/to/file2.php

# PHPStan only changed files
vendor/bin/phpstan analyse path/to/file1.php path/to/file2.php --level=7
```
- Fix any errors before considering the phase complete
- The user will commit manually

---

## Current Progress

Check `docs/implementation/restaurant-manager/logs/` to see which phases are done. If the folder is empty, start from Phase 1.

**Principe fondamental : Filament et API sont des miroirs.** Chaque phase livre le Filament admin ET l'API mobile ensemble. Tout ce qui est faisable côté admin doit l'être côté app, et vice versa.

**Build order:**
1. Phase 1 (Foundation & Schema) — all models, migrations, enums
2. Phase 2 (Menu System) + Phase 3 (Tables) — can be parallelized, each includes Filament + API
3. Phase 4 (Reservations) — Filament + Manager API + Customer API
4. Phase 5 (Cart & Checkout) — Filament + Manager API + Customer pre-order
5. Phase 6 (Dashboards) — Filament widgets + Manager API
6. Phase 7 (Cross-cutting)
7. Phase 8 (Seeder) — last

---

## Quick Reference

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

### Key existing files to reference (Shop Manager as template)
| What | File |
|---|---|
| Shop Manager middleware | `app/Http/Middleware/EnsureShopManagerMiddleware.php` |
| Shop cart controllers | `app/Http/Controllers/Api/Employee/ShopManager/` |
| Shop dashboard controllers | `app/Http/Controllers/Api/Employee/ShopManager/Dashboard/` |
| Shop dashboard service | `app/Services/ShopManager/DashboardService.php` |
| Shop dashboard cache | `app/Services/ShopManager/DashboardCacheService.php` |
| Order model | `app/Models/Order.php` |
| Service model (Orderable) | `app/Models/Service.php` |
| Booking model (reference) | `app/Models/Booking.php` |
| AdminRole enum | `app/Enums/AdminRole.php` |
| OrderableType enum | `app/Enums/OrderableType.php` |
| PaymentProvider enum | `app/Enums/PaymentProvider.php` |
| Morph maps | `app/Providers/AppServiceProvider.php` |
| API routes | `routes/api.php` |

### New route group prefixes
```
# Restaurant Manager (employee)
/v1/places/{place}/restaurants/{restaurant}/*
Middleware: auth:sanctum + EnsureRestaurantManagerMiddleware

# Customer-facing
/v1/places/{place}/restaurants/*
Middleware: auth:sanctum
```