feat: 실시간 페이스 코치 기능 구현

[hskhsmm]

#️⃣ 연관 이슈

ex) #150

개요

러닝 중 실시간으로 페이스를 체크하여 평균보다 느릴 때 사용자에게 알림을 제공하는 기능을 구현했습니다.

구현 목적

• 사용자가 러닝 중 페이스 조절을 할 수 있도록 실시간 피드백 제공
• 최근 5회 평균 페이스를 기준으로 현재 페이스 비교
• km 통과 시마다 자동으로 체크하여 느려진 경우에만 알림

주요 기능

• 설정 ON/OFF: 사용자가 설정에서 페이스 코치 활성화/비활성화 가능
• 실시간 체크: 러닝 중 km마다 페이스 자동 체크
• 평균 기반 판단: 최근 5회 완료된 러닝의 평균 페이스 계산
• 조건부 알림: 평균보다 느릴 때만 알림 (빠르거나 같으면 알림 없음)
• 최소 기록 요구: 5회 이상 러닝 완료 후부터 사용 가능

변경 사항

1. Entity 수정

• User.java
  • isPaceCoachEnabled 필드 추가 (Boolean, 기본값: false)
  • 사용자별 페이스 코치 설정 관리

2. DTO 수정/생성

• UserUpdateRequest.java

  • isPaceCoachEnabled 필드 추가
  • 사용자 설정 업데이트 시 페이스 코치 ON/OFF 가능

• PaceCoachCheckRequest.java (신규)

  • 러닝 중 페이스 체크 요청 DTO
  • 필드: sessionId, currentKm, currentPaceSeconds

• PaceCoachCheckResponse.java (신규)

  • 페이스 체크 결과 응답 DTO
  • 알림 필요 여부(shouldAlert), 페이스 비교 결과 포함

3. Service 구현

• PaceCoachService.java (신규)
  • 페이스 코치 핵심 로직
  • 기능:
    • 페이스 코치 활성화 여부 확인
    • 완료된 러닝 5회 이상 체크
    • 최근 5회 평균 페이스 계산
    • 현재 페이스와 비교하여 알림 필요 여부 판단
    • 페이스 포맷팅 유틸리티

4. Controller 구현

• PaceCoachController.java (신규)
  • API 엔드포인트: POST /v1/running/pace-coach/check
  • 인증된 사용자의 실시간 페이스 체크 요청 처리

🔌 API 스펙

엔드포인트

POST /v1/running/pace-coach/check

Request

{
  "session_id": "running-session-123",
  "current_km": 2,
  "current_pace_seconds": 380
}

Response (페이스 느림)

  {
    "status": "success",
    "message": "페이스 코치 체크 완료",
    "data": {
      "coach_enabled": true,
      "is_available": true,
      "should_alert": true,
      "reference_pace_seconds": 360,
      "reference_pace_formatted": "6:00/km",
      "current_pace_seconds": 380,
      "current_pace_formatted": "6:20/km",
      "difference_seconds": 20,
      "alert_message": "평균보다 20초 느려요! 조금만 더 힘내세요!"
    }
  }

Response (페이스 괜찮음)

  {
    "status": "success",
    "message": "페이스 코치 체크 완료",
    "data": {
      "coach_enabled": true,
      "is_available": true,
      "should_alert": false,
      "reference_pace_seconds": 360,
      "current_pace_seconds": 355,
      "difference_seconds": -5
    }
  }

Response (5회 미만)

  {
    "status": "success",
    "message": "페이스 코치 체크 완료",
    "data": {
      "coach_enabled": true,
      "is_available": false,
      "minimum_records_required": 5,
      "current_records": 3,
      "message": "페이스 코치는 5회 이상 러닝 후 사용 가능합니다 (현재: 3회)"
    }
  }

동작 플로우

1. 앱에서 km 통과 시 API 호출
   ↓
2. User 조회 및 isPaceCoachEnabled 확인
   ↓
3. 완료된 러닝 기록 5회 이상 확인
   ↓
4. 최근 5회 평균 페이스 계산
   ↓
5. 현재 페이스와 비교
   ↓
6. 느리면 shouldAlert: true 반환
   ↓
7. 앱에서 팝업 표시

🧪 테스트 방법

1. 페이스 코치 비활성화 테스트

User의 isPaceCoachEnabled = false 상태에서

POST /v1/running/pace-coach/check
{
"session_id": "test-session",
"current_km": 1,
"current_pace_seconds": 360
}

예상 결과: coach_enabled: false

2. 5회 미만 테스트

완료된 러닝 기록이 3회인 사용자

POST /v1/running/pace-coach/check

예상 결과: is_available: false, current_records: 3

3. 정상 작동 테스트 (느림)

완료된 러닝 5회 이상, 평균 360초/km

POST /v1/running/pace-coach/check

  {
    "session_id": "test-session",
    "current_km": 2,
    "current_pace_seconds": 380
  }

예상 결과: should_alert: true, difference_seconds: 20

4. 정상 작동 테스트 (빠름)

완료된 러닝 5회 이상, 평균 360초/km

  POST /v1/running/pace-coach/check
  {
    "session_id": "test-session",
    "current_km": 2,
    "current_pace_seconds": 350
  }

예상 결과: should_alert: false, difference_seconds: -10

📁 변경된 파일

수정

• src/main/java/com/waytoearth/entity/user/User.java
• src/main/java/com/waytoearth/dto/request/user/UserUpdateRequest.java

신규

• src/main/java/com/waytoearth/dto/request/running/PaceCoachCheckRequest.java
• src/main/java/com/waytoearth/dto/response/running/PaceCoachCheckResponse.java
• src/main/java/com/waytoearth/service/running/PaceCoachService.java
• src/main/java/com/waytoearth/controller/v1/running/PaceCoachController.java

✅ 체크리스트

• User 엔티티에 isPaceCoachEnabled 필드 추가
• UserUpdateRequest DTO 수정
• Request/Response DTO 생성
• PaceCoachService 핵심 로직 구현
• PaceCoachController API 엔드포인트 구현
• 5회 미만 비활성화 로직 작동 확인
• 평균 페이스 계산 로직 검증
• 컴파일 성공 확인
• Swagger 문서화 완료
• 프론트엔드 연동 테스트 (프론트 구현 후)
• DB 마이그레이션 스크립트 작성 (필요 시)

💡 주요 구현 포인트

1. 최소 5회 제한

• 평균 페이스의 신뢰도 확보를 위해 5회 이상 완료된 기록 필요
• 5회 미만 시 명확한 안내 메시지 제공

2. 평균 계산 방식

• 최근 5회 완료된 러닝의 averagePaceSeconds 평균 사용
• null 체크 및 0 이하 값 필터링

3. 알림 조건

• 차이 = 현재 페이스 - 평균 페이스
• 차이 > 0 (느림) → 알림
• 차이 <= 0 (빠르거나 같음) → 알림 없음

4. 페이스 포맷팅

• 초 단위를 "분:초/km" 형식으로 변환
• 예: 380초 → "6:20/km"

📌 참고사항

• AI라는 이름이 붙어있지만 실제로는 단순 계산 로직 (OpenAI 사용 안 함)
• 기존 AI 복기 기능(RunningAnalysisService)은 수정하지 않음
• 프론트엔드 구현 가이드 별도 전달 예정

🚀 배포 시 주의사항

• DB에 is_pace_coach_enabled 컬럼 추가 필요
  ALTER TABLE users ADD COLUMN is_pace_coach_enabled TINYINT(1) NOT NULL DEFAULT 0;
• 기존 사용자는 기본값 false로 시작 (사용자가 직접 ON 필요)