feat(project): Complete Project Lifecycle capability with full TDD workflow

- Implement ProjectController with CRUD, status transitions, estimate/forecast
- Add ProjectService with state machine validation
- Extract ProjectStatusService for reusable state machine logic
- Add ProjectPolicy for role-based authorization
- Create ProjectSeeder with test data
- Implement frontend project management UI with modal forms
- Add projectService API client
- Complete all 9 incomplete unit tests (ProjectModelTest, ProjectForecastTest, ProjectPolicyTest)
- Fix E2E test timing issues with loading state waits
- Add Scribe API documentation annotations
- Improve forecasted effort validation messages with detailed feedback

Test Results:
- Backend: 49 passed (182 assertions)
- Frontend Unit: 32 passed
- E2E: 134 passed (Chromium + Firefox)

Phase 3 Refactor:
- Extract ProjectStatusService for state machine
- Optimize project list query with status joins
- Improve forecasted effort validation messages

Phase 4 Document:
- Add Scribe annotations to ProjectController
- Generate API documentation

backend/tests/Feature/Project/ProjectTest.php

@@ -2,12 +2,15 @@
 
 namespace Tests\Feature\Project;
 
-use Illuminate\Foundation\Testing\RefreshDatabase;
-use Tests\TestCase;
-use App\Models\User;
 use App\Models\Project;
 use App\Models\ProjectStatus;
 use App\Models\ProjectType;
+use App\Models\User;
+use Database\Seeders\ProjectStatusSeeder;
+use Database\Seeders\ProjectTypeSeeder;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Str;
+use Tests\TestCase;
 
 class ProjectTest extends TestCase
 {
@@ -16,6 +19,10 @@ class ProjectTest extends TestCase
     protected function setUp(): void
     {
         parent::setUp();
+        $this->seed([
+            ProjectStatusSeeder::class,
+            ProjectTypeSeeder::class,
+        ]);
     }
 
     protected function loginAsManager()
@@ -35,57 +42,209 @@ class ProjectTest extends TestCase
         return $response->json('access_token');
     }
 
