Refactor: standardize API response structure across all controllers

- Add ApiResponse<T> wrapper class with success/message/data/meta fields
- Add ResponseFactory for standardized response creation methods
- Add ResponseInterceptor to automatically inject timestamp and path
- Add PaginationMeta to replace PageDto for pagination metadata
- Add BatchResponse and DeleteResponse for specific operation types
- Update ErrorResponse structure for consistency
- Refactor GlobalExceptionHandler to use new response structure
- Update all controllers to return ApiResponse wrapped responses:
  * AttendanceController
  * EmployeeController
  * LeaveController
  * PayrollController
  * UserController
- Remove deprecated PageDto and PageMapper classes

Benefits:
- Consistent response format across all endpoints
- Automatic timestamp and path injection via interceptor
- Better separation of concerns with ResponseFactory pattern

Author: iodsky

src/main/java/com/iodsky/motorph/attendance/AttendanceController.java

@@ -1,13 +1,12 @@
 package com.iodsky.motorph.attendance;
 
-import com.iodsky.motorph.common.PageDto;
-import com.iodsky.motorph.common.PageMapper;
+import com.iodsky.motorph.common.ApiResponse;
+import com.iodsky.motorph.common.ResponseFactory;
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.Max;
 import jakarta.validation.constraints.Min;
 import lombok.RequiredArgsConstructor;
 import org.springframework.data.domain.Page;
