← 프로젝트 목록
AI · Healthcare

CareNote

2025.12 - 현재·FE 1 · BE 1

음성 기반 간호 진술문 요약 서비스. 예약 크레딧과 멱등성으로 과금 정합성을 확보하고, 외부 API 호출량과 Kafka 처리·종료 경계를 관리했습니다.

주요 구현 기능

  • Spring Boot 3.3 + Java 17 기반 인증·채널·크레딧·병원·구독 관리 REST API 32개 엔드포인트 설계·구현
  • Clova Speech 전사 → Gemini 정제·요약을 Kafka 토픽(transcription · refinement · summary) 단위로 분리한 비동기 파이프라인 구축
  • 단계별 실패를 DLT(Dead Letter Topic)로 격리하고, 사용자 재처리 요청 시 실패 단계부터 재개해 불필요한 AI 호출 방지
  • 채널 상태를 13단계로 세분화하고, 30분 이상 정체된 채널을 10분 주기 스케줄러가 감지해 Kafka 이벤트 재발행
  • JWT Access/Refresh/Temp 3종 토큰 + OAuth(Kakao/Apple) 인증 체계, 내부 연동 API는 X-Internal-Token으로 별도 보호
  • 개인·병원 크레딧 지갑 2종과 구독 플랜 월별 리셋(compare-and-set)으로 멀티 테넌트 과금 모델 구현

성과

  • reserved_credit · SELECT FOR UPDATE · referenceId 멱등키로 동시 요청 환경의 중복 차감과 잔액 불일치 방지 (k6 35건 시나리오에서 중복 요청·초과 과금 0건)
  • 세마포어와 큐로 외부 STT API 동시 호출을 상한 안에서 소비하도록 유입량과 실행량을 분리
  • 처리 완료 기준 오프셋 커밋 + commit lock + Graceful shutdown으로 재시작·배포 시 메시지 유실과 중복 처리를 동시에 방지
  • 계정·채널 삭제 시 DB와 S3 정리를 함께 처리하고, 외부 스토리지 실패는 경고 로그로 격리해 핵심 트랜잭션 보호

트러블슈팅

CASE 01

예약 크레딧으로 동시 요청 과금 정합성 확보

잔액 검증과 예약을 원자적으로 처리하고, 멱등키로 중복 차감을 방지

문제 상황

AI 작업이 끝난 뒤 크레딧을 차감하는 후차감 정책을 사용했습니다. 동시에 들어온 요청이 같은 잔액으로 사전 검증을 통과하면, 먼저 완료된 요청의 차감으로 나머지 작업이 최종 과금 단계에서 실패했습니다.

원인 분석

잔액 확인과 사용 예정 금액의 예약이 하나의 원자적 작업으로 묶이지 않았습니다. 처리 중인 요청의 크레딧을 고려하더라도, 동시 검증 사이의 경쟁 조건을 막지 못했습니다.

해결 설계

  1. 01 예약 크레딧 도입reserved_credit에 사용 예정 금액을 반영해 가용 잔액을 계산했습니다.
  2. 02 지갑 행 잠금SELECT … FOR UPDATE로 검증·예약 구간을 직렬화해 동시 갱신 충돌을 방지했습니다.
  3. 03 멱등성 확보referenceId를 확인해 동일 요청의 재처리와 중복 차감을 차단했습니다.
예약 크레딧으로 동시 요청 과금 정합성 확보 해결 설계 다이어그램

결과와 검증

35건 → 25건 처리

사전 거절과 처리 실패를 구분

  • k6: 5건씩 10초 간격으로 7회 요청
  • 25건 처리 완료 · 10건 사전 검증에서 거절
  • 해당 테스트에서 검증 통과 후 AI 처리 실패 0건
  • 해당 테스트에서 중복 요청·초과 과금 0건
예약 크레딧으로 동시 요청 과금 정합성 확보 결과 다이어그램

검증 단계의 거절과 AI 처리 단계의 실패를 분리해 결과를 평가했습니다.

CASE 02

외부 API 호출량 제어로 비동기 처리 병목 완화

큐와 세마포어로 유입량과 동시 실행량을 분리

문제 상황

Clova Speech 전사와 Gemini 정제·요약 요청을 비동기로 처리했습니다. 요청이 몰리면 처리 시간이 길어지고, 대기 작업과 재시도가 함께 누적되는 병목이 발생했습니다.

원인 분석

내부 작업 생성량과 외부 API의 처리 용량을 함께 제어하지 않았습니다. 비동기 실행만 늘리는 방식으로는 외부 호출 제한과 네트워크 대기를 해소할 수 없었습니다.

해결 설계

  1. 01 동시 실행 상한세마포어로 STT 동시 호출을 제한했습니다. 설정값은 API 계약·운영 환경에 맞춰 관리합니다.
  2. 02 큐 기반 처리초과 요청을 큐에 대기시키고 워커가 소비하도록 유입량과 실행량을 분리했습니다.
  3. 03 재시도 간격 조정제한 응답과 일시적 오류에 지수 백오프를 적용해 재시도 집중을 완화했습니다.
외부 API 호출량 제어로 비동기 처리 병목 완화 해결 설계 다이어그램

결과와 검증

유입과 실행을 분리

호출 제한을 반영한 처리 구조

  • 초과 요청은 대기하고, 실행 중인 API 호출 수는 제한
  • 요청 급증을 큐에서 흡수해 외부 API 보호
  • Kafka 워커 구조로 처리 단계별 확장 경로 확보
외부 API 호출량 제어로 비동기 처리 병목 완화 결과 다이어그램

운영 기준: 동시성 상한은 외부 API 계약과 전체 워커 수를 고려해 조정해야 합니다.

CASE 03

처리 완료 기준 커밋과 안전한 워커 종료

비동기 완료 순서와 Kafka 재시작 위치를 일치시키는 설계

문제 상황

Kafka 기반 비동기 파이프라인에서도 일부 요청이 간헐적으로 누락되거나 중단됐습니다. 병렬 작업의 완료 순서가 뒤바뀌는 상황과, 처리 중 배포·종료되는 상황을 함께 다뤄야 했습니다.

원인 분석

같은 파티션에서 앞선 메시지가 미완료인데 더 뒤의 위치를 커밋하면, 재시작 후 미완료 메시지를 건너뛸 수 있습니다. 종료 시 실행 중 작업을 기다리지 않는 흐름도 처리 중단의 원인이었습니다.

해결 설계

  1. 01 처리 완료 추적완료 오프셋을 추적하고, 파티션별 미완료 작업을 건너뛰지 않는 위치까지 커밋했습니다.
  2. 02 커밋 구간 직렬화commit lock으로 동시 커밋 충돌을 제어했습니다. 잠금과 완료 범위 추적을 함께 적용했습니다.
  3. 03 Graceful shutdown실행 중 task를 추적하고 asyncio.gather로 완료를 기다린 뒤 consumer를 종료했습니다.
처리 완료 기준 커밋과 안전한 워커 종료 해결 설계 다이어그램

결과와 검증

완료 후 커밋

재시작과 종료 시 복구 경계 정리

  • 미완료 메시지를 건너뛰는 커밋 경로 개선
  • 종료 전에 실행 중 작업을 기다리는 절차 확보
  • 재처리 가능성과 멱등성을 함께 고려한 운영 구조
처리 완료 기준 커밋과 안전한 워커 종료 결과 다이어그램

설계 포인트: 커밋 잠금과 함께 미완료 메시지를 건너뛰지 않는 완료 범위 추적이 필요합니다.

Spring BootFastAPIKafkaLangGraphClova SpeechAWS