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

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

backend/app/Http/Controllers/Api/ActualController.php

@@ -10,15 +10,22 @@ use App\Models\Project;
 use App\Models\TeamMember;
 use App\Services\ActualsService;
 use Carbon\Carbon;
+use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Validator;
 use Illuminate\Pagination\LengthAwarePaginator;
 
 class ActualController extends Controller
 {
+    use AuthorizesRequests;
     protected ActualsService $actualsService;
-    private const LOCKED_PROJECT_STATUSES = ['Done', 'Cancelled', 'Closed'];
+
+    private const MAX_PER_PAGE = 250;
+    private const MAX_HOURS_PER_ENTRY = 744; // 24h * 31 days - maximum hours in a month
+    private const VARIANCE_GREEN_THRESHOLD = 5;
+    private const VARIANCE_YELLOW_THRESHOLD = 20;
 
     public function __construct(ActualsService $actualsService)
     {
@@ -31,9 +38,9 @@ class ActualController extends Controller
             'month' => ['required', 'date_format:Y-m'],
             'project_ids.*' => ['uuid'],
             'team_member_ids.*' => ['uuid'],
-            'include_inactive' => ['boolean'],
+            'include_inactive' => ['nullable', 'in:true,false,1,0'],
             'page' => ['integer', 'min:1'],
-            'per_page' => ['integer', 'min:1', 'max:250'],
+            'per_page' => ['integer', 'min:1', 'max:' . self::MAX_PER_PAGE],
         ]);
 
         if ($validator->fails()) {
@@ -46,7 +53,7 @@ class ActualController extends Controller
         $monthKey = $request->query('month');
 
         try {
-            $monthDate = Carbon::createFromFormat('Y-m', $monthKey)->startOfMonth();
+            $monthDate = Carbon::createFromFormat('Y-m', $monthKey)->startOfMonth()->toDateString();
         } catch (\Throwable) {
             return response()->json([
                 'message' => 'Validation failed',
@@ -63,17 +70,23 @@ class ActualController extends Controller
             $searchTerm = null;
         }
 
+        // Escape LIKE wildcards to prevent SQL injection via pattern matching
+        $escapedSearchTerm = $searchTerm !== null
+            ? str_replace(['%', '_', '\\'], ['\\%', '\\_', '\\\\'], $searchTerm)
+            : null;
+
+        $inactiveStatuses = $this->actualsService->getInactiveProjectStatuses();
+
         $projects = Project::with('status')
             ->when($projectIdsFilter, fn ($query) => $query->whereIn('id', $projectIdsFilter))
-            ->when(! $includeInactive, fn ($query) => $query->whereHas('status', fn ($query) => $query->whereNotIn('name', self::LOCKED_PROJECT_STATUSES)))
-            ->when($searchTerm, fn ($query) => $query->where(fn ($query) => $query->where('code', 'like', "%{$searchTerm}%")->orWhere('title', 'like', "%{$searchTerm}%")))
+            ->when(! $includeInactive, fn ($query) => $query->whereHas('status', fn ($query) => $query->whereNotIn('name', $inactiveStatuses)))
+            ->when($escapedSearchTerm !== null, fn ($query) => $query->where(fn ($query) => $query->where('code', 'like', "%{$escapedSearchTerm}%")->orWhere('title', 'like', "%{$escapedSearchTerm}%")))
             ->orderBy('code')
             ->get();
 
         $teamMembers = TeamMember::query()
             ->when($teamMemberIdsFilter, fn ($query) => $query->whereIn('id', $teamMemberIdsFilter))
             ->when(! $includeInactive, fn ($query) => $query->where('active', true))
-            ->when($searchTerm, fn ($query) => $query->where('name', 'like', "%{$searchTerm}%"))
             ->orderBy('name')
             ->get();
 
@@ -85,14 +98,14 @@ class ActualController extends Controller
 
         if (! empty($projectIds) && ! empty($teamMemberIds)) {
             $allocations = Allocation::query()
-                ->where('month', $monthDate)
+                ->whereDate('month', $monthDate)
                 ->when($projectIds, fn ($query) => $query->whereIn('project_id', $projectIds))
                 ->when($teamMemberIds, fn ($query) => $query->whereIn('team_member_id', $teamMemberIds))
                 ->get()
                 ->keyBy(fn (Allocation $allocation) => $allocation->project_id.'-'.$allocation->team_member_id);
 
             $actuals = Actual::query()
-                ->where('month', $monthDate)
+                ->whereDate('month', $monthDate)
                 ->when($projectIds, fn ($query) => $query->whereIn('project_id', $projectIds))
                 ->when($teamMemberIds, fn ($query) => $query->whereIn('team_member_id', $teamMemberIds))
                 ->get()
@@ -152,7 +165,7 @@ class ActualController extends Controller
         }
 
         $page = max(1, (int) $request->query('page', 1));
-        $perPage = max(1, min(250, (int) $request->query('per_page', 25)));
+        $perPage = max(1, min(self::MAX_PER_PAGE, (int) $request->query('per_page', 25)));
         $total = count($rows);
         $currentPageItems = array_slice($rows, ($page - 1) * $perPage, $perPage);
 
@@ -186,7 +199,7 @@ class ActualController extends Controller
             'project_id' => 'required|uuid|exists:projects,id',
             'team_member_id' => 'required|uuid|exists:team_members,id',
             'month' => 'required|date_format:Y-m',
-            'hours' => 'required|numeric|min:0',
+            'hours' => 'required|numeric|min:0|max:' . self::MAX_HOURS_PER_ENTRY,
             'notes' => 'nullable|string|max:1000',
         ]);
 
@@ -215,6 +228,9 @@ class ActualController extends Controller
             ], 422);
         }
 
