[SOU-646] FCM 인프라·APNs 설정

.codex/skills/souzip-pr/SKILL.md

@@ -37,6 +37,9 @@ Use this skill only when the user explicitly asks for a PR.
    - Jira link
 7. Push only the intended Story branch when needed for PR creation.
 8. Create the PR only after readiness checks pass.
+9. Set PR metadata immediately after creation:
+   - assignee: current user (`gh pr edit --add-assignee @me`)
+   - label: pick **one** from the allowed set below
 
 ## PR Title
 
@@ -58,6 +61,32 @@ Use the existing GitHub PR template:
 Write the Goal and Plan slice as a short summary only.
 Actual Goal, Story, and Plan documents stay local under `docs/goals/`.
 
+## PR Labels
+
+Use **only** these GitHub labels (same names as commit types):
+
+- `feat`
+- `fix`
+- `chore`
+- `refactor`
+- `docs`
+- `test`
+
+Pick one label per PR:
+
+1. Story PR with user-facing change → `feat` (even if the branch has `chore` setup commits)
+2. Bugfix Story → `fix`
+3. Docs-only Story → `docs`
+4. Test-only Story → `test`
+5. Structure-only Story with no behavior change → `refactor`
+6. Tooling, CI, harness-only Story → `chore`
+
+When unsure, prefer the Story intent over the majority commit type.
+
+```bash
+gh pr edit <number> --add-assignee @me --add-label <label>
+```
+
 ## Output
 
 - Story completion status
@@ -66,6 +95,7 @@ Actual Goal, Story, and Plan documents stay local under `docs/goals/`.
 - PR body
 - Push result when a branch push was needed
 - PR result
+- Assignee and label applied
 
 ## Boundaries
 

.gitignore

