# Phase 7: Housekeeping — DONE

**Completed:** 2026-03-16

## Summary

Room housekeeping status management with validated state transitions, task prioritization based on arrivals, Filament admin housekeeping page with quick-action buttons, 3 API endpoints, and comprehensive Pest tests.

## Files Created

### Actions (1)
- `app/Actions/HotelManager/UpdateHousekeepingStatusAction.php` — Validates state transitions (DIRTY→IN_PROGRESS, IN_PROGRESS→CLEAN, etc.), updates room status, creates HotelHousekeepingLog with started_at/completed_at timestamps. Static `isValidTransition()` helper for UI visibility checks.

### Filament Admin (2)
- `app/Filament/Resources/HotelResource/Pages/HotelHousekeeping.php` — Custom page with table of all rooms showing housekeeping status (color-coded badges), quick-action buttons for valid transitions, filters by floor/room type/status.
- `resources/views/filament/resources/hotel-resource/pages/hotel-housekeeping.blade.php` — Blade template for housekeeping page.

### API Resources (2)
- `app/Http/Resources/HotelManager/HotelHousekeepingDashboardResource.php` — Dashboard with summary counts + room list.
- `app/Http/Resources/HotelManager/HotelHousekeepingTaskResource.php` — Task with priority (HIGH/MEDIUM/LOW), arrival flag, checkout time.

### Form Requests (1)
- `app/Http/Requests/HotelManager/UpdateHousekeepingRequest.php` — Validates status (HotelHousekeepingStatus enum) and optional notes.

### Hotel Manager Controllers (3)
- `app/Http/Controllers/Api/Employee/HotelManager/HousekeepingDashboardController.php` — GET `/manage/housekeeping` — Summary counts per status + room list with filters (floor, room_type_id, housekeeping_status).
- `app/Http/Controllers/Api/Employee/HotelManager/UpdateHousekeepingStatusController.php` — PATCH `/manage/rooms/{room}/housekeeping` — Update status with transition validation, creates log entry with employee tracking.
- `app/Http/Controllers/Api/Employee/HotelManager/ListHousekeepingTasksController.php` — GET `/manage/housekeeping/tasks` — Dirty/in-progress rooms sorted by priority (HIGH: dirty + arrival today, MEDIUM: dirty or in-progress, LOW: other).

### Tests (1)
- `tests/Feature/Controllers/HotelManager/HousekeepingTest.php` — 8 tests covering dashboard summary, status updates, log creation, invalid transition rejection, task prioritization, arrival-based priority, started_at/completed_at timestamps.

## Files Modified

- `app/Filament/Resources/HotelResource.php` — Added HotelHousekeeping page registration.
- `routes/api.php` — Added 3 housekeeping routes under `/manage` prefix.

## API Routes

### Hotel Manager (requires `hotel_manager` role + place attachment)
| Method | URL | Controller |
|--------|-----|-----------|
| GET | `/v1/places/{place}/hotels/{hotel}/manage/housekeeping` | HousekeepingDashboardController |
| GET | `/v1/places/{place}/hotels/{hotel}/manage/housekeeping/tasks` | ListHousekeepingTasksController |
| PATCH | `/v1/places/{place}/hotels/{hotel}/manage/rooms/{room}/housekeeping` | UpdateHousekeepingStatusController |

## Valid Housekeeping Transitions

```
DIRTY → IN_PROGRESS, OUT_OF_ORDER
IN_PROGRESS → CLEAN, DIRTY (reset), OUT_OF_ORDER
CLEAN → INSPECTED, DIRTY, OUT_OF_ORDER
INSPECTED → DIRTY, OUT_OF_ORDER
OUT_OF_ORDER → DIRTY
```

## Quality Checks

- **Pint:** PASS (0 issues after auto-fix)
- **PHPStan level 7:** PASS (0 errors)
- **Pest tests:** 51 passing (18 Phase 1 + 14 Phase 2 + 11 Phase 3 + 8 Phase 7)

## Design Decisions

- **Transition validation**: Strict state machine in `UpdateHousekeepingStatusAction` with `VALID_TRANSITIONS` map. Invalid transitions return 422 with descriptive message.
- **Task prioritization**: Three-level priority system — HIGH (dirty room with today's arrival), MEDIUM (dirty or in-progress), LOW (fallback). Tasks sorted by priority then room number.
- **Filament quick-actions**: Dynamic action buttons based on `isValidTransition()` — only valid transitions appear as clickable buttons per room.
- **Employee tracking**: All housekeeping status changes log the employee who made the change via the authenticated user's employee relation.
- **Auto-transition on checkout**: Documented as Phase 5 concern (CheckOutGuestAction sets room → DIRTY). This phase provides the infrastructure and manual controls.

## Notes

- No commits created — user will commit manually.
- Swagger annotations present on all 3 new controllers.