⚙️[기능추가][Admin] 접속·방문자 실시간 분석 #772

📝 현재 문제점

• 현재 어디에도 사용자 행동/접속 이벤트가 기록되지 않는다. admin 대시보드에서 "현재 온라인 / 오늘 방문자 / 시간별 동시접속자 추이" 같은 트래픽 지표를 전혀 볼 수 없다.
• 운영자가 서비스 사용량(피크 시간대, DAU, 유입·이탈, 기능별 사용량)을 자세히 기록·추적·관리하고 싶어도 데이터 자체가 없다.
• 통계 대시보드(🚀[기능개선][Admin] 대시보드 고도화 #714)는 PostgreSQL 기존 도메인 데이터만 다루며, 행동 분석은 신규 수집 인프라가 필요해 범위가 다르다.
• ⚠️ 가장 중요한 위험: 지표를 하나씩 그때그때 추가하는 방식으로 만들면, 나중에 새 지표("물품 상세 조회수", "검색 키워드 빈도", "특정 버튼 클릭률" 등)가 필요할 때마다 새 컬렉션/스키마/마이그레이션이 생긴다. 운영 중 스키마 변경은 사고 위험이 크다.

🛠️ 해결 방안 / 제안 기능

핵심 설계 원칙 — 지표별 테이블이 아니라 "공통 이벤트 스트림" 하나로 통합한다.
모든 사용자 행동을 단일 이벤트 스키마로 쌓고, 모든 지표(방문자/동접/조회수/클릭률 등)는 이 스트림에서 집계로 파생한다. 새 지표 추가 = 코드(집계 쿼리)만 추가, DB 스키마/마이그레이션 변경 없음. MongoDB의 schemaless·Time Series 특성을 그대로 활용한다.

1. 공통 이벤트 스키마 (UserActivityEvent, MongoDB Time Series)

고정 공통 필드 + 자유 확장 필드(properties)로 구성. 모든 이벤트가 같은 컬렉션에 쌓인다.

공통 필드 (모든 이벤트 공유):
  eventId        UUID
  eventType      String   // "PAGE_VIEW", "API_CALL", "SESSION_START", "SESSION_END",
                          //  "ITEM_VIEW", "SEARCH", "TRADE_CREATED" ... (enum 확장만 하면 됨)
  eventCategory  String   // "TRAFFIC" | "ENGAGEMENT" | "TRANSACTION" ... (대분류, 집계 그룹핑용)
  memberId       UUID?    // 비로그인은 null
  anonymousId    String?  // 비로그인 식별(쿠키/디바이스)
  sessionId      String?  // 동접/세션 집계용
  path           String?
  ip             String?
  userAgent      String?
  platform       String?  // AOS / iOS / WEB
  occurredAt     Instant  // Time Series timeField

확장 필드 (이벤트별 자유):
  properties     Map<String,Object>  // ex) {"itemId":"...", "keyword":"닌텐도", "price":50000}

→ 새 이벤트 종류는 eventType enum에 값 하나 추가하고 properties에 필요한 키를 담으면 끝. 컬렉션/인덱스/마이그레이션 불변.

2. 수집 지점 (공통 진입점으로 일원화)

지표마다 수집 코드를 흩뿌리지 않고, 단일 기록 진입점(ActivityEventRecorder)을 두고 모든 수집 지점이 그것만 호출한다.

3. 집계 (파생)

• 실시간: Redis online set (현재 온라인) — 누적 DB 아님, 정확.
• 일·시간별: MongoDB Aggregation + (선택) 롤업 컬렉션으로 사전 집계해 차트 쿼리 비용 절감.
• 모든 집계는 eventType/eventCategory/기간으로 그룹핑 → 새 지표도 같은 패턴 재사용.

4. 설계 원칙 (운영 안정성)

• 적재는 반드시 비동기(@Async/이벤트/큐) — 요청 지연 방지, 유실 시 본 요청 영향 없음.
• MongoDB Time Series Collection(5.0+) + TTL 인덱스 — 원본 raw 이벤트는 N일 자동 만료, 롤업은 장기 보존.
• 차트: ApexCharts (시계열·실시간·줌·툴팁 내장, Tailwind/daisyUI 색 통일). daisyUI엔 차트 컴포넌트 없음(stat/radial-progress뿐) — 추이 그래프엔 부적합.
• 개인정보/보안: IP·UA 보관 정책, MongoDB 보안 강화 이슈(🔥❗[긴급][버그][보안] MongoDB 랜섬웨어 공격으로 데이터 삭제 및 보안 강화 필요 #672)와 정합성 확인.

⚙️ 작업 내용

공통 수집 인프라 (이 이슈의 본체)

• UserActivityEvent 문서 정의 (공통 필드 + properties Map) — MongoDB Time Series Collection 생성, timeField=occurredAt, TTL 인덱스
• EventType / EventCategory enum 정의 (확장 가능하도록 분류 체계 설계)
• ActivityEventRecorder 단일 기록 진입점 (비동기 적재) — 모든 수집 지점이 이것만 호출
• 비동기 처리 구성(@Async 풀 또는 이벤트 발행) + 화이트리스트(정적/헬스체크/admin 자체 호출 제외)
• (선택) 롤업 컬렉션 + 사전 집계 스케줄러

수집 지점 연결

• HandlerInterceptor — PAGE_VIEW/API_CALL 기록
• WebSocket connect/disconnect — SESSION_START/SESSION_END + Redis online set(TTL stale 정리)
• 동접 스냅샷 스케줄러 — N분 주기 현재 온라인 수 적재

집계 / API

• AdminAnalyticsService 신규 (RomRom-Application/service)
• API (admin 컨벤션: POST + multipart + @ModelAttribute, 별도 DTO 금지):
  • POST /api/admin/analytics/realtime — 현재 온라인 / 오늘 UV·PV / 신규가입·신규거래
  • POST /api/admin/analytics/timeseries — eventType(or eventCategory) + 기간 + 버킷단위(시간/일) 범용 시계열. 새 지표가 추가돼도 이 API 하나로 커버 (파라미터만 다름)
• AdminRequest/AdminResponse 필드 추가
• AdminAnalyticsControllerDocs + @ApiChangeLog 최상단 추가

Frontend

• ApexCharts 도입 (admin layout)
• 실시간 카드: 🟢현재 온라인 / 오늘 방문자 / 신규가입 / 신규거래
• 시간별 동시접속자 추이 차트 + 일별 방문자 추이 차트(기간 필터 연동)
• 현재 온라인 폴링(or SSE) 갱신

검증 / 성능

• 적재 비동기화가 API 레이턴시에 주는 영향 측정
• Time Series TTL 만료 + 롤업 보존 동작 확인
• 확장성 검증: 새 eventType 1개 추가 시 DB 마이그레이션 없이 timeseries API로 즉시 집계되는지 확인 (설계 목표 충족 여부)
• Redis online set vs 스냅샷 정확도 검증
• 부하 시 적재 유실/백프레셔 점검

관련 이슈

• 부모 Epic: 🚀[기능개선][Admin] 관리자 페이지 전면 개편 (Epic) #707
• 연계: 🚀[기능개선][Admin] 대시보드 고도화 #714 (대시보드에 실시간 카드/차트 함께 배치)
• 보안: 🔥❗[긴급][버그][보안] MongoDB 랜섬웨어 공격으로 데이터 삭제 및 보안 강화 필요 #672 (MongoDB 보안 강화) 정책 충돌 여부 확인

🙋‍♂️ 담당자

• 백엔드: SUH SAECHAN
• 프론트엔드: 미정
• 디자인: 미정