From b53e0b487573b81dd505c8058f5ade21b3535122 Mon Sep 17 00:00:00 2001
From: shooukie <bigcape@naver.com>
Date: Tue, 15 Sep 2026 15:18:40 +0900
Subject: [PATCH 1/2] =?UTF-8?q?feat:=20=EC=95=8C=EB=9E=8C=20=EB=AA=A9?=
 =?UTF-8?q?=EB=A1=9D=20=EC=A1=B0=ED=9A=8C/=EC=9D=BD=EC=9D=8C=EC=B2=98?=
 =?UTF-8?q?=EB=A6=AC=20api=20=EC=97=B0=EA=B2=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/apis/notification.ts                   | 173 +++++++++++++
 src/components/common/NotificationCard.tsx |   4 +-
 src/hooks/mutation/useNotification.ts      |  73 ++++++
 src/hooks/queries/useNotification.ts       |  47 ++++
 src/pages/NotificationPage.tsx             | 270 ++++++++++-----------
 5 files changed, 429 insertions(+), 138 deletions(-)
 create mode 100644 src/apis/notification.ts
 create mode 100644 src/hooks/mutation/useNotification.ts
 create mode 100644 src/hooks/queries/useNotification.ts

diff --git a/src/apis/notification.ts b/src/apis/notification.ts
new file mode 100644
index 0000000..01333fc
--- /dev/null
+++ b/src/apis/notification.ts
@@ -0,0 +1,173 @@
+import { apiClient } from "@/apis/client";
+import type { CommonResponse } from "@/types/api";
+
+// 알림 유형
+export type NotificationType = "MISSION_RECOMMENDATION";
+
+// 딥링크 대상 유형
+export type NotificationReferenceType = "MISSION";
+
+// 기기 유형
+export type DeviceType = "ANDROID" | "IOS" | "WEB";
+
+// 알림 항목
+export interface NotificationItem {
+  id: number;
+  type: NotificationType;
+  title: string;
+  body: string;
+  referenceType: NotificationReferenceType | null;
+  referenceId: number | null;
+  read: boolean;
+  createdAt: string;
+}
+
+// 알림 목록 조회 응답
+export interface Notifications {
+  notifications: NotificationItem[];
+  nextCursor: number | null;
+  hasNext: boolean;
+}
+
+// 알림 목록 조회 파라미터
+export interface NotificationsParams {
+  cursor?: number;
+  size?: number;
+}
+
+// 미읽음 알림 개수 조회 응답
+export interface UnreadNotificationCount {
+  unreadCount: number;
+}
+
+// 알림 설정 조회·변경 응답
+export interface NotificationSettings {
+  pushEnabled: boolean;
+}
+
+// 알림 설정 변경 요청
+export interface UpdateNotificationSettingsParams {
+  pushEnabled: boolean;
+}
+
+// FCM 토큰 등록 요청
+export type RegisterFcmTokenParams = {
+  token: string;
+  deviceType: DeviceType;
+} & (
+  | {
+      latitude: number;
+      longitude: number;
+    }
+  | {
+      latitude?: never;
+      longitude?: never;
+    }
+);
+
+// FCM 토큰 등록 응답
+export interface RegisteredFcmToken {
+  id: number;
+  deviceType: DeviceType;
+}
+
+// 인앱 알림 목록 조회
+// GET /api/notifications
+export const getNotifications = async (
+  params: NotificationsParams = {},
+): Promise<Notifications> => {
+  const response = await apiClient.get<CommonResponse<Notifications>>(
+    "/api/notifications",
+    {
+      params: {
+        ...params,
+        size: params.size ?? 20,
+      },
+    },
+  );
+
+  return response.data.result;
+};
+
+// 미읽음 알림 개수 조회
+// GET /api/notifications/unread-count
+export const getUnreadNotificationCount =
+  async (): Promise<UnreadNotificationCount> => {
+    const response = await apiClient.get<
+      CommonResponse<UnreadNotificationCount>
+    >("/api/notifications/unread-count");
+
+    return response.data.result;
+  };
+
+// 알림 설정 조회
+// GET /api/users/me/notification-settings
+export const getNotificationSettings =
+  async (): Promise<NotificationSettings> => {
+    const response = await apiClient.get<CommonResponse<NotificationSettings>>(
+      "/api/users/me/notification-settings",
+    );
+
+    return response.data.result;
+  };
+
+// 알림 설정 변경
+// PATCH /api/users/me/notification-settings
+export const updateNotificationSettings = async (
+  params: UpdateNotificationSettingsParams,
+): Promise<NotificationSettings> => {
+  const response = await apiClient.patch<CommonResponse<NotificationSettings>>(
+    "/api/users/me/notification-settings",
+    params,
+  );
+
+  return response.data.result;
+};
+
+// 알림 읽음 처리
+// PATCH /api/notifications/{notificationId}/read
+export const markNotificationAsRead = async (
+  notificationId: number,
+): Promise<string> => {
+  const response = await apiClient.patch<CommonResponse<string>>(
+    `/api/notifications/${notificationId}/read`,
+  );
+
+  return response.data.result;
+};
+
+// 알림 전체 읽음 처리
+// PATCH /api/notifications/read-all
+export const markAllNotificationsAsRead = async (): Promise<string> => {
+  const response = await apiClient.patch<CommonResponse<string>>(
+    "/api/notifications/read-all",
+  );
+
+  return response.data.result;
+};
+
+// FCM 토큰 등록
+// POST /api/notifications/fcm-tokens
+export const registerFcmToken = async (
+  params: RegisterFcmTokenParams,
+): Promise<RegisteredFcmToken> => {
+  const response = await apiClient.post<CommonResponse<RegisteredFcmToken>>(
+    "/api/notifications/fcm-tokens",
+    params,
+  );
+
+  return response.data.result;
+};
+
+// FCM 토큰 해제
+// DELETE /api/notifications/fcm-tokens
+export const deleteFcmToken = async (token: string): Promise<string> => {
+  const response = await apiClient.delete<CommonResponse<string>>(
+    "/api/notifications/fcm-tokens",
+    {
+      params: { token },
+    },
+  );
+
+  return response.data.result;
+};
diff --git a/src/components/common/NotificationCard.tsx b/src/components/common/NotificationCard.tsx
index 3b5aece..a92b41c 100644
--- a/src/components/common/NotificationCard.tsx
+++ b/src/components/common/NotificationCard.tsx
@@ -32,6 +32,7 @@ interface NotificationCardProps {
   amount?: number | null;
   createdAt: string;
   read?: boolean;
+  onRead?: (id: number, read: boolean) => void;
 }
 
 export function NotificationCard({
@@ -42,13 +43,14 @@ export function NotificationCard({
   amount,
   createdAt,
   read = false,
+  onRead,
 }: NotificationCardProps) {
   const unread = !read;
   const { icon, iconBg } = notificationStyles[type];
   return (
     <ContentCard
       key={id}
-      //   onClick={() => handleRead(notification.id)}
+      onClick={() => onRead?.(id, read)}
       className={`relative cursor-pointer transition ${unread ? "bg-white" : "!bg-[#F8FAFC]"}`}
     >
       <div className="flex gap-3">
diff --git a/src/hooks/mutation/useNotification.ts b/src/hooks/mutation/useNotification.ts
new file mode 100644
index 0000000..3d169a6
--- /dev/null
+++ b/src/hooks/mutation/useNotification.ts
@@ -0,0 +1,73 @@
+import {
+  deleteFcmToken,
+  markAllNotificationsAsRead,
+  markNotificationAsRead,
+  registerFcmToken,
+  updateNotificationSettings,
+} from "@/apis/notification";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { notificationKeys } from "../queries/useNotification";
+
+// 알림 설정 변경
+export const useUpdateNotificationSettings = () => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: updateNotificationSettings,
+    onSuccess: async () => {
+      await queryClient.invalidateQueries({
+        queryKey: notificationKeys.settings,
+      });
+    },
+  });
+};
+
+// 알림 하나 읽음 처리
+export const useMarkNotificationAsRead = () => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: markNotificationAsRead,
+    onSuccess: async () => {
+      await Promise.all([
+        queryClient.invalidateQueries({
+          queryKey: notificationKeys.lists,
+        }),
+        queryClient.invalidateQueries({
+          queryKey: notificationKeys.unreadCount,
+        }),
+      ]);
+    },
+  });
+};
+
+// 알림 전체 읽음 처리
+export const useMarkAllNotificationsAsRead = () => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: markAllNotificationsAsRead,
+    onSuccess: async () => {
+      await Promise.all([
+        queryClient.invalidateQueries({
+          queryKey: notificationKeys.lists,
+        }),
+        queryClient.invalidateQueries({
+          queryKey: notificationKeys.unreadCount,
+        }),
+      ]);
+    },
+  });
+};
+
+// FCM 토큰 등록
+export const useRegisterFcmToken = () =>
+  useMutation({
+    mutationFn: registerFcmToken,
+  });
+
+// FCM 토큰 해제
+export const useDeleteFcmToken = () =>
+  useMutation({
+    mutationFn: deleteFcmToken,
+  });
diff --git a/src/hooks/queries/useNotification.ts b/src/hooks/queries/useNotification.ts
new file mode 100644
index 0000000..68496d1
--- /dev/null
+++ b/src/hooks/queries/useNotification.ts
@@ -0,0 +1,47 @@
+import { useInfiniteQuery, useQuery } from "@tanstack/react-query";
+
+import {
+  getNotifications,
+  getUnreadNotificationCount,
+  getNotificationSettings,
+} from "@/apis/notification";
+
+// 쿼리 키
+export const notificationKeys = {
+  all: ["notifications"] as const,
+  lists: ["notifications", "list"] as const,
+  list: (size: number) => ["notifications", "list", size] as const,
+  unreadCount: ["notifications", "unread-count"] as const,
+  settings: ["notifications", "settings"] as const,
+};
+
+// 알림 목록 조회: 커서 기반 더보기
+export const useNotifications = (size = 20) =>
+  useInfiniteQuery({
+    queryKey: notificationKeys.list(size),
+    queryFn: ({ pageParam }) =>
+      getNotifications({
+        cursor: pageParam,
+        size,
+      }),
+    initialPageParam: undefined as number | undefined,
+    getNextPageParam: (lastPage) =>
+      lastPage.hasNext ? (lastPage.nextCursor ?? undefined) : undefined,
+    staleTime: 30 * 1000,
+  });
+
+// 미읽음 알림 개수 조회
+export const useUnreadNotificationCount = () =>
+  useQuery({
+    queryKey: notificationKeys.unreadCount,
+    queryFn: getUnreadNotificationCount,
+    staleTime: 30 * 1000,
+  });
+
+// 알림 설정 조회
+export const useNotificationSettings = () =>
+  useQuery({
+    queryKey: notificationKeys.settings,
+    queryFn: getNotificationSettings,
+    staleTime: 5 * 60 * 1000,
+  });
diff --git a/src/pages/NotificationPage.tsx b/src/pages/NotificationPage.tsx
index 03936b8..4a043c0 100644
--- a/src/pages/NotificationPage.tsx
+++ b/src/pages/NotificationPage.tsx
@@ -1,90 +1,57 @@
 import { SubHeader } from "@/components/DeviceFrame";
 import { useNavigate } from "react-router-dom";
