feat: 알림 목록·읽음 API

src/main/java/com/offway/core/notification/controller/NotificationApi.java

@@ -0,0 +1,81 @@
+package com.offway.core.notification.controller;
+
+import com.offway.core.common.response.ApiResponseBody;
+import com.offway.core.notification.controller.dto.NotificationsResponse;
+import com.offway.core.notification.controller.dto.UnreadCountResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/** 알림 API 문서 계약(#263). 매핑은 구현체({@link NotificationController})가 소유한다. */
+@Tag(name = "알림", description = "알림 목록 · 읽음 처리")
+public interface NotificationApi {
+
+    @Operation(
+            summary = "알림 목록",
+            description =
+                    """
+                    소유자의 알림을 **최근 것부터** 준다. 안 읽은 개수(`unreadCount`)를 함께 주므로 홈 배지가
+                    이 응답 하나로 채워진다.
+
+                    **문구는 서버가 주지 않는다.** 각 알림은 종류(`type`)만 싣고, 아이콘과 문구는 앱이 그 값에
+                    맞춘다. 문구를 서버에 굳혀 두면 이미 쌓인 알림이 옛 문구로 남아 화면에 두 세대가 섞인다.
+
+                    현재 `type` 은 `TRIP_TOMORROW`(내일 여행) 하나다. **값은 늘어날 수 있으므로 모르는 값은
+                    무시하거나 기본 아이콘으로 그린다** — 앱을 업데이트하지 않은 사용자에게도 새 알림이 간다.
+
+                    `courseId` 가 있으면 누를 때 그 코스로 이동한다. 없을 수도 있다(코스와 무관한 알림).
+                    지워진 코스를 가리킬 수도 있다 — 알림은 코스가 사라져도 남는다.
+
+                    **`unreadCount` 는 페이지와 무관한 전체 수다.** 이 페이지 안의 안읽음 수가 아니다.
+
+                    **페이지로 끊어 준다.** 전체 건수·페이지 수는 응답 래퍼의 `pageResponse` 에 담긴다.
+                    `size` 는 기본 20, 최대 100 이며 넘겨 보내면 거절하지 않고 100 으로 자른다.
+                    """)
+    @ApiResponse(responseCode = "200", description = "조회 성공(없으면 빈 목록). 페이지 정보는 pageResponse")
+    @ApiResponse(responseCode = "400", description = "게스트 ID 누락·빈 값·64자 초과, 또는 page·size 가 정수가 아님")
+    @ApiResponse(responseCode = "401", description = "인증 필요")
+    ApiResponseBody<NotificationsResponse> notifications(
+            @Parameter(description = "게스트 식별자", example = "guest-abc123") String guestId,
+            @Parameter(description = "0부터 시작하는 페이지 번호. 없으면 0, 음수는 0 으로 자른다", example = "0") Integer page,
+            @Parameter(description = "페이지 크기. 없으면 20, 최대 100(초과분은 잘림)", example = "20") Integer size);
+
+    @Operation(
+            summary = "알림 하나 읽음",
+            description =
+                    """
+                    알림 하나를 읽음으로 바꾸고 **남은 안읽음 개수**를 돌려준다. 배지를 고치려고 목록을 다시
+                    부르지 않아도 된다.
+
+                    **이미 읽은 알림에 다시 보내도 성공(200)이다.** 사용자가 원한 상태가 이미 이뤄져 있고,
+                    알림 화면은 같은 요청을 두 번 보내기 쉬운 자리다. 처음 읽은 시각은 덮어쓰지 않는다.
+
+                    **없는 알림과 남의 알림은 똑같이 404 다.** 남의 것에 403 을 주면 "그 id 는 존재한다" 를
+                    알려주는 셈이라, id 를 훑어 남의 알림 존재를 확인할 수 있다.
+                    """)
+    @ApiResponse(responseCode = "200", description = "읽음 처리 성공(이미 읽었어도 성공)")
+    @ApiResponse(responseCode = "400", description = "게스트 ID 누락·빈 값·64자 초과, 또는 알림 ID 가 정수가 아님")
+    @ApiResponse(responseCode = "401", description = "인증 필요")
+    @ApiResponse(responseCode = "404", description = "요청한 알림이 없거나 소유자가 아님")
+    ApiResponseBody<UnreadCountResponse> read(
+            @Parameter(description = "게스트 식별자", example = "guest-abc123") String guestId,
+            @Parameter(description = "알림 ID", example = "1") long notificationId);
+
+    @Operation(
+            summary = "전체 읽음",
+            description =
+                    """
+                    소유자의 안 읽은 알림을 한 번에 읽음 처리하고 **남은 안읽음 개수**를 돌려준다.
+
+                    보통 0 이지만, 처리와 같은 순간에 새 알림이 들어왔다면 0 이 아닐 수 있다. 응답 값을
+                    그대로 배지에 쓰면 된다.
+
+                    **읽을 것이 없어도 성공(200)이다.**
+                    """)
+    @ApiResponse(responseCode = "200", description = "전체 읽음 처리 성공(읽을 것이 없어도 성공)")
+    @ApiResponse(responseCode = "400", description = "게스트 ID 누락·빈 값·64자 초과")
+    @ApiResponse(responseCode = "401", description = "인증 필요")
+    ApiResponseBody<UnreadCountResponse> readAll(
+            @Parameter(description = "게스트 식별자", example = "guest-abc123") String guestId);
+}

