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)
This commit is contained in:
71
backend/app/Services/AllocationMatrixService.php
Normal file
71
backend/app/Services/AllocationMatrixService.php
Normal file
@@ -0,0 +1,71 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services;
|
||||
|
||||
use App\Models\Allocation;
|
||||
use App\Models\Project;
|
||||
use Illuminate\Support\Collection;
|
||||
|
||||
class AllocationMatrixService
|
||||
{
|
||||
/**
|
||||
* 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
|
||||
$projectTotals = $allocations->groupBy('project_id')
|
||||
->map(fn (Collection $group) => $group->sum('allocated_hours'))
|
||||
->toArray();
|
||||
|
||||
// Calculate team member totals
|
||||
$teamMemberTotals = $allocations->groupBy('team_member_id')
|
||||
->map(fn (Collection $group) => $group->sum('allocated_hours'))
|
||||
->toArray();
|
||||
|
||||
// Calculate grand total
|
||||
$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
|
||||
$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;
|
||||
}
|
||||
}
|
||||
163
backend/app/Services/AllocationValidationService.php
Normal file
163
backend/app/Services/AllocationValidationService.php
Normal file
@@ -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,
|
||||
];
|
||||
}
|
||||
}
|
||||
@@ -287,6 +287,23 @@ class CapacityService
|
||||
return $entry;
|
||||
}
|
||||
|
||||
public function batchUpsertAvailability(array $updates, string $month): int
|
||||
{
|
||||
$count = 0;
|
||||
|
||||
foreach ($updates as $update) {
|
||||
TeamMemberAvailability::updateOrCreate(
|
||||
['team_member_id' => $update['team_member_id'], 'date' => $update['date']],
|
||||
['availability' => $update['availability']]
|
||||
);
|
||||
$count++;
|
||||
}
|
||||
|
||||
$this->forgetCapacityCacheForMonth($month);
|
||||
|
||||
return $count;
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a CarbonPeriod for the given month.
|
||||
*/
|
||||
|
||||
Reference in New Issue
Block a user