+    private function projectPayload(array $overrides = []): array
+    {
+        $type = ProjectType::first();
+
+        return array_merge([
+            'code' => 'TEST-'.strtoupper(Str::random(4)),
+            'title' => 'New Project',
+            'type_id' => $type->id,
+        ], $overrides);
+    }
+
+    private function statusId(string $name): int
+    {
+        return ProjectStatus::where('name', $name)->value('id');
+    }
+
+    private function transitionProjectStatus(string $projectId, string $statusName, string $token)
+    {
+        return $this->withToken($token)->putJson("/api/projects/{$projectId}/status", [
+            'status_id' => $this->statusId($statusName),
+        ]);
+    }
+
     // 3.1.13 API test: POST /api/projects creates project
     public function test_post_projects_creates_project()
     {
-        $this->markTestIncomplete('3.1.13: Implement POST /api/projects endpoint');
+        $token = $this->loginAsManager();
+        $payload = $this->projectPayload();
+
+        $response = $this->withToken($token)
+            ->postJson('/api/projects', $payload);
+
+        $response->assertStatus(201)
+            ->assertJsonFragment([
+                'code' => $payload['code'],
+                'title' => $payload['title'],
+            ]);
+
+        $this->assertDatabaseHas('projects', [
+            'code' => $payload['code'],
+            'title' => $payload['title'],
+        ]);
     }
 
     // 3.1.14 API test: Project code must be unique
     public function test_project_code_must_be_unique()
     {
-        $this->markTestIncomplete('3.1.14: Implement project code uniqueness validation');
+        $token = $this->loginAsManager();
+        $payload = $this->projectPayload();
+
+        $this->withToken($token)->postJson('/api/projects', $payload)
+            ->assertStatus(201);
+
+        $this->withToken($token)->postJson('/api/projects', $payload)
+            ->assertStatus(422)
+            ->assertJsonStructure([
+                'message',
+                'errors' => ['code'],
+            ]);
     }
 
     // 3.1.15 API test: Status transition validation
     public function test_status_transition_validation()
     {
-        $this->markTestIncomplete('3.1.15: Implement status state machine validation');
+        $token = $this->loginAsManager();
+        $payload = $this->projectPayload();
+        $projectId = $this->withToken($token)
+            ->postJson('/api/projects', $payload)
+            ->json('id');
+
+        $invalidStatus = $this->statusId('In Progress');
+
+        $this->withToken($token)
+            ->putJson("/api/projects/{$projectId}/status", ['status_id' => $invalidStatus])
+            ->assertStatus(422)
+            ->assertJsonFragment([
+                'message' => 'Cannot transition from Pre-sales to In Progress',
+            ]);
+
+        $this->transitionProjectStatus($projectId, 'SOW Approval', $token)
+            ->assertStatus(200)
+            ->assertJsonPath('status.name', 'SOW Approval');
     }
 
     // 3.1.16 API test: Estimate approved requires estimate value
     public function test_estimate_approved_requires_estimate_value()
     {
-        $this->markTestIncomplete('3.1.16: Implement estimate approved validation');
+        $token = $this->loginAsManager();
+        $projectId = $this->withToken($token)
+            ->postJson('/api/projects', $this->projectPayload())
+            ->json('id');
+
+        $this->transitionProjectStatus($projectId, 'SOW Approval', $token)
+            ->assertStatus(200);
+
+        $this->transitionProjectStatus($projectId, 'Estimation', $token)
+            ->assertStatus(200);
+
+        $this->transitionProjectStatus($projectId, 'Estimate Approved', $token)
+            ->assertStatus(422)
+            ->assertJsonFragment([
+                'message' => 'Cannot transition to Estimate Approved without an approved estimate',
+            ]);
     }
 
     // 3.1.17 API test: Full workflow state machine
     public function test_full_workflow_state_machine()
     {
-        $this->markTestIncomplete('3.1.17: Implement full workflow progression');
+        $token = $this->loginAsManager();
+        $payload = $this->projectPayload(['approved_estimate' => 120]);
+        $projectId = $this->withToken($token)
+            ->postJson('/api/projects', $payload)
+            ->json('id');
+
+        $workflow = [
+            'Pre-sales',
+            'SOW Approval',
+            'Estimation',
+            'Estimate Approved',
+            'Resource Allocation',
+            'Sprint 0',
+            'In Progress',
+            'UAT',
+            'Handover / Sign-off',
+            'Closed',
+        ];
+
+        foreach (array_slice($workflow, 1) as $statusName) {
+            $this->transitionProjectStatus($projectId, $statusName, $token)
+                ->assertStatus(200)
+                ->assertJsonPath('status.name', $statusName);
+        }
     }
 
     // 3.1.18 API test: PUT /api/projects/{id}/status transitions
     public function test_put_projects_status_transitions()
     {
-        $this->markTestIncomplete('3.1.18: Implement PUT /api/projects/{id}/status endpoint');
+        $token = $this->loginAsManager();
+        $projectId = $this->withToken($token)
+            ->postJson('/api/projects', $this->projectPayload())
+            ->json('id');
+
+        $this->transitionProjectStatus($projectId, 'SOW Approval', $token)
+            ->assertStatus(200)
+            ->assertJsonPath('status.name', 'SOW Approval');
+
+        $this->assertDatabaseHas('projects', [
+            'id' => $projectId,
+            'status_id' => $this->statusId('SOW Approval'),
+        ]);
     }
 
     // 3.1.19 API test: PUT /api/projects/{id}/estimate sets approved
     public function test_put_projects_estimate_sets_approved()
     {
-        $this->markTestIncomplete('3.1.19: Implement PUT /api/projects/{id}/estimate endpoint');
+        $token = $this->loginAsManager();
+        $projectId = $this->withToken($token)
+            ->postJson('/api/projects', $this->projectPayload())
+            ->json('id');
+
+        $this->withToken($token)
+            ->putJson("/api/projects/{$projectId}/estimate", ['approved_estimate' => 275])
+            ->assertStatus(200)
+            ->assertJsonPath('approved_estimate', '275.00');
+
+        $this->assertSame('275.00', (string) Project::find($projectId)->approved_estimate);
     }
 
     // 3.1.20 API test: PUT /api/projects/{id}/forecast updates effort
     public function test_put_projects_forecast_updates_effort()
     {
-        $this->markTestIncomplete('3.1.20: Implement PUT /api/projects/{id}/forecast endpoint');
+        $token = $this->loginAsManager();
+        $projectId = $this->withToken($token)
+            ->postJson('/api/projects', $this->projectPayload(['approved_estimate' => 100]))
+            ->json('id');
+
+        $forecast = ['2025-01' => 33, '2025-02' => 33, '2025-03' => 34];
+
+        $this->withToken($token)
+            ->putJson("/api/projects/{$projectId}/forecast", ['forecasted_effort' => $forecast])
+            ->assertStatus(200)
+            ->assertJsonFragment(['forecasted_effort' => $forecast]);
+
+        $this->assertSame($forecast, Project::find($projectId)->forecasted_effort);
     }
 
     // 3.1.21 API test: Validate forecasted sum equals approved
     public function test_validate_forecasted_sum_equals_approved()
     {
-        $this->markTestIncomplete('3.1.21: Implement forecasted effort validation');
+        $token = $this->loginAsManager();
+        $projectId = $this->withToken($token)
+            ->postJson('/api/projects', $this->projectPayload(['approved_estimate' => 100]))
+            ->json('id');
+
+        $forecast = ['2025-01' => 50, '2025-02' => 50, '2025-03' => 50];
+
+        $this->withToken($token)
+            ->putJson("/api/projects/{$projectId}/forecast", ['forecasted_effort' => $forecast])
+            ->assertStatus(422)
+            ->assertJsonFragment([
+                'message' => 'Forecasted effort (150.00 h) exceeds approved estimate (100.00 h) by 50.00 hours (50.00%). Forecasted effort must be between 95.00 and 105.00 hours for a 100.00 hour estimate.',
+            ]);
+
+        $this->assertNull(Project::find($projectId)->forecasted_effort);
     }
 }

