# Scheduling Feature Flags Documentation

## Overview

The scheduling system uses feature flags to control gradual rollout and enable/disable specific functionality per store.

## Store Configuration

### `schedulingProvider` Column

| Value | Description |
|-------|-------------|
| `none` | Scheduling disabled for this store (default) |
| `wheniwork` | WhenIWork integration active |
| `homebase` | Homebase integration active |
| `buyerkiosk` | Native BuyerKiosk scheduling active |

### `schedulingFeatureFlags` Column (JSON)

Granular feature toggles stored as JSON. Example:

```json
{
  "timeClock": true,
  "scheduleManagement": true,
  "timesheets": false
}
```

## Flag Combinations & Effects

### Provider = `none`
- All scheduling features disabled
- Schedule panel shows "Scheduling not configured" message
- No time clock functionality available

### Provider = `wheniwork` or `homebase`
- External provider handles scheduling
- Workbook time clock/break UI remains available and routes to the external provider API
- Schedule panel displays data from external provider

### Provider = `buyerkiosk`
- All features enabled by default unless explicitly disabled via flags
- Full native scheduling experience

## Feature Flags

| Flag | Default (buyerkiosk) | Default (external) | Effect |
|------|---------------------|-------------------|--------|
| `timeClock` | `true` | `true` | Enables workbook clock in/out and break UI (routes to active provider backend) |
| `scheduleManagement` | `true` | `false` | Enables admin schedule CRUD operations (BuyerKiosk provider only) |
| `timesheets` | `true` | `false` | Enables timesheet dashboard, approval, and export (BuyerKiosk provider only) |

## Usage in Code

```php
use BuyerKiosk\Scheduling\SchedulingFeatureGate;

$featureGate = new SchedulingFeatureGate($store);

// Check if any scheduling is enabled
if ($featureGate->isSchedulingEnabled()) {
    // ...
}

// Check for native provider
if ($featureGate->isNativeSchedulingActive()) {
    // Show full admin UI
}

// Check specific features
if ($featureGate->isTimeClockEnabled()) {
    // Show clock in/out buttons
}

// Get current provider
$provider = $featureGate->getProvider(); // 'none', 'wheniwork', 'homebase', 'buyerkiosk'

// Check if using external provider
if ($featureGate->isExternalProvider()) {
    // Hide admin sections, show external provider data
}
```

## Migration/Rollout Notes

1. **Pilot Store**: Set `schedulingProvider = 'buyerkiosk'` on single test store
2. **Beta Rollout**: Enable for 5 stores, monitor metrics
3. **GA**: Enable for all stores via database update

### Switching from External Provider

When a store switches from `wheniwork` or `homebase` to `buyerkiosk`:
- Historical data from external provider is NOT migrated automatically
- Store starts fresh with native scheduling
- Consider running `migrateFromExternalProvider()` if historical import is needed