-import React, { useState } from "react";
-import { Target, Gift, MapPin, Bell, Medal } from "lucide-react";
-import { ContentCard } from "@/components/common/ContentCard";
-
-const initialNotifications = [
-  {
-    id: 1,
-    icon: <Target size={21} className="text-sky-400" />,
-    iconBg: "bg-sky-50",
-    title: "새 미션이 열렸어요!",
-    description: "'인사동 전통찻집 방문' 미션이 오픈됐어요.",
-    time: "방금",
-    unread: true,
-  },
-  {
-    id: 2,
-    icon: <Gift size={21} className="text-orange-400" />,
-    iconBg: "bg-orange-50",
-    title: "보상이 지급됐어요 🎉",
-    description: "경복궁 미션 완료! +150P가 지급됐습니다.",
-    time: "1시간 전",
-    unread: true,
-  },
-  {
-    id: 3,
-    icon: <MapPin size={21} className="text-emerald-500" />,
-    iconBg: "bg-emerald-50",
-    title: "근처 미션을 발견했어요",
-    description: "현재 위치 1.2km 내에 '경복궁' 미션이 있어요.",
-    time: "2시간 전",
-    unread: true,
-  },
-  {
-    id: 4,
-    icon: <Bell size={21} className="text-violet-400" />,
-    iconBg: "bg-violet-50",
-    title: "공지사항",
-    description: "Questpot v1.2 업데이트 – 마스코트 꾸미기 기능 추가!",
-    time: "어제",
-    unread: false,
-  },
-  {
-    id: 5,
-    icon: <Medal size={21} className="text-orange-400" />,
-    iconBg: "bg-orange-50",
-    title: "배지를 획득했어요 🏅",
-    description: "'탐험가' 배지를 획득했습니다. 축하해요!",
-    time: "어제",
-    unread: false,
-  },
-  {
-    id: 6,
-    icon: <Target size={21} className="text-sky-400" />,
-    iconBg: "bg-sky-50",
-    title: "미션 리마인더",
-    description: "저장한 '남산타워 야경' 미션을 완료해보세요.",
-    time: "2일 전",
-    unread: false,
-  },
-];
+import { useNotifications } from "@/hooks/queries/useNotification";
+import {
+  useMarkAllNotificationsAsRead,
+  useMarkNotificationAsRead,
+} from "@/hooks/mutation/useNotification";
+import { NotificationCard } from "@/components/common/NotificationCard";
 
 export default function NotificationPage() {
   const navigate = useNavigate();
 
-  const [notifications, setNotifications] = useState(initialNotifications);
+  // 알림 목록
+  const {
+    data: notificationData,
+    isPending: isNotificationPending,
+    isError: isNotificationError,
+    refetch,
+    fetchNextPage,
+    hasNextPage,
+    isFetching,
+    isFetchingNextPage,
+    isFetchNextPageError,
+  } = useNotifications();
+
+  const notifications =
+    notificationData?.pages.flatMap((page) => page.notifications) ?? [];
 
   // 하나 읽음 처리
-  const handleRead = (id: number) => {
-    setNotifications((prev) =>
-      prev.map((notification) =>
-        notification.id === id
-          ? { ...notification, unread: false }
-          : notification,
-      ),
-    );
-  };
+  const {
+    mutate: readNotification,
+    isPending: isReadPending,
+    isError: isReadError,
+  } = useMarkNotificationAsRead();
 
   // 모두 읽음 처리
+  const {
+    mutate: readAllNotifications,
+    isPending: isReadAllPending,
+    isError: isReadAllError,
+  } = useMarkAllNotificationsAsRead();
+
+  const isReadUpdating = isReadPending || isReadAllPending;
+
+  const handleRead = (id: number, read: boolean) => {
+    if (read || isReadUpdating) return;
+
+    readNotification(id);
+  };
+
   const handleReadAll = () => {
-    setNotifications((prev) =>
-      prev.map((notification) => ({
-        ...notification,
-        unread: false,
-      })),
-    );
+    if (isReadUpdating) return;
+
+    readAllNotifications();
   };
 
   return (
@@ -94,80 +61,109 @@ export default function NotificationPage() {
         onBack={() => navigate(-1)}
         action={
           <button
-            className="inline-flex items-center gap-1 bg-transparent text-xs font-bold text-[var(--primary-soft)]"
+            className="
+              inline-flex items-center gap-1 bg-transparent
+              text-xs font-bold text-[var(--primary-soft)]
+              disabled:cursor-not-allowed disabled:opacity-50
+            "
             type="button"
             onClick={handleReadAll}
+            disabled={isReadUpdating || isNotificationPending}
           >
-            모두 읽기
+            {isReadAllPending ? "처리 중..." : "모두 읽기"}
           </button>
         }
       />
 
       <div className="flex flex-1 flex-col gap-2 p-4">
-        {notifications.map((notification) => (
-          <ContentCard
-            key={notification.id}
-            onClick={() => handleRead(notification.id)}
-            className={`
-              relative cursor-pointer transition
-              ${notification.unread ? "bg-white" : "!bg-[#F8FAFC]"}
-            `}
-          >
-            <div className="flex gap-3">
-              {/* 아이콘 */}
-              <div
-                className={`
-                  flex h-12 w-12 shrink-0
-                  items-center justify-center rounded-2xl
-                  ${notification.iconBg}
-                  ${notification.unread ? "" : "opacity-60"}
-                `}
-              >
-                {notification.icon}
-              </div>
+        {(isReadError || isReadAllError) && (
+          <p role="alert" className="text-center text-sm text-red-500">
+            읽음 처리에 실패했어요. 다시 시도해 주세요.
+          </p>
+        )}
 
-              {/* 내용 */}
-              <div className="flex min-w-0 flex-1 flex-col pr-4">
-                <h3
-                  className={`
-                    text-[12px]
-                    ${
-                      notification.unread
-                        ? "font-black text-[var(--ink)]"
-                        : "font-semibold text-[#6F7782]"
-                    }
-                  `}
-                >
-                  {notification.title}
-                </h3>
-
-                <p
-                  className={`
-                    type-caption2
-                    ${notification.unread ? "text-[#777B81]" : "text-[#9AA2AC]"}
-                  `}
-                >
-                  {notification.description}
-                </p>
+        {isNotificationPending ? (
+          <p className="py-10 text-center text-sm text-[#A2A9B2]">
+            알림을 불러오는 중...
+          </p>
+        ) : isNotificationError && !notificationData ? (
+          /* 최초 조회 실패 */
+          <div className="flex flex-col items-center gap-3 py-10">
+            <p role="alert" className="text-sm text-[#A2A9B2]">
+              알림을 불러오지 못했어요.
+            </p>
 
-                <p className="type-body5 pt-1 text-[#A2A9B2]">
-                  {notification.time}
-                </p>
+            <button
+              type="button"
+              onClick={() => void refetch()}
+              disabled={isFetching}
+              className="text-sm font-bold text-[#5BB5F8]"
+            >
+              {isFetching ? "불러오는 중..." : "다시 시도"}
+            </button>
+          </div>
+        ) : (
+          <>
+            {isNotificationError && !isFetchNextPageError && (
+              <div className="text-center text-sm text-red-500">
+                <p role="alert">최신 알림을 불러오지 못했어요.</p>
+                <button
+                  type="button"
+                  onClick={() => void refetch()}
+                  disabled={isFetching}
+                  className="mt-1 font-bold"
+                >
+                  다시 시도
+                </button>
               </div>
+            )}
 
-              {/* 안 읽은 알림 표시 */}
-              {notification.unread && (
-                <span
-                  className="
-                    absolute right-4 top-5
-                    h-2.5 w-2.5 rounded-full
-                    bg-[#5BB5F8]
-                  "
+            {notifications.length === 0 && (
+              <p className="py-10 text-center text-sm text-[#A2A9B2]">
+                아직 알림이 없어요.
+              </p>
+            )}
+
+            {/* 알림 목록 */}
+            {notifications.map((notification) => {
+              return (
+                <NotificationCard
+                  key={notification.id}
+                  id={notification.id}
+                  type={notification.type}
+                  title={notification.title}
+                  description={notification.body}
+                  createdAt={notification.createdAt}
+                  read={notification.read}
+                  onRead={handleRead}
                 />
-              )}
-            </div>
-          </ContentCard>
-        ))}
+              );
+            })}
+
+            {/* 다음 페이지 조회 실패 */}
+            {isFetchNextPageError && (
+              <p role="alert" className="text-center text-sm text-red-500">
+                다음 알림을 불러오지 못했어요. 더보기를 다시 눌러 주세요.
+              </p>
+            )}
+
+            {/* 더보기 */}
+            {hasNextPage && (
+              <button
+                type="button"
+                onClick={() => void fetchNextPage()}
+                disabled={isFetching || isReadUpdating}
+                className="
+                  mt-4 rounded-xl bg-white py-3
+                  text-sm font-bold text-[#5BB5F8]
+                  disabled:opacity-50
+                "
+              >
+                {isFetchingNextPage ? "불러오는 중..." : "더보기"}
+              </button>
+            )}
+          </>
+        )}
       </div>
     </div>
   );

From 05bf30f3f87367fb93710fee3a535e1120be20f5 Mon Sep 17 00:00:00 2001
From: shooukie <bigcape@naver.com>
Date: Tue, 15 Sep 2026 15:39:53 +0900
Subject: [PATCH 2/2] =?UTF-8?q?feat:=20=EC=95=8C=EB=9E=8C=20=EA=B0=9C?=
 =?UTF-8?q?=EC=88=98=20api=20=EC=97=B0=EA=B2=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/components/common/Header.tsx | 13 +++++++++----
 src/pages/NotificationPage.tsx   |  1 -
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/src/components/common/Header.tsx b/src/components/common/Header.tsx
index d42ef16..eeb2820 100644
--- a/src/components/common/Header.tsx
+++ b/src/components/common/Header.tsx
@@ -3,12 +3,15 @@ import questyProfile from "@/assets/questy.svg";
 import { useNavigate } from "react-router-dom";
 import { PATH } from "@/routes/paths";
 import { ReactNode } from "react";
+import { useUnreadNotificationCount } from "@/hooks/queries/useNotification";
 
 interface HeaderProps {
   children?: ReactNode;
 }
 export function Header({ children }: HeaderProps) {
   const navigate = useNavigate();
+  const { data: unreadData } = useUnreadNotificationCount();
+  const unreadCount = unreadData?.unreadCount ?? 0;
   return (
     <header className="sticky top-0 z-20 flex min-h-[66px] shrink-0 items-center justify-between border-b border-[#dcecf8] bg-white/95 px-[22px] backdrop-blur-xl">
       <button
@@ -25,13 +28,15 @@ export function Header({ children }: HeaderProps) {
         <button
           className="relative grid h-10 w-10 place-items-center bg-transparent text-[#8290a2] transition active:scale-95"
           type="button"
-          aria-label="알림 3개"
+          aria-label={`알림 ${unreadCount}개`}
           onClick={() => navigate(PATH.NOTIFICATION)}
         >
           <Bell size={19} strokeWidth={2.2} />
-          <span className="absolute right-[1px] top-[1px] grid h-[16px] min-w-[16px] place-items-center rounded-full border-2 border-white bg-[#f26464] px-0.5 text-[8px] font-black leading-none text-white">
-            3
-          </span>
+          {unreadCount > 0 && (
+            <span className="absolute right-[1px] top-[1px] grid h-[16px] min-w-[16px] place-items-center rounded-full border-2 border-white bg-[#f26464] px-0.5 text-[8px] font-black leading-none text-white">
+              {unreadCount > 99 ? "99+" : unreadCount}
+            </span>
+          )}
         </button>
       </div>
     </header>
diff --git a/src/pages/NotificationPage.tsx b/src/pages/NotificationPage.tsx
index 4a043c0..99f4fe4 100644
--- a/src/pages/NotificationPage.tsx
+++ b/src/pages/NotificationPage.tsx
@@ -139,7 +139,6 @@ export default function NotificationPage() {
                 />
               );
             })}
-
             {/* 다음 페이지 조회 실패 */}
             {isFetchNextPageError && (
               <p role="alert" className="text-center text-sm text-red-500">