+        // Authorization check for creating actuals
+        $this->authorize('create', [Actual::class, $request->input('team_member_id')]);
+
         $project = Project::with('status')->find($request->input('project_id'));
 
         if ($project && $project->status && ! $this->actualsService->canLogToInactiveProjects()) {
@@ -235,32 +251,40 @@ class ActualController extends Controller
         $hours = (float) $request->input('hours');
         $notes = $request->input('notes');
 
-        $existing = Actual::where('project_id', $request->input('project_id'))
-            ->where('team_member_id', $request->input('team_member_id'))
-            ->where('month', $monthDate)
-            ->first();
-
         $status = 201;
+        $actual = null;
 
-        if ($existing) {
-            $existing->hours_logged = (float) $existing->hours_logged + $hours;
+        DB::transaction(function () use ($request, $monthDate, $hours, $notes, &$status, &$actual) {
+            $existing = Actual::where('project_id', $request->input('project_id'))
+                ->where('team_member_id', $request->input('team_member_id'))
+                ->whereDate('month', $monthDate)
+                ->lockForUpdate()
+                ->first();
 
-            if ($notes) {
-                $existing->notes = $this->appendNotes($existing->notes, $notes);
+            if ($existing) {
+                // Use atomic increment to prevent race conditions
+                DB::table('actuals')
+                    ->where('id', $existing->id)
+                    ->increment('hours_logged', $hours);
+
+                if ($notes) {
+                    $existing->notes = $this->appendNotes($existing->notes, $notes);
+                    $existing->save();
+                }
+
+                $existing->refresh();
+                $actual = $existing;
+                $status = 200;
+            } else {
+                $actual = Actual::create([
+                    'project_id' => $request->input('project_id'),
+                    'team_member_id' => $request->input('team_member_id'),
+                    'month' => $monthDate,
+                    'hours_logged' => $hours,
+                    'notes' => $notes,
+                ]);
             }
-
-            $existing->save();
-            $actual = $existing;
-            $status = 200;
-        } else {
-            $actual = Actual::create([
-                'project_id' => $request->input('project_id'),
-                'team_member_id' => $request->input('team_member_id'),
-                'month' => $monthDate,
-                'hours_logged' => $hours,
-                'notes' => $notes,
-            ]);
-        }
+        });
 
         $actual->load(['project.status', 'teamMember']);
         $this->hydrateVariance($actual, $monthKey);
@@ -299,8 +323,11 @@ class ActualController extends Controller
             ], 404);
         }
 
+        // Authorization check for updating actuals
+        $this->authorize('update', $actual);
+
         $validator = Validator::make($request->all(), [
-            'hours' => 'required|numeric|min:0',
+            'hours' => 'required|numeric|min:0|max:' . self::MAX_HOURS_PER_ENTRY,
             'notes' => 'nullable|string|max:1000',
         ]);
 
@@ -339,6 +366,9 @@ class ActualController extends Controller
             ], 404);
         }
 
+        // Authorization check for deleting actuals
+        $this->authorize('delete', $actual);
+
         $actual->delete();
 
         return response()->json([
@@ -398,7 +428,7 @@ class ActualController extends Controller
             return false;
         }
 
-        return in_array($status->name, self::LOCKED_PROJECT_STATUSES, true);
+        return in_array($status->name, $this->actualsService->getInactiveProjectStatuses(), true);
     }
 
     private function formatHours(float $hours): string
@@ -418,11 +448,11 @@ class ActualController extends Controller
 
         $absolute = abs($variancePercentage);
 
-        if ($absolute <= 5) {
+        if ($absolute <= self::VARIANCE_GREEN_THRESHOLD) {
             return 'green';
         }
 
-        if ($absolute <= 20) {
+        if ($absolute <= self::VARIANCE_YELLOW_THRESHOLD) {
             return 'yellow';
         }