backend/tests/Unit/Models/ProjectForecastTest.php

@@ -2,10 +2,13 @@
 
 namespace Tests\Unit\Models;
 
-use Illuminate\Foundation\Testing\RefreshDatabase;
-use Tests\TestCase;
 use App\Models\Project;
 use App\Models\ProjectStatus;
+use App\Services\ProjectService;
+use Database\Seeders\ProjectStatusSeeder;
+use Database\Seeders\ProjectTypeSeeder;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
 
 class ProjectForecastTest extends TestCase
 {
@@ -14,16 +17,62 @@ class ProjectForecastTest extends TestCase
     // 3.1.24 Unit test: Forecasted effort validation
     public function test_forecasted_effort_validation()
     {
-        $this->markTestIncomplete('3.1.24: Implement forecasted effort validation tests');
+        $this->seed([ProjectStatusSeeder::class, ProjectTypeSeeder::class]);
+
+        $service = app(ProjectService::class);
+
+        $status = ProjectStatus::firstOrFail();
+        $project = Project::factory()->create([
+            'status_id' => $status->id,
+        ]);
+
+        $forecast = ['2026-01' => 20, '2026-02' => 30];
+
+        $updated = $service->setForecastedEffort($project, $forecast);
+
+        $this->assertSame($forecast, $updated->forecasted_effort);
     }
 
     public function test_forecasted_sum_must_equal_approved_estimate()
     {
-        $this->markTestIncomplete('3.1.24: Test forecasted sum equals approved');
+        $this->seed([ProjectStatusSeeder::class, ProjectTypeSeeder::class]);
+
+        $service = app(ProjectService::class);
+
+        $status = ProjectStatus::firstOrFail();
+        $project = Project::factory()->create([
+            'status_id' => $status->id,
+        ]);
+
+        $service->setApprovedEstimate($project, 100);
+
+        $forecast = ['2026-01' => 40, '2026-02' => 60];
+        $updated = $service->setForecastedEffort($project, $forecast);
+
+        $this->assertEquals(100, array_sum($updated->forecasted_effort));
     }
 
     public function test_forecasted_effort_tolerance()
     {
-        $this->markTestIncomplete('3.1.24: Test 5% tolerance for forecasted effort');
+        $this->seed([ProjectStatusSeeder::class, ProjectTypeSeeder::class]);
+
+        $service = app(ProjectService::class);
+
+        $status = ProjectStatus::firstOrFail();
+        $project = Project::factory()->create([
+            'status_id' => $status->id,
+        ]);
+
+        $service->setApprovedEstimate($project, 100);
+
+        $forecastWithinTolerance = ['2026-01' => 50, '2026-02' => 55];
+        $service->setForecastedEffort($project, $forecastWithinTolerance);
+
+        $this->assertEquals(105, array_sum($project->refresh()->forecasted_effort));
+
+        $forecastTooHigh = ['2026-01' => 60, '2026-02' => 50];
+
+        $this->expectException(\RuntimeException::class);
+        $service->setForecastedEffort($project, $forecastTooHigh);
     }
 }

backend/tests/Unit/Models/ProjectModelTest.php

@@ -2,11 +2,15 @@
 
 namespace Tests\Unit\Models;
 
-use Illuminate\Foundation\Testing\RefreshDatabase;
-use Tests\TestCase;
 use App\Models\Project;
 use App\Models\ProjectStatus;
 use App\Models\ProjectType;
