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

feat(api): Implement API Resource Standard compliance

Browse Source 
- Create BaseResource with formatDate() and formatDecimal() utilities
- Create 11 API Resource classes for all models
- Update all 6 controllers to return wrapped responses via wrapResource()
- Update frontend API client with unwrapResponse() helper
- Update all 63+ backend tests to expect 'data' wrapper
- Regenerate Scribe API documentation

BREAKING CHANGE: All API responses now wrap data in 'data' key per architecture spec.

Backend Tests: 70 passed, 5 failed (unrelated to data wrapper)
Frontend Unit: 10 passed
E2E Tests: 102 passed, 20 skipped
API Docs: Generated successfully

Refs: openspec/changes/api-resource-standard
This commit is contained in:
Santhosh Janardhanan
2026-02-19 14:51:56 -05:00
parent 1592c5be8d
commit 47068dabce
49 changed files with 2426 additions and 809 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
backend/app/Http/Controllers/Api/AuthController.php
View File

@@ -3,6 +3,7 @@
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use App\Http\Resources\UserResource;
use App\Models\User;
use App\Services\JwtService;
use Illuminate\Http\JsonResponse;
@@ -39,16 +40,19 @@ class AuthController extends Controller
* @bodyParam password string required User password. Example: secret123
*
* @response 200 {
* "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
* "refresh_token": "abc123def456",
* "token_type": "bearer",
* "expires_in": 3600,
* "user": {
* "data": {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "name": "Alice Johnson",
* "email": "user@example.com",
* "role": "manager"
* }
* "role": "manager",
* "active": true,
* "created_at": "2026-01-01T00:00:00Z",
* "updated_at": "2026-01-01T00:00:00Z"
* },
* "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
* "refresh_token": "abc123def456",
* "token_type": "bearer",
* "expires_in": 3600
* }
* @response 401 {"message":"Invalid credentials"}
* @response 403 {"message":"Account is inactive"}
@@ -85,18 +89,12 @@ class AuthController extends Controller
$accessToken = $this->jwtService->generateAccessToken($user);
$refreshToken = $this->jwtService->generateRefreshToken($user);
return response()->json([
return (new UserResource($user))->additional([
'access_token' => $accessToken,
'refresh_token' => $refreshToken,
'token_type' => 'bearer',
'expires_in' => $this->jwtService->getAccessTokenTTL(),
'user' => [
'id' => $user->id,
'name' => $user->name,
'email' => $user->email,
'role' => $user->role,
],
]);
])->response();
}
/**
@@ -105,9 +103,19 @@ class AuthController extends Controller
* Exchange a valid refresh token for a new access token and refresh token pair.
*
* @authenticated
*
* @bodyParam refresh_token string required Refresh token returned by login. Example: abc123def456
*
* @response 200 {
* "data": {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "name": "Alice Johnson",
* "email": "user@example.com",
* "role": "manager",
* "active": true,
* "created_at": "2026-01-01T00:00:00Z",
* "updated_at": "2026-01-01T00:00:00Z"
* },
* "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
* "refresh_token": "newtoken123",
* "token_type": "bearer",
@@ -146,12 +154,12 @@ class AuthController extends Controller
$accessToken = $this->jwtService->generateAccessToken($user);
$newRefreshToken = $this->jwtService->generateRefreshToken($user);
return response()->json([
return (new UserResource($user))->additional([
'access_token' => $accessToken,
'refresh_token' => $newRefreshToken,
'token_type' => 'bearer',
'expires_in' => $this->jwtService->getAccessTokenTTL(),
]);
])->response();
}
/**
@@ -160,6 +168,7 @@ class AuthController extends Controller
* Invalidate a refresh token and end the active authenticated session.
*
* @authenticated
*
* @bodyParam refresh_token string Optional refresh token to invalidate immediately. Example: abc123def456
*
* @response 200 {"message":"Logged out successfully"}

109
backend/app/Http/Controllers/Api/CapacityController.php
View File

@@ -3,6 +3,10 @@
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use App\Http\Resources\CapacityResource;
use App\Http\Resources\RevenueResource;
use App\Http\Resources\TeamCapacityResource;
use App\Models\TeamMember;
use App\Services\CapacityService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
@@ -17,18 +21,25 @@ class CapacityController extends Controller
* Calculate capacity for a specific team member in a given month.
*
* @group Capacity Planning
*
* @urlParam month string required The month in YYYY-MM format. Example: 2026-02
* @urlParam team_member_id string required The team member UUID. Example: 550e8400-e29b-41d4-a716-446655440000
*
* @response {
* "person_days": 18.5,
* "hours": 148,
* "details": [
* {
* "date": "2026-02-02",
* "availability": 1,
* "is_pto": false
* }
* ]
* "data": {
* "team_member_id": "550e8400-e29b-41d4-a716-446655440000",
* "month": "2026-02",
* "working_days": 20,
* "person_days": 18.5,
* "hours": 148,
* "details": [
* {
* "date": "2026-02-02",
* "availability": 1,
* "is_pto": false
* }
* ]
* }
* }
*/
public function individual(Request $request): JsonResponse
@@ -39,8 +50,18 @@ class CapacityController extends Controller
]);
$capacity = $this->capacityService->calculateIndividualCapacity($data['team_member_id'], $data['month']);
$workingDays = $this->capacityService->calculateWorkingDays($data['month']);
return response()->json($capacity);
$payload = [
'team_member_id' => $data['team_member_id'],
'month' => $data['month'],
'working_days' => $workingDays,
'person_days' => $capacity['person_days'],
'hours' => $capacity['hours'],
'details' => $capacity['details'],
];
return $this->wrapResource(new CapacityResource($payload));
}
/**
@@ -49,19 +70,23 @@ class CapacityController extends Controller
* Summarize the combined capacity for all active team members in a month.
*
* @group Capacity Planning
*
* @urlParam month string required The month in YYYY-MM format. Example: 2026-02
*
* @response {
* "month": "2026-02",
* "person_days": 180.5,
* "hours": 1444,
* "members": [
* {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "name": "Ada Lovelace",
* "person_days": 18.5,
* "hours": 148
* }
* ]
* "data": {
* "month": "2026-02",
* "total_person_days": 180.5,
* "total_hours": 1444,
* "members": [
* {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "name": "Ada Lovelace",
* "person_days": 18.5,
* "hours": 148
* }
* ]
* }
* }
*/
public function team(Request $request): JsonResponse
@@ -72,7 +97,7 @@ class CapacityController extends Controller
$payload = $this->capacityService->calculateTeamCapacity($data['month']);
return response()->json($payload);
return $this->wrapResource(new TeamCapacityResource($payload));
}
/**
@@ -81,10 +106,23 @@ class CapacityController extends Controller
* Estimate monthly revenue based on capacity hours and hourly rates.
*
* @group Capacity Planning
*
* @urlParam month string required The month in YYYY-MM format. Example: 2026-02
*
* @response {
* "month": "2026-02",
* "possible_revenue": 21500.25
* "data": {
* "month": "2026-02",
* "possible_revenue": 21500.25,
* "member_revenues": [
* {
* "team_member_id": "550e8400-e29b-41d4-a716-446655440000",
* "team_member_name": "Ada Lovelace",
* "hours": 148,
* "hourly_rate": 150.0,
* "revenue": 22200.0
* }
* ]
* }
* }
*/
public function revenue(Request $request): JsonResponse
@@ -94,10 +132,29 @@ class CapacityController extends Controller
]);
$revenue = $this->capacityService->calculatePossibleRevenue($data['month']);
$memberRevenues = [];
return response()->json([
TeamMember::where('active', true)
->get()
->each(function (TeamMember $member) use ($data, &$memberRevenues): void {
$capacity = $this->capacityService->calculateIndividualCapacity($member->id, $data['month']);
$hours = $capacity['hours'];
$hourlyRate = $member->hourly_rate !== null ? (float) $member->hourly_rate : null;
$memberRevenue = $hourlyRate !== null ? round($hours * $hourlyRate, 2) : 0.0;
$memberRevenues[] = [
'team_member_id' => $member->id,
'team_member_name' => $member->name,
'hours' => $hours,
'hourly_rate' => $hourlyRate,
'revenue' => $memberRevenue,
];
});
return $this->wrapResource(new RevenueResource([
'month' => $data['month'],
'possible_revenue' => $revenue,
]);
'member_revenues' => $memberRevenues,
]));
}
}

