운동 목표 설정 기능 (FitnessGoal)

개요

사용자의 체중 관리 목표(감량/증가/유지)를 설정하고 추적할 수 있는 기능입니다. 일별 체중 기록을 통해 목표 달성률을 자동으로 계산하고, 목표 달성 시 자동 완료 처리됩니다.

주요 기능

• 목표 관리: 생성, 수정, 조회, 삭제, 취소
• 체중 기록: 일별 체중 기록 및 메모 관리
• 진행률 추적: 실시간 달성률 계산 및 상태 관리
• 자동화: 만료된 목표 자동 상태 업데이트

목표 타입 및 달성 조건

목표 타입	설명	달성 조건	단위
WEIGHT_LOSS	체중 감량	현재 체중 ≤ 목표 체중	kg
WEIGHT_GAIN	체중 증가	현재 체중 ≥ 목표 체중	kg
WEIGHT_MAINTAIN	체중 유지	목표 체중 ±1kg 범위 내에 있는 경우	kg

목표 상태

상태	설명	비고
ACTIVE	진행중	수정/취소 가능
COMPLETED	목표달성	수정/취소/삭제 불가
EXPIRED	기간만료	종료일 경과 시 자동 변경
CANCELLED	취소됨	사용자가 직접 취소

권한 승급 프로세스

목표 생성 → 체중 기록 → 진행률 자동 계산 → 달성 시 자동 완료 → 만료일 경과 시 자동 만료

목표 관리

목표 생성 필수 정보

• 목표 제목 (필수)
• 목표 타입 (WEIGHT_LOSS/WEIGHT_GAIN/WEIGHT_MAINTAIN)
• 시작 체중, 목표 체중 (양수)
• 시작일, 종료일

목표 생성 프로세스

• 입력 데이터 유효성 검증
• 목표 타입별 로직 검증
• 상태 자동 초기화 (ACTIVE/EXPIRED)
• 진행률 초기값 설정 (0%)

목표 수정

수정 가능한 정보

• 목표 제목, 설명
• 목표 체중
• 종료일

수정 제한사항

• COMPLETED 상태: 수정 불가
• CANCELLED 상태: 수정 불가
• 시작 체중, 목표 타입: 수정 불가 (데이터 일관성)

체중 기록 관리

체중 기록 생성 필수 정보

• 체중 (양수)
• 기록일
• 메모 (선택사항)

체중 기록 프로세스

• 체중 데이터 유효성 검증
• 목표의 현재 체중 업데이트
• 달성 조건 자동 체크
• 진행률 재계산
• 달성 시 COMPLETED 상태 변경

자동 달성 처리

• 감량 목표: 현재 체중 ≤ 목표 체중
• 증량 목표: 현재 체중 ≥ 목표 체중
• 유지 목표: |현재 체중 - 목표 체중| ≤ 1kg

진행률 계산 시스템

감량 목표 (WEIGHT_LOSS)

진행률 = min((시작체중 - 현재체중) / (시작체중 - 목표체중) × 100, 100)

증량 목표 (WEIGHT_GAIN)

진행률 = min((현재체중 - 시작체중) / (목표체중 - 시작체중) × 100, 100)

유지 목표 (WEIGHT_MAINTAIN)

차이 = |현재체중 - 목표체중| 진행률 = 차이 ≤ 1kg ? 100 : max(0, 100 - (차이 × 10))

스케줄러 자동화

• 실행 시간: 매일 자정 (0 0 0 * * *)
• 처리 내용: ACTIVE 상태의 만료된 목표를 EXPIRED로 자동 변경
• 로그 관리: 성공/실패 로그 기록

API 명세

목표 관리

Method	Endpoint	설명	권한
POST	/fitness-goals	목표 생성	USER+
GET	/fitness-goals	내 목표 목록 조회	USER+
GET	/fitness-goals/{id}	목표 상세 조회	USER+
PUT	/fitness-goals/{id}	목표 수정	USER+
PATCH	/fitness-goals/{id}/cancel	목표 취소	USER+
DELETE	/fitness-goals/{id}	목표 삭제	USER+

체중 기록 관리

Method	Endpoint	설명	권한
POST	/fitness-goals/{id}/weight-records	체중 기록 생성	USER+
GET	/fitness-goals/{id}/weight-records	체중 기록 목록 조회	USER+
PUT	/weight-records/{id}	체중 기록 수정	USER+
DELETE	/weight-records/{id}	체중 기록 삭제	USER+

요청/응답 예시

목표 생성 요청

{
  "title": "여름 다이어트",
  "description": "건강한 여름을 위한 체중 감량",
  "goalType": "WEIGHT_LOSS",
  "startWeight": 70.5,
  "targetWeight": 65.0,
  "startDate": "2024-06-01",
  "endDate": "2024-08-31"
}

목표 생성 응답

{
  "statusCode": 201,
  "message": "목표가 성공적으로 생성되었습니다.",
  "data": {
    "id": 1,
    "title": "여름 다이어트",
    "goalType": "WEIGHT_LOSS",
    "goalStatus": "ACTIVE",
    "startWeight": 70.5,
    "targetWeight": 65.0,
    "currentWeight": null,
    "progressRate": 0.0,
    "startDate": "2024-06-01",
    "endDate": "2024-08-31",
    "createdAt": "2024-06-01T10:30:00"
  }
}

비즈니스 규칙

목표 생성 제한

• 사용자당 동시 활성 목표: 제한 없음
• 종료일은 시작일 이후여야 함
• 체중은 양수여야 함

목표 수정 제한

• 수정 가능: ACTIVE, EXPIRED 상태
• 수정 불가: COMPLETED (달성 기록 보존), CANCELLED
• 수정 항목: 제목, 설명, 목표 체중, 종료일

목표 삭제 제한

• 삭제 가능: ACTIVE, EXPIRED, CANCELLED
• 삭제 불가: COMPLETED (성취 기록 보존)

체중 기록 규칙

• 목표당 일일 1회 기록 권장
• 기록 시 목표의 현재 체중 자동 업데이트
• 달성 조건 충족 시 자동 완료 처리