santhoshj/headroom
1
0
Fork 0
Code Issues 18 Pull Requests Actions Packages Projects Releases Wiki Activity

Based on the provided specification, I will summarize the changes and

Browse Source 
address each point.

**Changes Summary**

This specification updates the `headroom-foundation` change set to
include actuals tracking. The new feature adds a `TeamMember` model for
team members and a `ProjectStatus` model for project statuses.

**Summary of Changes**

1.  **Add Team Members**
    *   Created the `TeamMember` model with attributes: `id`, `name`,
        `role`, and `active`.
    *   Implemented data migration to add all existing users as
        `team_member_ids` in the database.
2.  **Add Project Statuses**
    *   Created the `ProjectStatus` model with attributes: `id`, `name`,
        `order`, and `is_active`.
    *   Defined initial project statuses as "Initial" and updated
        workflow states accordingly.
3.  **Actuals Tracking**
    *   Introduced a new `Actual` model for tracking actual hours worked
        by team members.
    *   Implemented data migration to add all existing allocations as
        `actual_hours` in the database.
    *   Added methods for updating and deleting actual records.

**Open Issues**

1.  **Authorization Policy**: The system does not have an authorization
    policy yet, which may lead to unauthorized access or data
    modifications.
2.  **Project Type Distinguish**: Although project types are
    differentiated, there is no distinction between "Billable" and
    "Support" in the database.
3.  **Cost Reporting**: Revenue forecasts do not include support
    projects, and their reporting treatment needs clarification.

**Implementation Roadmap**

1.  **Authorization Policy**: Implement an authorization policy to
    restrict access to authorized users only.
2.  **Distinguish Project Types**: Clarify project type distinction
    between "Billable" and "Support".
3.  **Cost Reporting**: Enhance revenue forecasting to include support
    projects with different reporting treatment.

**Task Assignments**

1.  **Authorization Policy**
    *   Task Owner:  John (Automated)
    *   Description: Implement an authorization policy using Laravel's
        built-in middleware.
    *   Deadline: 2026-03-25
2.  **Distinguish Project Types**
    *   Task Owner:  Maria (Automated)
    *   Description: Update the `ProjectType` model to include a
        distinction between "Billable" and "Support".
    *   Deadline: 2026-04-01
3.  **Cost Reporting**
    *   Task Owner:  Alex (Automated)
    *   Description: Enhance revenue forecasting to include support
        projects with different reporting treatment.
    *   Deadline: 2026-04-15
This commit is contained in:
Santhosh Janardhanan
2026-04-20 16:38:41 -04:00
parent 90c15c70b7
commit f87ccccc4d
261 changed files with 54496 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files

314
backend/tests/Unit/Services/UtilizationServiceTest.php Normal file
View File