-import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.*;
@@ -25,57 +24,63 @@ public class AttendanceController {
     private final AttendanceMapper attendanceMapper;
 
     @PostMapping
-    public ResponseEntity<AttendanceDto> createAttendance(@Valid @RequestBody(required = false) AttendanceDto attendanceDto) {
+    public ResponseEntity<ApiResponse<AttendanceDto>> createAttendance(@Valid @RequestBody(required = false) AttendanceDto attendanceDto) {
         Attendance attendance = attendanceService.createAttendance(attendanceDto);
         AttendanceDto dto = attendanceMapper.toDto(attendance);
-        return new ResponseEntity<>(dto, HttpStatus.CREATED);
+        return ResponseFactory.created("Attendance created successfully", dto);
     }
 
     @PreAuthorize("hasRole('HR')")
     @GetMapping
-    public ResponseEntity<PageDto<AttendanceDto>> getAllAttendances(
-            @RequestParam(defaultValue = "0") @Min(0) int page,
+    public ResponseEntity<ApiResponse<List<AttendanceDto>>> getAllAttendances(
+            @RequestParam(defaultValue = "0") @Min(0) int pageNo,
             @RequestParam(defaultValue = "10") @Min(1) @Max(100) int limit,
             @RequestParam(required = false) LocalDate startDate,
             @RequestParam(required = false) LocalDate endDate
     ) {
-        Page<Attendance> attendances = attendanceService.getAllAttendances(page, limit, startDate, endDate);
+        Page<Attendance> page = attendanceService.getAllAttendances(pageNo, limit, startDate, endDate);
 
-        return ResponseEntity.ok(PageMapper.map(attendances, attendanceMapper::toDto));
+        List<AttendanceDto> data = page.getContent().stream().map(attendanceMapper::toDto).toList();
+
+        return ResponseFactory.ok("Attendances retrieved successfully", data);
     }
 
     @GetMapping("/me")
-    public ResponseEntity<PageDto<AttendanceDto>> getMyAttendances(
-            @RequestParam(defaultValue = "0") @Min(0) int page,
+    public ResponseEntity<ApiResponse<List<AttendanceDto>>> getMyAttendances(
+            @RequestParam(defaultValue = "0") @Min(0) int pageNo,
             @RequestParam(defaultValue = "10") @Min(1) @Max(100) int limit,
             @RequestParam(required = false) LocalDate startDate,
             @RequestParam(required = false) LocalDate endDate
     ) {
-        Page<Attendance> attendances = attendanceService
-                .getEmployeeAttendances(page, limit, null, startDate, endDate);
+        Page<Attendance> page = attendanceService
+                .getEmployeeAttendances(pageNo, limit, null, startDate, endDate);
+
+        List<AttendanceDto> data = page.getContent().stream().map(attendanceMapper::toDto).toList();
 
-        return ResponseEntity.ok(PageMapper.map(attendances, attendanceMapper::toDto));
+        return ResponseFactory.ok("Attendances retrieved successfully", data);
     }
 
     @PreAuthorize("hasRole('HR')")
     @GetMapping("/employee/{id}")
-    public ResponseEntity<PageDto<AttendanceDto>> getEmployeeAttendancesForHR(
+    public ResponseEntity<ApiResponse<List<AttendanceDto>>> getEmployeeAttendancesForHR(
             @PathVariable Long id,
-            @RequestParam(defaultValue = "0") @Min(0) int page,
+            @RequestParam(defaultValue = "0") @Min(0) int pageNo,
             @RequestParam(defaultValue = "10") @Min(1) @Max(100) int limit,
             @RequestParam(required = false) LocalDate startDate,
             @RequestParam(required = false) LocalDate endDate
     ) {
-        Page<Attendance> attendances = attendanceService
-                .getEmployeeAttendances(page, limit, id, startDate, endDate);
+        Page<Attendance> page = attendanceService
+                .getEmployeeAttendances(pageNo, limit, id, startDate, endDate);
+
+        List<AttendanceDto> data = page.getContent().stream().map(attendanceMapper::toDto).toList();
 
-        return ResponseEntity.ok(PageMapper.map(attendances, attendanceMapper::toDto));
+        return ResponseFactory.ok("Attendances retrieved successfully", data);
     }
 
     @PatchMapping("/{id}")
-    public ResponseEntity<AttendanceDto> updateAttendance(@PathVariable UUID id, @Valid @RequestBody(required = false) AttendanceDto attendanceDto) {
+    public ResponseEntity<ApiResponse<AttendanceDto>> updateAttendance(@PathVariable UUID id, @Valid @RequestBody(required = false) AttendanceDto attendanceDto) {
         Attendance attendance = attendanceService.updateAttendance(id, attendanceDto);
         AttendanceDto dto = attendanceMapper.toDto(attendance);
-        return ResponseEntity.ok(dto);
+        return ResponseFactory.ok("Attendance updated successfully", dto);
     }
 }

src/main/java/com/iodsky/motorph/common/ApiResponse.java

@@ -0,0 +1,46 @@
+package com.iodsky.motorph.common;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonPropertyOrder;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.Setter;
+
+import java.time.Instant;
+
+@Getter
+@Setter
+@Builder
+@AllArgsConstructor
+@JsonInclude(JsonInclude.Include.NON_NULL)
+@JsonPropertyOrder({
+        "success",
+        "message",
+        "data",
+        "meta",
+        "timestamp",
+        "path"
+})
+public class ApiResponse<T> {
+
+    private boolean success;
+    private String message;
+    private T data;
+    private Instant timestamp;
+    private String path;
+    private PaginationMeta meta;
+
+    public ApiResponse(boolean success, String message, T data) {
+        this.success = success;
+        this.message = message;
+        this.data = data;
+    }
+
+    public ApiResponse(boolean success, String message, T data, PaginationMeta meta) {
+        this.success = success;
+        this.message = message;
+        this.data = data;
+        this.meta = meta;
+    }
+}

src/main/java/com/iodsky/motorph/common/BatchResponse.java

@@ -0,0 +1,12 @@
+package com.iodsky.motorph.common;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@AllArgsConstructor
+@NoArgsConstructor
+public class BatchResponse {
+    private Integer recordsCreated;
+}

src/main/java/com/iodsky/motorph/common/DeleteResponse.java

@@ -0,0 +1,18 @@
+package com.iodsky.motorph.common;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+@Getter
+@Setter
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class DeleteResponse {
+    private String resourceType;
+    private Object resourceId;
+}
+

src/main/java/com/iodsky/motorph/common/ErrorResponse.java

@@ -11,12 +11,13 @@
 @Data
 @Builder
 @AllArgsConstructor
+@JsonInclude(JsonInclude.Include.NON_NULL)
 public class ErrorResponse {
+
     private Instant timestamp;
     private int status;
     private String message;
-
-    @JsonInclude(JsonInclude.Include.NON_NULL)
+    private String path;
     private List<FieldValidationError> fieldErrors;
 
     @Data

src/main/java/com/iodsky/motorph/common/PageDto.java

@@ -1,15 +1,22 @@
 package com.iodsky.motorph.common;
 
+import lombok.Builder;
+import lombok.Getter;
 import org.springframework.data.domain.Page;
 
-import java.util.function.Function;
+@Getter
+@Builder
+public class PaginationMeta {
 
-public class PageMapper {
-    private PageMapper() {}
+    private final int page;
+    private final int size;
+    private final long totalElements;
+    private final int totalPages;
+    private final boolean first;
+    private final boolean last;
 
-    public static <T, U>PageDto<U> map(Page<T> page, Function<T, U> mapper) {
-        return PageDto.<U>builder()
-                .content(page.getContent().stream().map(mapper).toList())
+    public static PaginationMeta of(Page<?> page) {
+        return PaginationMeta.builder()
                 .page(page.getNumber())
                 .size(page.getSize())
                 .totalElements(page.getTotalElements())
@@ -18,5 +25,4 @@ public static <T, U>PageDto<U> map(Page<T> page, Function<T, U> mapper) {
                 .last(page.isLast())
                 .build();
     }
-
 }

…om/iodsky/motorph/common/PageMapper.java …odsky/motorph/common/PaginationMeta.javasrc/main/java/com/iodsky/motorph/common/PageMapper.java renamed to src/main/java/com/iodsky/motorph/common/PaginationMeta.java src/main/java/com/iodsky/motorph/common/PageMapper.java renamed to src/main/java/com/iodsky/motorph/common/PaginationMeta.java

@@ -0,0 +1,40 @@
+package com.iodsky.motorph.common;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+
+public class ResponseFactory {
+
+    private ResponseFactory() {}
+
+    public static <T> ResponseEntity<ApiResponse<T>> ok(String message, T data) {
+        ApiResponse<T> res = new ApiResponse<>(
+                true,
+                message,
+                data
+        );
+        return ResponseEntity.ok(res);
+    }
+
+    public static <T> ResponseEntity<ApiResponse<T>> ok(String message, T data, PaginationMeta meta) {
+
+        ApiResponse<T> res = new ApiResponse<>(
+                true,
+                message,
+                data,
+                meta
+        );
+
+        return ResponseEntity.ok(res);
+    }
+
+    public static <T> ResponseEntity<ApiResponse<T>> created(String message, T data) {
+        ApiResponse<T> res = new ApiResponse<>(
+                true,
+                message,
+                data
+        );
+        return new ResponseEntity<>(res, HttpStatus.CREATED);
+    }
+
+}

src/main/java/com/iodsky/motorph/common/ResponseFactory.java

@@ -0,0 +1,39 @@
+package com.iodsky.motorph.common;
+
+import org.springframework.core.MethodParameter;
+import org.springframework.http.MediaType;
+import org.springframework.http.converter.HttpMessageConverter;
+import org.springframework.http.server.ServerHttpRequest;
+import org.springframework.http.server.ServerHttpResponse;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;
+
+import java.time.Instant;
+
+@RestControllerAdvice
+public class ResponseInterceptor implements ResponseBodyAdvice<Object> {
+
+    @Override
+    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
+        return true;
+    }
+
+    @Override
+    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType,
+                                  Class<? extends HttpMessageConverter<?>> selectedConverterType,
+                                  ServerHttpRequest request,
+                                  ServerHttpResponse response
+    ) {
+
+        if (body instanceof ApiResponse<?> res) {
+            res.setTimestamp(Instant.now());
+
+            String path = request.getURI().getRawPath();
+            String query = request.getURI().getRawQuery();
+
+            res.setPath(query != null ? path + "?" + query : path);
+        }
+
+        return body;
+    }
+}

src/main/java/com/iodsky/motorph/common/ResponseInterceptor.java

@@ -1,6 +1,7 @@
 package com.iodsky.motorph.common.exception;
 
 import com.iodsky.motorph.common.ErrorResponse;
+import jakarta.servlet.http.HttpServletRequest;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.MethodArgumentNotValidException;
@@ -13,42 +14,45 @@
 public class GlobalExceptionHandler {
 
     @ExceptionHandler(DuplicateFieldException.class)
-    public ResponseEntity<ErrorResponse> handleDuplicateFieldException(DuplicateFieldException ex) {
+    public ResponseEntity<ErrorResponse> handleDuplicateFieldException(DuplicateFieldException ex, HttpServletRequest request) {
         ErrorResponse error = ErrorResponse.builder()
                 .timestamp(Instant.now())
                 .status(ex.getStatus().value())
                 .message(ex.getMessage())
+                .path(request.getRequestURI())
                 .build();
         return new ResponseEntity<>(error, ex.getStatus());
-
     }
 
     @ExceptionHandler(ApiException.class)
-    public ResponseEntity<ErrorResponse> handleApiException(ApiException ex) {
+    public ResponseEntity<ErrorResponse> handleApiException(ApiException ex, HttpServletRequest request) {
         ErrorResponse error = ErrorResponse.builder()
                 .timestamp(Instant.now())
                 .status(ex.getStatus().value())
                 .message(ex.getMessage())
+                .path(request.getRequestURI())
                 .build();
         return new ResponseEntity<>(error, ex.getStatus());
     }
 
     @ExceptionHandler(MethodArgumentNotValidException.class)
-    public ResponseEntity<ErrorResponse> handleMethodArgumentNotValidException(MethodArgumentNotValidException ex) {
+    public ResponseEntity<ErrorResponse> handleMethodArgumentNotValidException(MethodArgumentNotValidException ex, HttpServletRequest request) {
         ErrorResponse error = ErrorResponse.builder()
                 .timestamp(Instant.now())
                 .status(HttpStatus.BAD_REQUEST.value())
                 .message(ex.getMessage())
+                .path(request.getRequestURI())
                 .build();
         return new ResponseEntity<>(error, HttpStatus.BAD_REQUEST);
     }
 
     @ExceptionHandler(Exception.class)
-    public ResponseEntity<ErrorResponse> handleAllOtherException(Exception ex) {
+    public ResponseEntity<ErrorResponse> handleAllOtherException(Exception ex, HttpServletRequest request) {
         ErrorResponse error = ErrorResponse.builder()
                 .timestamp(Instant.now())
                 .status(HttpStatus.INTERNAL_SERVER_ERROR.value())
                 .message(ex.getMessage())
+                .path(request.getRequestURI())
                 .build();
         return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
     }