src/main/java/com/offway/core/notification/controller/NotificationController.java

@@ -0,0 +1,51 @@
+package com.offway.core.notification.controller;
+
+import com.offway.core.common.response.ApiResponseBody;
+import com.offway.core.common.response.PageResponse;
+import com.offway.core.notification.controller.dto.NotificationsResponse;
+import com.offway.core.notification.controller.dto.UnreadCountResponse;
+import com.offway.core.notification.service.NotificationService;
+import com.offway.core.notification.service.dto.MyNotifications;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PatchMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/api/v1/notifications")
+@RequiredArgsConstructor
+public class NotificationController implements NotificationApi {
+
+    /** 소유 키 — 코스·연차와 같은 헤더를 쓴다. 인증이 붙는 날 함께 옮긴다. */
+    private static final String GUEST_HEADER = "X-Guest-Id";
+
+    private final NotificationService notificationService;
+
+    @Override
+    @GetMapping
+    public ApiResponseBody<NotificationsResponse> notifications(
+            @RequestHeader(GUEST_HEADER) String guestId,
+            @RequestParam(required = false) Integer page,
+            @RequestParam(required = false) Integer size) {
+        MyNotifications myNotifications = notificationService.myNotifications(guestId, page, size);
+        return ApiResponseBody.ok(NotificationsResponse.from(myNotifications), PageResponse.of(myNotifications));
+    }
+
+    @Override
+    @PatchMapping("/{notificationId}/read")
+    public ApiResponseBody<UnreadCountResponse> read(
+            @RequestHeader(GUEST_HEADER) String guestId, @PathVariable long notificationId) {
+        return ApiResponseBody.ok(UnreadCountResponse.of(notificationService.markRead(guestId, notificationId)));
+    }
+
+    @Override
+    @PostMapping("/read-all")
+    public ApiResponseBody<UnreadCountResponse> readAll(@RequestHeader(GUEST_HEADER) String guestId) {
+        return ApiResponseBody.ok(UnreadCountResponse.of(notificationService.markAllRead(guestId)));
+    }
+}

src/main/java/com/offway/core/notification/controller/dto/NotificationResponse.java

@@ -0,0 +1,35 @@
+package com.offway.core.notification.controller.dto;
+
+import com.offway.core.notification.domain.Notification;
+import com.offway.core.notification.domain.NotificationType;
+import io.swagger.v3.oas.annotations.media.Schema;
+import java.time.LocalDateTime;
+
+/**
+ * 알림 한 건(#263).
+ *
+ * <p><b>문구가 없다.</b> 종류만 내려주고 아이콘·문구는 앱이 맞춘다 — 프론트가 그렇게 하겠다고 했고,
+ * 문구를 서버에 굳히면 이미 쌓인 알림이 옛 문구로 남는다.
+ *
+ * @param id 알림 식별자. 읽음 처리에 쓴다
+ * @param type 알림 종류. 앱이 이 값으로 아이콘·문구를 고른다
+ * @param courseId 누르면 이동할 코스. 코스와 무관한 알림이면 null
+ * @param read 읽었는지
+ * @param createdAt 알림이 만들어진 시각(KST)
+ */
+public record NotificationResponse(
+        long id,
+        NotificationType type,
+        @Schema(example = "12", nullable = true) Long courseId,
+        boolean read,
+        LocalDateTime createdAt) {
+
+    public static NotificationResponse from(Notification notification) {
+        return new NotificationResponse(
+                notification.getId(),
+                notification.getType(),
+                notification.getCourseId(),
+                notification.isRead(),
+                notification.getCreatedAt());
+    }
+}

