Implment matches domain

src/main/java/org/patinanetwork/patchats/api/match/AdminMatchController.java

@@ -0,0 +1,31 @@
+package org.patinanetwork.patchats.api.match;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.patinanetwork.patchats.api.match.dto.match.AdminMatchResponse;
+import org.patinanetwork.patchats.api.match.dto.match.CreateMatchRequest;
+import org.patinanetwork.patchats.common.dto.ApiResponder;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/api/admin/matches")
+@Tag(name = "Admin Matches")
+@RequiredArgsConstructor
+public class AdminMatchController {
+
+    private final MatchService matchService;
+
+    @Operation(summary = "Create a match between two members for a match cycle")
+    @PostMapping
+    public ResponseEntity<ApiResponder<AdminMatchResponse>> createMatch(
+            @Valid @RequestBody final CreateMatchRequest request) {
+        final AdminMatchResponse response = matchService.createMatch(request);
+        return ResponseEntity.ok(ApiResponder.success("Match created successfully", response));
+    }
+}

src/main/java/org/patinanetwork/patchats/api/match/MatchController.java

@@ -0,0 +1 @@
+

src/main/java/org/patinanetwork/patchats/api/match/MatchService.java

@@ -0,0 +1,48 @@
+package org.patinanetwork.patchats.api.match;
+
+import java.time.ZoneOffset;
+import java.time.format.DateTimeFormatter;
+import java.util.UUID;
+import lombok.RequiredArgsConstructor;
+import org.patinanetwork.patchats.api.match.db.models.Match;
+import org.patinanetwork.patchats.api.match.db.models.MatchCycle;
+import org.patinanetwork.patchats.api.match.db.repos.MatchCycleRepo;
+import org.patinanetwork.patchats.api.match.db.repos.MatchRepo;
+import org.patinanetwork.patchats.api.match.dto.match.AdminMatchResponse;
+import org.patinanetwork.patchats.api.match.dto.match.CreateMatchRequest;
+import org.patinanetwork.patchats.common.web.exception.MatchCycleNotFoundException;
+import org.springframework.stereotype.Service;
+
+@Service
+@RequiredArgsConstructor
+public class MatchService {
+
+    private static final String DEFAULT_MATCH_STATUS = "PENDING";
+    private static final DateTimeFormatter MONTH_FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM");
+
+    private final MatchRepo matchRepo;
+    private final MatchCycleRepo matchCycleRepo;
+
+    public AdminMatchResponse createMatch(CreateMatchRequest request) {
+        MatchCycle cycle = matchCycleRepo
+                .getMatchCycleById(request.matchCycleId())
+                .orElseThrow(() -> new MatchCycleNotFoundException(request.matchCycleId()));
+
+        Match match = Match.builder()
+                .id(UUID.randomUUID())
+                .memberAId(request.memberAId())
+                .memberBId(request.memberBId())
+                .matchCycleId(request.matchCycleId())
+                .matchScore(request.matchScore())
+                .status(request.status() == null ? DEFAULT_MATCH_STATUS : request.status())
+                .build();
+
+        Match createdMatch = matchRepo.createMatch(match);
+        return AdminMatchResponse.from(createdMatch, deriveMonth(cycle));
+    }
+
+    /** Derives the "YYYY-MM" month label for a match from its cycle's run time (UTC). */
+    private String deriveMonth(final MatchCycle cycle) {
+        return MONTH_FORMATTER.format(cycle.getRunAt().atZone(ZoneOffset.UTC));
+    }
+}

src/main/java/org/patinanetwork/patchats/api/match/dto/cycle/MatchCycleDetailResponse.java

@@ -0,0 +1,22 @@
+package org.patinanetwork.patchats.api.match.dto.cycle;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import java.util.List;
+import lombok.Builder;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.ToString;
+import org.patinanetwork.patchats.api.match.dto.match.AdminMatchResponse;
+
+@Getter
+@Builder
+@ToString
+@EqualsAndHashCode
+public class MatchCycleDetailResponse {
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private final MatchCycleResponse cycle;
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private final List<AdminMatchResponse> matches;
+}

src/main/java/org/patinanetwork/patchats/api/match/dto/match/AdminMatchResponse.java

