@fleetbase/fleetops-engine 0.6.25 → 0.6.27

package/DRIVER_SCHEDULING.md

@@ -0,0 +1,186 @@
+# FleetOps Driver Scheduling Module
+
+This module implements driver scheduling with Hours of Service (HOS) compliance for FleetOps.
+
+## Features
+
+- **Fleet-Wide Scheduler**: Manage all drivers' schedules in a single calendar view
+- **Driver Schedule Management**: Create, edit, and manage driver shifts
+- **HOS Compliance**: Real-time validation against FMCSA regulations
+- **Calendar View**: Visual schedule management with drag-and-drop
+- **Resource Timeline**: View multiple drivers' schedules simultaneously
+- **Individual Driver Schedules**: Dedicated schedule view on driver detail pages
+- **Availability Management**: Track driver availability and time-off requests
+- **Conflict Detection**: Automatic detection of scheduling conflicts
+- **Dual View Modes**: Toggle between order scheduling and driver scheduling
+
+## Components
+
+### Operations/Scheduler (Fleet-Wide View)
+
+The main scheduler view at `operations/scheduler` now supports both order scheduling and driver scheduling.
+
+**Location**: `addon/controllers/operations/scheduler/index.js`
+
+**Features**:
+- **View Mode Toggle**: Switch between "Orders" and "Driver Schedules" modes
+- **Resource Timeline**: In driver mode, shows all drivers as resources with their shifts
+- **Drag-and-Drop**: Drag shifts between drivers or reschedule by dragging
+- **Add Shift**: Quick action button to create new driver shifts
+- **Real-Time Updates**: Calendar updates automatically when shifts are modified
+- **Status Colors**: Visual indicators for shift status (pending, confirmed, etc.)
+
+**View Modes**:
+1. **Orders Mode** (default):
+   - Month calendar view
+   - Drag unscheduled orders to calendar
+   - Manage order scheduling
+
+2. **Driver Schedules Mode**:
+   - Resource timeline view (week view with drivers as resources)
+   - View all drivers' shifts simultaneously
+   - Drag shifts between drivers
+   - Reschedule shifts by dragging
+   - Click shifts to view/edit details
+
+**Usage**:
+Navigate to Operations → Scheduler, then toggle between "Orders" and "Driver Schedules" using the header buttons.
+
+### Driver::Schedule
+
+Displays and manages a driver's schedule from their detail page.
+
+**Location**: `addon/components/driver/schedule.js`
+
+**Features**:
+- HOS compliance dashboard with visual indicators
+- Weekly calendar view of driver shifts
+- Upcoming shifts list (next 5 shifts)
+- Availability and time-off management
+- Quick actions for adding shifts and requesting time off
+
+**Usage**:
+```handlebars
+<Driver::Schedule @driver={{@model}} />
+```
+
+**Integration**: Add a "Schedule" tab to the driver detail page.
+
+## Backend Components
+
+### HOSConstraint
+
+Validates schedule items against FMCSA Hours of Service regulations.
+
+**Location**: `server/src/Constraints/HOSConstraint.php`
+
+**Regulations Enforced**:
+1. **11-Hour Driving Limit**: Maximum 11 hours driving after 10 consecutive hours off duty
+2. **14-Hour Duty Window**: Cannot drive beyond 14th hour after coming on duty
+3. **60/70-Hour Weekly Limit**: Cannot drive after 60/70 hours in 7/8 consecutive days
+4. **30-Minute Break**: Required after 8 cumulative hours of driving
+
+**Violation Severity**:
+- `critical`: Immediate compliance issue, shift cannot be scheduled
+- `warning`: Approaching limit, requires attention
+
+**Registration**:
+```php
+// In FleetOps ServiceProvider boot() method
+$constraintService = app(\Fleetbase\Services\Scheduling\ConstraintService::class);
+$constraintService->register('driver', \Fleetbase\FleetOps\Constraints\HOSConstraint::class);
+```
+
+## HOS Compliance Dashboard
+
+The HOS dashboard displays:
+- **Daily Driving Hours**: X/11 hours with circular progress indicator
+- **Weekly Hours**: X/70 hours with circular progress indicator
+- **Compliance Status**: Badge indicating compliance level
+  - Green: Compliant
+  - Yellow: Approaching Limit
+  - Red: At Limit
+
+## API Endpoints
+
+FleetOps extends the core scheduling endpoints with driver-specific functionality:
+
+- `GET /drivers/{id}/hos-status` - Get HOS compliance status for a driver
+- `GET /drivers/{id}/schedule` - Get schedule items for a driver
+- `POST /drivers/{id}/schedule` - Create a new shift for a driver
+- `PUT /schedule-items/{id}` - Update a shift (with HOS validation)
+- `DELETE /schedule-items/{id}` - Delete a shift
+
+## Workflow
+
+### Creating a Driver Shift
+
+1. User clicks "Add Shift" button
+2. Modal opens with shift form
+3. User selects date, time, vehicle, and other details
+4. System validates against HOS constraints
+5. If violations found, display warnings/errors
+6. If valid, create schedule item
+7. Update driver schedule view and HOS dashboard
+
+### HOS Validation
+
+1. When a schedule item is created/updated
+2. `HOSConstraint::validate()` is called
+3. Checks all four HOS regulations
+4. Returns violations array if any
+5. Frontend displays violations to user
+6. User can adjust shift or override (with proper permissions)
+
+## Integration with Core Scheduling
+
+FleetOps uses the core scheduling module with driver-specific customizations:
+
+**Core Components Used**:
+- `Schedule` model (subject_type: 'fleet', subject_uuid: fleet.id)
+- `ScheduleItem` model (assignee_type: 'driver', assignee_uuid: driver.id)
+- `ScheduleAvailability` model (subject_type: 'driver')
+- `ScheduleConstraint` model (subject_type: 'driver')
+
+**FleetOps Extensions**:
+- `HOSConstraint` for compliance validation
+- `Driver::Schedule` component for driver-specific UI
+- HOS status API endpoint
+- Driver-specific scheduling logic
+
+## Future Enhancements
+
+- **Automatic Schedule Generation**: AI-powered schedule optimization
+- **ELD Integration**: Sync with Electronic Logging Devices
+- **Predictive HOS**: Forecast HOS availability for future dates
+- **Mobile App**: Driver-facing mobile app for schedule viewing
+- **Notifications**: Real-time alerts for schedule changes and HOS warnings
+- **Reporting**: HOS compliance reports and analytics
+
+## Testing
+
+### HOS Constraint Tests
+
+Test cases should cover:
+- 11-hour driving limit enforcement
+- 14-hour duty window enforcement
+- 60/70-hour weekly limit enforcement
+- 30-minute break requirement
+- Edge cases (consecutive shifts, split shifts, etc.)
+
+### Integration Tests
+
+- Create driver shift via API
+- Validate HOS constraints are enforced
+- Update shift and verify re-validation
+- Delete shift and verify HOS recalculation
+- Test driver schedule view rendering
+
+## Compliance Notes
+
+This implementation follows FMCSA Hours of Service regulations as of 2025. Regulations may vary by:
+- Jurisdiction (US Federal, state-specific, Canada, etc.)
+- Vehicle type (property-carrying vs. passenger-carrying)
+- Industry (short-haul vs. long-haul)
+
+**Important**: This is a software implementation and should not be the sole method of HOS compliance. Proper driver training, ELD integration, and regular audits are essential for full compliance.