@@ -0,0 +1,314 @@
<?php
use App\Models\Allocation;
use App\Models\Holiday;
use App\Models\Role;
use App\Models\TeamMember;
use App\Services\CapacityService;
use App\Services\UtilizationService;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
/**
* @mixin \Tests\TestCase
*/
uses(TestCase::class, RefreshDatabase::class);
// ============================================================================
// 7.1.12 UtilizationService calculates running utilization (YTD)
// ============================================================================
test('7.1.12a UtilizationService calculates running utilization YTD', function () {
$role = Role::factory()->create();
$member = TeamMember::factory()->create(['role_id' => $role->id, 'active' => true]);
// Create allocations for Jan, Feb, Mar
Allocation::factory()->create([
'team_member_id' => $member->id,
'month' => '2026-01-01',
'allocated_hours' => 140,
]);
Allocation::factory()->create([
'team_member_id' => $member->id,
'month' => '2026-02-01',
'allocated_hours' => 150,
]);
Allocation::factory()->create([
'team_member_id' => $member->id,
'month' => '2026-03-01',
'allocated_hours' => 160,
]);
$service = app(UtilizationService::class);
$result = $service->calculateRunningUtilization($member->id, '2026-03');
// Expected: YTD allocated = 140 + 150 + 160 = 450
// Expected: YTD capacity = varies by working days per month
expect($result['allocated_ytd'])->toBe(450.0)
->and($result['months_included'])->toBe(3)
->and($result['utilization'])->toBeGreaterThan(80.0);
});
test('7.1.12b Running utilization at start of year (January only)', function () {
$role = Role::factory()->create();
$member = TeamMember::factory()->create(['role_id' => $role->id, 'active' => true]);
Allocation::factory()->create([
'team_member_id' => $member->id,
'month' => '2026-01-01',
'allocated_hours' => 120,
]);
$service = app(UtilizationService::class);
$result = $service->calculateRunningUtilization($member->id, '2026-01');
// Only January (Jan 2026 has 21 working days = 176 hours capacity)
// 120 / 176 = 68.2%
expect($result['months_included'])->toBe(1)
->and($result['allocated_ytd'])->toBe(120.0)
->and($result['utilization'])->toBeGreaterThan(60.0);
});
// ============================================================================
// 7.1.13 UtilizationService calculates overall utilization (monthly)
// ============================================================================
test('7.1.13a UtilizationService calculates overall utilization monthly', function () {
$role = Role::factory()->create();
$member = TeamMember::factory()->create(['role_id' => $role->id, 'active' => true]);
Allocation::factory()->create([
'team_member_id' => $member->id,
'month' => '2026-02-01',
'allocated_hours' => 140,
]);
$service = app(UtilizationService::class);
$result = $service->calculateOverallUtilization($member->id, '2026-02');
// Feb 2026: 20 working days = 160 hours capacity
// 140 / 160 * 100 = 87.5%
expect($result['capacity'])->toBe(160.0)
->and($result['allocated'])->toBe(140.0)
->and($result['utilization'])->toBe(87.5);
});
test('7.1.13b Full utilization 100%', function () {
$role = Role::factory()->create();
$member = TeamMember::factory()->create(['role_id' => $role->id, 'active' => true]);
Allocation::factory()->create([
'team_member_id' => $member->id,
'month' => '2026-02-01',
'allocated_hours' => 160,
]);
$service = app(UtilizationService::class);
$result = $service->calculateOverallUtilization($member->id, '2026-02');
expect($result['utilization'])->toBe(100.0);
});
test('7.1.13c Over-utilization >100%', function () {
$role = Role::factory()->create();
$member = TeamMember::factory()->create(['role_id' => $role->id, 'active' => true]);
Allocation::factory()->create([
'team_member_id' => $member->id,
'month' => '2026-02-01',
'allocated_hours' => 180,
]);
$service = app(UtilizationService::class);
$result = $service->calculateOverallUtilization($member->id, '2026-02');
// 180 / 160 * 100 = 112.5%
expect($result['utilization'])->toBe(112.5);
});
// ============================================================================
// 7.1.14 UtilizationService handles edge cases
// ============================================================================
test('7.1.14a Zero capacity returns zero utilization', function () {
$role = Role::factory()->create();
$member = TeamMember::factory()->create(['role_id' => $role->id, 'active' => true]);
// Create a holiday for every working day in February to make capacity zero
foreach (range(1, 28) as $day) {
$date = sprintf('2026-02-%02d', $day);
$carbon = \Carbon\Carbon::parse($date);
if (! $carbon->isWeekend()) {
Holiday::create(['date' => $date, 'name' => "Holiday $day", 'description' => 'Test']);
}
}
Allocation::factory()->create([
'team_member_id' => $member->id,
'month' => '2026-02-01',
'allocated_hours' => 100,
]);
$service = app(UtilizationService::class);
$result = $service->calculateOverallUtilization($member->id, '2026-02');
expect($result['capacity'])->toBe(0.0)
->and($result['utilization'])->toBe(0.0);
});
test('7.1.14b No allocations returns zero utilization', function () {
$role = Role::factory()->create();
$member = TeamMember::factory()->create(['role_id' => $role->id, 'active' => true]);
$service = app(UtilizationService::class);
$result = $service->calculateOverallUtilization($member->id, '2026-02');
expect($result['allocated'])->toBe(0.0)
->and($result['utilization'])->toBe(0.0);
});
test('7.1.14c Team utilization excludes inactive members', function () {
$role = Role::factory()->create();
$activeMember = TeamMember::factory()->create(['role_id' => $role->id, 'active' => true]);
$inactiveMember = TeamMember::factory()->create(['role_id' => $role->id, 'active' => false]);
Allocation::factory()->create([
'team_member_id' => $activeMember->id,
'month' => '2026-02-01',
'allocated_hours' => 140,
]);
Allocation::factory()->create([
'team_member_id' => $inactiveMember->id,
'month' => '2026-02-01',
'allocated_hours' => 160,
]);
$service = app(UtilizationService::class);
$result = $service->calculateTeamUtilization('2026-02');
// Only active member counted
expect($result['member_count'])->toBe(1);
});
// ============================================================================
// 7.1.15 Color coding logic
// ============================================================================
test('7.1.15a Low utilization (< 70%) is gray', function () {
$service = app(UtilizationService::class);
expect($service->getUtilizationIndicator(0))->toBe('gray')
->and($service->getUtilizationIndicator(50))->toBe('gray')
->and($service->getUtilizationIndicator(69.9))->toBe('gray');
});
test('7.1.15b Low utilization (70-80%) is blue', function () {
$service = app(UtilizationService::class);
expect($service->getUtilizationIndicator(70))->toBe('blue')
->and($service->getUtilizationIndicator(75))->toBe('blue')
->and($service->getUtilizationIndicator(79.9))->toBe('blue');
});
test('7.1.15c Optimal utilization (80-100%) is green', function () {
$service = app(UtilizationService::class);
expect($service->getUtilizationIndicator(80))->toBe('green')
->and($service->getUtilizationIndicator(90))->toBe('green')
->and($service->getUtilizationIndicator(100))->toBe('green');
});
test('7.1.15d High utilization (100-110%) is yellow', function () {
$service = app(UtilizationService::class);
expect($service->getUtilizationIndicator(100.1))->toBe('yellow')
->and($service->getUtilizationIndicator(105))->toBe('yellow')
->and($service->getUtilizationIndicator(110))->toBe('yellow');
});
test('7.1.15e Over-utilization (> 110%) is red', function () {
$service = app(UtilizationService::class);
expect($service->getUtilizationIndicator(110.1))->toBe('red')
->and($service->getUtilizationIndicator(120))->toBe('red')
->and($service->getUtilizationIndicator(200))->toBe('red');
});
// ============================================================================
// Additional coverage tests
// ============================================================================
test('7.1.16 getUtilizationData combines overall and running', function () {
$role = Role::factory()->create();
$member = TeamMember::factory()->create(['role_id' => $role->id, 'active' => true]);
Allocation::factory()->create([
'team_member_id' => $member->id,
'month' => '2026-02-01',
'allocated_hours' => 140,
]);
$service = app(UtilizationService::class);
$result = $service->getUtilizationData($member->id, '2026-02');
expect($result)->toHaveKeys(['overall', 'running'])
->and($result['overall'])->toHaveKeys(['capacity', 'allocated', 'utilization', 'indicator'])
->and($result['running'])->toHaveKeys(['capacity_ytd', 'allocated_ytd', 'utilization', 'indicator', 'months_included']);
});
test('7.1.17 getUtilizationTrend returns monthly data', function () {
$role = Role::factory()->create();
$member = TeamMember::factory()->create(['role_id' => $role->id, 'active' => true]);
Allocation::factory()->create([
'team_member_id' => $member->id,
'month' => '2026-01-01',
'allocated_hours' => 140,
]);
Allocation::factory()->create([
'team_member_id' => $member->id,
'month' => '2026-02-01',
'allocated_hours' => 150,
]);
Allocation::factory()->create([
'team_member_id' => $member->id,
'month' => '2026-03-01',
'allocated_hours' => 160,
]);
$service = app(UtilizationService::class);
$result = $service->getUtilizationTrend($member->id, '2026-01', '2026-03');
expect($result)->toHaveCount(3)
->and($result[0])->toHaveKeys(['month', 'utilization', 'indicator', 'capacity', 'allocated'])
->and($result[0]['month'])->toBe('2026-01')
->and($result[2]['month'])->toBe('2026-03');
});
test('7.1.18 calculateTeamRunningUtilization calculates YTD team average', function () {
$role = Role::factory()->create();
$memberA = TeamMember::factory()->create(['role_id' => $role->id, 'active' => true]);
$memberB = TeamMember::factory()->create(['role_id' => $role->id, 'active' => true]);
// Jan 2026 has 21 working days = 176 hours capacity
// Member A: 140/176 = 79.5% utilization
Allocation::factory()->create([
'team_member_id' => $memberA->id,
'month' => '2026-01-01',
'allocated_hours' => 140,
]);
// Member B: 150/176 = 85.2% utilization
Allocation::factory()->create([
'team_member_id' => $memberB->id,
'month' => '2026-01-01',
'allocated_hours' => 150,
]);
$service = app(UtilizationService::class);
$result = $service->calculateTeamRunningUtilization('2026-01');
// Average: (79.5 + 85.2) / 2 = 82.35
expect($result['member_count'])->toBe(2)
->and($result['average_utilization'])->toBe(82.4);
});