feat: SSE 기반 실시간 모임 현황 업데이트 구현 (#87)

* feat: SSE 범용 훅 및 타입 정의 추가

- useServerSentEvent 범용 훅 구현
- SSE 이벤트 타입 정의 (ParticipantCountEvent, GatheringFullEvent)
- 이벤트 타입 동적 등록 지원
- readyState, close, reconnect 기능 제공

Co-Authored-By: Claude (us.anthropic.claude-sonnet-4-5-20250929-v1:0) <noreply@anthropic.com>

* refactor: useGetGatheringCapacity 폴링 제거

- 10초 폴링 제거하여 SSE 기반 실시간 업데이트로 전환
- 초기 데이터 로드만 수행

Co-Authored-By: Claude (us.anthropic.claude-sonnet-4-5-20250929-v1:0) <noreply@anthropic.com>

* feat: OpinionFormView에 SSE 통합

- gathering-full 이벤트 감지
- 모임 마감 시 자동으로 결과 페이지로 이동
- useServerSentEvent 훅 사용

Co-Authored-By: Claude (us.anthropic.claude-sonnet-4-5-20250929-v1:0) <noreply@anthropic.com>

* feat: PendingViewContainer에 SSE 통합

- participant-count 이벤트로 실시간 참여자 수 업데이트
- gathering-full 이벤트로 자동 Complete 페이지 이동
- React Query 캐시 동기화
- SSE 데이터 우선, 실패 시 초기 데이터 사용

Co-Authored-By: Claude (us.anthropic.claude-sonnet-4-5-20250929-v1:0) <noreply@anthropic.com>

* refactor: PendingViewContainer에서 불필요한 React Query 캐시 업데이트 제거

- queryClient.setQueryData 호출 제거
- useQueryClient, gatheringKeys import 제거
- SSE 데이터를 로컬 상태로만 관리하도록 단순화

Co-Authored-By: Claude (us.anthropic.claude-sonnet-4-5-20250929-v1:0) <noreply@anthropic.com>

* refactor: SSE 이벤트 핸들러에서 파싱된 데이터 직접 전달

- events 핸들러가 MessageEvent 대신 파싱된 데이터를 직접 받도록 변경
- useServerSentEvent 내부에서 JSON.parse 처리
- 각 핸들러에서 명시적으로 타입 지정 가능
- 에러 핸들링 내장

Co-Authored-By: Claude (us.anthropic.claude-sonnet-4-5-20250929-v1:0) <noreply@anthropic.com>

* refactor: SSE 이벤트 핸들러가 MessageEvent를 직접 받도록 변경

- events 핸들러가 MessageEvent를 직접 전달받음
- 사용자가 MessageEvent<T>로 타입 지정 가능
- JSON.parse는 사용자가 직접 수행
- 제네릭 제거로 더 단순하고 표준에 가까운 API

Co-Authored-By: Claude (us.anthropic.claude-sonnet-4-5-20250929-v1:0) <noreply@anthropic.com>

* refactor: SSE 타입 구조 개선

- types.ts → events.ts 리네임 (이벤트 타입임을 명확히)
- Hook Options/Return 타입은 useServerSentEvent.ts에 위치
- events.ts는 순수 이벤트 데이터 타입만 포함

Co-Authored-By: Claude (us.anthropic.claude-sonnet-4-5-20250929-v1:0) <noreply@anthropic.com>

* fix: Prettier 및 TypeScript 오류 수정

- Prettier 포맷팅 적용
- MessageEvent 타입 캐스팅 수정 (event.data를 string으로 파싱)
- useMemo 제거하여 capacity를 단순 객체로 변경

Co-Authored-By: Claude (us.anthropic.claude-sonnet-4-5-20250929-v1:0) <noreply@anthropic.com>

* refactor: SSE 재연결 문제 해결 및 Hook 개선

- useServerSentEvent 의존성 배열에서 콜백 제거하여 불필요한 재연결 방지
- useGetGatheringCapacity를 useQuery로 변경하고 enabled 옵션 추가
- reconnect, close 함수 제거로 Hook 단순화
- baseURL 처리를 Hook 내부로 이동하여 일관성 확보
- SSR 호환성을 위해 EventSource 상수 대신 숫자 리터럴 사용
- 디버깅을 위한 콘솔 로그 추가

Co-Authored-By: Claude (us.anthropic.claude-sonnet-4-5-20250929-v1:0) <noreply@anthropic.com>

* refactor: PendingViewContainer SSR 적용 및 SSE Hook 개선

- PendingViewContainer에서 초기 데이터를 서버 컴포넌트에서 가져와 props로 전달
- useGetGatheringCapacity를 useSuspenseQuery로 변경
- SSE 이벤트 핸들러를 useMemo로 최적화하여 불필요한 재생성 방지
- SSE 훅에서 이벤트 리스너 정리 로직 추가
- 불필요한 autoReconnect, reconnectInterval 옵션 제거
- console.log 정리

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* refactor: OpinionFormView SSE 이벤트 핸들러 useMemo 최적화

- eventHandlers를 useMemo로 메모이제이션하여 불필요한 재생성 방지
- accessKey와 router 변경 시에만 이벤트 핸들러 재생성
- PendingViewContainer와 동일한 최적화 패턴 적용

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* chore: prettier 포맷에 맞지 않았던 코드 수정

* feat: participantCount Event Data 에 대한 유효성 검증 및 Parsing 로직 추가:

* fix: 의견 수합 폼 내에서는 SSE 로 정원 초과 여부를 파악하지 않도록 소거

* fix: 코드 리뷰 반영하여 수정

---------

Co-authored-by: Claude (us.anthropic.claude-sonnet-4-5-20250929-v1:0) <noreply@anthropic.com>

Author: RookieAND

app/gathering/[accessKey]/opinion/pending/PendingViewContainer.tsx

@@ -1,30 +1,69 @@
 "use client";
 
-import { useEffect } from "react";
-import { useParams, redirect } from "next/navigation";
+import { useEffect, useMemo, useState } from "react";
+import { redirect } from "next/navigation";
 
 import { trackViewPage, trackShareClick } from "#/components/analytics";
 import { Button } from "#/components/button";
 import { Layout } from "#/components/layout";
+import { Toaster } from "#/components/toast";
+import { useServerSentEvent } from "#/hooks/sse";
 import {
 	PendingView,
 	SubmissionBottomSheet,
 } from "#/pageComponents/gathering/opinion";
-import { useGetGatheringCapacity } from "#/hooks/apis/gathering";
 import { share } from "#/utils/share";
-import { Toaster } from "#/components/toast";
+import { participantCountSchema } from "#/schemas/sse/participantCount.schema";
 
 const PAGE_ID = "의견수합_대기";
 
-export function PendingViewContainer() {
-	const { accessKey } = useParams<{ accessKey: string }>();
-	const { data: capacity } = useGetGatheringCapacity(accessKey);
+interface PendingViewContainerProps {
+	accessKey: string;
+	initialMaxCount: number;
+	initialCurrentCount: number;
+}
+
+export function PendingViewContainer({
+	accessKey,
+	initialMaxCount,
+	initialCurrentCount,
+}: PendingViewContainerProps) {
+	const [currentCount, setCurrentCount] =
+		useState<number>(initialCurrentCount);
+	const [maxCount, setMaxCount] = useState<number>(initialMaxCount);
 
-	const isComplete = capacity.currentCount >= capacity.maxCount;
+	const eventHandlers = useMemo(
+		() => ({
+			"participant-count": (event: MessageEvent) => {
+				const { data, success } = participantCountSchema.safeParse(
+					JSON.parse(event.data),
+				);
 
-	if (isComplete) {
-		redirect(`/gathering/${accessKey}/opinion/complete`);
-	}
+				// TODO : 응답이 유효하지 않을 경우에 대한 후속 에러 조치 시행 필요
+				if (success) {
+					setCurrentCount(data.currentCount);
+					setMaxCount(data.maxCount);
+				}
+			},
+			"gathering-full": () => {
+				redirect(`/gathering/${accessKey}/opinion/complete`);
+			},
+		}),
+		[accessKey],
+	);
+
+	useServerSentEvent({
+		url: `/gatherings/${accessKey}/subscribe`,
+		events: eventHandlers,
+	});
+
+	const capacity = useMemo(
+		() => ({
+			currentCount,
+			maxCount,
+		}),
+		[currentCount, maxCount],
+	);
 
 	const handleShare = () => {
 		trackShareClick({ page_id: PAGE_ID, share_location: "Footer" });

app/gathering/[accessKey]/opinion/pending/page.tsx

@@ -1,10 +1,4 @@
-import {
-	HydrationBoundary,
-	QueryClient,
-	dehydrate,
-} from "@tanstack/react-query";
-
-import { gatheringQueryOptions } from "#/apis/gathering";
+import { getGatheringCapacity } from "#/apis/gathering";
 import { PendingViewContainer } from "./PendingViewContainer";
 
 interface OpinionPendingPageProps {
@@ -15,19 +9,19 @@ interface OpinionPendingPageProps {
 
 /**
  * 의견 수렴 대기 페이지 (서버 컴포넌트)
- * - gathering capacity 데이터를 서버에서 prefetch하여 무한 렌더링 방지
  */
 export default async function OpinionPendingPage({
 	params,
 }: OpinionPendingPageProps) {
 	const { accessKey } = await params;
-	const queryClient = new QueryClient();
 
-	await queryClient.prefetchQuery(gatheringQueryOptions.capacity(accessKey));
+	const { data: initialCapacity } = await getGatheringCapacity(accessKey);
 
 	return (
-		<HydrationBoundary state={dehydrate(queryClient)}>
-			<PendingViewContainer />
-		</HydrationBoundary>
+		<PendingViewContainer
+			accessKey={accessKey}
+			initialMaxCount={initialCapacity.maxCount}
+			initialCurrentCount={initialCapacity.currentCount}
+		/>
 	);
 }

src/hooks/apis/gathering/useGetGatheringCapacity.ts

@@ -2,14 +2,9 @@ import { useSuspenseQuery } from "@tanstack/react-query";
 
 import { gatheringQueryOptions } from "#/apis/gathering";
 
-/**
- * 모임 참여자 현황 조회 query hook
- * - 10초마다 자동으로 refetch
- */
 export const useGetGatheringCapacity = (accessKey: string) => {
 	return useSuspenseQuery({
 		...gatheringQueryOptions.capacity(accessKey),
 		select: (response) => response.data,
-		refetchInterval: 1000 * 10,
 	});
 };

src/hooks/sse/index.ts

@@ -0,0 +1 @@
+export { useServerSentEvent } from "./useServerSentEvent";

src/hooks/sse/useServerSentEvent.ts

@@ -0,0 +1,72 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+
+export interface ServerSentEventOptions {
+	url: string;
+	enabled?: boolean;
+	withCredentials?: boolean;
+	onOpen?: () => void;
+	onError?: (error: Event) => void;
+	onMessage?: (event: MessageEvent) => void;
+	events?: Record<string, (event: MessageEvent) => void>;
+}
+
+export const useServerSentEvent = ({
+	url,
+	enabled = true,
+	withCredentials = false,
+	onOpen,
+	onError,
+	onMessage,
+	events = {},
+}: ServerSentEventOptions) => {
+	const eventSourceRef = useRef<EventSource | null>(null);
+
+	const [readyState, setReadyState] = useState<number>(0);
+
+	useEffect(() => {
+		if (!enabled) return;
+
+		const baseUrl = `${process.env.NEXT_PUBLIC_API_URL}/api/v1`;
+		const fullUrl = `${baseUrl}${url}`;
+		const eventSource = new EventSource(fullUrl, { withCredentials });
+
+		eventSourceRef.current = eventSource;
+
+		eventSource.addEventListener("open", () => {
+			setReadyState(1);
+			onOpen?.();
+		});
+
+		eventSource.addEventListener("error", (error) => {
+			setReadyState(eventSource.readyState);
+			onError?.(error);
+		});
+
+		if (onMessage) {
+			eventSource.addEventListener("message", onMessage);
+		}
+
+		Object.entries(events).forEach(([eventType, handler]) => {
+			eventSource.addEventListener(eventType, handler);
+		});
+
+		return () => {
+			Object.entries(events).forEach(([eventType, handler]) => {
+				eventSource.removeEventListener(eventType, handler);
+			});
+
+			eventSource.close();
+			eventSourceRef.current = null;
+			setReadyState(2);
+		};
+		// NOTE : events, onMessage, onOpen, onError는 의도적으로 의존성에서 제외
+		// 재연결이 필요한 경우(url, enabled, withCredentials 변경)에만 재연결
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [url, enabled, withCredentials]);
+
+	return {
+		readyState,
+	};
+};

src/pageComponents/gathering/opinion/OpinionFormView.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { useMemo } from "react";
 import { useParams, useRouter } from "next/navigation";
 import { FormProvider } from "react-hook-form";
 

src/schemas/sse/gatheringFull.schema.ts

@@ -0,0 +1,6 @@
+import z from "zod";
+
+export const gatheringFullSchema = z.object({
+	maxCount: z.number().positive(),
+	currentCount: z.number().positive(),
+});

src/schemas/sse/index.ts

@@ -0,0 +1,2 @@
+export { participantCountSchema } from "./participantCount.schema";
+export { gatheringFullSchema } from "./gatheringFull.schema";

src/schemas/sse/participantCount.schema.ts

@@ -0,0 +1,6 @@
+import z from "zod";
+
+export const participantCountSchema = z.object({
+	maxCount: z.number().positive(),
+	currentCount: z.number().positive(),
+});