# Hotel Manager (PMS) — 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 Hotel Manager (PMS) feature.

---

## Context

You are working on the **Hotel Manager (PMS)** feature for Champion Spirit API (Laravel 10 / PHP 8.2). This module enables places to operate one or more hotels with full room management, reservation lifecycle, seasonal pricing, housekeeping, extras/room service, checkout/billing, analytics dashboards, and channel manager integration.

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

---

## Architecture Decisions (LOCKED)

These decisions have been validated and must NOT be changed:

| Decision | Detail |
|---|---|
| **Hotel Model** | Standalone model. Place hasMany Hotel. Each hotel has its own config, rooms, rates, extras. |
| **Room Type → Room** | Two-level hierarchy. HotelRoomType defines categories + pricing. HotelRoom is a physical room linked to a type. |
| **HotelReservation** | Standalone model (NOT reusing Booking model). Implements `Orderable` for room charge prepayment. |
| **HotelExtra** | Standalone model. Implements `Orderable`. Charged to a reservation during the stay via HotelReservationExtra. |
| **Cart = Order** | Reuse existing Order model with WAITING_PAYMENT status, same as Shop/Restaurant. |
| **OrderStatus** | Do NOT add new values. Order stays PAID after refund. Same rule as Shop/Restaurant. |
| **Refunds** | Wallet credit-back transaction. No OrderStatus change. Same as Shop/Restaurant. |
| **DESK** | Do NOT touch. Admin-only for pack grants. |
| **POS/CASH** | Reuse existing PaymentProvider values. Same photo requirements as Shop. |
| **Folio pattern** | Charges accumulate in hotel_reservation_extras during stay. At checkout, GenerateFolioAction creates an Order with all unpaid charges. |
| **Pricing** | 3-tier on RoomType (money_price, member_money_price, resort_money_price). Seasonal overrides via HotelSeasonalRate. Rate engine in HotelRateService. |
| **Housekeeping** | Status on HotelRoom (housekeeping_status enum). Status changes logged in HotelHousekeepingLog. Auto-transition: room → DIRTY on checkout. |
| **Channel Manager** | Data structures + sync interface in initial scope. Concrete OTA adapters are future work, outside initial scope. |
| **Cancellation Policy** | Hotel-level config: `free_cancellation_hours` (default 24) + `cancellation_penalty_percentage` (default 100). Penalty = first night rate × penalty %. Refund via wallet credit-back (same as Shop/Restaurant). Manager can waive penalty. |
| **Role: `is_hotel_manager`** | Boolean on `Employee` model, same pattern as `is_shop_manager`. Restaurant uses Spatie role instead — Hotel follows Shop pattern intentionally for consistency with the more recent implementation. |
| **Invoice** | Same as Shop/Restaurant: queued Job, PDF snapshot, not synchronous. |
| **Dashboard cache** | Same as Shop/Restaurant: Redis, pre-compute at midnight, delta calculation during day. |
| **Translations** | Name/description fields on Hotel, HotelRoomType, HotelExtra, HotelSeasonalRate (name only) use HasDatabaseTranslations. |
| **Filament navigation** | Hotel gets a `navigationGroup = 'Hotel'` in Filament sidebar. PlaceResource gets a ManageHotels management page and HotelOccupancyWidget. |

---

## Phase Tracking

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

```
docs/implementation/hotel-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/hotel-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 cote admin doit l'etre cote app, et vice versa.

**Build order:**
1. Phase 1 (Foundation & Schema) — all models, migrations, enums
2. Phase 2 (Room Types & Rooms) — core room management
3. Phase 3 (Rates) + Phase 7 (Housekeeping) — can be parallelized
4. Phase 4 (Reservations) — depends on Phases 2, 3
5. Phase 5 (Check-in/out) — depends on Phase 4
6. Phase 6 (Extras) — depends on Phase 5
7. Phase 8 (Dashboards) — depends on Phases 4, 5, 6
8. Phase 9 (Channel Manager) — depends on Phases 3, 4
9. Phase 10 (Cross-cutting)
10. Phase 11 (Seeder) — last

---

## Quick Reference

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

### Key existing files to reference (Shop/Restaurant Manager as template)
| What | File |
|---|---|
| Shop Manager middleware | `app/Http/Middleware/EnsureShopManagerMiddleware.php` |
| Restaurant Manager middleware | `app/Http/Middleware/EnsureRestaurantManagerMiddleware.php` |
| Shop cart controllers | `app/Http/Controllers/Api/Employee/ShopManager/` |
| Restaurant cart controllers | `app/Http/Controllers/Api/Employee/RestaurantManager/` |
| 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` |
| Restaurant model (reference) | `app/Models/Restaurant.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
```
# Hotel Manager (employee)
/v1/places/{place}/hotels/{hotel}/*
Middleware: auth:sanctum + ability:ABILITY_FULL + EnsureHotelManagerMiddleware

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