@@ -0,0 +1,54 @@
+package org.patinanetwork.patchats.api.match.dto.match;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import java.time.Instant;
+import java.util.UUID;
+import lombok.Builder;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.ToString;
+import org.patinanetwork.patchats.api.match.db.models.Match;
+
+@Getter
+@Builder
+@ToString
+@EqualsAndHashCode
+public class AdminMatchResponse {
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private final UUID matchId;
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private final UUID memberAId;
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private final UUID memberBId;
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private final Integer matchCycleId;
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private final String month;
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private final String status;
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED, nullable = true)
+    private final Double matchScore;
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private final Instant createdAt;
+
+    public static AdminMatchResponse from(final Match match, final String month) {
+        return AdminMatchResponse.builder()
+                .matchId(match.getId())
+                .memberAId(match.getMemberAId())
+                .memberBId(match.getMemberBId())
+                .matchCycleId(match.getMatchCycleId())
+                .month(month)
+                .status(match.getStatus())
+                .matchScore(match.getMatchScore())
+                .createdAt(match.getCreatedAt())
+                .build();
+    }
+}

src/main/java/org/patinanetwork/patchats/api/match/dto/match/BulkCreateMatchesRequest.java

@@ -0,0 +1,7 @@
+package org.patinanetwork.patchats.api.match.dto.match;
+
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotEmpty;
+import java.util.List;
+
+public record BulkCreateMatchesRequest(@Valid @NotEmpty List<CreateMatchRequest> matches) {}

src/main/java/org/patinanetwork/patchats/api/match/dto/match/CreateMatchRequest.java

@@ -0,0 +1,11 @@
+package org.patinanetwork.patchats.api.match.dto.match;
+
+import jakarta.validation.constraints.NotNull;
+import java.util.UUID;
+
+public record CreateMatchRequest(
+        @NotNull UUID memberAId,
+        @NotNull UUID memberBId,
+        @NotNull Integer matchCycleId,
+        Double matchScore,
+        String status) {}

src/main/java/org/patinanetwork/patchats/api/match/dto/match/MatchListQuery.java

@@ -0,0 +1,6 @@
+package org.patinanetwork.patchats.api.match.dto.match;
+
+import java.time.Instant;
+import java.util.UUID;
+
+public record MatchListQuery(UUID memberId, String period, Instant startTime, Instant endTime, String status) {}

src/main/java/org/patinanetwork/patchats/api/match/dto/match/MatchResponse.java

@@ -0,0 +1,41 @@
+package org.patinanetwork.patchats.api.match.dto.match;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import java.util.UUID;
+import lombok.Builder;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.ToString;
+import org.patinanetwork.patchats.api.match.db.models.Match;
+
+@Getter
+@Builder
+@ToString
+@EqualsAndHashCode
+public class MatchResponse {
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private final UUID matchId;
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private final UUID memberAId;
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private final UUID memberBId;
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private final String month;
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private final String status;
+
+    public static MatchResponse from(final Match match, final String month) {
+        return MatchResponse.builder()
+                .matchId(match.getId())
+                .memberAId(match.getMemberAId())
+                .memberBId(match.getMemberBId())
+                .month(month)
+                .status(match.getStatus())
+                .build();
+    }
+}

src/main/java/org/patinanetwork/patchats/api/match/dto/match/UpdateMatchFeedbackRequest.java

@@ -0,0 +1,5 @@
+package org.patinanetwork.patchats.api.match.dto.match;
+
+import jakarta.validation.constraints.NotBlank;
+
+public record UpdateMatchFeedbackRequest(@NotBlank String feedback) {}

src/main/java/org/patinanetwork/patchats/api/match/dto/match/UpdateMatchStatusRequest.java

@@ -0,0 +1,5 @@
+package org.patinanetwork.patchats.api.match.dto.match;
+
+import jakarta.validation.constraints.NotBlank;
+
+public record UpdateMatchStatusRequest(@NotBlank String status) {}

src/main/java/org/patinanetwork/patchats/common/web/ApiExceptionHandler.java

@@ -2,6 +2,8 @@
 
 import java.util.stream.Collectors;
 import org.patinanetwork.patchats.common.dto.ApiResponder;
+import org.patinanetwork.patchats.common.web.exception.MatchCycleNotFoundException;
+import org.patinanetwork.patchats.common.web.exception.MatchNotFoundException;
 import org.patinanetwork.patchats.common.web.exception.MemberDuplicateException;
 import org.patinanetwork.patchats.common.web.exception.MemberNotFoundException;
 import org.springframework.http.HttpStatus;
@@ -34,6 +36,16 @@ public ResponseEntity<ApiResponder<Void>> handleMemberDuplicate(final MemberDupl
         return ResponseEntity.status(HttpStatus.CONFLICT).body(ApiResponder.failure(ex.getMessage()));
     }
 
+    @ExceptionHandler(MatchNotFoundException.class)
+    public ResponseEntity<ApiResponder<Void>> handleMatchNotFound(final MatchNotFoundException ex) {
+        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ApiResponder.failure(ex.getMessage()));
+    }
+
+    @ExceptionHandler(MatchCycleNotFoundException.class)
+    public ResponseEntity<ApiResponder<Void>> handleMatchCycleNotFound(final MatchCycleNotFoundException ex) {
+        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ApiResponder.failure(ex.getMessage()));
+    }
+
     private String formatError(final FieldError error) {
         return error.getField() + " " + error.getDefaultMessage();
     }