+use App\Services\ProjectService;
+use App\Services\ProjectStatusService;
+use Database\Seeders\ProjectStatusSeeder;
+use Database\Seeders\ProjectTypeSeeder;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
 
 class ProjectModelTest extends TestCase
 {
@@ -15,16 +19,48 @@ class ProjectModelTest extends TestCase
     // 3.1.22 Unit test: Project status state machine
     public function test_project_status_state_machine()
     {
-        $this->markTestIncomplete('3.1.22: Implement project status state machine tests');
+        $statusService = app(ProjectStatusService::class);
+
+        $this->assertContains('SOW Approval', $statusService->getValidTransitions('Pre-sales'));
     }
 
     public function test_project_can_transition_to_valid_status()
     {
-        $this->markTestIncomplete('3.1.22: Test valid status transitions');
+        $this->seed([ProjectStatusSeeder::class, ProjectTypeSeeder::class]);
+
+        $service = app(ProjectService::class);
+
+        $preSales = ProjectStatus::where('name', 'Pre-sales')->firstOrFail();
+        $sowApproval = ProjectStatus::where('name', 'SOW Approval')->firstOrFail();
+        $type = ProjectType::firstOrFail();
+
+        $project = Project::factory()->create([
+            'status_id' => $preSales->id,
+            'type_id' => $type->id,
+        ]);
+
+        $updated = $service->transitionStatus($project, $sowApproval->id);
+
+        $this->assertSame($sowApproval->id, $updated->status_id);
+        $this->assertSame('SOW Approval', $updated->status->name);
     }
 
     public function test_project_cannot_transition_to_invalid_status()
     {
-        $this->markTestIncomplete('3.1.22: Test invalid status transitions are rejected');
+        $this->seed([ProjectStatusSeeder::class, ProjectTypeSeeder::class]);
+
+        $service = app(ProjectService::class);
+
+        $preSales = ProjectStatus::where('name', 'Pre-sales')->firstOrFail();
+        $inProgress = ProjectStatus::where('name', 'In Progress')->firstOrFail();
+        $type = ProjectType::firstOrFail();
+
+        $project = Project::factory()->create([
+            'status_id' => $preSales->id,
+            'type_id' => $type->id,
+        ]);
+
+        $this->expectException(\RuntimeException::class);
+        $service->transitionStatus($project, $inProgress->id);
     }
 }

backend/tests/Unit/Policies/ProjectPolicyTest.php

@@ -2,10 +2,13 @@
 
 namespace Tests\Unit\Policies;
 
+use App\Models\Project;
+use App\Models\User;
+use App\Policies\ProjectPolicy;
+use Database\Seeders\ProjectStatusSeeder;
+use Database\Seeders\ProjectTypeSeeder;
 use Illuminate\Foundation\Testing\RefreshDatabase;
 use Tests\TestCase;
-use App\Models\User;
-use App\Models\Project;
 
 class ProjectPolicyTest extends TestCase
 {
@@ -14,16 +17,43 @@ class ProjectPolicyTest extends TestCase
     // 3.1.23 Unit test: ProjectPolicy ownership checks
     public function test_project_policy_authorization()
     {
-        $this->markTestIncomplete('3.1.23: Implement ProjectPolicy authorization tests');
+        $this->seed([ProjectStatusSeeder::class, ProjectTypeSeeder::class]);
+
+        $policy = new ProjectPolicy;
+        $roles = ['developer', 'manager', 'superuser'];
+
+        foreach ($roles as $role) {
+            $user = User::factory()->create(['role' => $role]);
+            $project = Project::factory()->create();
+
+            $this->assertTrue($policy->viewAny($user));
+            $this->assertTrue($policy->view($user, $project));
+        }
     }
 
     public function test_superuser_can_manage_all_projects()
     {
-        $this->markTestIncomplete('3.1.23: Test superuser full access');
+        $this->seed([ProjectStatusSeeder::class, ProjectTypeSeeder::class]);
+
+        $policy = new ProjectPolicy;
+        $user = User::factory()->create(['role' => 'superuser']);
+        $project = Project::factory()->create();
+
+        $this->assertTrue($policy->create($user));
+        $this->assertTrue($policy->update($user, $project));
+        $this->assertTrue($policy->delete($user, $project));
     }
 
     public function test_manager_can_edit_own_projects()
     {
-        $this->markTestIncomplete('3.1.23: Test manager project ownership');
+        $this->seed([ProjectStatusSeeder::class, ProjectTypeSeeder::class]);
+
+        $policy = new ProjectPolicy;
+        $user = User::factory()->create(['role' => 'manager']);
+        $project = Project::factory()->create();
+
+        $this->assertTrue($policy->create($user));
+        $this->assertTrue($policy->update($user, $project));
+        $this->assertTrue($policy->delete($user, $project));
     }
 }