KPI 대시보드 구현 및 버그 수정

[sgo722]

📋 요약

이번 릴리즈는 관리자용 KPI 대시보드를 처음부터 완전히 구현하고, 데이터 정확성 및 성능을 개선했습니다. 총 35개의 커밋이 포함되어 있으며, 주요 기능 추가와 버그 수정이 이루어졌습니다.

---

🎯 주요 변경사항

📊 1. KPI 대시보드 구현 (22개 커밋)

Phase 1: 기본 인프라 구축

• DB 마이그레이션 (V18)

  • daily_kpi 테이블 생성 (시그널, 채팅, 질문, 코드해제, 종료 KPI)
  • chat_room_question.is_initial 필드 추가 (초기 질문 구분)

• 도메인 레이어

  • DailyKpi 엔티티 구현
  • KPI 계산 메서드 (시그널 수락률, 채팅 활성률 등)

• 인프라 레이어

  • DailyKpiJpaRepository, KpiChatRepository, KpiSignalRepository 구현
  • 날짜 기반 KPI 조회 쿼리 메서드

Phase 2: 배치 집계 시스템

• KpiBatchService: 5개 카테고리 KPI 집계 로직

  • 시그널 KPI (보낸 수, 수락 수, 수락률)
  • 채팅 KPI (열린 채팅방, 활성 채팅방, 활성률, 메시지 수 등)
  • 질문추천 KPI (클릭 수, 사용 채팅방, 비교 지표)
  • 코드해제 KPI (요청 수, 승인 수, 승인률)
  • 종료 KPI (종료 채팅방 수, 평균 지속 기간)

• KpiScheduler: 매일 새벽 1시 자동 집계

• 초기 질문 구분 로직

  • 채팅방 생성일 기준 질문 사용 여부 판단
  • QuestionService, ChatService 수정

Phase 3: API 및 프론트엔드

• KpiController: 6개 엔드포인트

  • GET /v1/admin/kpi - 대시보드 페이지
  • GET /v1/admin/kpi/summary - 기간별 KPI 요약
  • GET /v1/admin/kpi/all - 전체 KPI 목록
  • POST /v1/admin/kpi/aggregate - 단일 날짜 수동 집계
  • GET /v1/admin/kpi/question-insights - 질문 인사이트
  • GET /v1/admin/kpi/chatroom-statistics - 실시간 채팅방 통계

• 프론트엔드 구현

  • Thymeleaf 템플릿 기반 대시보드
  • Chart.js 그래프 시각화
  • 기간 필터링 UI (오늘, 7일, 30일, 커스텀)
  • 사이드바 공통화 (Thymeleaf fragment)

---

🐛 2. 데이터 정확성 개선 (5개 커밋)

• 시그널 수락률 개선

  • 문제: acceptedAt 기준으로 수락률 계산 → 타임존 불일치
  • 해결: createdAt 기준으로 변경, 정확한 수락률 산출

• 질문 인사이트 데이터 소스 변경

  • 문제: Profile 기반 → 프로필만 설정하고 실제 사용 안 한 질문도 포함
  • 해결: ChatRoomQuestion 기반 → 실제 채팅에서 사용된 질문만 집계

• 질문 추천 KPI 버그 수정

  • 문제: 질문 사용 여부 판단 로직 오류
  • 해결: 채팅방 생성일 기준 isInitial 판단 개선

• KPI 대시보드 날짜별 데이터 반영

  • 문제: 채팅 KPI와 질문 인사이트가 기간 선택에 반응하지 않음
  • 해결: API에 날짜 파라미터 전달, 실시간 채팅방 통계 API 추가

• 질문 카테고리 쿼리 수정

  • 문제: 카테고리 통계 조회 오류
  • 해결: 쿼리 메서드 수정

---

⚡ 3. 성능 및 로직 최적화 (6개 커밋)

• 채팅방 집계 로직 개선

  • 문제: 활성 채팅방이 전체 채팅방(58개)을 초과하여 248개 표시
  • 원인: 일별 활성 채팅방 수를 합산하면서 중복 카운팅
  • 해결 (V19 마이그레이션):
    • current_open_chatrooms_count 필드 추가 (endDate 스냅샷)
    • 활성 채팅방을 단일 시점 조회로 변경
    • 채팅방 활성률 분모 변경: 활성 / 현재 열린 채팅방

• KPI 쿼리 최적화

  • 활성 채팅방 카운트 쿼리: 서브쿼리 제거, updated_at 직접 사용
  • 그래프 날짜 정렬: DESC → ASC (좌측부터 과거 → 최신)

• KPI 요약 조회 개선

  • currentOpenChatroomsSum, activeChatroomsSum을 기간별 합계에서 endDate 스 냅샷으로 변경
  • 중복 카운팅 방지

• 스케줄러 최적화

  • 서버 시작 시 60일 자동 집계 제거
  • 매일 새벽 1시 스케줄러만 유지
  • 서버 시작 시간 단축

---

🔧 4. 대량 집계 기능 (2개 커밋)

• API 구현

  • 엔드포인트: POST /v1/admin/kpi/aggregate-range
  • 기능: startDate ~ endDate 기간 일괄 집계
  • 응답: 각 날짜별 성공/실패 통계, 상세 오류 정보