39
backend/app/Http/Controllers/Api/HolidayController.php
View File

@@ -3,6 +3,7 @@
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use App\Http\Resources\HolidayResource;
use App\Models\Holiday;
use App\Services\CapacityService;
use Illuminate\Http\JsonResponse;
@@ -18,15 +19,19 @@ class HolidayController extends Controller
* Retrieve holidays for a specific month or all holidays when no month is provided.
*
* @group Capacity Planning
*
* @urlParam month string nullable The month in YYYY-MM format. Example: 2026-02
* @response [
* {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "date": "2026-02-14",
* "name": "Company Holiday",
* "description": "Office closed"
* }
* ]
*
* @response {
* "data": [
* {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "date": "2026-02-14",
* "name": "Company Holiday",
* "description": "Office closed"
* }
* ]
* }
*/
public function index(Request $request): JsonResponse
{
@@ -38,7 +43,7 @@ class HolidayController extends Controller
? $this->capacityService->getHolidaysForMonth($data['month'])
: Holiday::orderBy('date')->get();
return response()->json($holidays);
return $this->wrapResource(HolidayResource::collection($holidays));
}
/**
@@ -47,14 +52,18 @@ class HolidayController extends Controller
* Add a holiday and clear cached capacity data for the related month.
*
* @group Capacity Planning
*
* @bodyParam date string required Date of the holiday. Example: 2026-02-14
* @bodyParam name string required Name of the holiday. Example: Presidents' Day
* @bodyParam description string nullable Optional description of the holiday.
*
* @response 201 {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "date": "2026-02-14",
* "name": "Presidents' Day",
* "description": "Office closed"
* "data": {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "date": "2026-02-14",
* "name": "Presidents' Day",
* "description": "Office closed"
* }
* }
*/
public function store(Request $request): JsonResponse
@@ -68,7 +77,7 @@ class HolidayController extends Controller
$holiday = Holiday::create($data);
$this->capacityService->forgetCapacityCacheForMonth($holiday->date->format('Y-m'));
return response()->json($holiday, 201);
return $this->wrapResource(new HolidayResource($holiday), 201);
}
/**
@@ -77,7 +86,9 @@ class HolidayController extends Controller
* Remove a holiday and clear affected capacity caches.
*
* @group Capacity Planning
*
* @urlParam id string required The holiday UUID. Example: 550e8400-e29b-41d4-a716-446655440000
*
* @response {
* "message": "Holiday deleted"
* }

133
backend/app/Http/Controllers/Api/ProjectController.php
View File

@@ -3,6 +3,9 @@
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use App\Http\Resources\ProjectResource;
use App\Http\Resources\ProjectStatusResource;
use App\Http\Resources\ProjectTypeResource;
use App\Models\Project;
use App\Models\ProjectStatus;
use App\Models\ProjectType;
@@ -41,21 +44,21 @@ class ProjectController extends Controller
* @queryParam status_id integer Filter by status ID. Example: 1
* @queryParam type_id integer Filter by type ID. Example: 2
*
* @response 200 [
* {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "code": "PROJ-001",
* "title": "Client Dashboard Redesign",
* "status_id": 1,
* "status": {"id": 1, "name": "Pre-sales"},
* "type_id": 2,
* "type": {"id": 2, "name": "Support"},
* "approved_estimate": "120.00",
* "forecasted_effort": {"2024-02": 40, "2024-03": 60, "2024-04": 20},
* "created_at": "2024-01-15T10:00:00.000000Z",
* "updated_at": "2024-01-15T10:00:00.000000Z"
* }
* ]
* @response 200 {
* "data": [
* {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "code": "PROJ-001",
* "title": "Client Dashboard Redesign",
* "status": {"id": 1, "name": "Pre-sales"},
* "type": {"id": 2, "name": "Support"},
* "approved_estimate": "120.00",
* "forecasted_effort": {"2024-02": 40, "2024-03": 60, "2024-04": 20},
* "created_at": "2024-01-15T10:00:00.000000Z",
* "updated_at": "2024-01-15T10:00:00.000000Z"
* }
* ]
* }
*/
public function index(Request $request): JsonResponse
{
@@ -64,7 +67,7 @@ class ProjectController extends Controller
$projects = $this->projectService->getAll($statusId, $typeId);
return response()->json($projects);
return $this->wrapResource(ProjectResource::collection($projects));
}
/**
@@ -79,13 +82,13 @@ class ProjectController extends Controller
* @bodyParam type_id integer required Project type ID. Example: 1
*
* @response 201 {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "code": "PROJ-001",
* "title": "Client Dashboard Redesign",
* "status_id": 1,
* "status": {"id": 1, "name": "Pre-sales"},
* "type_id": 1,
* "type": {"id": 1, "name": "Project"}
* "data": {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "code": "PROJ-001",
* "title": "Client Dashboard Redesign",
* "status": {"id": 1, "name": "Pre-sales"},
* "type": {"id": 1, "name": "Project"}
* }
* }
* @response 422 {"message":"Validation failed","errors":{"code":["Project code must be unique"],"title":["The title field is required."]}}
*/
@@ -94,7 +97,7 @@ class ProjectController extends Controller
try {
$project = $this->projectService->create($request->all());
return response()->json($project, 201);
return $this->wrapResource(new ProjectResource($project), 201);
} catch (ValidationException $e) {
return response()->json([
'message' => 'Validation failed',
@@ -113,13 +116,15 @@ class ProjectController extends Controller
* @urlParam id string required Project UUID. Example: 550e8400-e29b-41d4-a716-446655440000
*
* @response 200 {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "code": "PROJ-001",
* "title": "Client Dashboard Redesign",
* "status": {"id": 1, "name": "Pre-sales"},
* "type": {"id": 1, "name": "Project"},
* "approved_estimate": "120.00",
* "forecasted_effort": {"2024-02": 40, "2024-03": 60}
* "data": {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "code": "PROJ-001",
* "title": "Client Dashboard Redesign",
* "status": {"id": 1, "name": "Pre-sales"},
* "type": {"id": 1, "name": "Project"},
* "approved_estimate": "120.00",
* "forecasted_effort": {"2024-02": 40, "2024-03": 60}
* }
* }
* @response 404 {"message":"Project not found"}
*/
@@ -133,7 +138,7 @@ class ProjectController extends Controller
], 404);
}
return response()->json($project);
return $this->wrapResource(new ProjectResource($project));
}
/**
@@ -150,10 +155,12 @@ class ProjectController extends Controller
* @bodyParam type_id integer Project type ID. Example: 2
*
* @response 200 {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "code": "PROJ-002",
* "title": "Updated Title",
* "type_id": 2
* "data": {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "code": "PROJ-002",
* "title": "Updated Title",
* "type": {"id": 2, "name": "Support"}
* }
* }
* @response 404 {"message":"Project not found"}
* @response 422 {"message":"Validation failed","errors":{"type_id":["The selected type id is invalid."]}}
@@ -173,7 +180,7 @@ class ProjectController extends Controller
'code', 'title', 'type_id',
]));
return response()->json($project);
return $this->wrapResource(new ProjectResource($project));
} catch (ValidationException $e) {
return response()->json([
'message' => 'Validation failed',
@@ -194,8 +201,10 @@ class ProjectController extends Controller
* @bodyParam status_id integer required Target status ID. Example: 2
*
* @response 200 {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "status": {"id": 2, "name": "SOW Approval"}
* "data": {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "status": {"id": 2, "name": "SOW Approval"}
* }
* }
* @response 404 {"message":"Project not found"}
* @response 422 {"message":"Cannot transition from Pre-sales to Done"}
@@ -220,7 +229,7 @@ class ProjectController extends Controller
(int) $request->input('status_id')
);
return response()->json($project);
return $this->wrapResource(new ProjectResource($project));
} catch (\RuntimeException $e) {
return response()->json([
'message' => $e->getMessage(),
@@ -239,7 +248,12 @@ class ProjectController extends Controller
*
* @bodyParam approved_estimate number required Approved estimate hours (must be > 0). Example: 120
*
* @response 200 {"id":"550e8400-e29b-41d4-a716-446655440000", "approved_estimate":"120.00"}
* @response 200 {
* "data": {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "approved_estimate": "120.00"
* }
* }
* @response 404 {"message":"Project not found"}
* @response 422 {"message":"Approved estimate must be greater than 0"}
*/
@@ -263,7 +277,7 @@ class ProjectController extends Controller
(float) $request->input('approved_estimate')
);
return response()->json($project);
return $this->wrapResource(new ProjectResource($project));
} catch (\RuntimeException $e) {
return response()->json([
'message' => $e->getMessage(),
@@ -282,7 +296,12 @@ class ProjectController extends Controller
*
* @bodyParam forecasted_effort object required Monthly effort breakdown. Example: {"2024-02": 40, "2024-03": 60}
*
* @response 200 {"id":"550e8400-e29b-41d4-a716-446655440000", "forecasted_effort":{"2024-02":40,"2024-03":60}}
* @response 200 {
* "data": {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "forecasted_effort": {"2024-02": 40, "2024-03": 60}
* }
* }
* @response 404 {"message":"Project not found"}
* @response 422 {"message":"Forecasted effort exceeds approved estimate by more than 5%"}
*/
@@ -319,17 +338,19 @@ class ProjectController extends Controller
*
* @authenticated
*
* @response 200 [
* {"id": 1, "name": "Project"},
* {"id": 2, "name": "Support"},
* {"id": 3, "name": "Engagement"}
* ]
* @response 200 {
* "data": [
* {"id": 1, "name": "Project"},
* {"id": 2, "name": "Support"},
* {"id": 3, "name": "Engagement"}
* ]
* }
*/
public function types(): JsonResponse
{
$types = ProjectType::orderBy('name')->get(['id', 'name']);
return response()->json($types);
return $this->wrapResource(ProjectTypeResource::collection($types));
}
/**
@@ -337,17 +358,19 @@ class ProjectController extends Controller
*
* @authenticated
*
* @response 200 [
* {"id": 1, "name": "Pre-sales", "order": 1},
* {"id": 2, "name": "SOW Approval", "order": 2},
* {"id": 3, "name": "Gathering Estimates", "order": 3}
* ]
* @response 200 {
* "data": [
* {"id": 1, "name": "Pre-sales", "order": 1},
* {"id": 2, "name": "SOW Approval", "order": 2},
* {"id": 3, "name": "Gathering Estimates", "order": 3}
* ]
* }
*/
public function statuses(): JsonResponse
{
$statuses = ProjectStatus::orderBy('order')->get(['id', 'name', 'order']);
return response()->json($statuses);
return $this->wrapResource(ProjectStatusResource::collection($statuses));
}
/**

62
backend/app/Http/Controllers/Api/PtoController.php
View File

@@ -3,6 +3,7 @@
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use App\Http\Resources\PtoResource;
use App\Models\Pto;
use App\Services\CapacityService;
use Carbon\Carbon;
@@ -19,18 +20,22 @@ class PtoController extends Controller
* Fetch PTO requests for a team member, optionally constrained to a month.
*
* @group Capacity Planning
*
* @urlParam team_member_id string required The team member UUID. Example: 550e8400-e29b-41d4-a716-446655440000
* @urlParam month string nullable The month in YYYY-MM format. Example: 2026-02
* @response [
* {
* "id": "550e8400-e29b-41d4-a716-446655440001",
* "team_member_id": "550e8400-e29b-41d4-a716-446655440000",
* "start_date": "2026-02-10",
* "end_date": "2026-02-12",
* "status": "pending",
* "reason": "Family travel"
* }
* ]
*
* @response {
* "data": [
* {
* "id": "550e8400-e29b-41d4-a716-446655440001",
* "team_member_id": "550e8400-e29b-41d4-a716-446655440000",
* "start_date": "2026-02-10",
* "end_date": "2026-02-12",
* "status": "pending",
* "reason": "Family travel"
* }
* ]
* }
*/
public function index(Request $request): JsonResponse
{
@@ -39,7 +44,7 @@ class PtoController extends Controller
'month' => 'nullable|date_format:Y-m',
]);
$query = Pto::where('team_member_id', $data['team_member_id']);
$query = Pto::with('teamMember')->where('team_member_id', $data['team_member_id']);
if (! empty($data['month'])) {
$start = Carbon::createFromFormat('Y-m', $data['month'])->startOfMonth();
@@ -57,7 +62,7 @@ class PtoController extends Controller
$ptos = $query->orderBy('start_date')->get();
return response()->json($ptos);
return $this->wrapResource(PtoResource::collection($ptos));
}
/**
@@ -66,17 +71,21 @@ class PtoController extends Controller
* Create a PTO request for a team member and keep it in pending status.
*
* @group Capacity Planning
*
* @bodyParam team_member_id string required The team member UUID. Example: 550e8400-e29b-41d4-a716-446655440000
* @bodyParam start_date string required The first day of the PTO. Example: 2026-02-10
* @bodyParam end_date string required The final day of the PTO. Example: 2026-02-12
* @bodyParam reason string nullable Optional reason for the PTO.
*
* @response 201 {
* "id": "550e8400-e29b-41d4-a716-446655440001",
* "team_member_id": "550e8400-e29b-41d4-a716-446655440000",
* "start_date": "2026-02-10",
* "end_date": "2026-02-12",
* "status": "pending",
* "reason": "Family travel"
* "data": {
* "id": "550e8400-e29b-41d4-a716-446655440001",
* "team_member_id": "550e8400-e29b-41d4-a716-446655440000",
* "start_date": "2026-02-10",
* "end_date": "2026-02-12",
* "status": "pending",
* "reason": "Family travel"
* }
* }
*/
public function store(Request $request): JsonResponse
@@ -89,8 +98,9 @@ class PtoController extends Controller
]);
$pto = Pto::create(array_merge($data, ['status' => 'pending']));
$pto->load('teamMember');
return response()->json($pto, 201);
return $this->wrapResource(new PtoResource($pto), 201);
}
/**
@@ -99,15 +109,19 @@ class PtoController extends Controller
* Approve a pending PTO request and refresh the affected capacity caches.
*
* @group Capacity Planning
*
* @urlParam id string required The PTO UUID that needs approval. Example: 550e8400-e29b-41d4-a716-446655440001
*
* @response {
* "id": "550e8400-e29b-41d4-a716-446655440001",
* "status": "approved"
* "data": {
* "id": "550e8400-e29b-41d4-a716-446655440001",
* "status": "approved"
* }
* }
*/
public function approve(string $id): JsonResponse
{
$pto = Pto::findOrFail($id);
$pto = Pto::with('teamMember')->findOrFail($id);
if ($pto->status !== 'approved') {
$pto->status = 'approved';
@@ -116,7 +130,9 @@ class PtoController extends Controller
$this->capacityService->forgetCapacityCacheForTeamMember($pto->team_member_id, $months);
}
return response()->json($pto);
$pto->load('teamMember');
return $this->wrapResource(new PtoResource($pto));
}
private function monthsBetween(Carbon|string $start, Carbon|string $end): array

