Entity-to-DTO Mapping

@Mapper(componentModel = "spring")
public interface UserMapper {

    UserResponse toResponse(User entity);

    User toEntity(CreateUserRequest request);
}

@Service
@RequiredArgsConstructor
public class UserService {
    private final UserMapper userMapper;
    private final UserRepository userRepository;

    public UserResponse createUser(CreateUserRequest request) {
        User entity = userMapper.toEntity(request);
        User saved = userRepository.save(entity);
        return userMapper.toResponse(saved);
    }
}

@Mapper(componentModel = "spring")
public interface OrderMapper {

    @Mapping(source = "customer.fullName", target = "customerName")
    @Mapping(source = "createdAt", target = "orderDate", dateFormat = "yyyy-MM-dd")
    @Mapping(target = "totalFormatted", expression = "java(\"$\" + order.getTotal())")
    @Mapping(target = "id", ignore = true)
    OrderResponse toResponse(Order order);
}

@Mapper(componentModel = "spring")
public interface OrderMapper {

    OrderResponse toResponse(Order order);

    OrderItemResponse toItemResponse(OrderItem item);

    // MapStruct auto-maps List<OrderItem> → List<OrderItemResponse>
    // by calling toItemResponse() for each element
}

@Mapper(componentModel = "spring")
public interface ProductMapper {

    ProductResponse toResponse(Product product);

    List<ProductResponse> toResponseList(List<Product> products);

    Set<TagResponse> toTagResponses(Set<Tag> tags);
}

@Mapper(componentModel = "spring")
public abstract class UserMapper {

    @Mapping(target = "displayName", ignore = true)
    @Mapping(target = "ageGroup", ignore = true)
    public abstract UserResponse toResponse(User user);

    @AfterMapping
    protected void enrichResponse(User user, @MappingTarget UserResponse response) {
        response.setDisplayName(user.getFirstName() + " " + user.getLastName());
        response.setAgeGroup(calculateAgeGroup(user.getDateOfBirth()));
    }

    @BeforeMapping
    protected void validate(User user) {
        if (user.getEmail() == null) {
            throw new IllegalArgumentException("User email must not be null");
        }
    }

    private String calculateAgeGroup(LocalDate dob) {
        int age = Period.between(dob, LocalDate.now()).getYears();
        if (age < 18) return "MINOR";
        if (age < 65) return "ADULT";
        return "SENIOR";
    }
}

@Mapper(componentModel = "spring", imports = {UUID.class, Instant.class})
public interface AuditMapper {

    @Mapping(target = "id", expression = "java(UUID.randomUUID().toString())")
    @Mapping(target = "timestamp", expression = "java(Instant.now())")
    @Mapping(target = "fullAddress",
             expression = "java(entity.getStreet() + \", \" + entity.getCity())")
    AuditResponse toResponse(AuditEntity entity);
}

@Mapper(componentModel = "spring",
        nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE,
        nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT)
public interface PatchMapper {

    @Mapping(target = "status", defaultValue = "ACTIVE")
    @Mapping(target = "priority", defaultExpression = "java(Priority.NORMAL)")
    @Mapping(target = "tags", nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.SET_TO_DEFAULT)
    void updateEntity(PatchRequest request, @MappingTarget Task entity);
}

@Mapper(componentModel = "spring")
public interface VehicleMapper {

    @SubclassMapping(source = Car.class, target = CarResponse.class)
    @SubclassMapping(source = Truck.class, target = TruckResponse.class)
    VehicleResponse toResponse(Vehicle vehicle);

    CarResponse toCarResponse(Car car);
    TruckResponse toTruckResponse(Truck truck);
}

@MapperConfig(
    componentModel = "spring",
    nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE
)
public interface CentralConfig {}

@Mapper(config = CentralConfig.class)
public interface UserMapper { /* ... */ }

@Mapper(config = CentralConfig.class)
public interface OrderMapper { /* ... */ }

// Response DTO — immutable, auto-generates equals/hashCode/toString
public record UserResponse(
    Long id,
    String username,
    String email,
    String displayName,
    LocalDate joinedAt
) {
    // Compact constructor for validation/transformation
    public UserResponse {
        Objects.requireNonNull(username, "username must not be null");
        email = email.toLowerCase();
    }

    // Factory method for mapping
    public static UserResponse from(User entity) {
        return new UserResponse(
            entity.getId(),
            entity.getUsername(),
            entity.getEmail(),
            entity.getFirstName() + " " + entity.getLastName(),
            entity.getCreatedAt().toLocalDate()
        );
    }
}

@Mapper(componentModel = "spring")
public interface UserMapper {
    UserResponse toResponse(User entity);  // MapStruct uses record constructor
}

// Request: what the client sends (validated, minimal)
public record CreateUserRequest(
    @NotBlank @Size(min = 3, max = 30) String username,
    @NotBlank @Email String email,
    @NotBlank @Size(min = 8) String password,
    @NotNull LocalDate dateOfBirth
) {}

// Request: update (no password, no username change)
public record UpdateUserRequest(
    @NotBlank @Email String email,
    @Size(max = 100) String bio,
    @Valid AddressRequest address
) {}

// Response: what the client receives (no secrets, computed fields)
public record UserDetailResponse(
    Long id,
    String username,
    String email,
    String bio,
    String avatarUrl,
    LocalDate joinedAt,
    int postCount,        // computed
    String memberSince    // formatted
) {}

// Response: lightweight for lists
public record UserListResponse(
    Long id,
    String username,
    String avatarUrl
) {}

@RestController
@RequestMapping("/api/orders")
@RequiredArgsConstructor
public class OrderController {

    private final OrderService orderService;

    @PostMapping
    public ResponseEntity<OrderResponse> createOrder(
            @Valid @RequestBody CreateOrderRequest request) {
        return ResponseEntity.status(HttpStatus.CREATED)
                .body(orderService.create(request));
    }
}

public record CreateOrderRequest(
    @NotNull Long customerId,

    @NotEmpty(message = "Order must have at least one item")
    @Size(max = 50, message = "Maximum 50 items per order")
    List<@Valid OrderItemRequest> items,

    @NotNull ShippingMethod shippingMethod,

    @Valid @NotNull AddressRequest shippingAddress
) {}

public record OrderItemRequest(
    @NotNull Long productId,
    @Positive int quantity,
    @Size(max = 200) String specialInstructions
) {}

// Only these columns are fetched from DB — optimal SELECT
public interface UserSummaryProjection {
    Long getId();
    String getUsername();
    String getEmail();
}

public interface UserRepository extends JpaRepository<User, Long> {

    List<UserSummaryProjection> findByStatus(UserStatus status);

    @Query("SELECT u.id as id, u.username as username, u.email as email " +
           "FROM User u WHERE u.department = :dept")
    List<UserSummaryProjection> findSummariesByDepartment(@Param("dept") String dept);
}

public interface UserDisplayProjection {
    String getFirstName();
    String getLastName();

    @Value("#{target.firstName + ' ' + target.lastName}")
    String getFullName();
}

public record UserStats(Long id, String username, long postCount) {}

public interface UserRepository extends JpaRepository<User, Long> {

    @Query("SELECT new com.example.dto.UserStats(u.id, u.username, COUNT(p)) " +
           "FROM User u LEFT JOIN u.posts p GROUP BY u.id, u.username")
    List<UserStats> findUserStats();
}