# Phase 9: Channel Manager

## Objective
Implement the channel manager framework for OTA integration (Booking.com, Airbnb, Expedia). This phase focuses on data structures, sync interface, and configuration — concrete OTA API adapters are future work.

---

## Tasks

### 9.1 Filament — Channel Mappings

**File:** `app/Filament/Resources/HotelResource/RelationManagers/ChannelMappingsRelationManager.php`

CRUD for channel mappings:
- Form: channel (enum), room_type (select), external_property_id, external_room_type_id, sync_rates, sync_availability, sync_reservations, is_active
- Table: channel, room_type, external IDs, sync flags, last_synced_at, is_active
- Actions: Toggle active, Trigger sync

### 9.2 Channel Sync Interface

**File:** `app/Interface/HotelChannelDriverInterface.php`

```php
interface HotelChannelDriverInterface
{
    /** Push available room count for date range to OTA */
    public function pushAvailability(
        HotelChannelMapping $mapping,
        CarbonImmutable $from,
        CarbonImmutable $to,
        int $availableRooms,
    ): bool;

    /** Push nightly rate to OTA */
    public function pushRate(
        HotelChannelMapping $mapping,
        CarbonImmutable $date,
        Money $rate,
    ): bool;

    /** Pull new/updated reservations from OTA */
    public function pullReservations(
        HotelChannelMapping $mapping,
        CarbonImmutable $since,
    ): Collection;

    /** Get channel connection status */
    public function getConnectionStatus(HotelChannelMapping $mapping): bool;
}
```

### 9.3 HotelChannelService

**File:** `app/Services/HotelManager/HotelChannelService.php`

```php
final class HotelChannelService
{
    /** Sync availability for all active mappings of a hotel */
    public function syncAvailability(Hotel $hotel, CarbonImmutable $from, CarbonImmutable $to): array;

    /** Sync rates for all active mappings of a hotel */
    public function syncRates(Hotel $hotel, CarbonImmutable $from, CarbonImmutable $to): array;

    /** Import reservations from all active channels */
    public function importReservations(Hotel $hotel): Collection;

    /** Get driver instance for a channel type */
    public function getDriver(HotelChannelType $channel): HotelChannelDriverInterface;

    /** Log sync result */
    public function logSync(HotelChannelMapping $mapping, string $action, bool $success, ?string $error = null): void;
}
```

### 9.4 Stub Driver (for testing)

**File:** `app/Services/HotelManager/ChannelDrivers/StubChannelDriver.php`

A no-op implementation for testing and development. Returns success for all operations.

### 9.5 Sync Jobs

**File:** `app/Jobs/SyncHotelChannelAvailabilityJob.php`

Queued job to push availability updates. Dispatched:
- After reservation created/updated/cancelled
- After room status change
- Via manual sync trigger

**File:** `app/Jobs/ImportHotelChannelReservationsJob.php`

Queued job to pull reservations. Dispatched:
- On scheduled interval (every 15 min)
- Via manual sync trigger

### 9.6 API — Channel Manager Endpoints

#### ListChannelsController
```
GET /v1/places/{place}/hotels/{hotel}/channels
```
Returns all channel mappings with sync status, last synced timestamp.

#### TriggerChannelSyncController
```
POST /v1/places/{place}/hotels/{hotel}/channels/sync
Body: channel (optional — sync specific channel or all)
```
Dispatches sync jobs. Returns accepted (202).

#### ListChannelLogsController
```
GET /v1/places/{place}/hotels/{hotel}/channels/{channel}/logs
Query: page, size
```
Returns sync history logs.

### 9.7 Artisan Commands

**File:** `app/Console/Commands/SyncHotelChannelsCommand.php`

```bash
php artisan hotel:channels:sync
```

Scheduled every 15 minutes. Syncs availability + pulls reservations for all active channel mappings.

### 9.8 Channel Sync Log Model (optional — could use activity_log)

For channel sync logging, use Spatie ActivityLog on HotelChannelMapping model rather than a dedicated table. Log properties include: action, success, error, items_count.

### 9.9 Resources

- `HotelChannelMappingResource` — Channel mapping with sync status
- `HotelChannelLogResource` — Sync log entry

### 9.10 Tests

**File:** `tests/Feature/Controllers/HotelManager/ChannelManagerTest.php`

- [ ] Manager can list channel mappings
- [ ] Manager can trigger manual sync
- [ ] Manager can view sync logs
- [ ] Sync job dispatches correctly
- [ ] Stub driver returns success
- [ ] Imported reservations have correct source set
- [ ] Availability push triggered after reservation change

---

## Acceptance Criteria

- [ ] Filament channel mappings CRUD functional
- [ ] Channel driver interface defined
- [ ] Stub driver operational for testing
- [ ] All 3 API endpoints functional
- [ ] Sync jobs dispatch correctly
- [ ] Scheduled command registered
- [ ] Activity logging captures sync operations
- [ ] All Swagger annotations present
- [ ] All tests pass
- [ ] Pint + PHPStan pass on new/modified files