📌“진도율 로직은 결국 상태 머신이다 – ProgressService 설계기”

🗓 2025년 4월

✍️ by 박찬희

---

🧭 문제 정의: 단순한 퍼센트가 아닌, 학습 상태의 흐름

사용자의 콘텐츠 학습 진행 상황을 “숫자 하나(%)”로 표현하는 건 쉬워 보이지만,

이를 신뢰할 수 있게 저장하고, 수료 조건에 따라 상태를 정확히 전환하는 건 작지 않은 일이다.

이번 모듈의 목표는 단순한 progressPercent 저장이 아니라,

정확한 상태 전이(진도율 → 수료)까지 책임지는 “학습 상태 머신”을 설계하는 데 있었다.

---

🎯 설계 목표: 진도율 저장 + 수료 자동화 + 퍼포먼스 최적화

항목	전략
💡 단일 진입점	모든 로직을 saveOrUpdateProgress()에 집중
📊 수료 상태 자동화	전체 콘텐츠 완료 시 수료 처리
💾 DB 부하 최소화	불필요한 업데이트 제거 (WHERE progress < newValue)
🧪 테스트 가능성	JUnit 기반 단위 테스트 구조로 설계
🔁 확장성	Redis/Kafka 기반 확장 여지 확보

---

🧱 전체 구조 흐름

[사용자 콘텐츠 재생]
      ↓
[ProgressService.saveOrUpdateProgress()]
      ├── 기존 진도 < 신규 진도일 경우만 upsert
      ├── lectureId 역추적 (contentId → lectureId)
      └── 잔여 미완료 콘텐츠 수 = 0 → 수료 처리(markEnrollmentComplete)

---

🔧 핵심 로직 상세

1️⃣ 진도율 저장 - Upsert 최적화

mapper.upsertProgress(userId, contentId, progressPercent);

• 기존 진도율보다 높은 경우에만 갱신 → 의미 없는 UPDATE 방지
• DB 쿼리에서 자체 비교 조건 포함:

UPDATE user_progress
SET progress_percent = #{progressPercent}
WHERE content_id = #{contentId} AND user_id = #{userId} AND progress_percent < #{progressPercent}

✅ DB 부하를 최소화하고, 네트워크 대역도 줄여줌

---

2️⃣ 수료 상태 자동화 – 정확하고 명확하게

int remaining = mapper.countIncompleteContents(userId, lectureId);

if (remaining == 0) {
  mapper.markEnrollmentComplete(userId, lectureId);
}

• lectureId는 contentId로부터 역추적
• 남은 콘텐츠가 0 → 수료 상태로 전이

📌 실무에서는 “하나라도 완료 안 된 콘텐츠가 있으면 수료 X”가 매우 중요

→ 사용자의 신뢰와 보상 체계를 지키는 기반이 된다.

---

3️⃣ 진도율 조회 – Map 기반 구조

Map<Integer, Integer> getProgressMap(userId, lectureId);

• 프론트(JSP, React 등)에서 contentId → percent 매핑이 바로 가능
• 반복 렌더링에 직관적이며, 추가 필드 확장에도 유리

✅ 실시간 진도율 UI 구성에 이상적인 구조

---

⚙️ 트랜잭션 & 예외 처리 전략

try (SqlSession session = MyBatisUtil.getSqlSessionFactory().openSession()) {
  ...
  throw new RuntimeException("❌ 진도율 저장 또는 수료 상태 처리 중 오류", e);
}

• try-with-resources로 SqlSession 누수 방지
• 모든 흐름 중 하나라도 실패 시 전체 예외 → 불완전한 상태 저장 방지
• 명확한 메시지로 모니터링/로깅 대응 가능

---

📉 성능 고려 및 확장 전략

전략	설명
불필요 UPDATE 방지	progress < newValue 조건 적용
수료 검증 최소화	남은 콘텐츠 수만 체크 (countIncompleteContents)
비동기화 확장	추후 @Async, Kafka로 처리 분리 가능
캐싱 고려	Redis 기반 진도율 캐시 (대형 강의 대응)
배치 처리	반복적인 progress → complete 전환 시 Batching 고려 가능

---

🧪 단위 테스트 고려 구조

• Service와 DAO 분리 구조

• saveOrUpdateProgress()는 비즈니스 로직을 그대로 담고 있어

  → 단위 테스트로 로직 흐름 검증 가능

예:

@Test
void whenAllContentsComplete_thenLectureMarkedAsComplete() {
  // given: 모든 콘텐츠 완료된 상태
  // when: 마지막 progress 저장
  // then: 수료 처리 확인
}

---

🧠 시니어 리뷰 피드백 (실제 코드 리뷰 요약)

평가 항목	리뷰
✅ 유지보수성	“모든 로직이 Service에 집중되어 있어 추적과 변경이 용이하다”
✅ 도메인 연계성	“교육 서비스 도메인에 맞는 수료 전이 구조가 설계에 녹아 있다”
✅ DB 전략	“불필요한 update가 차단된 점이 매우 좋다”
🔜 확장성	“멀티 모듈 강의, 출석 기반 학습에도 대응 가능할 구조”

---

📌 향후 확장 계획

• Redis 캐시로 진도율 Map을 캐싱하여 대형 강의 대응
• Kafka 기반 이벤트 처리로 수료 로직 비동기 전환
• 사용자 행동 로그 테이블 구축 → 학습 분석/추천 기반 사용

---

✅ 요약

기능	설명
진도율 저장	upsert (기존 값보다 클 때만 저장)
수료 처리	모든 콘텐츠 완료 시 자동 전이
진도율 조회	Map<contentId, percent> 반환 구조
트랜잭션	실패 시 전체 롤백, 자원 누수 방지
테스트성	단위 테스트로 모든 로직 흐름 확인 가능

---

🧾 회고

이번 ProgressService는 단순 저장이 아닌,

학습 상태를 제어하는 핵심 상태 머신으로 작동하게 설계했다.

• 유저에게는 정확한 수료 경험을,
• 시스템에게는 확장성과 예외 안정성을,
• 개발자에게는 테스트 가능한 구조와 유지보수성을 제공하는

탄탄한 도메인 중심 모듈이 되었다.