[NO-ISSUE] FCM 푸시 알림 기능 develop 이식 및 회원 탈퇴 시 토큰 정리

build.gradle

@@ -60,6 +60,8 @@ dependencies {
 
 	implementation 'com.amazonaws:aws-java-sdk-s3:1.12.529'
 
+	implementation 'com.google.firebase:firebase-admin:9.4.3'
+
 	compileOnly 'org.projectlombok:lombok'
 	annotationProcessor 'org.projectlombok:lombok'
 

src/docs/asciidoc/admin/index.adoc

@@ -16,3 +16,4 @@ include::auth.adoc[]
 include::management.adoc[]
 include::location.adoc[]
 include::notice.adoc[]
+include::push.adoc[]

src/docs/asciidoc/admin/push.adoc

@@ -0,0 +1,22 @@
+[[admin-push-api]]
+== 푸시 브로드캐스트 관리
+
+[[admin-push-broadcast]]
+=== 전체 기기 푸시 발송
+
+관리자가 입력한 제목·본문으로 활성 FCM 토큰 전체에 푸시를 발송합니다.
+
+* ADMIN 권한이 필요합니다.
+* 발송 결과(대상/성공/실패 수)는 이력으로 저장됩니다.
+* Firebase가 설정되지 않은 경우 전송하지 않고 대상 기기 수만 반환합니다.
+
+operation::admin/push/broadcast[snippets='http-request,request-fields,http-response,response-fields']
+
+[[admin-push-broadcast-history]]
+=== 푸시 발송 이력 조회
+
+푸시 브로드캐스트 발송 이력을 최신순으로 페이지 조회합니다.
+
+* VIEWER 이상 권한이 필요합니다.
+
+operation::admin/push/broadcast-history[snippets='http-request,query-parameters,http-response,response-fields']

src/docs/asciidoc/app/index.adoc

@@ -24,3 +24,4 @@ include::location.adoc[]
 include::geocoding.adoc[]
 include::search.adoc[]
 include::notice.adoc[]
+include::notification.adoc[]

src/docs/asciidoc/app/notification.adoc

@@ -0,0 +1,21 @@
+[[notification-api]]
+== FCM 토큰 API
+
+[[fcm-token-register]]
+=== FCM 토큰 등록
+
+로그인 사용자의 FCM 디바이스 토큰을 등록하거나 갱신합니다.
+
+* 인증이 필요합니다.
+* 동일 토큰 또는 동일 디바이스가 있으면 갱신하고, 없으면 신규 등록합니다.
+
+operation::fcm-token/register[snippets='http-request,request-fields,http-response,response-fields']
+
+[[fcm-token-deactivate]]
+=== FCM 토큰 비활성화
+
+로그아웃 등으로 해당 디바이스의 FCM 토큰을 비활성화합니다.
+
+* 인증이 필요합니다.
+
+operation::fcm-token/deactivate[snippets='http-request,query-parameters,http-response,response-fields']

src/main/java/com/souzip/adapter/webapi/admin/AdminPushApi.java

@@ -0,0 +1,75 @@
+package com.souzip.adapter.webapi.admin;
+
+import com.souzip.adapter.webapi.admin.dto.PushBroadcastRequest;
+import com.souzip.application.notification.FcmNotificationService;
+import com.souzip.application.notification.PushBroadcastHistoryCommandService;
+import com.souzip.application.notification.PushBroadcastHistoryQueryService;
+import com.souzip.application.notification.dto.PushBroadcastHistoryResponse;
+import com.souzip.application.notification.dto.PushBroadcastResult;
+import com.souzip.domain.admin.infrastructure.security.annotation.AdminAccess;
+import com.souzip.domain.admin.infrastructure.security.annotation.CurrentAdminId;
+import com.souzip.domain.admin.infrastructure.security.annotation.ViewerAccess;
+import com.souzip.shared.common.dto.SuccessResponse;
+import com.souzip.shared.common.dto.pagination.PaginationRequest;
+import com.souzip.shared.common.dto.pagination.PaginationResponse;
+import jakarta.validation.Valid;
+import java.util.UUID;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.ModelAttribute;
+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;
+
+@RequestMapping("/api/admin/push")
+@RequiredArgsConstructor
+@RestController
+public class AdminPushApi {
+
+    private final FcmNotificationService fcmNotificationService;
+    private final PushBroadcastHistoryCommandService pushBroadcastHistoryCommandService;
+    private final PushBroadcastHistoryQueryService pushBroadcastHistoryQueryService;
+
+    // 관리자가 입력한 제목·본문으로 활성 FCM 토큰 전체에 푸시를 발송합니다.
+    @AdminAccess
+    @PostMapping("/broadcast")
+    public SuccessResponse<PushBroadcastResult> broadcast(
+            @CurrentAdminId UUID adminId,
+            @Valid @RequestBody PushBroadcastRequest request
+    ) {
+        PushBroadcastResult result = fcmNotificationService.broadcastToAllActiveTokens(
+                request.title(),
+                request.body()
+        );
+        pushBroadcastHistoryCommandService.record(adminId, request.title(), request.body(), result);
+        String message = buildMessage(result);
+        return SuccessResponse.of(result, message);
+    }
+
+    // 푸시 브로드캐스트 발송 이력을 최신순으로 페이지 조회합니다.
+    @ViewerAccess
+    @GetMapping("/broadcast/history")
+    public SuccessResponse<PaginationResponse<PushBroadcastHistoryResponse>> broadcastHistory(
+            @ModelAttribute PaginationRequest paginationRequest
+    ) {
+        PaginationResponse<PushBroadcastHistoryResponse> page =
+                pushBroadcastHistoryQueryService.findPage(paginationRequest);
+        return SuccessResponse.of(page);
+    }
+
+    private static String buildMessage(PushBroadcastResult result) {
+        if (result.totalTargets() == 0) {
+            return "등록된 활성 기기가 없어 전송하지 않았습니다.";
+        }
+        if (!result.firebaseConfigured()) {
+            return "Firebase가 설정되지 않아 전송하지 않았습니다. (대상 기기 " + result.totalTargets() + "건)";
+        }
+        return String.format(
+                "푸시 발송 완료. 대상 %d건, 성공 %d건, 실패 %d건",
+                result.totalTargets(),
+                result.successCount(),
+                result.failCount()
+        );
+    }
+}

src/main/java/com/souzip/adapter/webapi/admin/dto/PushBroadcastRequest.java

@@ -0,0 +1,19 @@
+package com.souzip.adapter.webapi.admin.dto;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Size;
+
+public record PushBroadcastRequest(
+        @NotBlank(message = "제목은 필수입니다.")
+        @Size(max = 200, message = "제목은 200자를 초과할 수 없습니다.")
+        String title,
+
+        @NotBlank(message = "내용은 필수입니다.")
+        @Size(max = 1000, message = "내용은 1000자를 초과할 수 없습니다.")
+        String body
+) {
+    public PushBroadcastRequest {
+        title = title != null ? title.trim() : null;
+        body = body != null ? body.trim() : null;
+    }
+}

src/main/java/com/souzip/application/notification/FcmNotificationService.java

@@ -0,0 +1,145 @@
+package com.souzip.application.notification;
+
+import com.google.firebase.messaging.FirebaseMessaging;
+import com.google.firebase.messaging.FirebaseMessagingException;
+import com.google.firebase.messaging.Message;
+import com.google.firebase.messaging.Notification;
+import com.souzip.application.notification.dto.PushBroadcastResult;
+import com.souzip.application.notification.provided.FcmTokenFinder;
+import com.souzip.domain.notification.FcmToken;
+import com.souzip.shared.exception.BusinessException;
+import com.souzip.shared.exception.ErrorCode;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.stereotype.Service;
+
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class FcmNotificationService {
+
+    private final FcmTokenFinder fcmTokenFinder;
+    private final FcmTokenCommandService fcmTokenCommandService;
+    private final ObjectProvider<FirebaseMessaging> firebaseMessaging;
+
+    // 단일 기기 토큰으로 알림(제목·본문)을 전송합니다.
+    public void sendToToken(String registrationToken, String title, String body) {
+        sendToToken(registrationToken, title, body, Map.of());
+    }
+
+    // 데이터 페이로드를 포함해 전송합니다.
+    public void sendToToken(String registrationToken, String title, String body, Map<String, String> data) {
+        FirebaseMessaging messaging = firebaseMessaging.getIfAvailable();
+        if (messaging == null) {
+            log.warn("FirebaseMessaging 빈이 없습니다. firebase.enabled 와 credentials 를 확인하세요. 전송을 건너뜁니다.");
+            return;
+        }
+        try {
+            Notification notification = Notification.builder()
+                    .setTitle(title)
+                    .setBody(body)
+                    .build();
+            Message.Builder messageBuilder = Message.builder()
+                    .setToken(registrationToken)
+                    .setNotification(notification);
+            if (data != null && !data.isEmpty()) {
+                messageBuilder.putAllData(new HashMap<>(data));
+            }
+            messaging.send(messageBuilder.build());
+        } catch (FirebaseMessagingException e) {
+            log.error("FCM 전송 실패 tokenPrefix={} error={}", maskToken(registrationToken), e.getMessagingErrorCode(), e);
+            // 예외 메시지에 원본 토큰 등 민감 정보가 섞일 수 있어 그대로 전파하지 않고, 오류 코드만 보존합니다.
+            throw new FcmSendException(e.getMessagingErrorCode());
+        }
+    }
+
+    // DB 조회는 FcmTokenFinder(짧은 readOnly 트랜잭션)에서만 하고, FCM 전송은 트랜잭션 밖에서 수행합니다.
+    public void sendToUser(Long userId, String title, String body) {
+        List<FcmToken> tokens = fcmTokenFinder.getActiveTokensByUserId(userId);
+        if (tokens.isEmpty()) {
+            return;
+        }
+        int successCount = 0;
+        int failCount = 0;
+        List<Long> staleTokenIds = new ArrayList<>();
+        for (FcmToken token : tokens) {
+            try {
+                sendToToken(token.getToken(), title, body);
+                successCount++;
+            } catch (FcmSendException e) {
+                failCount++;
+                if (e.isPermanentFailure()) {
+                    staleTokenIds.add(token.getId());
+                }
+                log.warn(
+                        "FCM 전송 실패(다음 토큰으로 계속) userId={}, fcmTokenId={}, errorCode={}",
+                        userId,
+                        token.getId(),
+                        e.getMessagingErrorCode()
+                );
+            }
+        }
+        deactivateStaleTokens(staleTokenIds);
+        if (failCount > 0 && successCount == 0) {
+            throw new BusinessException(ErrorCode.FCM_SEND_FAILED, "활성 토큰 전송이 모두 실패했습니다.");
+        }
+        if (failCount > 0) {
+            log.warn("FCM 일부 토큰 실패 userId={}, 성공={}, 실패={}", userId, successCount, failCount);
+        }
+    }
+
+    // DB 조회는 FcmTokenFinder(짧은 readOnly 트랜잭션)에서만 하고, FCM 전송 루프는 트랜잭션 밖에서 수행합니다.
+    public PushBroadcastResult broadcastToAllActiveTokens(String title, String body) {
+        List<FcmToken> tokens = fcmTokenFinder.getAllActiveTokens();
+        if (tokens.isEmpty()) {
+            return new PushBroadcastResult(0, 0, 0, true);
+        }
+        FirebaseMessaging messaging = firebaseMessaging.getIfAvailable();
+        if (messaging == null) {
+            log.warn("FirebaseMessaging 빈이 없습니다. 브로드캐스트를 건너뜁니다. 대상 기기 수={}", tokens.size());
+            return new PushBroadcastResult(tokens.size(), 0, 0, false);
+        }
+        int successCount = 0;
+        int failCount = 0;
+        List<Long> staleTokenIds = new ArrayList<>();
+        for (FcmToken token : tokens) {
+            try {
+                sendToToken(token.getToken(), title, body);
+                successCount++;
+            } catch (FcmSendException e) {
+                failCount++;
+                if (e.isPermanentFailure()) {
+                    staleTokenIds.add(token.getId());
+                }
+                log.warn(
+                        "FCM 브로드캐스트 실패(다음 토큰으로 계속) fcmTokenId={}, errorCode={}",
+                        token.getId(),
+                        e.getMessagingErrorCode()
+                );
+            }
+        }
+        deactivateStaleTokens(staleTokenIds);
+        return new PushBroadcastResult(tokens.size(), successCount, failCount, true);
+    }
+
+    // 영구 실패(UNREGISTERED 등) 토큰은 이후 전송 대상에서 제외되도록 비활성화합니다.
+    private void deactivateStaleTokens(List<Long> staleTokenIds) {
+        if (staleTokenIds.isEmpty()) {
+            return;
+        }
+        fcmTokenCommandService.deactivateByIds(staleTokenIds);
+        log.info("영구 실패로 비활성화한 FCM 토큰 수={}", staleTokenIds.size());
+    }
+
+    private static String maskToken(String token) {
+        if (token == null || token.length() < 12) {
+            return "***";
+        }
+        return token.substring(0, 6) + "..." + token.substring(token.length() - 4);
+    }
+}

src/main/java/com/souzip/application/notification/FcmSendException.java

@@ -0,0 +1,28 @@
+package com.souzip.application.notification;
+
+import com.google.firebase.messaging.MessagingErrorCode;
+import com.souzip.shared.exception.BusinessException;
+import com.souzip.shared.exception.ErrorCode;
+
+// FCM 전송 실패를 나타내며, 영구 실패 여부 판별을 위해 MessagingErrorCode 를 보존합니다.
+// (예외 메시지에는 토큰 등 민감 정보를 담지 않습니다.)
+public class FcmSendException extends BusinessException {
+
+    private final transient MessagingErrorCode messagingErrorCode;
+
+    public FcmSendException(MessagingErrorCode messagingErrorCode) {
+        super(ErrorCode.FCM_SEND_FAILED);
+        this.messagingErrorCode = messagingErrorCode;
+    }
+
+    public MessagingErrorCode getMessagingErrorCode() {
+        return messagingErrorCode;
+    }
+
+    // 토큰이 더 이상 유효하지 않아 재전송해도 계속 실패하는 영구 오류인지 여부.
+    public boolean isPermanentFailure() {
+        return messagingErrorCode == MessagingErrorCode.UNREGISTERED
+                || messagingErrorCode == MessagingErrorCode.INVALID_ARGUMENT
+                || messagingErrorCode == MessagingErrorCode.SENDER_ID_MISMATCH;
+    }
+}