Feature/#379 KPI 대시보드 구현 및 집계 로직 전면 개선

[sgo722]

요약

KPI 대시보드를 처음부터 완전히 구현하고, 데이터 정확성 및 성능을 개선했습니다.

주요 구현 내용

📊 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개 엔드포인트

  • /v1/admin/kpi: 대시보드 페이지
  • /v1/admin/kpi/summary: 기간별 KPI 요약
  • /v1/admin/kpi/all: 전체 KPI 목록
  • /v1/admin/kpi/aggregate: 단일 날짜 수동 집계
  • /v1/admin/kpi/question-insights: 질문 인사이트
  • /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
• 집계 진행 상태 표시 (로딩 스피너)
• 성공 시 자동 대시보드 새로고침
• 실패 시 상세 오류 정보 표시

기술 스택

• 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 패키지 전체 신규 추가
• ✅ Frontend: KPI 대시보드 페이지 신규 추가
• ✅ 기존 서비스: QuestionService, ChatService 일부 수정

테스트 체크리스트

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

스크린샷

(대시보드 UI 스크린샷 첨부)

관련 이슈

Closes #381

---

커밋 히스토리 (22개)

Phase 1: 기본 인프라 (7개)

1. c9b333f - KPI 대시보드 DB 마이그레이션
2. 7b7e07e - KPI 도메인 레이어 구현
3. 97e56e9 - KPI 인프라 레이어 구현
4. dc3fc0d - 초기 질문 구분 로직 구현
5. e2720a0 - KPI 배치 서비스 구현
6. 56bbb92 - KPI 배치 스케줄러 구현
7. e9fcd3b - KPI API 구현

Phase 2: 프론트엔드 (4개)

8. 20cd4ca - KPI 대시보드 프론트엔드 구현
9. b03788c - KPI 대시보드 네비게이션 추가
10. 1ea1673 - 사이드바 중복 코드 제거
11. c57cfd3 - KPI 대시보드 실제 API 연동

Phase 3: 초기 버그 수정 (5개)

12. bd68404 - KPI 자동 집계 기능 추가
13. fdfe8e7 - KPI 대시보드 12개 이슈 수정
14. 231e068 - 질문 추천 KPI 수집 로직 버그 수정
15. e72d8d4 - 질문 인사이트 데이터 소스 변경
16. b6e0838 - 시그널 수락률 및 채팅방 통계 개선

Phase 4: 추가 개선 (1개)

17. 8616b08 - KPI 대시보드 날짜별 데이터 반영 개선

Phase 5: 성능 최적화 및 대량 집계 (6개)

18. f0f6dcb - KPI 쿼리 및 그래프 정렬 최적화
19. 866f490 - KPI 채팅방 집계 로직 개선
20. 1cbb2e9 - KPI 요약 조회 채팅방 수 계산 개선
21. 9bf99ce - KPI 서버 시작 시 자동 집계 제거
22. fc6eac2 - KPI 대량 수동 집계 API 추가
23. 947af06 - KPI 대시보드에 대량 집계 UI 추가