Merge pull request #77 from billilge/feat/#76-fcm-push-setup

[Feat/#76] FCM 푸시 발송 초기 세팅

Author: tnals0924

.dockerignore

@@ -19,6 +19,7 @@ local-storage/
 .env
 .env.*
 !.env.example
+*firebase-adminsdk*.json
 
 # 문서·기타
 docs/

.env.example

@@ -43,3 +43,11 @@ KCONNECT_USER_INFO_STUDENT_ID_FIELD=replace-with-field-name
 KCONNECT_USER_INFO_NAME_FIELD=replace-with-field-name
 KCONNECT_USER_INFO_MAJOR_FIELD=replace-with-field-name
 KCONNECT_USER_INFO_ACADEMIC_STATUS_FIELD=replace-with-field-name
+
+### infrastructure:client — 푸시 알림 (log | fcm) ###
+# log는 실제 발송 없이 로그만 남긴다 (로컬 기본값)
+PUSH_TYPE=log
+
+# type=fcm일 때. Firebase 콘솔 > 프로젝트 설정 > 서비스 계정에서 받은 비공개 키 JSON을 base64로 인코딩한 값
+# 예: base64 < firebase-adminsdk.json | tr -d '\n'
+FIREBASE_CREDENTIALS_BASE64=replace-with-base64-encoded-service-account-json

.gitignore

@@ -38,4 +38,7 @@ out/
 
 .DS_Store
 
-docs/plans
+docs/plans
+
+# Firebase 서비스 계정 키 (env로 주입하고 파일은 커밋하지 않는다)
+*firebase-adminsdk*.json

core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/notification/client/PushNotificationClient.java

@@ -0,0 +1,9 @@
+package kr.ac.kookmin.stream.member.domain.notification.client;
+
+import java.util.List;
+import kr.ac.kookmin.stream.member.domain.notification.domain.PushMessage;
+import kr.ac.kookmin.stream.member.domain.notification.domain.PushSendResult;
+
+public interface PushNotificationClient {
+    PushSendResult send(List<String> tokens, PushMessage message);
+}

core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/notification/domain/PushMessage.java

@@ -0,0 +1,5 @@
+package kr.ac.kookmin.stream.member.domain.notification.domain;
+
+import java.util.Map;
+
+public record PushMessage(String title, String body, Map<String, String> data) {}

core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/notification/domain/PushSendOutcome.java

@@ -0,0 +1,3 @@
+package kr.ac.kookmin.stream.member.domain.notification.domain;
+
+public record PushSendOutcome(String token, PushSendStatus status) {}

core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/notification/domain/PushSendResult.java

@@ -0,0 +1,23 @@
+package kr.ac.kookmin.stream.member.domain.notification.domain;
+
+import java.util.List;
+
+/**
+ * 토큰별 발송 결과. 멤버와의 매핑은 토큰을 넘긴 호출 측이 갖는다.
+ * INVALID_TOKEN 정리는 memberId가 아니라 토큰 값으로 해야 발송 이후 새로 등록된 토큰을 지우지 않는다.
+ */
+public record PushSendResult(List<PushSendOutcome> outcomes) {
+
+    public static PushSendResult of(List<String> tokens, PushSendStatus status) {
+        return new PushSendResult(tokens.stream()
+            .map(token -> new PushSendOutcome(token, status))
+            .toList());
+    }
+
+    public List<String> tokensWith(PushSendStatus status) {
+        return outcomes.stream()
+            .filter(outcome -> outcome.status() == status)
+            .map(PushSendOutcome::token)
+            .toList();
+    }
+}

core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/notification/domain/PushSendStatus.java

@@ -0,0 +1,8 @@
+package kr.ac.kookmin.stream.member.domain.notification.domain;
+
+public enum PushSendStatus {
+    SUCCESS,
+    INVALID_TOKEN,  // 만료·삭제되어 다시 보내도 성공할 수 없는 토큰. fcm_token 정리 대상
+    RETRYABLE,      // 일시적 장애로 실패. 해당 토큰만 재시도 대상
+    FAILED          // 설정·요청 문제(자격증명, APNs 키, 다른 Firebase 프로젝트, 잘못된 페이로드 등). 원인을 고치기 전에는 재시도해도 실패
+}

gradle/libs.versions.toml

@@ -7,6 +7,7 @@ junitBomVersion = "6.0.0"
 lombokVersion = "1.18.36"
 springdocVersion = "3.1.1"
 awsSdkVersion = "2.54.15"
+firebaseAdminVersion = "9.11.0"
 
 [libraries]
 # BOMs — import as `platform(...)` in modules that don't apply the Boot plugin directly
@@ -47,6 +48,8 @@ mysqlConnectorJ = { module = "com.mysql:mysql-connector-j" }
 
 awsS3 = { module = "software.amazon.awssdk:s3" }
 
+firebaseAdmin = { module = "com.google.firebase:firebase-admin", version.ref = "firebaseAdminVersion" }
+
 jjwtApi = { module = "io.jsonwebtoken:jjwt-api", version.ref = "jjwtVersion" }
 jjwtImpl = { module = "io.jsonwebtoken:jjwt-impl", version.ref = "jjwtVersion" }
 jjwtJackson = { module = "io.jsonwebtoken:jjwt-jackson", version.ref = "jjwtVersion" }

infrastructure/client/build.gradle.kts

@@ -8,6 +8,7 @@ dependencies {
     implementation(project(":core:common"))
     implementation(project(":core:domain:auth"))
     implementation(project(":core:domain:internal"))
+    implementation(project(":core:domain:member"))
 
     implementation(platform(libs.springBootDependenciesBom))
     implementation(libs.springBootStarter)
@@ -17,6 +18,8 @@ dependencies {
     implementation(platform(libs.awsSdkBom))
     implementation(libs.awsS3)
 
+    implementation(libs.firebaseAdmin)
+
     testImplementation(platform(libs.springBootDependenciesBom))
     testImplementation(libs.springBootStarterTest)
     testRuntimeOnly(libs.junitPlatformLauncher)