headroom/backend/app/Services/AllocationMatrixService.php

<?php

namespace App\Services;

use App\Models\Allocation;
use App\Models\Project;
use Illuminate\Support\Collection;

class AllocationMatrixService
{
    public function __construct(
        private VarianceCalculator $varianceCalculator
    ) {}

    /**
     * Get the allocation matrix with totals.
     *
     * @return array{
     *   allocations: \Illuminate\Support\Collection,
     *   projectTotals: array<string, float>,
     *   teamMemberTotals: array<string, float>,
     *   grandTotal: float
     * }
     */
    public function getMatrix(string $month): array
    {
        $allocations = Allocation::with(['project', 'teamMember'])
            ->where('month', $month)
            ->get();

        // Calculate project totals (including untracked)
        $projectTotals = $allocations->groupBy('project_id')
            ->map(fn (Collection $group) => $group->sum('allocated_hours'))
            ->toArray();

        // Calculate team member totals (excluding untracked/null)
        $teamMemberTotals = $allocations
            ->filter(fn ($a) => $a->team_member_id !== null)
            ->groupBy('team_member_id')
            ->map(fn (Collection $group) => $group->sum('allocated_hours'))
            ->toArray();

        // Calculate grand total (including untracked)
        $grandTotal = $allocations->sum('allocated_hours');

        return [
            'allocations' => $allocations,
            'projectTotals' => $projectTotals,
            'teamMemberTotals' => $teamMemberTotals,
            'grandTotal' => $grandTotal,
        ];
    }

    /**
     * Get matrix with utilization data for each team member.
     */
    public function getMatrixWithUtilization(string $month, CapacityService $capacityService): array
    {
        $matrix = $this->getMatrix($month);

        // Add utilization for each team member (excluding untracked)
        $teamMemberUtilization = [];
        foreach ($matrix['teamMemberTotals'] as $teamMemberId => $totalHours) {
            $capacityData = $capacityService->calculateIndividualCapacity($teamMemberId, $month);
            $capacity = $capacityData['hours'] ?? 0;
            $teamMemberUtilization[$teamMemberId] = [
                'capacity' => $capacity,
                'allocated' => $totalHours,
                'utilization' => $capacity > 0 ? round(($totalHours / $capacity) * 100, 1) : 0,
            ];
        }

        $matrix['teamMemberUtilization'] = $teamMemberUtilization;

        return $matrix;
    }

    /**
     * Get matrix with variance data against explicit month plans.
     *
     * @return array{
     *   allocations: \Illuminate\Support\Collection,
     *   projectTotals: array<string, float>,
     *   teamMemberTotals: array<string, float>,
     *   grandTotal: float,
     *   projectVariances: array<string, array>,
     *   teamMemberVariances: array<string, array>
     * }
     */
    public function getMatrixWithVariance(string $month, CapacityService $capacityService): array
    {
        $matrix = $this->getMatrix($month);

        // Calculate variances
        $variances = $this->varianceCalculator->calculateMatrixVariances($month, $capacityService);

        $matrix['projectVariances'] = $variances['project_variances'];
        $matrix['teamMemberVariances'] = $variances['team_member_variances'];

        return $matrix;
    }

    /**
     * Check if allocation includes untracked (null team_member_id).
     */
    public function hasUntracked(Allocation $allocation): bool
    {
        return $allocation->team_member_id === null;
    }

    /**
     * Get total allocated hours for a project/month including untracked.
     */
    public function getProjectTotalWithUntracked(string $projectId, string $month): float
    {
        $monthDate = strlen($month) === 7 ? $month.'-01' : $month;

        return Allocation::where('project_id', $projectId)
            ->where('month', $monthDate)
            ->sum('allocated_hours');
    }

    /**
     * Get total allocated hours for a team member/month (excludes untracked).
     */
    public function getTeamMemberTotal(string $teamMemberId, string $month): float
    {
        $monthDate = strlen($month) === 7 ? $month.'-01' : $month;

        return Allocation::where('team_member_id', $teamMemberId)
            ->where('month', $monthDate)
            ->sum('allocated_hours');
    }
}