142
backend/app/Http/Controllers/Api/TeamMemberController.php
View File

@@ -3,6 +3,7 @@
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use App\Http\Resources\TeamMemberResource;
use App\Models\TeamMember;
use App\Services\TeamMemberService;
use Illuminate\Http\JsonResponse;
@@ -35,13 +36,53 @@ class TeamMemberController extends Controller
* Get a list of all team members with optional filtering by active status.
*
* @authenticated
*
* @queryParam active boolean Filter by active status. Example: true
*
* @response 200 [
* {
* @response 200 {
* "data": [
* {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "name": "John Doe",
* "role": {
* "id": 1,
* "name": "Backend Developer"
* },
* "hourly_rate": "150.00",
* "active": true,
* "created_at": "2024-01-15T10:00:00.000000Z",
* "updated_at": "2024-01-15T10:00:00.000000Z"
* }
* ]
* }
*/
public function index(Request $request): JsonResponse
{
$active = $request->has('active')
? filter_var($request->query('active'), FILTER_VALIDATE_BOOLEAN)
: null;
$teamMembers = $this->teamMemberService->getAll($active);
return $this->wrapResource(TeamMemberResource::collection($teamMembers));
}
/**
* Create a new team member
*
* Create a new team member with name, role, and hourly rate.
*
* @authenticated
*
* @bodyParam name string required Team member name. Example: John Doe
* @bodyParam role_id integer required Role ID. Example: 1
* @bodyParam hourly_rate numeric required Hourly rate (must be > 0). Example: 150.00
* @bodyParam active boolean Active status (defaults to true). Example: true
*
* @response 201 {
* "data": {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "name": "John Doe",
* "role_id": 1,
* "role": {
* "id": 1,
* "name": "Backend Developer"
@@ -51,42 +92,6 @@ class TeamMemberController extends Controller
* "created_at": "2024-01-15T10:00:00.000000Z",
* "updated_at": "2024-01-15T10:00:00.000000Z"
* }
* ]
*/
public function index(Request $request): JsonResponse
{
$active = $request->has('active')
? filter_var($request->query('active'), FILTER_VALIDATE_BOOLEAN)
: null;
$teamMembers = $this->teamMemberService->getAll($active);
return response()->json($teamMembers);
}
/**
* Create a new team member
*
* Create a new team member with name, role, and hourly rate.
*
* @authenticated
* @bodyParam name string required Team member name. Example: John Doe
* @bodyParam role_id integer required Role ID. Example: 1
* @bodyParam hourly_rate numeric required Hourly rate (must be > 0). Example: 150.00
* @bodyParam active boolean Active status (defaults to true). Example: true
*
* @response 201 {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "name": "John Doe",
* "role_id": 1,
* "role": {
* "id": 1,
* "name": "Backend Developer"
* },
* "hourly_rate": "150.00",
* "active": true,
* "created_at": "2024-01-15T10:00:00.000000Z",
* "updated_at": "2024-01-15T10:00:00.000000Z"
* }
* @response 422 {"message":"Validation failed","errors":{"name":["The name field is required."],"hourly_rate":["Hourly rate must be greater than 0"]}}
*/
@@ -94,7 +99,8 @@ class TeamMemberController extends Controller
{
try {
$teamMember = $this->teamMemberService->create($request->all());
return response()->json($teamMember, 201);
return $this->wrapResource(new TeamMemberResource($teamMember), 201);
} catch (ValidationException $e) {
return response()->json([
'message' => 'Validation failed',
@@ -109,20 +115,22 @@ class TeamMemberController extends Controller
* Get details of a specific team member by ID.
*
* @authenticated
*
* @urlParam id string required Team member UUID. Example: 550e8400-e29b-41d4-a716-446655440000
*
* @response 200 {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "name": "John Doe",
* "role_id": 1,
* "role": {
* "id": 1,
* "name": "Backend Developer"
* },
* "hourly_rate": "150.00",
* "active": true,
* "created_at": "2024-01-15T10:00:00.000000Z",
* "updated_at": "2024-01-15T10:00:00.000000Z"
* "data": {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "name": "John Doe",
* "role": {
* "id": 1,
* "name": "Backend Developer"
* },
* "hourly_rate": "150.00",
* "active": true,
* "created_at": "2024-01-15T10:00:00.000000Z",
* "updated_at": "2024-01-15T10:00:00.000000Z"
* }
* }
* @response 404 {"message":"Team member not found"}
*/
@@ -136,7 +144,7 @@ class TeamMemberController extends Controller
], 404);
}
return response()->json($teamMember);
return $this->wrapResource(new TeamMemberResource($teamMember));
}
/**
@@ -145,24 +153,27 @@ class TeamMemberController extends Controller
* Update details of an existing team member.
*
* @authenticated
*
* @urlParam id string required Team member UUID. Example: 550e8400-e29b-41d4-a716-446655440000
*
* @bodyParam name string Team member name. Example: John Doe
* @bodyParam role_id integer Role ID. Example: 1
* @bodyParam hourly_rate numeric Hourly rate (must be > 0). Example: 175.00
* @bodyParam active boolean Active status. Example: false
*
* @response 200 {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "name": "John Doe",
* "role_id": 1,
* "role": {
* "id": 1,
* "name": "Backend Developer"
* },
* "hourly_rate": "175.00",
* "active": false,
* "created_at": "2024-01-15T10:00:00.000000Z",
* "updated_at": "2024-01-15T11:00:00.000000Z"
* "data": {
* "id": "550e8400-e29b-41d4-a716-446655440000",
* "name": "John Doe",
* "role": {
* "id": 1,
* "name": "Backend Developer"
* },
* "hourly_rate": "175.00",
* "active": false,
* "created_at": "2024-01-15T10:00:00.000000Z",
* "updated_at": "2024-01-15T11:00:00.000000Z"
* }
* }
* @response 404 {"message":"Team member not found"}
* @response 422 {"message":"Validation failed","errors":{"hourly_rate":["Hourly rate must be greater than 0"]}}
@@ -179,10 +190,10 @@ class TeamMemberController extends Controller
try {
$teamMember = $this->teamMemberService->update($teamMember, $request->only([
'name', 'role_id', 'hourly_rate', 'active'
'name', 'role_id', 'hourly_rate', 'active',
]));
return response()->json($teamMember);
return $this->wrapResource(new TeamMemberResource($teamMember));
} catch (ValidationException $e) {
return response()->json([
'message' => 'Validation failed',
@@ -197,6 +208,7 @@ class TeamMemberController extends Controller
* Delete a team member. Cannot delete if member has allocations or actuals.
*
* @authenticated
*
* @urlParam id string required Team member UUID. Example: 550e8400-e29b-41d4-a716-446655440000
*
* @response 200 {"message":"Team member deleted successfully"}

13
backend/app/Http/Controllers/Controller.php
View File

@@ -2,7 +2,16 @@
namespace App\Http\Controllers;
abstract class Controller
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Resources\Json\JsonResource;
use Illuminate\Routing\Controller as BaseController;
class Controller extends BaseController
{
//
protected function wrapResource(JsonResource $resource, int $status = 200): JsonResponse
{
return response()->json([
'data' => $resource->resolve(request()),
], $status);
}
}