src/main/java/org/patinanetwork/patchats/common/web/exception/MatchCycleNotFoundException.java

@@ -0,0 +1,7 @@
+package org.patinanetwork.patchats.common.web.exception;
+
+public class MatchCycleNotFoundException extends RuntimeException {
+    public MatchCycleNotFoundException(Integer id) {
+        super("Match Cycle with ID " + id + " not found");
+    }
+}

src/main/java/org/patinanetwork/patchats/common/web/exception/MatchNotFoundException.java

@@ -0,0 +1,9 @@
+package org.patinanetwork.patchats.common.web.exception;
+
+import java.util.UUID;
+
+public class MatchNotFoundException extends RuntimeException {
+    public MatchNotFoundException(UUID id) {
+        super("Match with ID " + id + " not found");
+    }
+}

src/test/java/org/patinanetwork/patchats/api/match/AdminMatchControllerTest.java

@@ -0,0 +1,88 @@
+package org.patinanetwork.patchats.api.match;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.when;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+import java.time.Instant;
+import java.util.UUID;
+import org.junit.jupiter.api.Test;
+import org.patinanetwork.patchats.api.match.dto.match.AdminMatchResponse;
+import org.patinanetwork.patchats.common.web.ApiExceptionHandler;
+import org.patinanetwork.patchats.common.web.exception.MatchCycleNotFoundException;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
+import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.http.MediaType;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.test.web.servlet.MockMvc;
+
+@WebMvcTest(AdminMatchController.class)
+@AutoConfigureMockMvc(addFilters = false)
+@Import(ApiExceptionHandler.class)
+class AdminMatchControllerTest {
+
+    private static final String MEMBER_A_ID = "11111111-1111-1111-1111-111111111111";
+    private static final String MEMBER_B_ID = "22222222-2222-2222-2222-222222222222";
+    private static final String REQUEST_BODY =
+            "{\"memberAId\":\"%s\",\"memberBId\":\"%s\",\"matchCycleId\":1,\"matchScore\":0.85,\"status\":\"CONFIRMED\"}"
+                    .formatted(MEMBER_A_ID, MEMBER_B_ID);
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @MockitoBean
+    private MatchService matchService;
+
+    @Test
+    void createMatch_ReturnsOkAndAdminMatchResponse() throws Exception {
+        when(matchService.createMatch(any()))
+                .thenReturn(AdminMatchResponse.builder()
+                        .matchId(UUID.fromString("33333333-3333-3333-3333-333333333333"))
+                        .memberAId(UUID.fromString(MEMBER_A_ID))
+                        .memberBId(UUID.fromString(MEMBER_B_ID))
+                        .matchCycleId(1)
+                        .month("2026-07")
+                        .status("CONFIRMED")
+                        .matchScore(0.85)
+                        .createdAt(Instant.parse("2026-07-15T10:00:00Z"))
+                        .build());
+
+        mockMvc.perform(post("/api/admin/matches")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(REQUEST_BODY))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.success").value(true))
+                .andExpect(jsonPath("$.payload.matchId").value("33333333-3333-3333-3333-333333333333"))
+                .andExpect(jsonPath("$.payload.memberAId").value(MEMBER_A_ID))
+                .andExpect(jsonPath("$.payload.memberBId").value(MEMBER_B_ID))
+                .andExpect(jsonPath("$.payload.matchCycleId").value(1))
+                .andExpect(jsonPath("$.payload.month").value("2026-07"))
+                .andExpect(jsonPath("$.payload.status").value("CONFIRMED"))
+                .andExpect(jsonPath("$.payload.matchScore").value(0.85))
+                .andExpect(jsonPath("$.payload.createdAt").isNotEmpty());
+    }
+
+    @Test
+    void createMatch_ReturnsBadRequestWhenMemberAIdMissing() throws Exception {
+        mockMvc.perform(post("/api/admin/matches")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"memberBId\":\"%s\",\"matchCycleId\":1}".formatted(MEMBER_B_ID)))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.success").value(false));
+    }
+
+    @Test
+    void createMatch_ReturnsNotFoundWhenCycleMissing() throws Exception {
+        when(matchService.createMatch(any())).thenThrow(new MatchCycleNotFoundException(1));
+
+        mockMvc.perform(post("/api/admin/matches")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(REQUEST_BODY))
+                .andExpect(status().isNotFound())
+                .andExpect(jsonPath("$.success").value(false));
+    }
+}