Aditya-feat: Implement Paid Labor Cost API endpoint with comprehensive filtering and validation

[Aditya-gam]

---

Description

Implements a complete backend API for the Paid Labor Cost grouped-bar graph feature. The controller was previously a stub returning an empty array. This PR provides a fully functional GET /api/labor-cost endpoint supporting date filtering, project filtering, task filtering, and proper data formatting with comprehensive validation and error handling.

---

Related PRs (if any):

• Related to old PRs: #3420 + #1451
• Frontend Pair for this PR: PR #4496

---

Main changes explained:

Created/Updated Files:

1. src/controllers/bmdashboard/bmPaidLaborCostController.js
   Complete controller implementation with:

   • Helper functions: looksLikeJson(), parseArrayParam(), parseDateRangeParam(), isValidDateValue()
   • Parameter extraction & validation: Extracts and validates projects, tasks, date_range from query params
   • MongoDB query building: Supports partial date ranges, project/task filters using the $in operator
   • Database querying: Uses LaborCost.find() with .lean() and .sort({ date: 1 })
   • Response formatting: Maps DB fields (project_name → project) and calculates totalCost
   • Error handling: Distinguishes database vs unexpected errors, logs with context
   • Edge cases: Handles null params, empty results, invalid dates (e.g., "2025-13-01"), UTC timezone handling

2. src/routes/bmdashboard/bmPaidLaborCostRouter.js

   • Changed route method from POST to GET to align with frontend requirements.

3. src/controllers/bmdashboard/__tests__/bmPaidLaborCostController.test.js
   119 unit tests covering:

   • Helper functions (59 tests): JSON detection, array parsing, date validation
   • Controller logic (60 tests): Parameter validation, query building, response formatting, error handling, edge cases
   • Coverage: 97% (above 90% target)

4. src/__tests__/integration/bmPaidLaborCostRoutes.integration.test.js (+113 lines)
   Integration tests for route configuration, authentication (401 without auth), and GET method verification.

5. package.json

   • Added @aws-sdk/client-s3 dependency for integration tests.

---

Key Implementation Details:

API Endpoint: GET /api/labor-cost.

Request Parameters (query string):

• projects: Optional array (empty = all projects)
• tasks: Optional array (empty = all tasks)
• date_range: Optional object with start_date and/or end_date (null = all dates)

Response Structure:

{
	"totalCost": 15000,
	"data": [
		{ "project": "Project A", "task": "Task 1", "date": "2025-04-01T00:00:00.000Z", "cost": 5000 }
	]
}

Key Features:

• Partial date ranges: Supports only start_date, only end_date, or both
• UTC timezone handling: Uses UTC methods for consistent date filtering
• Flexible parameter parsing: Accepts JSON strings, comma-separated values, or parsed arrays
• Comprehensive validation: Date format (ISO 8601), date values (catches "2025-13-01"), date range logic, array formats
• Error responses: 400 (invalid params), 422 (invalid dates), 500 (server errors)

How to test:

1. Check into branch: Aditya-fix/implement-paid-labor-cost-controller.
2. Reinstall dependencies and clean cache using rm -rf node_modules package-lock.json && npm cache clean --force.
3. Run npm install to install dependencies, then start the backend locally (npm start or npm run dev)
4. Test API Endpoint GET /api/labor-cost:

Basic functionality:

# Get all data
curl "http://localhost:3000/api/labor-cost"

# Filter by date range
curl "http://localhost:3000/api/labor-cost?date_range={\"start_date\":\"2025-04-01\",\"end_date\":\"2025-04-30\"}"

# Filter by projects and tasks
curl "http://localhost:3000/api/labor-cost?projects=[\"Project A\"]&tasks=[\"Task 1\"]"

Edge cases:

# Partial date range (only start_date)
curl "http://localhost:3000/api/labor-cost?date_range={\"start_date\":\"2025-04-01\",\"end_date\":null}"

# Empty results (future dates)
curl "http://localhost:3000/api/labor-cost?date_range={\"start_date\":\"2030-01-01\",\"end_date\":\"2030-12-31\"}"

# Invalid date format (should return 422)
curl "http://localhost:3000/api/labor-cost?date_range={\"start_date\":\"2025-13-01\",\"end_date\":\"2025-04-30\"}"

5. Run test suite:

# Unit tests (119 tests, 97% coverage)
npm test -- src/controllers/bmdashboard/__tests__/bmPaidLaborCostController.test.js

# Integration tests
npm test -- src/__tests__/integration/bmPaidLaborCostRoutes.integration.test.js

Screenshots or videos of changes:

TestVideo.mov

---

Note:

• Database Changes: Added some mock data to the dev database, so testing this endpoint is easier.
• Performance: Uses .lean() for better performance. Consider adding indexes on date, project_name, and task if the dataset is very large
• Validation: Comprehensive validation for dates (ISO 8601, invalid months/days), arrays (format detection), and date ranges
• Error Handling: User-friendly messages with error codes. Internal details not exposed. Errors logged with full context
• Testing: 97% coverage (119 unit tests + integration tests). All edge cases and error conditions covered