feat(allocation): implement resource allocation feature

- Add AllocationController with CRUD + bulk endpoints - Add AllocationValidationService for capacity/estimate validation - Add AllocationMatrixService for optimized matrix queries - Add AllocationPolicy for authorization - Add AllocationResource for API responses - Add frontend allocationService and matrix UI - Add E2E tests for allocation matrix (20 tests) - Add unit tests for validation service and policies - Fix month format conversion (YYYY-MM to YYYY-MM-01)
2026-02-25 16:28:47 -05:00
parent fedfc21425
commit 3324c4f156
35 changed files with 3337 additions and 67 deletions
--- a/backend/app/Services/AllocationValidationService.php
+++ b/backend/app/Services/AllocationValidationService.php
@@ -0,0 +1,163 @@
+<?php
+
+namespace App\Services;
+
+use App\Models\Allocation;
+use App\Models\Project;
+use App\Models\TeamMember;
+
+class AllocationValidationService
+{
+    /**
+     * Validate an allocation against team member capacity.
+     *
+     * @return array{valid: bool, warning: ?string, utilization: float}
+     */
+    public function validateCapacity(
+        string $teamMemberId,
+        string $month,
+        float $newHours,
+        ?string $excludeAllocationId = null
+    ): array {
+        $teamMember = TeamMember::with('role')->find($teamMemberId);
+
+        if (! $teamMember) {
+            return ['valid' => true, 'warning' => null, 'utilization' => 0];
+        }
+
+        // Get capacity for the month
+        $capacityService = app(CapacityService::class);
+        $capacityData = $capacityService->calculateIndividualCapacity($teamMemberId, $month);
+        $capacity = $capacityData['hours'] ?? 0;
+
+        if ($capacity <= 0) {
+            return ['valid' => true, 'warning' => null, 'utilization' => 0];
+        }
+
+        // Convert YYYY-MM to YYYY-MM-01 for database query
+        $monthDate = $month . '-01';
+
+        // Get existing allocations for this team member in this month
+        $existingHours = Allocation::where('team_member_id', $teamMemberId)
+            ->where('month', $monthDate)
+            ->when($excludeAllocationId, fn ($query) => $query->where('id', '!=', $excludeAllocationId))
+            ->sum('allocated_hours');
+
+        $totalHours = $existingHours + $newHours;
+        $utilization = ($totalHours / $capacity) * 100;
+
+        // Over-allocated: warn but allow
+        if ($utilization > 100) {
+            $overBy = $totalHours - $capacity;
+
+            return [
+                'valid' => true,
+                'warning' => "Team member over-allocated by {$overBy} hours ({$utilization}% utilization)",
+                'utilization' => round($utilization, 1),
+            ];
+        }
+
+        return [
+            'valid' => true,
+            'warning' => null,
+            'utilization' => round($utilization, 1),
+        ];
+    }
+
+    /**
+     * Validate an allocation against project approved estimate.
+     *
+     * @return array{valid: bool, indicator: string, message: ?string}
+     */
+    public function validateApprovedEstimate(
+        string $projectId,
+        string $month,
+        float $newHours,
+        ?string $excludeAllocationId = null
+    ): array {
+        $project = Project::find($projectId);
+
+        if (! $project || ! $project->approved_estimate) {
+            return ['valid' => true, 'indicator' => 'gray', 'message' => null];
+        }
+
+        // Convert YYYY-MM to YYYY-MM-01 for database query
+        $monthDate = $month . '-01';
+
+        // Get existing allocations for this project in this month
+        $existingHours = Allocation::where('project_id', $projectId)
+            ->where('month', $monthDate)
+            ->when($excludeAllocationId, fn ($query) => $query->where('id', '!=', $excludeAllocationId))
+            ->sum('allocated_hours');
+
+        $totalHours = $existingHours + $newHours;
+        $approved = (float) $project->approved_estimate;
+
+        if ($approved <= 0) {
+            return ['valid' => true, 'indicator' => 'gray', 'message' => null];
+        }
+
+        $percentage = ($totalHours / $approved) * 100;
+
+        // Over-allocated: RED indicator
+        if ($percentage > 100) {
+            $overBy = $totalHours - $approved;
+
+            return [
+                'valid' => true,
+                'indicator' => 'red',
+                'message' => "{$percentage}% allocated (over by {$overBy} hours). Project will be over-charged.",
+            ];
+        }
+
+        // Exactly at estimate: GREEN indicator
+        if ($percentage >= 100) {
+            return [
+                'valid' => true,
+                'indicator' => 'green',
+                'message' => '100% allocated',
+            ];
+        }
+
+        // Under-allocated: YELLOW indicator
+        $underBy = $approved - $totalHours;
+
+        return [
+            'valid' => true,
+            'indicator' => 'yellow',
+            'message' => "{$percentage}% allocated (under by {$underBy} hours)",
+        ];
+    }
+
+    /**
+     * Get validation results for all allocations in a month.
+     */
+    public function getAllocationValidation(
+        string $teamMemberId,
+        string $month
+    ): array {
+        $capacityValidation = $this->validateCapacity($teamMemberId, $month, 0);
+
+        // Convert YYYY-MM to YYYY-MM-01 for database query
+        $monthDate = $month . '-01';
+
+        $allocations = Allocation::where('team_member_id', $teamMemberId)
+            ->where('month', $monthDate)
+            ->with('project')
+            ->get();
+
+        $projectValidations = $allocations->map(function ($allocation) use ($month) {
+            return $this->validateApprovedEstimate(
+                $allocation->project_id,
+                $month,
+                (float) $allocation->allocated_hours,
+                $allocation->id
+            );
+        });
+
+        return [
+            'capacity' => $capacityValidation,
+            'projects' => $projectValidations,
+        ];
+    }
+}