feat(backend): enhance allocation and project management
Update controllers and services for allocation fidelity: - AllocationController: variance data in responses, bulk operations - ProjectController: include plan data in responses - ProjectMonthPlanController: planning grid API - AllocationMatrixService: support untracked allocations - ProjectResource/TeamMemberResource: include reconciliation data Improved test coverage for allocation flows.
This commit is contained in:
@@ -5,7 +5,10 @@ namespace App\Http\Controllers\Api;
|
||||
use App\Http\Controllers\Controller;
|
||||
use App\Http\Resources\AllocationResource;
|
||||
use App\Models\Allocation;
|
||||
use App\Services\AllocationMatrixService;
|
||||
use App\Services\AllocationValidationService;
|
||||
use App\Services\CapacityService;
|
||||
use App\Services\VarianceCalculator;
|
||||
use Illuminate\Http\JsonResponse;
|
||||
use Illuminate\Http\Request;
|
||||
use Illuminate\Support\Facades\Validator;
|
||||
@@ -19,8 +22,12 @@ class AllocationController extends Controller
|
||||
{
|
||||
protected AllocationValidationService $validationService;
|
||||
|
||||
public function __construct(AllocationValidationService $validationService)
|
||||
{
|
||||
public function __construct(
|
||||
AllocationValidationService $validationService,
|
||||
protected VarianceCalculator $varianceCalculator,
|
||||
protected CapacityService $capacityService,
|
||||
protected AllocationMatrixService $allocationMatrixService
|
||||
) {
|
||||
$this->validationService = $validationService;
|
||||
}
|
||||
|
||||
@@ -40,7 +47,10 @@ class AllocationController extends Controller
|
||||
* "project_id": "550e8400-e29b-41d4-a716-446655440001",
|
||||
* "team_member_id": "550e8400-e29b-41d4-a716-446655440002",
|
||||
* "month": "2026-02",
|
||||
* "allocated_hours": 40.00
|
||||
* "allocated_hours": 40.00,
|
||||
* "is_untracked": false,
|
||||
* "row_variance": { "allocated_total": 80, "planned_month": 100, "variance": -20, "status": "UNDER" },
|
||||
* "column_variance": { "allocated": 80, "capacity": 160, "variance": -80, "status": "UNDER" }
|
||||
* }
|
||||
* ]
|
||||
* }
|
||||
@@ -53,57 +63,42 @@ class AllocationController extends Controller
|
||||
|
||||
if ($month) {
|
||||
// Convert YYYY-MM to YYYY-MM-01 for date comparison
|
||||
$monthDate = $month . '-01';
|
||||
$monthDate = $month.'-01';
|
||||
$query->where('month', $monthDate);
|
||||
}
|
||||
|
||||
$allocations = $query->get();
|
||||
|
||||
// Compute allocation_indicator for each allocation based on project totals
|
||||
$allocations->each(function ($allocation) {
|
||||
$allocation->allocation_indicator = $this->computeAllocationIndicator(
|
||||
$allocation->project_id,
|
||||
$allocation->month
|
||||
);
|
||||
});
|
||||
// Compute variance indicators for each allocation if month is specified
|
||||
if ($month) {
|
||||
$allocations->each(function ($allocation) use ($month) {
|
||||
// Add untracked flag
|
||||
$allocation->is_untracked = $allocation->team_member_id === null;
|
||||
|
||||
// Add row variance (project level)
|
||||
$rowVariance = $this->varianceCalculator->calculateRowVariance(
|
||||
$allocation->project_id,
|
||||
$month
|
||||
);
|
||||
$allocation->row_variance = $rowVariance;
|
||||
|
||||
// Add column variance only for tracked allocations
|
||||
if ($allocation->team_member_id !== null) {
|
||||
$columnVariance = $this->varianceCalculator->calculateColumnVariance(
|
||||
$allocation->team_member_id,
|
||||
$month,
|
||||
$this->capacityService
|
||||
);
|
||||
$allocation->column_variance = $columnVariance;
|
||||
} else {
|
||||
$allocation->column_variance = null;
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
return $this->wrapResource(AllocationResource::collection($allocations));
|
||||
}
|
||||
|
||||
/**
|
||||
* Compute allocation indicator based on project totals.
|
||||
*/
|
||||
private function computeAllocationIndicator(string $projectId, string $month): string
|
||||
{
|
||||
// Convert month to date format if needed
|
||||
$monthDate = strlen($month) === 7 ? $month . '-01' : $month;
|
||||
|
||||
// Get total allocated for this project in this month
|
||||
$totalAllocated = Allocation::where('project_id', $projectId)
|
||||
->where('month', $monthDate)
|
||||
->sum('allocated_hours');
|
||||
|
||||
// Get project approved estimate
|
||||
$project = \App\Models\Project::find($projectId);
|
||||
$approvedEstimate = $project?->approved_estimate;
|
||||
|
||||
// Handle no estimate
|
||||
if (! $approvedEstimate || $approvedEstimate <= 0) {
|
||||
return 'gray';
|
||||
}
|
||||
|
||||
$percentage = ($totalAllocated / $approvedEstimate) * 100;
|
||||
|
||||
// Check in correct order: over first, then at capacity, then under
|
||||
if ($percentage > 100) {
|
||||
return 'red';
|
||||
} elseif ($percentage >= 100) {
|
||||
return 'green';
|
||||
} else {
|
||||
return 'yellow';
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a new allocation
|
||||
*
|
||||
@@ -112,7 +107,7 @@ class AllocationController extends Controller
|
||||
* @authenticated
|
||||
*
|
||||
* @bodyParam project_id string required Project UUID. Example: 550e8400-e29b-41d4-a716-446655440001
|
||||
* @bodyParam team_member_id string required Team member UUID. Example: 550e8400-e29b-41d4-a716-446655440002
|
||||
* @bodyParam team_member_id string optional Team member UUID (null for untracked). Example: 550e8400-e29b-41d4-a716-446655440002
|
||||
* @bodyParam month string required Month (YYYY-MM format). Example: 2026-02
|
||||
* @bodyParam allocated_hours numeric required Hours to allocate (must be >= 0). Example: 40
|
||||
*
|
||||
@@ -146,7 +141,7 @@ class AllocationController extends Controller
|
||||
// Validate against capacity and approved estimate (skip for untracked)
|
||||
$teamMemberId = $request->input('team_member_id');
|
||||
$capacityValidation = ['valid' => true, 'warning' => null, 'utilization' => 0];
|
||||
|
||||
|
||||
if ($teamMemberId) {
|
||||
$capacityValidation = $this->validationService->validateCapacity(
|
||||
$teamMemberId,
|
||||
@@ -163,26 +158,48 @@ class AllocationController extends Controller
|
||||
|
||||
// Convert YYYY-MM to YYYY-MM-01 for database storage
|
||||
$data = $request->all();
|
||||
$data['month'] = $data['month'] . '-01';
|
||||
$data['month'] = $data['month'].'-01';
|
||||
|
||||
$allocation = Allocation::create($data);
|
||||
$allocation->load(['project', 'teamMember']);
|
||||
|
||||
$response = new AllocationResource($allocation);
|
||||
$data = $response->toArray($request);
|
||||
$responseData = $response->toArray($request);
|
||||
|
||||
// Add variance data
|
||||
$month = $request->input('month');
|
||||
$responseData['is_untracked'] = $teamMemberId === null;
|
||||
|
||||
// Row variance (project level)
|
||||
$rowVariance = $this->varianceCalculator->calculateRowVariance(
|
||||
$allocation->project_id,
|
||||
$month
|
||||
);
|
||||
$responseData['row_variance'] = $rowVariance;
|
||||
|
||||
// Column variance (member level) - only for tracked allocations
|
||||
if ($teamMemberId) {
|
||||
$columnVariance = $this->varianceCalculator->calculateColumnVariance(
|
||||
$teamMemberId,
|
||||
$month,
|
||||
$this->capacityService
|
||||
);
|
||||
$responseData['column_variance'] = $columnVariance;
|
||||
$responseData['utilization'] = $capacityValidation['utilization'];
|
||||
} else {
|
||||
$responseData['column_variance'] = null;
|
||||
}
|
||||
|
||||
// Add validation warnings/info to response
|
||||
$data['warnings'] = [];
|
||||
$responseData['warnings'] = [];
|
||||
if ($capacityValidation['warning']) {
|
||||
$data['warnings'][] = $capacityValidation['warning'];
|
||||
$responseData['warnings'][] = $capacityValidation['warning'];
|
||||
}
|
||||
if ($estimateValidation['message']) {
|
||||
$data['warnings'][] = $estimateValidation['message'];
|
||||
$responseData['warnings'][] = $estimateValidation['message'];
|
||||
}
|
||||
$data['utilization'] = $capacityValidation['utilization'];
|
||||
$data['allocation_indicator'] = $estimateValidation['indicator'];
|
||||
|
||||
return response()->json(['data' => $data], 201);
|
||||
return response()->json(['data' => $responseData], 201);
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -300,7 +317,8 @@ class AllocationController extends Controller
|
||||
/**
|
||||
* Bulk create allocations
|
||||
*
|
||||
* Create or update multiple allocations in a single request.
|
||||
* Create multiple allocations in a single request.
|
||||
* Supports partial success - valid items are created, invalid items are reported.
|
||||
*
|
||||
* @authenticated
|
||||
*
|
||||
@@ -308,24 +326,23 @@ class AllocationController extends Controller
|
||||
*
|
||||
* @response 201 {
|
||||
* "data": [
|
||||
* {
|
||||
* "id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
* "project_id": "550e8400-e29b-41d4-a716-446655440001",
|
||||
* "team_member_id": "550e8400-e29b-41d4-a716-446655440002",
|
||||
* "month": "2026-02",
|
||||
* "allocated_hours": 40.00
|
||||
* }
|
||||
* ]
|
||||
* { "index": 0, "id": "...", "status": "created" }
|
||||
* ],
|
||||
* "failed": [
|
||||
* { "index": 1, "errors": { "allocated_hours": ["..."] } }
|
||||
* ],
|
||||
* "summary": { "created": 1, "failed": 1 }
|
||||
* }
|
||||
*/
|
||||
public function bulkStore(Request $request): JsonResponse
|
||||
{
|
||||
// Basic validation only - individual item validation happens in the loop
|
||||
// This allows partial success even if some items have invalid data
|
||||
$validator = Validator::make($request->all(), [
|
||||
'allocations' => 'required|array|min:1',
|
||||
'allocations.*.project_id' => 'required|uuid|exists:projects,id',
|
||||
'allocations.*.team_member_id' => 'required|uuid|exists:team_members,id',
|
||||
'allocations.*.month' => 'required|date_format:Y-m',
|
||||
'allocations.*.allocated_hours' => 'required|numeric|min:0',
|
||||
'allocations.*.project_id' => 'required',
|
||||
'allocations.*.month' => 'required',
|
||||
'allocations.*.allocated_hours' => 'required|numeric',
|
||||
]);
|
||||
|
||||
if ($validator->fails()) {
|
||||
@@ -335,12 +352,57 @@ class AllocationController extends Controller
|
||||
], 422);
|
||||
}
|
||||
|
||||
$created = [];
|
||||
foreach ($request->input('allocations') as $allocationData) {
|
||||
$allocation = Allocation::create($allocationData);
|
||||
$created[] = $allocation;
|
||||
$data = [];
|
||||
$failed = [];
|
||||
$created = 0;
|
||||
$failedCount = 0;
|
||||
|
||||
foreach ($request->input('allocations') as $index => $allocationData) {
|
||||
// Convert YYYY-MM to YYYY-MM-01 for database storage
|
||||
$allocationData['month'] = $allocationData['month'].'-01';
|
||||
|
||||
// Validate each item individually (for partial bulk success)
|
||||
$itemValidator = Validator::make($allocationData, [
|
||||
'project_id' => 'required|uuid|exists:projects,id',
|
||||
'team_member_id' => 'nullable|uuid|exists:team_members,id',
|
||||
'month' => 'required|date',
|
||||
'allocated_hours' => 'required|numeric|min:0',
|
||||
]);
|
||||
|
||||
if ($itemValidator->fails()) {
|
||||
$failed[] = [
|
||||
'index' => $index,
|
||||
'errors' => $itemValidator->errors()->toArray(),
|
||||
];
|
||||
$failedCount++;
|
||||
|
||||
continue;
|
||||
}
|
||||
|
||||
try {
|
||||
$allocation = Allocation::create($allocationData);
|
||||
$data[] = [
|
||||
'index' => $index,
|
||||
'id' => $allocation->id,
|
||||
'status' => 'created',
|
||||
];
|
||||
$created++;
|
||||
} catch (\Exception $e) {
|
||||
$failed[] = [
|
||||
'index' => $index,
|
||||
'errors' => ['allocation' => ['Failed to create allocation: '.$e->getMessage()]],
|
||||
];
|
||||
$failedCount++;
|
||||
}
|
||||
}
|
||||
|
||||
return $this->wrapResource(AllocationResource::collection($created), 201);
|
||||
return response()->json([
|
||||
'data' => $data,
|
||||
'failed' => $failed,
|
||||
'summary' => [
|
||||
'created' => $created,
|
||||
'failed' => $failedCount,
|
||||
],
|
||||
], 201);
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user