• UI 구현

  • KPI 대시보드에 "대량 집계" 버튼 추가
  • 모달 창: 기간 선택 UI
  • 집계 진행 상태 표시 (로딩 스피너)
  • 성공 시 자동 대시보드 새로고침
  • 실패 시 상세 오류 정보 표시

---

🔔 5. 알림 개선 (1개 커밋)

• 코드 해제 요청 알림 본문 제거
  • 문제: 알림에 제목과 본문이 함께 전송되어 불필요한 정보 노출
  • 해결: ChatService.sendCodeUnlockNotification() 함수의 body 필드를 빈 문자열로 변경
  • 효과: 알림의 간결성 향상, 제목만 표시

---

🐞 6. 기타 버그 수정

• 하위버전 재심사 시 상태 변경 이슈 수정

  • 하위버전 재심사 시 상태가 PENDING으로 정상 변경되도록 수정

• 하위버전 알림 개선

  • 하위버전 관련 알림이 정상적으로 발송되도록 수정

• 히든이미지 저장 이슈 수정

  • 히든이미지 저장 시 필드값이 DB에 반영되지 않던 문제 해결
  • 히든이미지 제출 시 상태가 PENDING으로 변경되도록 수정

---

🛠 기술 스택

• Backend: Kotlin, Spring Boot, JPA, Flyway
• Frontend: Thymeleaf, Chart.js, Vanilla JavaScript
• Database: MySQL (2개 마이그레이션 추가: V18, V19)

---

📦 영향 범위

Database

• ✅ daily_kpi 테이블 생성
• ✅ chat_room_question.is_initial 필드 추가
• ✅ daily_kpi.current_open_chatrooms_count 필드 추가

Backend

• ✅ KPI 패키지 전체 신규 추가
• ✅ 기존 서비스: QuestionService, ChatService, ChatRoomService 일부 수정

Frontend

• ✅ KPI 대시보드 페이지 신규 추가
• ✅ 관리자 네비게이션 사이드바 공통화

---

✅ 테스트 체크리스트

• V18, V19 마이그레이션 정상 적용
• 매일 새벽 1시 자동 집계 동작 확인
• 대시보드 기간 필터링 동작 확인
• 활성 채팅방 수 정상화 (0-58 범위)
• 대량 집계 API 동작 확인
• 질문 인사이트 실제 데이터 반영 확인
• 그래프 날짜 정렬 확인 (과거 → 최신)
• 코드 해제 알림 본문 제거 확인

---

📊 주요 커밋 히스토리

KPI 대시보드 (22개)

c9b333f - KPI 대시보드 DB 마이그레이션
7b7e07e - KPI 도메인 레이어 구현
97e56e9 - KPI 인프라 레이어 구현
dc3fc0d - 초기 질문 구분 로직 구현
e2720a0 - KPI 배치 서비스 구현
56bbb92 - KPI 배치 스케줄러 구현
e9fcd3b - KPI API 구현
20cd4ca - KPI 대시보드 프론트엔드 구현
b03788c - KPI 대시보드 네비게이션 추가
1ea1673 - 사이드바 중복 코드 제거
c57cfd3 - KPI 대시보드 실제 API 연동
bd68404 - KPI 자동 집계 기능 추가
fdfe8e7 - KPI 대시보드 12개 이슈 수정
231e068 - 질문 추천 KPI 수집 로직 버그 수정
e72d8d4 - 질문 인사이트 데이터 소스 변경
b6e0838 - 시그널 수락률 및 채팅방 통계 개선
8616b08 - KPI 대시보드 날짜별 데이터 반영 개선
f0f6dcb - KPI 쿼리 및 그래프 정렬 최적화
866f490 - KPI 채팅방 집계 로직 개선
1cbb2e9 - KPI 요약 조회 채팅방 수 계산 개선
9bf99ce - KPI 서버 시작 시 자동 집계 제거
fc6eac2 - KPI 대량 수동 집계 API 추가
947af06 - KPI 대시보드에 대량 집계 UI 추가

버그 수정 및 개선 (13개)

c09831c - Merge pull request #376 from CODE-LG/bug/#375
5fff556 - [bug] 히든이미지 저장 시 필드값 저장이 DB반영이 안되던 문제 수정
023738a - [hotfix] 하위버전 재심사 시 PENDING으로 상태 변경
81178ca - Merge pull request #372 from CODE-LG/feature/#370
eca1200 - [feat] 하위버전 알람가도록 수정, 히든이미지 제출 시 PENDING바뀌도록 수 정
8e04497 - [feat] 코드 해제 요청 알림 본문 제거

---

🔗 관련 이슈 및 PR

• Closes [refactor] 앱 버전별 히든 프로필 제출 로직 분리 (Strategy Pattern) #370 - 하위버전 알림 개선
• Closes [BUG] 히든 이미지 제출 시 회원 상태가 DB에 반영되지 않는 문제 #375 - 히든이미지 저장 이슈
• Closes 코드 해제 요청 알림 본문 제거 #381 - 코드 해제 요청 알림 본문 제거

---

🚀 배포 노트

배포 전 체크사항

1. DB 마이그레이션 V18, V19 적용 확인
2. 환경 변수 설정 확인
3. 서버 재시작 후 KPI 스케줄러 동작 확인

배포 후 모니터링

1. KPI 대시보드 접근 확인 (/v1/admin/kpi)
2. 새벽 1시 자동 집계 로그 확인
3. 알림 발송 정상 동작 확인