README

Framework-agnostic field service management engine for work orders, technician dispatch, mobile job execution, service contracts, and SLA tracking.

Overview

The FieldService package provides a complete solution for managing field service operations including:

Work order lifecycle management (NEW → SCHEDULED → IN_PROGRESS → COMPLETED → VERIFIED)
Intelligent technician assignment based on skills, proximity, and capacity
Service contract management with SLA tracking
Mobile job execution with offline sync capability
Parts consumption with van stock waterfall logic
GPS location tracking with privacy controls
Customer signature capture and verification
Automated preventive maintenance scheduling
Service report generation

Features by Tier

Tier 1: Basic Work Orders

Manual work order creation and assignment
Technician schedule management
Basic parts consumption tracking
Customer signature capture (SHA-256 hash)
Service report PDF generation

Tier 2: Service Contracts & Preventive Maintenance

Service contract management with asset linkage
SLA deadline tracking and breach alerts
Automated preventive maintenance scheduling (7 days before due date)
Maintenance deduplication (±3 days conflict detection)
Checklist templates and validation

Tier 3: Enterprise Features

ML-powered technician assignment via Nexus\Intelligence
VRP route optimization via Nexus\Routing
RFC 3161 cryptographic timestamp signing for signatures
Advanced GPS tracking and analytics
Event sourcing for compliance auditing

Installation

composer require azaharizaman/nexus-field-service

Key Concepts

Work Order States

NEW → SCHEDULED → IN_PROGRESS → COMPLETED → VERIFIED
  ↓       ↓            ↓            ↓
  └───────┴────────────┴────────────┴─→ CANCELLED

Parts Consumption Waterfall

Check technician van stock
Deduct available quantity from van
Deduct remainder from primary warehouse
Update work order parts cost

SLA Tracking

Service contracts define response times (e.g., "4 hours"). When a work order is created against a contract:

Calculate SLA deadline based on response time
Schedule escalation check job
Monitor progress via Nexus\Workflow
Trigger escalation workflow on breach

Dependencies

Required Packages

azaharizaman/nexus-party - Customer and vendor management
azaharizaman/nexus-backoffice - Staff/technician management
azaharizaman/nexus-inventory - Parts consumption tracking
azaharizaman/nexus-warehouse - Van stock management
azaharizaman/nexus-scheduler - Preventive maintenance automation
azaharizaman/nexus-routing - Route optimization (Tier 3)
azaharizaman/nexus-geo - Geocoding and distance calculation
azaharizaman/nexus-workflow - SLA escalation
azaharizaman/nexus-sequencing - Work order numbering
azaharizaman/nexus-document - Service report PDF generation
azaharizaman/nexus-storage - Photo and signature storage
azaharizaman/nexus-notifier - Multi-channel notifications
azaharizaman/nexus-audit-logger - Audit trail
azaharizaman/nexus-tenant - Multi-tenancy isolation
azaharizaman/nexus-product - Service and parts catalog

Optional Packages

azaharizaman/nexus-assets - Asset tracking and maintenance history
azaharizaman/nexus-intelligence - AI-powered assignment (Tier 3)
azaharizaman/nexus-crypto - Signature timestamp signing (Tier 3)
azaharizaman/nexus-event-stream - Event sourcing for compliance

Usage

Creating a Work Order

use Nexus\FieldService\Services\WorkOrderManager;
use Nexus\FieldService\Enums\WorkOrderPriority;
use Nexus\FieldService\Enums\ServiceType;

$workOrder = $workOrderManager->create([
    'customer_party_id' => 'party-123',
    'service_location_id' => 'address-456',
    'service_type' => ServiceType::REPAIR,
    'priority' => WorkOrderPriority::HIGH,
    'description' => 'HVAC system not cooling properly',
    'scheduled_start' => new \DateTimeImmutable('2025-11-25 09:00:00'),
]);

Assigning a Technician

use Nexus\FieldService\Services\TechnicianDispatcher;

// Find best available technician
$technician = $technicianDispatcher->findBestTechnician(
    $workOrder,
    $availableTechnicians
);

// Assign to work order
$workOrderManager->assign($workOrder->getId(), $technician->getId());

Recording Parts Consumption

use Nexus\FieldService\Services\PartsConsumptionManager;

$partsConsumptionManager->recordConsumption(
    $workOrder->getId(),
    $productVariantId,
    $quantity,
    $technicianId
);
// Automatically deducts from van stock first, then warehouse

Capturing Customer Signature

$signatureData = base64_encode($signatureImageBinary);

$workOrderManager->captureSignature(
    $workOrder->getId(),
    $signatureData,
    $technicianId,
    $gpsLocation
);

Generating Service Report

use Nexus\FieldService\Services\ServiceReportGenerator;

$document = $serviceReportGenerator->generate($workOrder->getId());
// Returns DocumentInterface with PDF content

Architecture

This package follows the Nexus monorepo architecture:

Package Layer (packages/FieldService/): Framework-agnostic business logic
Application Layer (apps/Atomy/): Laravel implementation with Eloquent models and migrations

Package Structure

packages/FieldService/
├── src/
│   ├── Contracts/          # Interfaces for dependency injection
│   ├── Services/           # Business logic orchestrators
│   ├── Core/               # Internal engine components
│   ├── Enums/              # Native PHP 8.3 enums
│   ├── ValueObjects/       # Immutable data structures
│   ├── Events/             # Domain events
│   └── Exceptions/         # Domain-specific exceptions

Testing

composer test

Documentation

Getting Started

Getting Started Guide - Comprehensive 840-line guide covering:
- Prerequisites and installation
- 7 core concepts (work order lifecycle, assignment strategies, SLA enforcement, preventive maintenance, offline sync, GPS tracking, parts consumption)
- Configuration and setup
- Integration examples
- Troubleshooting and performance tips

API Reference

API Reference - Complete documentation of:
- 17 interfaces (WorkOrderInterface, TechnicianAssignmentStrategyInterface, GpsTrackerInterface, MobileSyncManagerInterface, etc.)
- 3 value objects (GpsLocation, SkillSet, LaborHours)
- 3 enums (WorkOrderStatus, WorkOrderPriority, MaintenanceType)
- 14 exceptions with factory methods

Integration Guides

Integration Guide - Framework integration examples:
- Laravel service provider and controller examples
- Symfony services.yaml and controller examples
- Common patterns (offline sync, GPS tracking, SLA monitoring)
- Testing examples

Code Examples

Basic Usage - Common operations:
- Create and auto-assign work orders
- Start work orders with GPS validation
- Complete work orders with signatures
- Service contract validation
- SLA breach detection
Advanced Usage - Complex scenarios:
- Custom technician assignment strategies
- Offline mobile sync with conflict resolution
- Preventive maintenance scheduling with deduplication

Implementation Documentation

Implementation Summary - 806-line detailed implementation status
Requirements - 100 documented requirements with traceability
Test Suite Summary - ~95 tests with coverage metrics
Valuation Matrix - Package valuation ($820K value, 3,696% ROI)

License

MIT License. See LICENSE file for details.

azaharizaman / nexus-field-service

Maintainers

Package info

Statistics

Security