@@ -31,6 +31,7 @@ Package.resolved
 # Config files
 Config/*.xcconfig
 !Config/Example.xcconfig
+Config/GoogleService-Info*.plist
 
 # System files
 .DS_Store

Config/Example.xcconfig

@@ -22,3 +22,7 @@ AMPLITUDE_API_KEY =
 // AdMob App ID
 ADMOB_APP_ID = 
 ADMOB_BANNER_AD_UNIT_ID =
+
+// Firebase (GoogleService-Info.plist — Git 미추적, Config/에 로컬 배치)
+// Debug: GoogleService-Info-Debug.plist  (BUNDLE_ID: com.swyp.souzip.dev)
+// Release: GoogleService-Info-Release.plist (BUNDLE_ID: com.swyp.souzip)

Projects/App/App-Debug.entitlements

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>aps-environment</key>
+    <string>development</string>
+    <key>com.apple.developer.applesignin</key>
+    <array>
+        <string>Default</string>
+    </array>
+</dict>
+</plist>

Projects/App/App.entitlements → Projects/App/App-Release.entitlements

@@ -2,6 +2,8 @@
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
+    <key>aps-environment</key>
+    <string>production</string>
     <key>com.apple.developer.applesignin</key>
     <array>
         <string>Default</string>

Projects/App/Sources/AppDelegate.swift

@@ -1,12 +1,50 @@
+import FCM
+import Logger
 import UIKit
 
 @main
 final class AppDelegate: UIResponder, UIApplicationDelegate {
+    private let fcmTokenProvider: FCMTokenProviding = DefaultFCMFactory.shared.makeFCMTokenProvider()
+    private let pushTokenSyncer: PushTokenSyncing = DeferredPushTokenSyncer()
+    private var pushTokenSyncTask: Task<Void, Never>?
+
     func application(
         _ application: UIApplication,
         didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
     ) -> Bool {
-        true
+        fcmTokenProvider.configure()
+        observeFCMTokenUpdates()
+        return true
+    }
+
+    func application(
+        _ application: UIApplication,
+        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
+    ) {
+        fcmTokenProvider.setAPNSToken(deviceToken)
+    }
+
+    func application(
+        _ application: UIApplication,
+        didFailToRegisterForRemoteNotificationsWithError error: Error
+    ) {
+        Logger.shared.error(
+            "APNs 등록 실패: \(error.localizedDescription)",
+            category: .general
+        )
+    }
+
+    private func observeFCMTokenUpdates() {
+        pushTokenSyncTask?.cancel()
+
+        let tokenUpdates = fcmTokenProvider.fcmTokenUpdates()
+        let pushTokenSyncer = pushTokenSyncer
+
+        pushTokenSyncTask = Task {
+            for await token in tokenUpdates {
+                await pushTokenSyncer.sync(fcmToken: token)
+            }
+        }
     }
 
     func application(

Projects/App/Sources/Factory/AppFactory.swift

@@ -1,16 +1,22 @@
 import Data
 import Domain
+import FCM
 import Networking
 import Storage
 import Utils
 
 final class AppFactory {
+    let fcmTokenProvider: FCMTokenProviding
     let keychainFactory: KeychainFactory
     let networkFactory: NetworkFactory
     let dataFactory: DataFactory
     let domainFactory: DomainFactory
 
-    init(config: AppConfiguration) {
+    init(
+        config: AppConfiguration,
+        fcmTokenProvider: FCMTokenProviding = DefaultFCMFactory.shared.makeFCMTokenProvider()
+    ) {
+        self.fcmTokenProvider = fcmTokenProvider
         // keyChain
         let keychainFactory = DefaultKeychainFactory(bundleID: AppInfo.bundleID)
 

Projects/App/Sources/Push/PushNotificationRegistrar.swift

@@ -0,0 +1,58 @@
+import Logger
+import UIKit
+import UserNotifications
+
+/// 푸시 권한 요청·APNs 등록은 App 레이어 책임. Core FCM은 토큰 수신만 담당한다.
+final class PushNotificationRegistrar {
+    private enum UserDefaultsKey {
+        static let hasPresentedPushPermissionPrompt = "push.hasPresentedPermissionPrompt"
+    }
+
+    func requestPermissionIfNeeded() {
+        if UserDefaults.standard.bool(forKey: UserDefaultsKey.hasPresentedPushPermissionPrompt) {
+            syncRegistrationIfAuthorized()
+            return
+        }
+
+        UNUserNotificationCenter.current().requestAuthorization(options: [
+            .alert,
+            .badge,
+            .sound,
+        ]) { granted, error in
+            if let error {
+                Logger.shared.error(
+                    "푸시 권한 요청 실패: \(error.localizedDescription)",
+                    category: .general
+                )
+                return
+            }
+
+            UserDefaults.standard.set(
+                true,
+                forKey: UserDefaultsKey.hasPresentedPushPermissionPrompt
+            )
+
+            Logger.shared.info(
+                "푸시 권한 \(granted ? "허용" : "거부")",
+                category: .general
+            )
+
+            guard granted else { return }
+
+            DispatchQueue.main.async {
+                UIApplication.shared.registerForRemoteNotifications()
+            }
+        }
+    }
+
+    /// 설정 앱에서 권한을 켠 뒤 앱으로 돌아온 경우 등 APNs 재등록
+    func syncRegistrationIfAuthorized() {
+        UNUserNotificationCenter.current().getNotificationSettings { settings in
+            guard settings.authorizationStatus == .authorized else { return }
+
+            DispatchQueue.main.async {
+                UIApplication.shared.registerForRemoteNotifications()
+            }
+        }
+    }
+}

Projects/App/Sources/Push/PushTokenSyncer.swift

@@ -0,0 +1,20 @@
+import Logger
+
+protocol PushTokenSyncing: AnyObject {
+    func sync(fcmToken: String) async
+}
+
+/// 서버 API 스펙이 연결되기 전까지 토큰 수신 지점만 고정한다.
+final class DeferredPushTokenSyncer: PushTokenSyncing {
+    private var lastObservedToken: String?
+
+    func sync(fcmToken: String) async {
+        guard lastObservedToken != fcmToken else { return }
+
+        lastObservedToken = fcmToken
+        Logger.shared.info(
+            "FCM 토큰 수신됨. 서버 등록 API 연결 대기",
+            category: .general
+        )
+    }
+}

Projects/App/Sources/SceneDelegate.swift

@@ -5,6 +5,7 @@ import UIKit
 final class SceneDelegate: UIResponder, UIWindowSceneDelegate {
     var window: UIWindow?
     private var coordinator: RootCoordinator?
+    private let pushNotificationRegistrar = PushNotificationRegistrar()
 
     func scene(
         _ scene: UIScene,
@@ -14,6 +15,8 @@ final class SceneDelegate: UIResponder, UIWindowSceneDelegate {
         guard let windowScene = (scene as? UIWindowScene) else { return }
 
         let config = AppConfiguration()
+        pushNotificationRegistrar.requestPermissionIfNeeded()
+
         let factory = AppFactory(config: config)
 
         let nav = CommonNavigationController()
@@ -29,6 +32,10 @@ final class SceneDelegate: UIResponder, UIWindowSceneDelegate {
         window?.makeKeyAndVisible()
     }
 
+    func sceneDidBecomeActive(_ scene: UIScene) {
+        pushNotificationRegistrar.syncRegistrationIfAuthorized()
+    }
+
     func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
         guard let url = URLContexts.first?.url else { return }
         AuthRedirect.handle(url: url)

Projects/Core/FCM/Project.swift

@@ -0,0 +1,11 @@
+import ProjectDescription
+import ProjectDescriptionHelpers
+
+let project = Project.framework(
+    .fcm,
+    additionalBaseSettings: [
+        "PRODUCT_NAME": "FCM",
+        "ENABLE_MODULE_VERIFIER": "NO",
+        "CLANG_ENABLE_MODULE_VERIFIER": "NO",
+    ]
+)

Projects/Core/FCM/Sources/FCMManager.swift

@@ -0,0 +1,87 @@
+import FirebaseCore
+import FirebaseMessaging
+import Logger
+
+public final class FCMManager: NSObject, FCMTokenProviding {
+    public static let shared = FCMManager()
+
+    private let tokenStore = FCMTokenStore()
+
+    public func currentToken() async -> String? {
+        await tokenStore.currentToken()
+    }
+
+    // swiftformat:disable:next modifierOrder
+    private override init() {
+        super.init()
+    }
+
+    // MARK: - Token
+
+    public func fcmTokenUpdates() -> AsyncStream<String> {
+        let tokenStore = tokenStore
+
+        return AsyncStream { continuation in
+            let streamID = UUID()
+
+            Task {
+                await tokenStore.registerStream(
+                    id: streamID,
+                    continuation: continuation
+                )
+            }
+
+            continuation.onTermination = { @Sendable _ in
+                Task {
+                    await tokenStore.unregisterStream(id: streamID)
+                }
+            }
+        }
+    }
+
+    // MARK: - Bootstrap
+
+    public func configure() {
+        guard FirebaseApp.app() == nil else { return }
+
+        FirebaseApp.configure()
+        Messaging.messaging().delegate = self
+
+        Logger.shared.info("Firebase 초기화 완료", category: .general)
+    }
+
+    public func setAPNSToken(_ deviceToken: Data) {
+        Messaging.messaging().apnsToken = deviceToken
+
+        Logger.shared.info(
+            "APNs device token 등록 완료",
+            category: .general
+        )
+    }
+
+    private func deliverToken(_ token: String) {
+        Task {
+            let isNewToken = await tokenStore.updateToken(token)
+            guard isNewToken else { return }
+
+            #if DEBUG
+                Logger.shared.debug("FCM 토큰: \(token)", category: .general)
+            #else
+                Logger.shared.info("FCM 토큰 갱신됨", category: .general)
+            #endif
+        }
+    }
+}
+
+// MARK: - MessagingDelegate
+
+extension FCMManager: MessagingDelegate {
+    public func messaging(
+        _ messaging: Messaging,
+        didReceiveRegistrationToken fcmToken: String?
+    ) {
+        guard let fcmToken else { return }
+
+        deliverToken(fcmToken)
+    }
+}

Projects/Core/FCM/Sources/FCMTokenProviding.swift

@@ -0,0 +1,11 @@
+import Foundation
+
+public protocol FCMTokenProviding: AnyObject {
+    func currentToken() async -> String?
+
+    /// 토큰 갱신 스트림. 구독 시점에 이미 토큰이 있으면 즉시 한 번 방출한다.
+    func fcmTokenUpdates() -> AsyncStream<String>
+
+    func configure()
+    func setAPNSToken(_ deviceToken: Data)
+}