package/addon/components/driver/schedule.hbs

@@ -0,0 +1,100 @@
+<div class="driver-schedule-container" ...attributes>
+    <ContentPanel @title="Hours of Service Status" @open={{true}} @isLoading={{this.loadHOSStatus.isRunning}} @wrapperClass="bordered-top">
+        {{#if this.hosStatus}}
+            <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
+                <div class="flex items-center justify-between p-3 bg-gray-50 dark:bg-gray-700 rounded">
+                    <div>
+                        <div class="text-sm text-gray-500 dark:text-gray-400">Daily Driving Hours</div>
+                        <div class="text-2xl font-bold">{{this.hosStatus.daily_hours}}/11</div>
+                    </div>
+                    <div class="w-16 h-16">
+                        <CircularProgress @value={{this.hosStatus.daily_hours}} @max={{11}} />
+                    </div>
+                </div>
+
+                <div class="flex items-center justify-between p-3 bg-gray-50 dark:bg-gray-700 rounded">
+                    <div>
+                        <div class="text-sm text-gray-500 dark:text-gray-400">Weekly Hours</div>
+                        <div class="text-2xl font-bold">{{this.hosStatus.weekly_hours}}/70</div>
+                    </div>
+                    <div class="w-16 h-16">
+                        <CircularProgress @value={{this.hosStatus.weekly_hours}} @max={{70}} />
+                    </div>
+                </div>
+
+                <div class="flex items-center justify-between p-3 bg-gray-50 dark:bg-gray-700 rounded">
+                    <div>
+                        <div class="text-sm text-gray-500 dark:text-gray-400">Compliance Status</div>
+                        <span
+                            class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-{{this.hosComplianceBadge.color}}-100 text-{{this.hosComplianceBadge.color}}-800"
+                        >
+                            {{this.hosComplianceBadge.text}}
+                        </span>
+                    </div>
+                </div>
+            </div>
+        {{/if}}
+    </ContentPanel>
+    <ContentPanel @title="Schedule Calendar" @open={{true}} @isLoading={{this.loadDriverSchedule.isRunning}} @actionButtons={{this.scheduleActionButtons}} @wrapperClass="bordered-top">
+        <ScheduleCalendar @items={{this.scheduleItems}} @view="timeGridWeek" @onItemClick={{this.handleItemClick}}>
+            <:item as |ctx|>
+                <div class="schedule-item-content">
+                    <div class="font-medium">{{ctx.item.title}}</div>
+                    <div class="text-xs">{{ctx.item.duration}} min</div>
+                </div>
+            </:item>
+        </ScheduleCalendar>
+    </ContentPanel>
+
+    <ContentPanel @title="Upcoming Shifts" @open={{true}} @actionButtons={{this.shiftActionButtons}} @wrapperClass="bordered-top">
+        {{#if this.upcomingShifts.length}}
+            <div class="space-y-2">
+                {{#each this.upcomingShifts as |shift|}}
+                    <ScheduleItemCard @item={{shift}} @onClick={{this.handleItemClick}}>
+                        <:actions>
+                            <button type="button" class="text-blue-600 hover:text-blue-800 text-sm" {{on "click" (fn this.editScheduleItem shift)}}>
+                                Edit
+                            </button>
+                        </:actions>
+                    </ScheduleItemCard>
+                {{/each}}
+            </div>
+        {{else}}
+            <div class="text-center py-4 text-gray-500 dark:text-gray-400">
+                No upcoming shifts scheduled
+            </div>
+        {{/if}}
+    </ContentPanel>
+
+    <ContentPanel @title="Availability & Time Off" @open={{true}} @actionButtons={{this.availabilityActionButtons}} @wrapperClass="bordered-top">
+        {{#if this.availability.length}}
+            <div class="space-y-2">
+                {{#each this.availability as |avail|}}
+                    <div class="flex items-center justify-between p-2 bg-gray-50 dark:bg-gray-700 rounded">
+                        <div>
+                            <div class="font-medium">
+                                {{#if avail.is_available}}
+                                    <span class="text-green-600">Available</span>
+                                {{else}}
+                                    <span class="text-red-600">Unavailable</span>
+                                {{/if}}
+                            </div>
+                            <div class="text-sm text-gray-500">
+                                {{format-date-fns avail.start_at "MMM DD, YYYY"}}
+                                -
+                                {{format-date-fns avail.end_at "MMM DD, YYYY"}}
+                            </div>
+                            {{#if avail.reason}}
+                                <div class="text-xs text-gray-400">{{avail.reason}}</div>
+                            {{/if}}
+                        </div>
+                    </div>
+                {{/each}}
+            </div>
+        {{else}}
+            <div class="text-center py-4 text-gray-500 dark:text-gray-400">
+                No availability restrictions set
+            </div>
+        {{/if}}
+    </ContentPanel>
+</div>

package/addon/components/driver/schedule.js

@@ -0,0 +1,267 @@
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { inject as service } from '@ember/service';
+import { action } from '@ember/object';
+import { task } from 'ember-concurrency';
+
+/**
+ * Driver::Schedule Component
+ *
+ * Displays and manages a driver's schedule from their detail page.
+ * Includes HOS compliance tracking, upcoming shifts, and availability management.
+ *
+ * @example
+ * <Driver::Schedule @resource={{@model}} />
+ */
+export default class DriverScheduleComponent extends Component {
+    @service driverScheduling;
+    @service notifications;
+    @service modalsManager;
+    @service store;
+    @tracked scheduleItems = [];
+    @tracked upcomingShifts = [];
+    @tracked hosStatus = null;
+    @tracked availability = [];
+    @tracked timeOffRequests = [];
+    @tracked selectedItem = null;
+
+    get scheduleActionButtons() {
+        return [
+            {
+                type: 'default',
+                text: 'Request Time Off',
+                icon: 'calendar-times',
+                iconPrefix: 'fas',
+                permission: 'fleet-ops update driver',
+                onClick: this.requestTimeOff,
+            },
+        ];
+    }
+
+    get shiftActionButtons() {
+        return [
+            {
+                type: 'default',
+                text: 'Add Shift',
+                icon: 'plus',
+                iconPrefix: 'fas',
+                permission: 'fleet-ops update driver',
+                onClick: this.addShift,
+            },
+        ];
+    }
+
+    get availabilityActionButtons() {
+        return [
+            {
+                type: 'default',
+                text: 'Set Availability',
+                icon: 'clock',
+                iconPrefix: 'fas',
+                permission: 'fleet-ops update driver',
+                onClick: this.setAvailability,
+            },
+        ];
+    }
+
+    constructor() {
+        super(...arguments);
+        this.loadDriverSchedule.perform();
+        this.loadHOSStatus.perform();
+        this.loadAvailability.perform();
+    }
+
+    /**
+     * Load driver schedule items
+     */
+    @task *loadDriverSchedule() {
+        try {
+            const items = yield this.driverScheduling.getScheduleItemsForAssignee.perform('driver', this.args.resource.id, {
+                start_at: this.startDate,
+                end_at: this.endDate,
+            });
+
+            this.scheduleItems = items.toArray();
+            this.upcomingShifts = this.scheduleItems.filter((item) => new Date(item.start_at) > new Date()).slice(0, 5);
+        } catch (error) {
+            console.error('Failed to load driver schedule:', error);
+        }
+    }
+
+    /**
+     * Load HOS status for the driver
+     */
+    @task *loadHOSStatus() {
+        try {
+            const response = yield this.fetch.get(`drivers/${this.args.resource.id}/hos-status`);
+            this.hosStatus = response;
+        } catch (error) {
+            console.error('Failed to load HOS status:', error);
+        }
+    }
+
+    /**
+     * Load driver availability
+     */
+    @task *loadAvailability() {
+        try {
+            const availability = yield this.store.query('schedule-availability', {
+                subject_type: 'driver',
+                subject_uuid: this.args.resource.id,
+                start_at: this.startDate,
+                end_at: this.endDate,
+            });
+
+            this.availability = availability.toArray();
+        } catch (error) {
+            console.error('Failed to load availability:', error);
+        }
+    }
+
+    /**
+     * Get start date for schedule query (current week)
+     */
+    get startDate() {
+        const now = new Date();
+        const dayOfWeek = now.getDay();
+        const diff = now.getDate() - dayOfWeek;
+        return new Date(now.setDate(diff)).toISOString();
+    }
+
+    /**
+     * Get end date for schedule query (4 weeks out)
+     */
+    get endDate() {
+        const now = new Date();
+        return new Date(now.setDate(now.getDate() + 28)).toISOString();
+    }
+
+    /**
+     * Get HOS compliance badge color
+     */
+    get hosComplianceBadge() {
+        if (!this.hosStatus) {
+            return { color: 'gray', text: 'Unknown' };
+        }
+
+        const { daily_hours, weekly_hours } = this.hosStatus;
+
+        if (daily_hours >= 11 || weekly_hours >= 70) {
+            return { color: 'red', text: 'At Limit' };
+        }
+
+        if (daily_hours >= 9 || weekly_hours >= 60) {
+            return { color: 'yellow', text: 'Approaching Limit' };
+        }
+
+        return { color: 'green', text: 'Compliant' };
+    }
+
+    /**
+     * Handle item click
+     */
+    @action
+    handleItemClick(item) {
+        this.selectedItem = item;
+        this.modalsManager.show('modals/schedule-item-details', {
+            item,
+            onEdit: this.editScheduleItem,
+            onDelete: this.deleteScheduleItem,
+        });
+    }
+
+    /**
+     * Add new shift
+     */
+    @action
+    addShift() {
+        this.modalsManager.show('modals/add-shift', {
+            driver: this.args.resource,
+            onSave: this.handleShiftAdded,
+        });
+    }
+
+    /**
+     * Edit schedule item
+     */
+    @action
+    async editScheduleItem(item) {
+        this.modalsManager.show('modals/edit-shift', {
+            item,
+            driver: this.args.resource,
+            onSave: this.handleShiftUpdated,
+        });
+    }
+
+    /**
+     * Delete schedule item
+     */
+    @action
+    async deleteScheduleItem(item) {
+        if (confirm('Are you sure you want to delete this shift?')) {
+            try {
+                await this.driverScheduling.deleteScheduleItem.perform(item);
+                await this.loadDriverSchedule.perform();
+            } catch (error) {
+                console.error('Failed to delete shift:', error);
+            }
+        }
+    }
+
+    /**
+     * Handle shift added
+     */
+    @action
+    async handleShiftAdded() {
+        await this.loadDriverSchedule.perform();
+        await this.loadHOSStatus.perform();
+    }
+
+    /**
+     * Handle shift updated
+     */
+    @action
+    async handleShiftUpdated() {
+        await this.loadDriverSchedule.perform();
+        await this.loadHOSStatus.perform();
+    }
+
+    /**
+     * Request time off
+     */
+    @action
+    requestTimeOff() {
+        this.modalsManager.show('modals/request-time-off', {
+            driver: this.args.resource,
+            onSave: this.handleTimeOffRequested,
+        });
+    }
+
+    /**
+     * Handle time off requested
+     */
+    @action
+    async handleTimeOffRequested() {
+        await this.loadAvailability.perform();
+        await this.loadDriverSchedule.perform();
+    }
+
+    /**
+     * Set availability
+     */
+    @action
+    setAvailability() {
+        this.modalsManager.show('modals/set-availability', {
+            driver: this.args.resource,
+            onSave: this.handleAvailabilitySet,
+        });
+    }
+
+    /**
+     * Handle availability set
+     */
+    @action
+    async handleAvailabilitySet() {
+        await this.loadAvailability.perform();
+    }
+}

package/addon/components/order/kanban-card.hbs

@@ -47,7 +47,7 @@
         <div class="flex flex-row">
             <div class="flex-1">
                 <div class="flex flex-row space-x-2">
-                    <div class="resource-assigned-photo">
+                    <div class="resource-assigned-photo relative">
                         <Image
                             src={{avatar-url @card.customer.photo_url}}
                             @fallbackSrc={{config "defaultValues.contactImage"}}
@@ -64,7 +64,7 @@
             </div>
             <div class="flex-1">
                 <div class="flex flex-row space-x-2">
-                    <div class="resource-assigned-photo">
+                    <div class="resource-assigned-photo relative">
                         <Image
                             src={{avatar-url @card.driver_assigned.photo_url}}
                             @fallbackSrc={{config "defaultValues.driverImage"}}