src/main/java/com/offway/core/notification/controller/dto/NotificationsResponse.java

@@ -0,0 +1,21 @@
+package com.offway.core.notification.controller.dto;
+
+import com.offway.core.notification.service.dto.MyNotifications;
+import java.util.List;
+
+/**
+ * 알림 목록 응답(#263) — 한 페이지 + 안읽음 전체 수.
+ *
+ * @param notifications 이 페이지의 알림. 최근 것부터
+ * @param unreadCount 안 읽은 알림 <b>전체</b> 개수. 홈 배지가 쓰는 값이라 페이지와 무관하다
+ */
+public record NotificationsResponse(List<NotificationResponse> notifications, long unreadCount) {
+
+    public static NotificationsResponse from(MyNotifications myNotifications) {
+        return new NotificationsResponse(
+                myNotifications.notifications().stream()
+                        .map(NotificationResponse::from)
+                        .toList(),
+                myNotifications.unreadCount());
+    }
+}

src/main/java/com/offway/core/notification/controller/dto/UnreadCountResponse.java

@@ -0,0 +1,15 @@
+package com.offway.core.notification.controller.dto;
+
+/**
+ * 읽음 처리 응답(#263) — 처리 후 남은 안읽음 개수.
+ *
+ * <p>읽은 직후 앱은 홈 배지를 고쳐야 한다. 안 주면 목록을 한 번 더 부르게 되므로 같은 응답에 실어 보낸다.
+ *
+ * @param unreadCount 안 읽은 알림 전체 개수
+ */
+public record UnreadCountResponse(long unreadCount) {
+
+    public static UnreadCountResponse of(long unreadCount) {
+        return new UnreadCountResponse(unreadCount);
+    }
+}

src/main/java/com/offway/core/notification/domain/Notification.java

@@ -0,0 +1,120 @@
+package com.offway.core.notification.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import java.time.LocalDateTime;
+import java.util.Objects;
+import java.util.Optional;
+import lombok.AccessLevel;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+/**
+ * 사용자에게 보여줄 알림 한 건(#263).
+ *
+ * <p><b>문구를 담지 않는다.</b> 종류({@link NotificationType})만 저장하고 화면 문구는 앱이 만든다. 문구를
+ * 서버에 굳혀 두면 이미 쌓인 알림은 영영 옛 문구로 남아, 앱이 표현을 고칠 때 화면에 두 세대가 섞인다.
+ *
+ * <p><b>읽음을 boolean 이 아니라 시각으로 둔다.</b> 저장 비용이 같은데 "읽었다" 외에 "언제 읽었나" 까지
+ * 답한다. 나중에 안 읽은 알림을 다시 밀어주는 규칙을 넣을 때 근거가 이미 있다.
+ *
+ * <p>{@code courseId} 는 도메인 경계를 넘는 참조라 <b>raw ID</b> 다(영속성 규약). 코스가 지워져도 알림은
+ * 남아야 하므로 연관관계로 묶지 않는다 — 지워진 코스를 가리키는 알림은 눌러도 코스가 없을 뿐이다.
+ */
+@Entity
+@Table(name = "notification")
+@Getter
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+public class Notification {
+
+    /** 소유 키 길이 — 코스({@code Course.MAX_GUEST_ID_LENGTH})·연차와 같은 값을 쓴다. */
+    public static final int MAX_OWNER_ID_LENGTH = 64;
+
+    /** enum 이름을 담는 칸. 지금 가장 긴 이름의 두 배 남짓으로, 새 종류가 늘어도 마이그레이션이 필요 없다. */
+    public static final int TYPE_LENGTH = 40;
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(name = "guest_id", nullable = false, length = MAX_OWNER_ID_LENGTH)
+    private String guestId;
+
+    /**
+     * ordinal 이 아니라 이름으로 저장한다 — ordinal 은 상수를 재배치하는 순간 이미 저장된 행의 뜻이 통째로
+     * 바뀐다. enum 이름은 클라이언트 계약이기도 하다.
+     */
+    @Enumerated(EnumType.STRING)
+    @Column(name = "type", nullable = false, length = TYPE_LENGTH)
+    private NotificationType type;
+
+    /** 누르면 이동할 코스. 코스와 무관한 알림도 생길 수 있어 없을 수 있다. */
+    @Column(name = "course_id")
+    private Long courseId;
+
+    /** 읽은 시각. null 이면 안 읽음. */
+    @Column(name = "read_at")
+    private LocalDateTime readAt;
+
+    @Column(name = "created_at", nullable = false)
+    private LocalDateTime createdAt;
+
+    @Builder
+    private Notification(String guestId, NotificationType type, Long courseId, LocalDateTime createdAt) {
+        this.guestId = requireOwner(guestId);
+        this.type = Objects.requireNonNull(type, "알림 종류는 필수입니다");
+        this.courseId = courseId;
+        this.createdAt = Objects.requireNonNull(createdAt, "생성 시각은 필수입니다");
+    }
+
+    /**
+     * 소유 키 계약 검증(400).
+     *
+     * <p>빈 헤더({@code X-Guest-Id: " "})는 {@code @RequestHeader} 를 통과하므로 <b>멀쩡한 클라이언트가
+     * 정상 요청으로 닿는다</b> — 불변식으로 다루면 500 이 나간다.
+     *
+     * <p>도메인이 들고 조회 경로도 이걸 쓴다. 조회만 통과시키면 같은 헤더가 메서드에 따라 200 과 400 으로
+     * 갈린다.
+     */
+    public static String requireOwner(String guestId) {
+        if (guestId == null || guestId.isBlank() || guestId.length() > MAX_OWNER_ID_LENGTH) {
+            throw NotificationException.invalidOwnerId();
+        }
+        return guestId;
+    }
+
+    /**
+     * 읽음으로 바꾼다 — <b>이미 읽었으면 아무것도 하지 않는다</b>.
+     *
+     * <p>재요청을 409 로 막지 않는 이유: 사용자가 원한 상태("읽음")가 이미 이뤄져 있다. 알림 화면은 스크롤
+     * 중에 같은 요청을 두 번 보내기 쉬운 자리라, 두 번째를 실패로 만들면 화면이 오류를 띄운다.
+     *
+     * <p>처음 읽은 시각을 덮어쓰지 않는다.
+     *
+     * @return 이 호출로 실제 바뀌었으면 true
+     */
+    public boolean markRead(LocalDateTime readAt) {
+        Objects.requireNonNull(readAt, "읽은 시각은 필수입니다");
+        if (isRead()) {
+            return false;
+        }
+        this.readAt = readAt;
+        return true;
+    }
+
+    public boolean isRead() {
+        return readAt != null;
+    }
+
+    /** 누르면 이동할 코스. 없으면 비어 있다. */
+    public Optional<Long> course() {
+        return Optional.ofNullable(courseId);
+    }
+}

src/main/java/com/offway/core/notification/domain/NotificationErrorCode.java

@@ -0,0 +1,48 @@
+package com.offway.core.notification.domain;
+
+import com.offway.core.common.exception.ErrorCategory;
+import com.offway.core.common.exception.ErrorCode;
+
+/**
+ * 알림 관련 에러 사유(#263).
+ *
+ * <p>번호는 append-only — 재사용·재배치하지 않고 결번을 유지한다.
+ */
+public enum NotificationErrorCode implements ErrorCode {
+
+    /** 소유 키(게스트 ID) 가 비었거나 너무 길다. 빈 헤더는 {@code @RequestHeader} 를 통과하므로 정상 요청이 닿는다. */
+    INVALID_OWNER_ID("NOTIFICATION-001", ErrorCategory.BAD_REQUEST, "게스트 식별자가 올바르지 않습니다."),
+
+    /**
+     * 요청한 알림이 없거나 소유자가 아니다.
+     *
+     * <p><b>둘을 나누지 않는다.</b> 남의 알림에 403 을 주면 "그 id 는 존재하는데 네 것이 아니다" 를 알려주는
+     * 셈이라, id 를 훑어 남의 알림 존재를 확인할 수 있다.
+     */
+    NOTIFICATION_NOT_FOUND("NOTIFICATION-002", ErrorCategory.NOT_FOUND, "요청한 알림을 찾을 수 없습니다.");
+
+    private final String code;
+    private final ErrorCategory category;
+    private final String message;
+
+    NotificationErrorCode(String code, ErrorCategory category, String message) {
+        this.code = code;
+        this.category = category;
+        this.message = message;
+    }
+
+    @Override
+    public String code() {
+        return code;
+    }
+
+    @Override
+    public ErrorCategory category() {
+        return category;
+    }
+
+    @Override
+    public String message() {
+        return message;
+    }
+}