끄적이는 개발 log

푸시 알림 서버까지 만들고도 로컬 알림을 선택한 이유

pp8817 — Wed, 5 Aug 2026 01:15:05 +0900

이 글은 Velog에서 이전한 글입니다. Velog 원문 보기

푸시 알림 서버까지 만들고도 로컬 알림을 선택한 이유

Landit에는 사용자가 학습을 이어가도록 매일 20시에 리마인더를 보내는 기능이 필요했다.

이 알림 하나를 위해 EventBridge Scheduler, SQS, Push Device, 발송 이력, Expo Ticket과 Receipt까지 백엔드 구조를 설계하고 구현했다. 처음에는 서버가 최신 학습 상태를 확인한 뒤 Expo Push Service로 알림을 보내는 방식이 자연스럽다고 생각했다.

그런데 구조를 완성해 갈수록 질문이 달라졌다.

서버 푸시를 안정적으로 만들 수 있는가가 아니라, 현재 제품이 이 복잡성을 정말 필요로 하는가?

결론부터 말하면 첫 학습 리마인더의 구현 방향을 앱의 로컬 알림으로 바꿨다.

서버 푸시 구현이 실패해서 로컬 알림으로 돌아간 것은 아니다. 서버 푸시에 필요한 책임을 코드 수준까지 구체화한 뒤, 현재 요구사항과 운영 제약에는 더 단순한 구조가 맞다고 판단했다.

매일 20시 알림 하나에서 시작했다

처음 확정된 요구사항은 단순했다.

사용자가 학습을 이어가도록 알림을 보낸다.
발송 시각은 매일 오후 8시다.
알림을 누르면 다음 학습 화면으로 이동한다.
사용자는 알림을 켜거나 끌 수 있다.

고정된 시간에 같은 문구를 보내는 것만 생각하면 앱이 직접 알림을 예약해도 된다. Expo Notifications는 앱에서 특정 시각의 알림을 예약하고, 예약 식별자를 이용해 기존 알림을 취소하는 기능을 제공한다.

하지만 알림 내용을 구체화하면서 서버가 필요해 보이는 이유도 늘어났다.

서버 푸시를 설계할 때 사용자의 상태에 따라 알림을 세 가지로 나누기로 했기 때문이다.

알림 유형	선택 조건	이동 화면
`CONTINUE_SCENARIO`	다음으로 진행할 시나리오가 있음	`/conversation/{scenarioId}`
`CONTINUE_EXPRESSION`	완료한 시나리오에 아직 학습하지 않은 표현이 있음	`/expressions/{expressionId}`
`REVIEW_LEARNING`	현재 활성 콘텐츠를 모두 완료함	`/home`

최근에 시나리오를 완료했는지, 표현 학습을 완료했는지에 따라 우선순위도 달라졌다. 최근 활동에 이어갈 대상이 없으면 다른 학습 유형으로 대체하고, 새로운 콘텐츠가 추가되면 다음 계산에서는 다시 이어 하기 알림으로 전환돼야 했다.

이 조건만 놓고 보면 최신 학습 데이터가 있는 서버에서 대상을 계산하는 편이 정확하다.

그래서 처음에는 서버 푸시를 기준으로 설계를 시작했다.

다만 이 세 유형은 서버 푸시에서 검토한 정책이다. 로컬 알림으로 방향을 바꾸면서 첫 배포 범위는 앱이 직접 아는 학습 이벤트를 기준으로 리마인더를 예약하는 형태로 줄였다.

Expo API를 호출하는 일보다 그 앞뒤가 더 복잡했다

서버 푸시의 마지막 단계만 보면 단순하다.

Expo Push Token
+ 제목
+ 본문
+ 이동 경로
→ Expo Push API

하지만 실제 시스템에는 이 요청 앞뒤로 더 많은 책임이 필요했다.

flowchart LR
    APP["Landit 앱"] -->|"설치 상태와 Token 동기화"| API["기존 API 서버"]
    EB["EventBridge Scheduler<br/>매일 20시"] --> SQS["Push SQS"]
    SQS --> CONSUMER["PushNotificationConsumer"]
    CONSUMER -->|"SCHEDULED_NOTIFICATION_BATCH"| TARGET["사용자별 알림 대상 계산"]
    CONSUMER -->|"PUSH_RECEIPT_CHECK"| RECEIPT["Receipt 확인"]
    TARGET --> DELIVERY["발송 이력 선점"]
    DELIVERY --> EXPO["Expo Push Service"]
    EXPO --> PROVIDER["FCM / APNs"]
    EXPO --> TICKET["Ticket 결과 저장"]
    TICKET -->|"15분 지연 메시지"| SQS
    RECEIPT --> EXPO
    SQS -->|"반복 실패"| DLQ["Push DLQ"]

서버는 다음 질문에 모두 답해야 했다.

Token은 사용자와 기기 중 어디에 귀속되는가?
한 사용자가 여러 기기를 사용하면 어디까지 발송해야 하는가?
같은 기기에서 다른 계정으로 로그인하면 Token의 소유자는 누구인가?
20시에 어떤 사용자를 조회해야 하는가?
사용자마다 다른 학습 상태를 어떻게 N+1 조회 없이 계산할 것인가?
SQS가 같은 메시지를 다시 전달하면 중복 알림을 어떻게 막을 것인가?
Expo가 요청을 접수했다는 것과 FCM 또는 APNs가 받았다는 것을 어떻게 구분할 것인가?
일시 오류와 영구 오류를 어떤 기준으로 나눌 것인가?
삭제된 앱의 Token을 어떻게 발송 대상에서 제외할 것인가?

문제의 핵심은 Push API 호출이 아니라 발송 전후의 상태를 누가 소유할 것인가였다.

Token은 사용자 ID가 아니라 앱 설치를 기준으로 관리했다

처음에는 사용자 ID에 Expo Push Token을 저장하면 충분해 보였다.

하지만 Token은 사용자 계정 자체가 아니라 알림을 받을 앱 설치와 연결된다.

한 사용자가 iPhone과 Android 기기를 함께 사용할 수 있다. 반대로 하나의 기기에서 로그아웃한 뒤 다른 사용자가 로그인할 수도 있다. 이때 사용자 ID만 기준으로 Token을 저장하면 다중 기기와 계정 전환을 안전하게 표현하기 어렵다.

그래서 앱 설치마다 installationId를 만들고 서버에는 다음 상태를 저장하도록 설계했다.

installationId
+ 현재 사용자
+ 플랫폼
+ Landit 알림 ON/OFF
+ Expo Push Token
+ Token 상태

클라이언트 API도 설치 상태를 멱등하게 동기화하는 하나의 API로 제한했다.

PUT /api/v1/me/push-devices/{installationId}

동일한 installationId로 다시 요청하면 행을 추가하지 않고 현재 상태를 갱신한다. 같은 Expo Push Token이 다른 설치에 연결돼 있으면 이전 연결을 해제하고 현재 설치로 옮긴다.

발송 가능한 설치는 다음 조건을 모두 만족해야 한다.

pushEnabled == true
&& expoPushToken != null
&& tokenStatus == ACTIVE

이 구조는 다중 기기와 계정 전환을 안전하게 다룰 수 있었다.

다만 로컬 알림을 선택하면 이 중앙 Token 소유권 관리 자체가 첫 번째 알림 범위에서는 필요하지 않다. 서버 푸시가 제공하는 정교함이 곧 서버가 계속 소유해야 할 상태의 양이기도 했다.

별도 Worker는 만들지 않았지만 서버의 책임은 여전히 컸다

예약 알림을 서버에서 처리한다면 Spring의 @Scheduled보다 EventBridge Scheduler를 사용하는 편이 안전하다고 판단했다.

API 서버가 여러 대라면 각 인스턴스의 Spring Scheduler가 같은 작업을 실행할 수 있다. 배포나 재시작 시점도 예약 실행에 영향을 줄 수 있다. EventBridge Scheduler가 매일 20시에 SQS 메시지 한 건을 발행하면 예약 실행 시점과 애플리케이션 배포를 분리할 수 있다.

처음 검토한 전체 구조는 다음과 같았다.

EventBridge Scheduler
→ SCHEDULED_NOTIFICATION_BATCH
→ Push SQS
→ 별도 Push Worker
→ 사용자별 대상 계산
→ Expo Push Service

하지만 현재 규모에서 별도 ECS Service나 Fargate Task를 추가하는 것은 과하다고 판단했다.

Worker를 분리하면 CPU와 메모리를 API 서버와 격리할 수 있고 배포 책임도 명확해진다. 반면 새로운 실행 환경, 배포 파이프라인, 모니터링 대상과 고정 비용이 생긴다.

그래서 중간안으로 기존 API 서버 안에 SQS Consumer를 두었다.

EventBridge Scheduler
→ Push SQS
→ 기존 API 서버의 PushNotificationConsumer
→ 대상 계산과 Expo 발송

Consumer 동시성은 2로 작게 시작했다. 별도 서버 비용은 만들지 않으면서 SQS의 재시도와 DLQ는 사용할 수 있었다.

이 선택은 서버 푸시를 유지한다는 전제에서는 합리적이었다.

하지만 Worker를 없애도 다음 책임은 사라지지 않았다.

Queue 소비와 Visibility Timeout 관리.
API 서버와 배치 작업의 CPU·메모리 공유.
발송 대상 계산을 위한 DB 조회.
중복 발송 방지.
Expo와 FCM/APNs 오류 처리.
Ticket과 Receipt 상태 저장.
운영 Queue와 DLQ 모니터링.

별도 Worker 비용은 줄였지만 서버 푸시라는 선택의 운영 비용까지 사라진 것은 아니었다.

500명씩 계산하고 100건씩 발송했다

모든 활성 사용자를 한 번에 메모리에 올리거나 사용자마다 Repository를 조회하면 사용자 수가 늘수록 처리 시간과 쿼리 수가 함께 증가한다.

그래서 대상 계산은 userProfileId Keyset Pagination으로 500명씩 처리하도록 구성했다.

long lastUserProfileId = 0L;

while (true) {
  NotificationTargetPage page = loadPage(lastUserProfileId, 500);
  if (page.userProfileIds().isEmpty()) {
    return;
  }

  List<SendPushNotificationCommand> commands = processPage(page);
  notificationDispatchService.sendAll(commands);
  lastUserProfileId = page.userProfileIds().getLast();
}

이 코드는 실제 구조를 설명하기 위해 세부 로직을 줄인 형태다.

대상 계산 단계에서는 각 페이지의 시나리오, 표현, 최근 완료 시각, 발송 가능한 Push Device를 일괄 조회한다. 사용자마다 같은 데이터를 다시 조회하지 않고 메모리에서 알림 유형 하나를 선택한다. 전체 사용자를 하나의 긴 트랜잭션으로 묶지 않고 페이지마다 상태를 저장한다.

계산 결과는 user_notification_state에 스냅샷으로 남긴다. 이 테이블은 학습 사실의 원본이 아니다. 시나리오와 표현의 실제 완료 이력에서 그날의 알림 유형과 대상을 다시 계산하므로, 새 콘텐츠가 추가되면 다음 배치에서 이어 하기 알림으로 전환된다.

Expo 발송 단위는 별개였다.

Expo Push API는 한 요청에 최대 100개의 메시지 객체를 받을 수 있다. 따라서 500명은 DB 조회와 정책 계산 단위이고, 100건은 Expo HTTP 요청 단위다.

500명
= DB 조회와 대상 계산 단위

100건
= Expo 요청 분할 단위

한때 실제 발송 대상마다 PUSH_SEND 메시지를 다시 SQS에 넣는 구조도 검토했다.

사용자가 5만 명이면 기기 수에 따라 5만 개가 넘는 메시지가 새로 생길 수 있다. 개별 실패를 격리하기는 쉬워지지만 현재 규모에서는 메시지 유형, 재처리 상태와 DLQ 관리만 더 복잡해졌다.

결국 500명 단위는 Queue Fan-out 단위가 아니라 서버 내부의 조회 단위로 남겼다. 선택된 기기는 페이지 안에서 모아 Expo에 최대 100건씩 직접 보냈다.

SQS가 같은 메시지를 다시 줘도 알림은 한 번만 보내야 했다

SQS Standard Queue는 최소 한 번 전달 방식을 사용한다. Visibility Timeout은 같은 메시지를 동시에 처리할 가능성을 줄여 주지만, 중복 전달 자체를 완전히 없애지는 않는다.

따라서 서버는 SQS가 메시지를 정확히 한 번 전달한다고 가정할 수 없었다.

중복 방지는 Expo 호출 전에 push_delivery 발송 이력을 선점하는 방식으로 구현했다.

날짜
+ 사용자
+ 알림 유형
+ Push Device
→ 중복 방지 키 생성

개념적인 키는 다음과 같다.

push:scheduled:{date}:{userProfileId}:{notificationType}:{pushDeviceId}

같은 예약 메시지가 다시 전달되면 동일한 키의 발송 이력이 이미 존재한다. 이때 Expo를 다시 호출하지 않는다. 일시 오류로 재시도가 허용된 이력만 기존 행을 다시 선점한다.

발송 이력은 단순한 로그가 아니었다.

외부 호출 전에 이번 발송을 어느 처리 흐름이 맡았는지 확정하는 멱등성 경계였다.

다만 현재 키가 보장하는 범위는 같은 날짜·사용자·알림 유형·기기에 대한 중복 방지다. 첫 처리와 중복 처리 사이에 사용자가 학습해 선정 유형이 바뀌면 다른 키가 만들어질 수 있다. 사용자·기기별 하루 한 건을 엄격하게 보장하려면 알림 유형을 제외한 일일 키를 사용하거나, 첫 계산 결과를 그날의 확정 대상으로 고정해야 한다.

배치 처리 시간이 길어질 가능성도 고려해야 했다. Consumer는 처리 시작과 페이지 전환 시 현재 SQS 메시지의 Visibility Timeout을 300초로 연장한다. Handler가 정상 종료된 경우에만 메시지를 삭제하도록 승인 정책도 ON_SUCCESS로 설정했다.

이 방식도 한 페이지의 조회와 발송이 300초 안에 끝난다는 전제가 필요하다. 실제 처리 시간이 이를 넘는다면 페이지 처리 중에도 주기적으로 연장하는 heartbeat를 두거나 작업 단위를 더 작게 나눠야 한다.

현재 구현은 같은 발송 이벤트의 중복 Expo 호출을 막는다. 사용자당 하루 한 건이라는 제품 정책까지 보장하려면 중복 키의 범위를 별도로 확정해야 한다.

Expo Ticket은 기기 전달 완료가 아니었다

Expo Push Service에 HTTP 요청이 성공했다고 해서 사용자 기기에 알림이 표시된 것은 아니다.

Expo는 요청을 접수하면 Push Ticket을 반환한다. Ticket은 Expo가 Payload를 받았다는 의미다. Expo가 이후 FCM 또는 APNs에 전달을 시도한 결과는 Push Receipt로 확인해야 한다.

stateDiagram-v2
    [*] --> REQUESTED
    REQUESTED --> TICKET_ACCEPTED: "Expo가 Ticket 반환"
    REQUESTED --> FAILED: "영구 오류"
    REQUESTED --> REQUESTED: "429, 5xx, timeout 재시도"
    TICKET_ACCEPTED --> DELIVERED: "FCM 또는 APNs가 수신"
    TICKET_ACCEPTED --> FAILED: "Receipt 실패"

여기서 DELIVERED는 사용자 기기에 알림이 표시됐다는 뜻이 아니다. Expo Receipt로 FCM 또는 APNs가 알림을 받았음을 확인한 상태다.

DeviceNotRegistered가 반환되면 두 상태가 함께 바뀐다.

flowchart LR
    ERROR["Ticket 또는 Receipt<br/>DeviceNotRegistered"] --> DELIVERY_FAILED["PushDelivery<br/>FAILED"]
    ERROR --> DEVICE_INVALID["현재 Token 소유 PushDevice<br/>INVALID"]

Expo는 발송 약 15분 뒤 Receipt를 확인할 것을 권장한다. 그래서 Ticket을 저장한 뒤 PUSH_RECEIPT_CHECK 메시지를 SQS에 900초 지연 발행하도록 구성했다.

오류라고 해서 모두 자동 재발송하지도 않았다.

오류	처리
HTTP 429, 5xx, timeout	같은 발송 이력으로 재시도
잘못된 Payload, 영구적인 요청 오류	`FAILED`로 종료
일반 I/O, interruption, 응답 파싱 실패	Expo 수신 여부가 불확실해 자동 재발송하지 않음
`DeviceNotRegistered`	현재 Token 소유 설치를 `INVALID` 처리

네트워크 오류가 발생했다고 바로 재발송하면 Expo는 이미 첫 번째 요청을 받았는데 응답만 유실된 상황에서 중복 알림을 만들 수 있다.

재시도는 실패를 복구하는 기능이지만, 외부 시스템이 요청을 받았는지 모르는 상황에서는 새로운 중복 원인이 될 수도 있었다.

기술적으로 올바른 구조와 지금 필요한 구조는 달랐다

여기까지 구현하면서 서버 푸시에 필요한 책임은 분명해졌다.

앱 설치와 Token 소유권 관리.
사용자별 최신 학습 상태 계산.
예약 실행과 Queue 소비.
페이지 단위 조회와 트랜잭션.
발송 멱등성.
Expo 요청 분할.
Ticket과 Receipt 추적.
오류 분류와 Token 무효화.
Visibility Timeout과 DLQ 운영.

각각은 불필요한 기능이 아니었다. 서버가 알림 발송의 원본이라면 필요한 책임이었다.

하지만 현재 제품 요구사항을 다시 보면 다른 결론이 나왔다.

첫 번째 알림의 목적은 복잡한 마케팅 캠페인이나 운영 공지가 아니었다. 사용자가 다시 학습하도록 정해진 시각에 리마인더를 보여주는 것이었다.

현재 범위에서는 다음 기능이 필요하지 않았다.

운영자가 특정 사용자 집단에 임의 알림을 발송하는 기능.
국가나 사용자별 시간대를 서버에서 관리하는 기능.
휴면 기간에 따라 여러 캠페인을 순차 발송하는 기능.
앱을 열지 않은 상태에서 서버 데이터만으로 알림 정책을 바꾸는 기능.
모든 기기의 발송 상태를 중앙에서 추적하는 기능.
Receipt 기반 전달 분석.

반대로 앱은 사용자가 학습한 시점과 다음 알림을 갱신해야 하는 시점을 이미 알고 있었다.

이 조건에서는 서버가 매일 전체 사용자의 상태를 다시 계산하는 것보다, 앱이 학습 이벤트를 기준으로 다음 알림을 예약하는 편이 단순했다.

판단 기준	서버 푸시	로컬 알림
최신 서버 상태 기반 대상 계산	유리함	앱이 알고 있는 상태로 제한됨
운영자 임의 발송	가능함	어려움
다중 기기 중앙 통제	가능함	기기별 독립 동작
Ticket·Receipt 추적	가능함	중앙 추적 없음
Queue·DB·외부 푸시 서비스 운영	필요함	필요하지 않음
오프라인 예약	서버와 네트워크 필요	OS가 예약 실행
현재 고정 리마인더 범위	구현 가능하지만 책임이 큼	더 단순하게 충족 가능

서버 푸시가 더 많은 기능을 제공한다는 사실은 분명했다.

문제는 그 기능들이 지금 필요하지 않았다는 점이었다.

첫 배포는 로컬 알림으로 방향을 바꿨다

최종적으로 첫 학습 리마인더는 앱에서 예약하는 로컬 알림으로 정리했다. 서버의 세 가지 알림 정책을 그대로 옮기는 대신, 앱이 직접 확인한 학습 이벤트를 기준으로 다음 리마인더를 갱신하는 범위부터 시작했다.

개념적인 흐름은 다음과 같다.

flowchart LR
    COMPLETE["사용자 학습 완료"] --> STATE["기기 내부 알림 상태 갱신"]
    STATE --> CANCEL["이전 예약 알림 취소"]
    CANCEL --> SCHEDULE["다음 알림 예약"]
    SCHEDULE --> OS["iOS / Android"]
    OS -->|"예약 시각 도달"| USER["사용자에게 알림 표시"]

앱은 사용자가 학습할 때마다 기존 예약을 갱신한다. OS가 예약 실행을 담당하므로 알림 발송을 위해 서버가 실행되고 있을 필요가 없다.

Expo Notifications는 scheduleNotificationAsync가 반환한 식별자를 저장하고, cancelScheduledNotificationAsync로 특정 예약을 취소할 수 있다.

학습할 때까지 매일 알림을 보내는 정책이라면 20시 반복 예약 하나를 유지하면 된다. 사용자가 학습을 완료했을 때 기존 예약을 취소하고 다음 문구와 이동 경로로 다시 예약한다.

구현에 필요한 핵심 책임도 다음 정도로 줄어든다.

이전 예약 식별자 조회
→ 이전 예약이 있으면 취소
→ 다음 학습 리마인더 예약
→ 새 예약 식별자 저장

FE 구현에서는 사용자별 저장 키, OS 알림 권한, Android Notification Channel, 앱 재설치와 로그아웃 시 상태 초기화도 함께 고려해야 한다.

로컬 알림도 지정한 시각의 표시를 무조건 보장하는 기능은 아니다. Expo 문서 기준으로 Android 12 이상에서 정확한 시각의 알림을 예약하려면 SCHEDULE_EXACT_ALARM 권한이 필요하고, 실제 표시 여부는 OS 권한과 알림 Handler 설정에도 영향을 받는다.

따라서 제품 요구사항도 “반드시 20시 정각에 실행되는 작업”과 “20시 무렵 학습을 상기시키는 리마인더”를 구분해야 한다. 첫 번째라면 로컬 알림의 플랫폼 제약을 더 깊게 검토해야 하고, 두 번째라면 현재 구조로 충분할 수 있다.

기기 간 동기화도 자동으로 해결되지 않는다. 사용자가 기기 A에서 학습을 끝내도 기기 B에 저장된 예약은 B가 앱을 열어 상태를 동기화하기 전까지 그대로 남을 수 있다. 서버에 새 콘텐츠가 추가돼도 앱이 이를 확인하기 전에는 예약된 문구와 이동 경로를 바꿀 수 없다.

첫 배포가 이 시차를 허용할 수 있다면 로컬 알림의 단순성이 더 크다. 반대로 모든 기기의 알림을 즉시 맞춰야 한다면 서버 푸시가 다시 필요하다.

로컬 알림으로 방향을 바꾸면서 다음 항목은 첫 배포의 운영 대상에서 빠졌다.

EventBridge Scheduler
Push SQS와 DLQ
SQS Consumer
Push Device 동기화 API
Expo Push Token 소유권
push_delivery
Ticket과 Receipt 확인
외부 푸시 서비스 오류 재시도

단순히 코드 몇 줄이 줄어든 것이 아니다.

운영 중 확인해야 할 Queue, DB 상태, Expo와 FCM/APNs의 장애 경계도 첫 배포에서는 관리할 필요가 없어졌다.

로컬 알림이 항상 더 좋은 선택은 아니다

이번 결론을 “작은 서비스는 로컬 알림을 쓰면 된다”로 일반화할 수는 없다.

다음 요구사항이 생기면 서버 푸시가 다시 적절해진다.

앱을 오래 열지 않은 사용자를 서버 활동 기준으로 선별해야 함.
마지막 학습 후 1일, 3일, 7일처럼 휴면 기간별 정책이 달라짐.
새로운 콘텐츠나 운영 공지를 즉시 전달해야 함.
A/B 테스트에 따라 문구와 발송 시간을 바꿔야 함.
사용자별 시간대와 국가 정책을 서버에서 통제해야 함.
여러 기기에 일관된 설정을 적용해야 함.
발송 이력과 FCM/APNs 전달 결과를 분석해야 함.
관리자 임의 발송과 긴급 알림이 필요함.

반대로 알림이 기기 안의 행동만으로 예약될 수 있고, 정책이 단순하며, 중앙 발송 이력이 필요하지 않다면 로컬 알림은 유효한 선택이다.

판단 기준은 서버 푸시와 로컬 알림 중 어느 기술이 더 우수한지가 아니었다.

알림 정책의 원본을 서버가 가져야 하는가, 아니면 기기가 이미 필요한 상태와 시점을 알고 있는가?

서버 푸시 구현은 낭비였을까?

결과만 보면 첫 배포의 구현 방향은 로컬 알림으로 바뀌었고, 서버 푸시 코드는 매일 20시 예약 발송에 사용하지 않았다.

그렇다고 서버 설계가 의미 없었던 것은 아니다.

구현을 통해 서버 푸시로 전환할 때 필요한 경계를 구체적으로 확인할 수 있었다.

사용자 ID와 설치 ID를 분리해야 하는 이유.
SQS 중복 전달을 DB 멱등성으로 흡수하는 방법.
DB 계산 단위와 Expo 요청 단위가 다른 이유.
Ticket 접수와 FCM/APNs 전달 결과의 차이.
자동 재시도가 오히려 중복 알림을 만들 수 있는 조건.
별도 Worker가 다시 필요해지는 규모와 운영 신호.

무엇보다 “안정적으로 만들 수 있다”와 “지금 만들어야 한다”가 다른 판단이라는 점을 확인했다.

서버 푸시는 구현과 자동 테스트까지 진행했지만 당시 Scheduler는 비활성 상태였다. dev 실기기 E2E와 운영 발송 결과를 성과처럼 주장하지 않는 이유도 여기에 있다. 첫 배포에서 검증할 기준은 로컬 알림이다.

마치며

사용자별 학습 상태를 정확히 계산하려면 서버 푸시가 필요하다고 생각했다. 하지만 정확한 발송을 위해 필요한 상태와 실패 처리를 모두 펼쳐 놓고 보니, 첫 리마인더의 요구사항보다 시스템이 먼저 커지고 있었다.

중앙 통제, 사용자 세분화, 발송 추적이 필요해지면 서버 푸시는 다시 유효하다. 지금은 앱이 학습 이벤트와 다음 예약 시점을 이미 알고 있었고, 그 정보만으로 제품 요구사항을 충족할 수 있었다.

가장 어려웠던 부분은 Expo Push API 호출이 아니었다. 현재 제품에 필요한 신뢰성의 경계를 정하고, 이미 만든 구조보다 단순한 선택을 받아들이는 일이었다.

알림 아키텍처의 출발점은 어떤 기술을 쓸지가 아니라, 알림 정책의 원본을 누가 가지고 있는지였다.

참고 자료

Sentry 500은 서버 장애가 아니었다. WAF Count 뒤에 있던 취약점 스캐너

pp8817 — Wed, 5 Aug 2026 01:14:46 +0900

이 글은 Velog에서 이전한 글입니다. Velog 원문 보기

Sentry 500은 서버 장애가 아니었다. WAF Count 뒤에 있던 취약점 스캐너

2026년 7월 25일 20시 5분, 운영 서버에서 서로 다른 Sentry 이슈 세 개가 37초 안에 발생했다.

두 건은 multipart 요청을 읽다가 본문이 갑자기 끝났다는 오류였다. 나머지 한 건은 form body의 % 인코딩이 깨져 발생했다.

처음 보이는 모양은 애플리케이션 장애였다. 운영 ECS task 한 곳에서 500이 연달아 발생했고, Sentry는 예외 체인이 다른 두 multipart 오류를 별도 이슈로 묶었다.

하지만 같은 시각의 Grafana, ALB access log, WAF 로그를 맞춰 보니 상황이 달랐다. 특정 task에 자동화된 취약점 탐색 요청이 몰렸고, 잘린 연결과 비정상 본문이 같은 시간대에 반복됐다. 로그 패턴상 외부 자동 스캐너가 전송 도중 연결을 끊거나 깨진 본문을 보냈을 가능성이 가장 높았다.

이번 글은 세 건의 500에서 시작해 요청 주체를 확인하고, WAF 규칙을 실제 차단으로 바꾸기까지의 과정을 정리한 기록이다.

수치와 시간은 실제 운영 로그를 집계한 값이다. 공개용 이미지에서는 IP, 계정 ID, task 이름, Trace ID 등 내부 식별자를 제거했다.

20시 5분에 무슨 일이 있었나

Grafana에서 같은 구간을 열자 평소와 다른 모양이 바로 보였다. BE 로그 발생량이 20시 5분 직후 짧은 구간에 몰렸고, 패널 표시 기준 최고 약 480 ops/s까지 올라갔다.

같은 시간대의 관측값을 모으면 아래와 같다.

관측 대상	결과
Sentry 이슈	3건
분석한 대표 이벤트 3건 사이의 시간	37초
이벤트가 발생한 ECS task	동일 task 1개
해당 40초의 ALB 404	671건
해당 40초의 ALB 460	1,954건
해당 40초의 500	2건
WAF IP Reputation 매칭	1,953건
Rate rule이 차단한 요청	306건
Count 상태라 ALB까지 도달한 요청	1,647건

Sentry의 세 이슈만 보면 공통점을 찾기 어렵다. Sentry 이벤트에는 요청 URL과 User-Agent가 남아 있지 않았기 때문에 특정 ALB 요청과 1대1로 연결할 수도 없었다.

대신 시간, task, 예외 원인, 같은 구간의 요청 패턴을 함께 봤다. 네 단서가 모두 같은 방향을 가리켰다.

두 종류의 깨진 요청

첫 번째 유형은 multipart 본문이 종료 boundary 전에 끊긴 요청이었다.

Grafana Loki에서 같은 구간을 Stream ended unexpectedly로 조회하자 Tomcat의 MultipartStream$MalformedStreamException, FileUploadException, IOFileUploadException이 연속으로 확인됐다.

Sentry의 두 multipart 이슈는 내부 예외 체인이 조금 달라 별도 그룹이 됐다. 직접 원인은 같았다. 서버가 multipart body를 다 읽기 전에 스트림이 끝났다.

두 화면의 제목은 같지만 이벤트 수와 로거 구성이 다르다. Sentry는 예외 체인과 스택 정보에 따라 같은 원인의 오류도 별도 이슈로 묶을 수 있다. 정확한 하위 원인인 Stream ended unexpectedly는 앞의 Grafana 로그에서 확인했다.

두 번째 유형은 application/x-www-form-urlencoded 본문의 잘못된 % escape였다.

URLDecoder: Illegal hex characters in escape (%) pattern은 % 뒤에 정상적인 16진수 두 자리가 오지 않았다는 뜻이다. 정상 클라이언트가 만든 form 요청이라기보다, 임의의 payload를 대량으로 던지는 스캔 요청과 더 잘 맞는 형태였다.

Sentry에는 상위 예외인 HttpMessageNotReadableException과 Could not decode HTTP form payload가 남았고, 실제 % escape 파싱 실패는 Grafana의 애플리케이션 로그에서 확인했다.

ALB 460이 원인을 좁혀 줬다

같은 40초 동안 ALB 460이 1,954건 발생했다.

AWS 문서에서 ALB 460은 로드 밸런서의 idle timeout 전에 클라이언트가 연결을 닫았을 때 기록되는 상태다. 서버가 응답을 끝내기 전에 요청을 보낸 쪽이 연결을 끊은 셈이다.

이 값은 multipart 본문이 중간에 끊겼다는 애플리케이션 로그와 맞아떨어졌다. 같은 task와 같은 시각에 잘린 body 예외가 발생했고, ALB에서는 클라이언트가 연결을 먼저 종료한 요청이 대량으로 관측됐다.

경로도 결정적이었다. 같은 구간에는 존재하지 않는 WordPress, PHP, 관리자, 원격 실행 취약점 경로를 순회하는 요청이 몰려 있었다. Landit 앱이 사용하는 /api/v1/... 호출 패턴과는 전혀 달랐다.

이 때문에 내부 BE나 AI 장애보다 외부 자동 스캐너가 깨진 요청을 보냈다는 설명이 훨씬 잘 맞았다.

다만 정확도를 위해 한계도 남겼다. Sentry에 URL과 User-Agent가 없으므로 이벤트 한 건을 ALB의 특정 한 줄과 직접 연결한 것은 아니다. 동일 task, 37초라는 좁은 시간, 대량의 스캔 경로, ALB 460, 동일한 예외 원인을 함께 본 상관분석이다.

왜 WAF가 1,647건을 통과시켰나

문제의 요청은 AWS WAF Amazon IP Reputation List에 1,953건 매칭됐다.

그런데 당시 이 관리형 규칙은 Count였다.

AWS WAF의 Count action은 요청을 공격으로 확정한다는 뜻도, 차단한다는 뜻도 아니다. 규칙 조건에 맞은 요청을 집계하고 라벨과 로그를 남기지만, 그 규칙 자체는 요청을 종료하지 않는다. 오탐 가능성을 먼저 관찰할 때 쓰는 모드다.

따라서 1,953건 중 1,647건은 IP Reputation 규칙에 걸렸지만 ALB와 BE까지 도달했다. 같은 출발지가 5분당 2,000회를 넘은 뒤의 306건만 별도 rate rule에서 차단됐다.

이 숫자는 “초과 요청이 총 306건뿐이었다”는 뜻이 아니다. AWS WAF rate-based rule은 최근 요청률을 주기적으로 추정해 제한한다. 임계치를 넘기 전 요청과 탐지 시차 동안의 요청은 통과할 수 있다.

5분당 2,000회를 어떻게 정했나

차단 규칙은 정상 클라이언트까지 막지 않는 선에서 정해야 했다. 그래서 먼저 ALB access log로 운영 서버, 정상 사용자 기기, 외부 스캐너의 최고 5분 요청량을 따로 계산했다.

분석 구간은 2026년 7월 22일 02:58:52부터 7월 25일 14:59:54 KST까지였다.

구분	최고 5분 요청량	2,000회와의 차이
운영 BE에서 AI로 보내는 대화 요청	42건	약 48배
정상 iOS·Android 사용자 요청	21건	약 95배
외부 스캐너 A	2,654건	임계치 초과
외부 스캐너 B	5,986건	임계치 초과

같은 기간 전체 ALB 요청 49,837건 가운데 두 스캐너가 만든 요청은 36,410건이었다. 전체의 73.06%다.

정상 트래픽의 최고치는 42건이었다. 회사, 학교, 통신사 NAT처럼 여러 기기가 하나의 공인 IP를 공유하는 상황도 출발지 IP 집계에 이미 포함돼 있었다.

이 관측 결과를 근거로 rate rule을 5분당 2,000회 기준 Count에서 Block으로 바꿨다. 정상 최고치와 간격이 컸고, 실제로 임계치를 넘은 것은 두 스캐너뿐이었다.

관측 기간이 약 3.5일이라는 한계는 남는다. 그래서 “정상 사용자 영향이 절대 없다”가 아니라 “현재 관측에서 위험이 낮고, 이상 시 바로 Count로 되돌릴 수 있다”를 적용 기준으로 잡았다.

WAF 로그를 켠 뒤 판단이 달라졌다

초기 분석에는 WAF 전체 요청 로그가 없었다. CloudWatch Count 지표와 sampled request만으로는 같은 요청이 어떤 하위 규칙에 걸렸는지, 실제 정상 요청이 섞였는지 전수 확인하기 어려웠다.

그래서 prod WAF의 Count와 Block 요청만 별도 S3 bucket에 저장하도록 구성했다.

로그에는 client IP, URI path, method, User-Agent를 남겼다. 대신 Authorization, Cookie, X-Api-Key, query string은 redaction했다. bucket은 공개 접근을 막고 SSE-S3 암호화와 30일 만료 정책을 적용했다.

로그가 실제로 쌓인 뒤 64개 객체, 3,539건을 분석했다.

규칙	실제 로그 결과
Amazon IP Reputation Count	3,527건, 23개 출발지
Common Rule Set Count	500건
IP rate limit Block	311건, 1개 출발지
한 출발지의 최고 5분 요청량	3,253건
해당 출발지가 순회한 경로	1,316개

같은 요청이 여러 managed rule에 동시에 매칭될 수 있다. 따라서 3,527, 500, 311을 단순히 더하면 공격 요청 수가 되지 않는다.

IP Reputation List에 가장 많이 걸린 출발지는 WordPress, PHP, PHPUnit, .env 같은 Landit과 무관한 1,316개 경로를 순회했다. 이 표본에서는 api.landit.im, ai.landit.im, 실제 Landit BE route에 대한 Count 매칭이 0건이었다.

이 결과를 근거로 IP Reputation List의 override_action을 count에서 none으로 바꿨다.

여기서 none은 규칙을 끈다는 뜻이 아니다. AWS 관리형 Rule Group의 원래 action을 그대로 사용한다는 뜻이다. AWS가 Block으로 정의한 서브룰은 차단하고, 기본 Count 서브룰은 계속 Count한다.

Common Rule Set은 왜 Count로 남겼나

Common Rule Set 표본도 공격성 패턴이 대부분이었다.

하위 라벨	Count
XSS	284건
LFI	146건
그 외	RFI, SSRF, 제한 확장자, 악성 봇, body size 등

그렇다고 관리형 그룹 전체를 바로 Block으로 바꾸지는 않았다.

Landit에는 대화와 학습 입력처럼 사용자가 코드 조각이나 긴 본문을 보낼 수 있는 API가 있다. XSS body·query 규칙과 body size 규칙은 이런 정상 입력을 오탐할 여지가 있다.

반면 이번 스캐너는 IP Reputation List만 기본 action으로 복원해도 rate limit에 도달하기 전에 먼저 막을 수 있었다. 추가 효과는 얻으면서 오탐 위험은 더 작은 변경이었다.

현재 적용 상태는 아래와 같다.

규칙	운영 action
IP rate limit, 5분당 2,000회	Block
Amazon IP Reputation List	AWS 관리형 기본 action
Common Rule Set	Count

Athena 테이블은 만들어졌지만 처음에는 쓸 수 없었다

로그를 S3에 저장했다고 분석이 끝난 것은 아니었다.

처음 만든 ALB Athena 테이블은 count(*)는 반환했지만 client_ip, status, URL, User-Agent가 모두 NULL이었다. Glue table 컬럼 수와 RegexSerDe capture group 수가 맞지 않았기 때문이다.

최신 ALB 로그의 transformed_host, transformed_uri, request_transform_status를 schema와 regex에 추가해 37개 컬럼과 37개 capture group을 맞췄다.

그런데도 첫 운영 조회에서는 주요 컬럼이 계속 NULL이었다.

원인은 Terraform heredoc 끝에 들어간 개행 한 글자였다. Glue의 input.regex에 \n이 저장되면서 RegexSerDe의 전체 행 매칭이 실패했다. regex를 개행 없는 HCL 문자열로 바꾼 뒤 1,130행의 type, client IP, User-Agent가 모두 정상 파싱됐다.

WAF Athena 테이블에서도 비슷한 검증이 한 번 더 필요했다. 분 단위 partition format은 yyyy/MM/dd/HH/mm인데 range 시작값이 2026/07/25로 짧아 파티션 생성이 실패했다. 시작값을 2026/07/25/00/00으로 맞췄다.

최종 조회에서는 전체 3,539행과 action, client IP, URI, terminating rule이 모두 3,539행으로 일치했다.

위 쿼리는 원본 client IP나 URI를 출력하지 않고 파싱된 행 수만 집계했다. 전체 행과 네 주요 컬럼의 행 수가 모두 같으므로 NULL 파싱 문제와 시간 파티션 문제가 해결됐음을 확인할 수 있다.

애플리케이션에서도 500을 줄여야 한다

WAF 차단과 별개로 BE 처리도 보완할 지점이 있다.

현재 malformed multipart 요청은 공통 Exception 처리에 들어가 500과 Sentry error가 된다. 스캐너가 깨진 body를 보낼 때마다 내부 장애처럼 보이는 노이즈가 생긴다.

MultipartException처럼 요청 자체가 잘못된 경우는 400으로 명시 처리하는 편이 맞다. form URL decoding 오류도 실제 예외 타입과 발생 지점을 확인해 잘못된 요청으로 제한적으로 매핑해야 한다.

주의할 점도 있다. 모든 IllegalArgumentException을 일괄 400으로 바꾸면 서버 코드 버그까지 클라이언트 오류로 숨길 수 있다. 이번에 확인한 요청 파싱 경로만 좁게 처리해야 한다.

적용할 때 지킨 순서

운영 WAF 변경은 아래 순서로 진행했다.

ALB 로그로 정상 트래픽과 스캐너의 5분 요청량을 분리했다.
rate rule만 바꾸는 좁은 Terraform plan을 만들었다.
plan이 기존 Web ACL 한 건의 in-place 변경만 포함하는지 확인했다.
승인 뒤 apply했다.
live WAF action과 API·AI health endpoint를 직접 확인했다.
post-apply plan이 No changes인지 다시 확인했다.

IP Reputation 전환도 같은 방식으로 진행했다. prod plan과 apply 모두 0 added, 1 changed, 0 destroyed였고, 기존 Web ACL 한 건만 변경됐다.

정상 요청이 차단되면 해당 rule을 Count로 되돌리는 절차도 운영 문서에 남겼다. Block 전환은 롤백 경로까지 준비돼야 완료된 변경으로 볼 수 있다.

이번 조사에서 얻은 교훈

애플리케이션 TPS만 보면 놓칠 수 있다

malformed multipart는 controller까지 정상 진입하기 전에 요청 파싱 단계에서 실패할 수 있다. 실제로 Grafana의 애플리케이션 TPS는 큰 변화를 보여 주지 않았지만 로그와 ALB 460은 짧은 시간에 폭증했다.

HTTP metric, 애플리케이션 로그, ALB access log를 함께 봐야 했던 이유다.

Count는 차단이 아니라 관찰이다

“IP Reputation에 1,953건이 잡혔다”와 “1,953건을 차단했다”는 완전히 다른 문장이다.

당시에는 1,647건이 Count 상태로 통과했다. WAF 화면에서 Count 숫자만 보고 보호되고 있다고 판단하면 안 된다.

테이블 생성과 데이터 활용은 다른 완료 조건이다

Athena table이 존재하고 row count가 나온다고 파서가 정상인 것은 아니다. 주요 컬럼의 non-null count를 함께 확인해야 한다.

이번에는 컬럼과 capture group 수, regex 끝 개행, 파티션 시간 format까지 실제 데이터로 검증하고 나서야 분석 가능한 상태가 됐다.

관리형 규칙도 그룹별로 판단해야 한다

IP Reputation List는 실제 스캐너 비중과 정상 route 0건이라는 근거가 있었다. Common Rule Set은 공격성 라벨이 많아도 정상 대화·학습 입력의 오탐 가능성이 남았다.

두 규칙을 한꺼번에 Block으로 바꾸지 않은 이유다.

마무리

이번 사건의 출발점은 Sentry의 500 세 건이었다.

상관분석 결과, BE나 AI의 내부 장애보다는 외부 자동 스캔이 가장 설득력 있는 원인이었다. 특정 ECS task에 자동화된 탐색 요청과 잘린 multipart, 깨진 form body가 함께 몰렸고, 당시 Count 상태였던 IP Reputation 규칙은 이 요청들을 차단하지 않았다.

조사 뒤 rate rule은 5분당 2,000회 기준 Block으로 바꿨다. WAF 로그를 추가해 IP Reputation List의 실제 매칭을 확인했고, AWS 관리형 기본 action으로 전환했다. Common Rule Set은 오탐 가능성 때문에 Count를 유지했다.

가장 오래 남은 교훈은 단순하다.

보안 규칙의 Count는 보호 완료 상태가 아니다. 실제 요청 로그로 무엇이 걸렸는지 확인하고, 정상 트래픽과의 간격을 계산하고, 롤백 가능한 범위에서 Block으로 옮겨야 한다.

참고 자료

Spring Boot 4에서 사라진 ObjectMapper Bean

pp8817 — Wed, 5 Aug 2026 01:00:13 +0900

이 글은 Velog에서 이전한 글입니다. Velog 원문 보기

Spring Boot 4에서 사라진 ObjectMapper Bean

배포 파이프라인은 거의 끝까지 정상적으로 진행됐다.
테스트가 통과했고 Docker 이미지도 만들어졌다. ECR 업로드와 ECS 강제 배포도 성공했다. 그런데 마지막 Verify ECS service 단계에서 배포가 멈췄다.

처음 보이는 에러는 타임아웃이었다.

The action 'Verify ECS service' has timed out after 12 minutes.

하지만 타임아웃은 원인이 아니었다. 새로 배포한 애플리케이션이 시작되지 못하고 종료된 결과였다.

ECS에서는 무슨 일이 벌어지고 있었을까

실패 당시 PRIMARY deployment의 상태는 다음과 같았다.

{
  "status": "PRIMARY",
  "rolloutState": "IN_PROGRESS",
  "desiredCount": 1,
  "runningCount": 0,
  "pendingCount": 0,
  "failedTasks": 1
}

ECS가 원하는 태스크는 1개였지만 실행 중인 태스크도, 시작을 기다리는 태스크도 없었다. 이미 한 차례 기동에 실패한 상태였다.

그런데 ECS 서비스 전체의 runningCount는 여전히 1로 표시됐다. 이전 버전의 태스크가 계속 실행되고 있었기 때문이다.
이 상태만 보면 서비스가 정상적으로 살아 있는 것처럼 보인다.

서비스 전체 runningCount = 1
신규 PRIMARY deployment runningCount = 0

배포 성공 여부를 확인할 때 서비스 전체 상태만 봐서는 안 되는 이유다. 새로 생성된 PRIMARY deployment를 따로 확인해야 한다.

새 태스크가 시작되지 못한 이유

원인은 RemoteAiConversationClient가 필요로 하는 ObjectMapper Bean이었다.

프로젝트는 Spring Boot 4를 사용하고 있었다. Spring Boot 4의 기본 Jackson 자동 구성은 Jackson 3 계열을 사용한다.
문제는 기존 AI 클라이언트가 Jackson 2의 타입을 사용하고 있었다는 점이다.

import com.fasterxml.jackson.databind.ObjectMapper;

Jackson 3의 패키지는 다음과 같다.

import tools.jackson.databind.ObjectMapper;

클래스 이름은 둘 다 ObjectMapper지만 완전히 다른 타입이다.

Spring Boot는 Jackson 3의 ObjectMapper를 자동으로 등록했다.
하지만 RemoteAiConversationClient가 요구한 것은 Jackson 2의 com.fasterxml.jackson.databind.ObjectMapper였다.

Spring 컨테이너 입장에서는 주입할 수 있는 Bean이 없었다. 그 결과 원격 AI 클라이언트를 생성하는 과정에서 NoSuchBeanDefinitionException이 발생했고, ApplicationContext가 기동하지 못했다.

흐름을 정리하면 다음과 같다.

ECS가 새 컨테이너 실행
→ Spring Boot 애플리케이션 기동
→ RemoteAiConversationClient 생성 시도
→ Jackson 2 ObjectMapper 주입 시도
→ 해당 타입의 Bean 없음
→ ApplicationContext 기동 실패
→ 컨테이너 종료
→ ECS failedTasks 증가

인프라 문제처럼 보였지만 실제 원인은 애플리케이션의 의존성 주입 실패였다.

그런데 왜 테스트는 통과했을까

배포 전에 실행한 테스트는 모두 통과했다.

이유는 기존 @SpringBootTest가 원격 AI 모드로 ApplicationContext를 실행하지 않았기 때문이다. 테스트 환경에서는 RemoteAiConversationClient가 활성화되지 않았고, 따라서 Jackson 2 ObjectMapper Bean이 없어도 문제가 드러나지 않았다.

운영 배포에서는 다음 설정으로 원격 클라이언트가 활성화됐다.

landit.ai.client-mode=remote

테스트와 배포 환경이 서로 다른 Bean 생성 경로를 사용한 셈이다.

문제를 재현하기 위해 ApplicationContext 테스트도 실제 배포 설정과 맞췄다.

@ActiveProfiles("test")
@SpringBootTest(properties = "landit.ai.client-mode=remote")
class LanditBeApplicationTests {

    @Autowired
    private RemoteAiConversationClient remoteAiConversationClient;

    @Test
    void remoteAiClientModeLoadsApplicationContext() {
        assertThat(remoteAiConversationClient).isNotNull();
    }
}

이 테스트는 수정 전에는 ObjectMapper Bean 누락으로 실패했다. 운영 환경에서만 보이던 문제가 테스트에서도 그대로 재현됐다.

단순히 contextLoads()를 실행하는 것만으로는 부족했다. 배포 환경에서 활성화되는 조건부 Bean까지 실제로 생성해야 했다.

Jackson 2 ObjectMapper를 명시적으로 등록했다

기존 AI 클라이언트의 타입을 한꺼번에 Jackson 3로 변경하는 대신, 필요한 Jackson 2 ObjectMapper Bean만 명시적으로 등록했다.

// Jackson 2 기반 외부 API 클라이언트용 ObjectMapper Bean을 제공한다.
package com.landit.landitbe.common.config;

import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class JacksonConfiguration {

    @Bean
    ObjectMapper objectMapper() {
        return new ObjectMapper();
    }
}

변경 범위를 좁힌 이유가 있다.

Jackson 2와 Jackson 3가 함께 존재하는 상황에서 전체 직렬화 구성을 섣불리 변경하면 다른 API 응답이나 메시지 변환에도 영향을 줄 수 있다. 이번 장애의 직접적인 원인은 RemoteAiConversationClient가 요구하는 Jackson 2 Bean의 부재였다.

그래서 해당 타입의 Bean만 제공했다.

수정 후에는 원격 AI 모드의 ApplicationContext 테스트와 전체 Gradle 테스트가 통과했다.

이 선택은 Jackson 3 전환을 끝낸 해법이 아니라, 기존 Jackson 2 기반 클라이언트를 유지하기 위한 호환 조치다. Spring Boot 공식 마이그레이션 가이드도 Jackson 3 전환을 우선 권장하며, Jackson 2 지원은 마이그레이션을 위한 임시 수단으로 설명한다. 장기적으로는 클라이언트까지 Jackson 3 타입으로 옮겨 두 버전이 공존하는 범위를 줄여야 한다.

배포 검증 로직도 실패를 놓치고 있었다

애플리케이션 기동 실패와 별개로 배포 검증 스크립트에도 문제가 있었다.

ECS는 이미 다음 상태를 보여주고 있었다.

runningCount = 0
pendingCount = 0
failedTasks = 1

이 정도면 새로운 태스크가 실패했다고 바로 판단할 수 있다. 하지만 기존 스크립트는 failedTasks 값을 정상적으로 처리하지 못했다.

실제 로그에는 다음 오류가 반복됐다.

line 57: [: : integer expression expected

AWS CLI 조회 결과가 빈 값이나 None으로 들어오자 Bash의 정수 비교가 실패한 것이다. 스크립트는 실패 태스크를 발견하고 종료하지 못했고, ECS 상태를 계속 조회하다가 제한 시간에 도달했다.

그래서 failedTasks를 비교하기 전에 안전하게 정규화했다.

case "$failed_tasks" in
  "" | "None" | "null" | *[!0-9]*) failed_tasks=0 ;;
esac

실패 태스크가 확인되면 더 이상 기다리지 않도록 조건도 바꿨다.

if [ "$failed_tasks" -gt 0 ]; then
  echo "PRIMARY ECS deployment has failed tasks"
  print_service_state
  print_service_events
  exit 1
fi

이제 같은 문제가 발생하면 의미 없는 타임아웃 대신 PRIMARY deployment의 상태와 최근 ECS 이벤트를 남기고 즉시 실패한다.

검증 스크립트가 애플리케이션 장애를 막아 주지는 않는다. 하지만 장애를 12분짜리 타임아웃으로 숨기지 않고, 처음 실패한 시점에 드러내 준다.

이번 장애에서 배운 점

첫 번째는 테스트 환경에서 실제 배포 조건을 활성화해야 한다는 점이다.

@SpringBootTest가 통과했다는 사실만으로 운영 설정의 ApplicationContext까지 정상이라고 볼 수 없다. 프로파일이나 프로퍼티에 따라 Bean 구성이 달라진다면 배포 환경과 같은 조건으로 기동하는 테스트가 필요하다.

두 번째는 같은 이름의 클래스라도 패키지가 다르면 전혀 다른 타입이라는 점이다.

Jackson 2: com.fasterxml.jackson.databind.ObjectMapper
Jackson 3: tools.jackson.databind.ObjectMapper

Spring Boot 메이저 버전을 올릴 때는 의존성 버전만 확인해서는 부족하다. 자동 구성으로 등록되는 Bean의 실제 타입과 기존 코드가 주입받는 타입도 함께 확인해야 한다.

세 번째는 ECS 서비스 전체 상태와 신규 deployment 상태를 분리해서 봐야 한다는 점이다.

이전 태스크가 살아 있으면 서비스의 runningCount는 정상처럼 보인다. 하지만 PRIMARY deployment의 runningCount=0, pendingCount=0, failedTasks>0라면 새 버전은 이미 실패한 상태다.

참고 자료

테스트 주도 개발 | 켄트 백

pp8817 — Wed, 5 Aug 2026 00:59:55 +0900

이 글은 Velog에서 이전한 글입니다. Velog 원문 보기

테스트가 코드를 이끄는 방식

켄트 백의 '테스트 주도 개발'은 개발자가 코드를 작성하는 순서를 바꾸자고 말하는 책이다.
내가 지금까지 코드를 작성한 흐름은

기능을 먼저 구현하고
어느 정도 완성된 뒤에 테스트한다.

하지만 TDD는 이 흐름을 역행한다.

먼저 테스트를 작성하고
그 테스트를 통과하는 코드를 만들고
마지막으로 코드를 정리한다.

처음에는 "이게 무슨 말이지?" 생각했다.
당연히 그럴만한게 이전까지의 나에게 테스트 코드란

내가 작성한 코드를 검증하는 것

이었기 때문이다. 당연히 코드가 있어야 테스트 코드를 작성할 수 있다고 생각했다. 코드도 없는데 어떻게 테스트를 작성할 수 있을까?

하지만 이 의문이 바로 TDD의 출발점이다.
테스트를 먼저 작성한다는 것은 '내가 만들 코드가 어떤 동작을 해야 하는지'를 먼저 정한다는 뜻이다.

요약: 구현보다 기대 동작을 앞세우는 것이다.

TDD가 해결하려는 문제

개발을 하다 보면 간단해 보이던 코드가 점점 다루기 어려워진다.
기능을 추가하고... 예외를 추가하고... 버그를 고치다 보면 어느 순간부터는 코드를 수정하는 일이 부담스러워진다.

테스트 코드가 부재할 때의 문제는 코드가 정상적으로 동작하는지 확인하는 과정에 있다. 테스트 코드가 없다면 흔히들 사용하는 Swagger, Postman, ... 등으로 직접 API 호출하며 점검해야 한다.
당연하게도 이런 방식은 느리고 불안정하다.

사람이 직접 개입하는 순간부터는 휴먼 에러(Human Error)를 무시할 수 없다.

더 큰 문제는 리팩토링에 있다.
리팩토링을 하는 과정에서 기존 동작에 영향을 줬는지 바로 확인할 수가 없으니 문제가 없는지 하나하나 확인해야 한다.
코드 규모가 크지 않다면 괜찮지만, 수만줄이 넘어가는 코드를 하나씩 점검한다는 것은 상상만 해도 식은땀이 난다.

TDD는 이 문제를 작은 피드백 루프로 해결한다. 한 번에 큰 기능을 만들지 않고, 아주 작은 기대 동작 하나를 테스트로 적는다.
그 테스트를 통과시키고, 다시 코드를 정리한다. 이 과정을 반복하면서 코드는 기능을 갖추고, 테스트는 안전망으로 쌓인다.

아주 작은 기대 동작?
코드가 만족해야 하는 가장 작은 단위의 행동을 뜻한다.

'할인 기능'을 예시로 들면, TDD식으로 작게 쪼개면 아래처럼 된다.

가격 10,000원에 할인율 10%를 넣으면 9,000원이 나온다.

가격 20,000원에 할인율 20%를 넣으면 16,000원이 나온다.

할인율이 0%면 원래 가격이 그대로 나온다.

TDD의 핵심 사이클

TDD는 흔히 Red, Green, Refactor라는 세 단계로 설명된다.

Red 단계

실패하는 테스트를 작성한다.
아직 구현이 없거나 부족하기 때문에 테스트는 실패해야 한다.

Green 단계

테스트를 통과하는 가장 단순한 코드를 작성한다.
이때 목표는 좋은 설계가 아니다. 일단 테스트를 초록색으로 만드는 것이다.
중복이 있거나 어색한 코드가 있어도 괜찮다.

Refactor 단계

테스트가 통과하는 상태를 유지한 채 코드를 정리한다.
이름을 바꾸고, 중복을 제거하고, 책임을 나눈다. 테스트가 있기 때문에 정리 과정에서 기존 동작이 깨졌는지 확인할 수 있다.

정리하면,

Red 단계에서는 기대하는 동작을 테스트로 먼저 작성한다. 아직 실제 코드가 없거나 구현이 부족하기 때문에 이 테스트는 실패한다. 여기서 중요한 점은 테스트가 내가 의도한 이유로 실패하는지 확인하는 것이다.
Green 단계에서는 Red 단계에서 작성한 테스트를 통과하는 가장 단순한 코드를 작성한다. 이 단계에서는 완벽한 설계나 역할 분리보다 테스트를 통과시키는 것이 우선이다.
Refactor 단계에서는 테스트가 계속 통과하는 상태를 유지하면서 Green 단계에서 작성한 코드를 정리한다. 중복을 제거하고, 이름을 다듬고, 책임과 구조를 더 명확하게 만든다.

간단한 예제로 이해하기

예를 들어 할인 가격을 계산하는 함수를 만든다고 해 보자. 가격이 10,000원이고 할인율이 10퍼센트라면 결과는 9,000원이어야 한다.

먼저 Red 단계에서 테스트를 작성한다.

def test_discount_price():
    assert discount_price(10000, 10) == 9000

당연히 테스트는 실패한다. discount_price라는 함수가 아직 없기 때문이다.

이제 Green 단게에서 테스트가 통과하는 최소한의 코드를 작성한다.

def discount_price(price, rate):
    return 9000

이 코드는 개발자에게는 최악의 코드처럼 보일 것이다.
입력값을 전혀 사용하지 않고 무조건 9,000을 반환한다.
하지만 첫 번째 테스트는 통과한다. TDD에서는 이런 식의 '가짜 구현'도 허용된다. 중요한 것은 처음부터 필요 이상의 일반화를 하지 않는 것이다.

이제 두 번째 테스트를 추가한다.

def test_discount_price():
    assert discount_price(10000, 10) == 9000
    assert discount_price(20000, 20) == 16000

이제 하드코딩은 더 이상 통하지 않는다. 테스트가 더 일반적인 구현을 요구한다.

def discount_price(price, rate):
    return price * (100 - rate) // 100

이 흐름이 TDD의 핵심을 잘 보여 준다.
처음부터 완벽한 공식을 떠올려서 구현하는 것이 아니라, 테스트가 요구하는 만큼 코드를 발전시킨다. 필요가 실제로 드러났을 때만 일반화한다.

세 가지 구현 전략

책에서는 TDD를 진행할 때 사용할 수 있는 몇 가지 전략을 보여 준다.

핵심은 무리하게 똑똑한 코드를 쓰지 않는 것이다.

첫 번째는 가짜 구현이다.

앞의 예시처럼 일단 정해진 값을 반환해서 테스트를 통과시키는 방식이다. 보기에는 허술하지만, 현재 테스트가 요구하는 최소 동작을 빠르게 확인할 수 있다.

두 번째는 삼각측량이다.

하나의 테스트만으로는 일반화할 근거가 부족할 때 테스트를 하나 더 추가한다. 서로 다른 두 사례가 생기면 코드가 어떤 방향으로 일반화되어야 하는지 더 분명해진다.

세 번째는 명백한 구현이다.

너무 뻔한 경우에는 바로 일반적인 구현을 작성한다. 예를 들어 두 숫자를 더하는 함수라면 굳이 가짜 구현부터 시작할 필요가 없다. 다만 이때도 테스트를 통해 동작을 확인하는 리듬은 유지한다.

이 전략들의 공통점은 추측을 줄인다는 데 있다.
TDD는 '나중에 필요할 것 같으니까'라는 이유로 코드를 늘리지 않는다.

테스트가 설계를 이끄는 방식

TDD에서 테스트는 단순한 검증 도구가 아니다. 테스트는 설계 도구다.
테스트를 먼저 쓰려면 내가 만들 코드를 어떻게 사용할지 먼저 생각해야 한다.

함수 이름은 무엇이 자연스러운지, 입력값은 어떤 형태여야 하는지, 결과는 어떻게 확인할 수 있어야 하는지 고민하게 된다.

테스트는 코드의 외부 인터페이스를 먼저 드러낸다.

좋은 테스트는 읽기 쉬운 사용 예시가 된다. 나중에 코드를 처음 보는 사람도 테스트를 보면 이 코드가 어떤 상황에서 어떤 결과를 내야 하는지 이해할 수 있다.

def test_sum_empty_list_is_zero():
    assert sum_numbers([]) == 0

def test_sum_multiple_numbers():
    assert sum_numbers([1, 2, 3]) == 6

이 테스트들은 단순히 오류를 잡는 장치가 아니다. sum_numbers라는 함수가 어떤 입력을 받고, 빈 배열을 어떻게 처리하며, 여러 숫자를 어떻게 계산하는지 설명한다. 테스트가 문서처럼 작동하는 것이다.

TDD의 장점

TDD의 가장 큰 장점은 빠른 피드백이다. 코드를 조금 바꾼 뒤 바로 테스트를 실행하면 방금 한 변경이 의도대로 동작하는지 알 수 있다. 비용이 낮아지면 개발자는 더 자주 확인하게 된다.

두 번째 장점은 리팩터링이 쉬워진다는 점이다. 테스트가 없으면 코드를 정리하는 일은 위험하다. 하지만 테스트가 있으면 기존 동작이 유지되는지 확인하면서 구조를 바꿀 수 있다.

개인적으로 가장 강력한 장점이라고 생각한다.

세 번째 장점은 불필요한 코드를 줄인다는 점이다. TDD는 테스트가 요구하는 코드만 작성하게 만든다. 아직 필요하지 않은 추상화, 설정, 확장 포인트를 미리 만들지 않는다.

네 번째 장점은 설계가 사용성 중심으로 바뀐다는 점이다. 테스트를 먼저 쓰면 코드를 사용하는 입장에서 API를 생각하게 된다. 자연스럽게 호출하기 쉬운 코드, 확인하기 쉬운 코드, 분리하기 쉬운 코드가 된다.

TDD의 한계와 오해

TDD가 모든 문제의 정답은 아니다. UI의 시각적 완성도, 복잡한 외부 시스템 연동, 성능 튜닝처럼 테스트만으로 판단하기 어려운 영역도 있다. 이런 영역에서는 다른 검증 방법이 함께 필요하다.

또 TDD를 한다고 해서 좋은 설계가 자동으로 생기는 것도 아니다. 테스트를 너무 구현 세부사항에 묶어 두면 오히려 리팩터링을 방해할 수 있다. 좋은 테스트는 내부 구현보다 외부 동작을 검증해야 한다.

가장 흔한 오해는 TDD가 테스트를 많이 쓰는 방법이라는 것이다. 핵심은 양이 아니라 순서다. 테스트를 먼저 쓰고, 작은 피드백을 반복하며, 동작을 보존한 채 설계를 개선하는 흐름이 중요하다.

실제 프로젝트에 적용하는 방법

처음부터 모든 기능을 TDD로 만들 필요는 없다. 작고 순수한 로직부터 시작하는 것이 좋다. 계산 함수, 문자열 처리, 검증 로직, 정책 판단처럼 입력과 출력이 분명한 코드가 적합하다.

적용 순서는 단순하다.

만들 기능을 한 문장으로 적는다.
그 기능이 성공했다는 증거를 테스트로 작성한다.
테스트가 실패하는지 확인한다.
테스트를 통과하는 최소 코드를 작성한다.
중복과 어색한 이름을 정리한다.
다음 테스트를 추가한다.

처음에는 속도가 느려질 수 있다. 하지만 중요한 것은 속도가 아니라 리듬을 익히는 것이다. 테스트를 작게 쓰고, 구현을 작게 하고, 정리를 작게 하는 감각이 쌓이면 코드 변경에 대한 두려움이 줄어든다.

책을 읽고 남는 태도

이 책에서 가장 크게 남는 태도는 '작은 것부터 하나씩'이다.
큰 설계를 한 번에 완성하려 하지 말고, 작은 테스트 하나로 다음 행동을 정한다. 불확실한 상황에서 가장 확실한 한 걸음을 고르는 방식이다.

또 하나는 '필요해질 때까지 기다리라'는 태도다. 개발자는 미래를 예측해 코드를 복잡하게 만들기 쉽다. TDD는 그 충동을 제어한다. 지금 테스트가 요구하지 않는 코드는 지금 필요하지 않은 코드일 가능성이 높다.

마지막으로 TDD는 개발을 더 안전한 활동으로 만든다. 테스트가 쌓이면 코드는 고정되는 것이 아니라 바꿀 수 있는 대상이 된다. 변경할 수 있는 코드가 좋은 코드라는 점에서, TDD는 단순한 테스트 작성법보다 더 넓은 개발 철학에 가깝다.

결론

'테스트 주도 개발'은 오래된 책이지만 여전히 유효하다. 프레임워크와 언어는 바뀌었지만, 개발자가 겪는 불안은 크게 달라지지 않았다. 내가 작성한 코드가 제대로 동작하는지, 고쳐도 괜찮은지, 지금 만든 설계가 과한 것은 아닌지 계속 고민하게 된다.

TDD는 이 고민을 한 번에 해결하지 않는다. 대신 아주 작은 단위로 쪼갠다. 실패하는 테스트를 쓰고, 통과시키고, 정리한다. 이 짧은 반복이 쌓이면 코드는 점점 기능을 갖추고, 테스트는 변경을 지탱하는 안전망이 된다.

그래서 이 책은 테스트를 배우려는 사람뿐 아니라, 코드를 더 단순하게 만들고 싶은 개발자에게도 의미가 있다. TDD는 더 많은 코드를 쓰는 기술이 아니다. 필요한 코드만 쓰고, 그 코드가 계속 바뀔 수 있게 만드는 기술이다.

앱 웹뷰 도입 후 Refresh Token 구조를 다시 설계한 이유

pp8817 — Wed, 5 Aug 2026 00:59:36 +0900

이 글은 Velog에서 이전한 글입니다. Velog 원문 보기

들어가며

척척학사는 본래 웹 서비스 중심으로 운영되고 있었다.

기존 인증 구조에서는 사용자가 로그인하면 서버가 Access Token과 Refresh Token을 발급했다.

refresh_token
- user_id  PK
- token
- expiry

이 구조에는 하나의 가정이 숨어 있었다.

한 사용자는 동시에 하나의 Refresh Token만 가진다.

웹 서비스만 운영할 때는 이 가정이 크게 문제 되지 않았다.
대부분의 사용 흐름이 브라우저라는 하나의 진입점에서 시작됐고, 같은 계정으로 여러 클라이언트 환경에 동시에 로그인하는 상황도 많지 않았다.

그런데 별도 앱 서비스가 붙으면서 상황이 달라졌다.

척척학사는 웹, 앱 서비스가 별도의 기능을 가지고 있었다.
앱: 에브리타임의 시간표 기능을 이용하지 못하는 수원대 학우들을 위한 시간표 서비스
웹: 학점 관리 및 졸업 요건 분석 서비스

기존 척척학사 앱은 시간표 기능만 제공하고 있었는데, 이번에 앱 안의 웹뷰로 척척학사 웹 서비스를 보여주게 됐다.
사용자는 이제 브라우저에서도 척척학사에 들어오고, 앱 웹뷰에서도 같은 웹 서비스에 들어올 수 있게 됐다.

물리적으로는 같은 사용자의 같은 서비스 접근이다.
하지만 인증 관점에서는 서로 다른 클라이언트 세션이 생긴다. 브라우저와 앱 웹뷰는 토큰 저장 공간이 다르고, 각각 독립적으로 로그인과 refresh API 호출을 수행한다.

서버 입장에서는 다중 기기 로그인과 비슷한 상황이 만들어진 것이다.

이때 기존 Refresh Token 저장 구조의 약점이 드러났다.
Refresh Token을 userId 기준으로 하나만 저장하고 있었기 때문이다.

기존 구조의 문제

단일 클라이언트만 생각하면 userId를 primary key로 쓰는 구조도 동작한다.

사용자가 로그인하면 서버는 Refresh Token을 저장한다.
이후 토큰 재발급 API가 호출되면 요청으로 들어온 Refresh Token과 DB에 저장된 Refresh Token을 비교한다. 두 값이 같으면 새 Access Token을 발급한다.

문제는 같은 계정으로 두 클라이언트에서 로그인할 때 생긴다.

이런 경우 브라우저 사용자는 정상적으로 로그인했고, 정상적으로 refresh API를 호출했다.

하지만 앱 웹뷰에서 같은 계정으로 로그인하면서 DB row가 덮어씌어 지고 브라우저 사용자의 Refresh Token은 유효하지 않은 토큰이 된다.
그래서 브라우저에서 토큰 재발급 API를 호출하면 토큰 불일치가 발생한다.

문제의 핵심은 Refresh Token 자체가 아니라 저장 기준이었다.

기존 구조는 사용자를 기준으로 Refresh Token을 하나만 보관했다.
하지만 실제로는 같은 사용자에게도 브라우저 세션과 앱 웹뷰 세션이 따로 존재할 수 있다. 사용자 단위로는 하나지만, 로그인 세션 단위로는 여러 개일 수 있는 것이다.

1차 완화책: Refresh Token을 매번 갱신하지 않기

빠르게 문제를 줄이는 방법은 refresh API가 호출될 때마다 Refresh Token을 새로 발급하지 않는 것이다.

기존에는 refresh API 호출 시점마다 Access Token과 Refresh Token을 함께 재발급했다.
이 방식은 보안상 토큰 탈취 피해를 줄이는 장점이 있지만, userId 단일 row 구조에서는 충돌을 더 자주 만든다.

그래서 1차 완화책으로는 만료까지 충분히 남아 있으면 Access Token만 새로 발급하고, Refresh Token은 그대로 유지하도록 바꿀 수 있다.

예시로 아래의 경우에만 Refresh Token을 갱신한다.

운영: 만료까지 7일 이하

개발: 만료까지 2일 이하

이 방식은 충돌 빈도를 줄인다.

브라우저와 앱 웹뷰가 refresh API를 자주 호출하더라도 DB에 저장된 Refresh Token이 매번 바뀌지는 않는다. 따라서 한쪽의 refresh 요청이 다른 쪽 세션을 계속 깨뜨리는 상황을 어느 정도 줄일 수 있다.

하지만 근본적인 문제를 해결하지 못한다.

DB row가 여전히 userId 기준 하나뿐이기 때문이다. 만료가 가까워지는 시점에는 결국 Refresh Token을 새로 발급해야 한다. 그때 한 클라이언트의 갱신이 다른 클라이언트의 토큰을 다시 덮어쓸 수 있다.

1차 완화책은 충돌을 없애는 방법이 아니라, 충돌이 일어나는 횟수를 줄이는 방법일 뿐이다.

근본 해결책: Refresh Token을 로그인 세션 단위로 저장하기

근본적으로는 저장 기준을 바꿔야 했다.

Refresh Token은 사용자에게 속하지만, 실제 생명주기는 로그인 세션 단위로 움직인다.

한쪽에서 Refresh Token을 rotate해도 다른 쪽 토큰이 깨지면 안 된다.

그래서 Refresh Token JWT 안에 sid claim을 추가했다.

sid: 서버가 로그인 성공 시점에 발급하는 UUID

public RefreshTokenWithExpiry createRefreshToken(String userId) {
    return createRefreshToken(userId, UUID.randomUUID().toString());
}

같은 사용자가 브라우저와 앱 웹뷰에서 로그인하면 서로 다른 sid가 생긴다.

브라우저 로그인.
userId=U, sid=S1, token=RT_BROWSER.

앱 웹뷰 로그인.
userId=U, sid=S2, token=RT_WEBVIEW.

DB 스키마도 userId PK가 아니라 session_id PK로 바꾼다.

refresh_token
- session_id  PK
- user_id
- token
- expiry

구조를 그림으로 보면 이렇게 바뀐다.

이제 같은 사용자의 Refresh Token도 여러 row로 저장된다.

session_id=S1, user_id=U, token=RT_BROWSER
session_id=S2, user_id=U, token=RT_WEBVIEW

브라우저의 refresh는 S1 row만 갱신한다.
앱 웹뷰의 refresh는 S2 row만 갱신한다. 서로의 토큰을 덮어쓰지 않는다.

토큰 재발급 API는 어떻게 바뀌나

토큰 재발급 API에서는 요청으로 들어온 Refresh Token을 먼저 파싱한다.
여기서 subject로 userId를 얻고, claim에서 sid를 읽는다.

Claims claims = jwtProvider.parseToken(refreshToken);
String userId = claims.getSubject();
String sessionId = resolveSessionId(claims, userId);

RefreshToken saved = refreshTokenRepository.findById(sessionId)
        .orElseThrow(...);

그 다음 DB에 저장된 토큰과 요청 토큰이 정확히 같은지 비교한다.

if (!saved.getToken().equals(refreshToken)) {
    throw new TokenException(ErrorCode.REFRESH_TOKEN_MISMATCH);
}

sid는 DB row를 찾기 위한 식별자일 뿐이다. 실제 Refresh Token이 유효한지는 DB에 저장된 토큰 문자열과 요청 토큰 문자열이 일치하는지로 판단해야 한다.

새 Refresh Token을 발급할 때는 기존 sid를 유지한다.

AuthDto.RefreshTokenWithExpiry newRefresh =
        jwtProvider.createRefreshToken(userId, sessionId);

save(sessionId, userId, newRefresh.token(), newRefresh.expiry());

여기가 중요하다. refresh 시점에 sid를 새로 만들면 같은 로그인 세션의 연속성이 끊긴다. 토큰 문자열은 rotate하되, 세션 식별자는 유지해야 한다.

전체 흐름은 이렇게 된다.

이 구조에서는 브라우저와 앱 웹뷰가 같은 계정으로 로그인해도 각자의 세션 row만 갱신한다.

왜 deviceId를 쓰지 않았나

이 문제를 보면 “기기별로 관리해야 하니 deviceId를 받으면 되지 않나”라고 생각할 수 있다.

하지만 이번 문제의 본질은 물리 기기를 식별하는 것이 아니었다. 브라우저와 앱 웹뷰처럼 서로 다른 로그인 세션을 분리하는 것이 핵심이었다.

클라이언트가 안정적인 deviceId를 제공하지 않는 상황에서 서버가 기기를 추정하려고 하면 설계가 더 복잡해진다.
IP, User-Agent, OS 정보는 신뢰하기 어렵고 개인정보 관점에서도 불필요한 수집이 될 수 있다.

서버가 UUID 기반 sid를 발급하면 API contract를 바꾸지 않고도 세션을 분리할 수 있다.

나중에 로그인된 기기 목록이나 특정 기기 로그아웃 기능이 필요해지면 그때 deviceName이나 client deviceId를 추가하면 된다. 이번 단계에서는 세션 분리가 목적이었다. 그래서 서버 발급 sid가 더 단순하고 안전한 선택이었다.

기존 Refresh Token 호환

기존에 발급된 Refresh Token에는 sid가 없다. 배포 직후 기존 사용자를 모두 로그아웃시키지 않으려면 fallback이 필요했다.

그래서 sid가 없으면 userId를 session id처럼 사용한다.

private String resolveSessionId(Claims claims, String userId) {
    String sessionId = claims.get("sid", String.class);
    if (sessionId == null || sessionId.isBlank()) {
        return userId;
    }
    return sessionId;
}

migration에서도 기존 row의 session_id를 user_id로 채운다.

ALTER TABLE public.refresh_token
    ADD COLUMN IF NOT EXISTS session_id VARCHAR(255);

UPDATE public.refresh_token
SET session_id = user_id
WHERE session_id IS NULL;

ALTER TABLE public.refresh_token
    DROP CONSTRAINT IF EXISTS pk_refresh_token;

ALTER TABLE public.refresh_token
    ADD CONSTRAINT pk_refresh_token PRIMARY KEY (session_id);

이렇게 하면 기존 Refresh Token도 한 번 더 refresh할 수 있다. 기존 토큰에는 sid가 없으므로 userId fallback으로 row를 찾는다. 이후 새로 발급되는 Refresh Token에는 sid가 들어간다.

호환성의 핵심은 두 가지다.

첫째, DB에는 기존 row를 찾을 수 있도록 session_id=user_id 값을 채워 둔다. 둘째, 코드에서는 sid가 없는 토큰을 만났을 때 userId fallback을 사용한다.

테스트로 확인한 것

이 변경은 인증 흐름과 DB schema를 함께 바꾸는 작업이라 테스트도 같이 보강했다.

JwtProvider 테스트에서는 Refresh Token에 sid가 들어가는지 확인했다. 같은 사용자에게 Refresh Token을 여러 번 발급해도 sid가 매번 달라지는지도 확인했다. 반대로 refresh API에서 토큰을 재발급할 때는 기존 sid를 유지할 수 있어야 한다.

RefreshTokenService 테스트에서는 refresh API가 sid 기준으로 row를 조회하는지 확인했다. 요청 토큰과 DB 토큰이 다르면 mismatch가 발생해야 하고, sid가 없는 기존 토큰은 userId fallback으로 처리되어야 한다.

Flyway migration 테스트에서는 V5 migration 이후 refresh_token 테이블에 session_id 컬럼이 생기고, primary key가 session_id로 바뀌는지 확인했다.

이 테스트들이 있어야 나중에 누군가 Refresh Token 저장 구조를 다시 건드리더라도 다중 세션 문제가 재발했는지 바로 알 수 있다.

정리

처음 문제는 단순해 보였다. 같은 계정으로 브라우저와 앱 웹뷰에 로그인했더니 한쪽 Refresh Token이 깨졌다.

원인은 Refresh Token을 userId 기준으로 하나만 저장하던 구조였다.
웹 서비스만 있을 때는 잘 드러나지 않았지만, 앱 웹뷰가 붙으면서 하나의 사용자가 여러 클라이언트 세션을 갖게 됐다. 기존 저장 모델이 그 상황을 버티지 못한 것이다.

1차 완화책은 Refresh Token 갱신 빈도를 줄여 충돌 가능성을 낮춘다.

운영 중인 문제를 빠르게 줄이는 데는 도움이 된다. 하지만 userId 단일 row 구조가 그대로 남기 때문에 충돌 가능성을 완전히 없애지는 못한다.

근본 해결책은 저장 모델을 바꾸는 것이다.

Refresh Token을 사용자 단위가 아니라 로그인 세션 단위로 관리한다. sid를 JWT에 넣고, DB는 session_id를 primary key로 사용한다. 그러면 브라우저와 앱 웹뷰가 같은 계정으로 로그인해도 서로의 토큰을 덮어쓰지 않는다.

[Saynow] LLM Workflow 개선기 - availableOptions를 버리고 RAG로 간 이유

pp8817 — Wed, 5 Aug 2026 00:59:18 +0900

이 글은 Velog에서 이전한 글입니다. Velog 원문 보기

SayNow의 AI 서버를 손보면서 처음에는 프롬프트만 잘 고치면 된다고 생각했다. 메뉴 추천 요청에서 하트가 깎이고, That’s all. 같은 자연스러운 답변이 실패처럼 처리되는 문제였기 때문이다.

하지만 테스트를 계속하다 보니 이건 단순한 프롬프트 문제가 아니었다. LLM을 어느 단계에서 어떻게 쓰는지, 그리고 어떤 정보를 어디에 저장할지에 가까운 문제였다.

이 글은 SayNow에서 next-question, feedback, 도움 요청을 어떤 workflow로 나눴는지 정리한 글이다.

모든 LLM 작업을 같은 구조로 묶지 않았다

LLM을 쓰는 구조는 여러 가지가 있다.

가장 단순한 구조는 단일 모델 호출이다. 입력을 넣고 응답을 받는다. 분류, 짧은 생성, 간단한 변환에는 이 방식이 빠르고 관리하기 쉽다.

조금 더 복잡한 구조는 멀티스텝이다. 한 번의 LLM 호출에 모든 책임을 넣지 않고, 중간에 검증이나 후처리를 둔다. 실패 지점을 나눠 볼 수 있고 테스트하기도 쉽다.

RAG는 외부 지식을 검색한 뒤 LLM 응답에 넣는 구조다. 이미 있는 문서나 누적된 지식을 바탕으로 답해야 할 때 맞다.

Agent Loop는 모델이 계획을 세우고 도구를 부르고, 결과를 보고 다시 판단하는 구조다. 강력하지만 지연 시간과 실패 지점도 늘어난다.

SayNow에는 하나의 정답 구조를 고르지 않았다. 기능마다 요구가 달랐기 때문이다.

영역	선택한 구조	이유
꼬리 질문	단일 모델 중심	대화 중 바로 응답해야 해서 빠른 처리가 중요하다
최종 피드백	멀티스텝	품질, 점수, 턴별 피드백을 더 꼼꼼히 봐야 한다
도움 요청	RAG 분기	메뉴, 추천, 원두 질문처럼 추가 정보가 필요하다
전체 대화	Agent Loop 제외	현재 문제는 반복 계획이나 도구 자동화가 아니다

즉 개선 후에도 꼬리 질문은 단일 모델 중심이다. 다만 사용자가 도움을 요청한 순간만 RAG 분기로 빠진다.

기존 구조의 한계

기존 next-question 흐름은 이렇게 단순했다.

이 구조는 슬롯 답변을 처리하기에는 충분했다.

사용자가 Small iced Americano, please.라고 말하면 drink와 size를 채우면 된다. 사용자가 I want drink.라고 말하면 구체 음료가 아니므로 INVALID_RESPONSE로 볼 수 있다.

하지만 사용자가 질문을 던지면 이야기가 달라진다.

Can you recommend a menu?
What beans do you use?
Do you have decaf?
Can I get it with oat milk?

이 발화들은 슬롯을 채우지 않는다. 그렇다고 실패 발화도 아니다. 사용자가 시나리오를 이어가기 위해 필요한 정보를 요청한 것이다.

처음에는 이 문제를 availableOptions로 풀려고 했다.

왜 `availableOptions`를 버렸나

availableOptions는 단순하고 직관적이었다. 백엔드가 아래처럼 메뉴 정보를 넘겨주면 AI가 그 목록을 보고 답한다.

Available options=drink: iced Americano, latte, tea

그러면 I need a menu 같은 요청에 이렇게 답할 수 있다.

{
  "turnClassification": "ASSISTANCE_REQUEST",
  "filledSlots": [],
  "nextQuestion": "The drink options are iced Americano, latte, and tea. What would you like to order?"
}

메뉴 요청만 보면 좋은 해결책처럼 보였다. 실제 Prompt 8 live 테스트에서도 I need a menu, Can I get a menu?, Menu please.는 잘 처리됐다.

그런데 이 방식은 질문이 조금만 넓어져도 무거워진다.

사용자가 원두를 물으면 원두 정보를 넣어야 한다. 디카페인을 물으면 디카페인 여부를 넣어야 한다. 단맛, 우유 변경, 알레르기, 가격, 사이즈 정책까지 대비하려면 시나리오마다 옵션성 데이터를 계속 늘려야 한다.

카페만 해도 이런데, 앞으로 공항, 호텔, 식당으로 확장하면 필드는 더 늘어난다. 카테고리별 프롬프트를 따로 만드는 방법도 생각했지만, 그것도 같은 문제를 다른 곳으로 옮길 뿐이었다.

결국 문제는 “메뉴 목록을 어떻게 넘길 것인가”가 아니었다. 사용자가 예상하지 못한 도움 요청을 했을 때, 어떻게 대화 흐름을 깨지 않고 받아줄 것인가였다.

그래서 availableOptions를 백엔드 계약에서 제거했다.

새 구조는 `ASSISTANCE_REQUEST`만 RAG로 보낸다

개선 구조는 아래와 같다.

여기서 RAG는 전체 대화를 대신 처리하지 않는다.

ANSWER는 기존처럼 슬롯을 채운다. INVALID_RESPONSE는 하트 정책으로 보낸다. RAG는 ASSISTANCE_REQUEST일 때만 돈다.

이렇게 나누면 빠른 대화 흐름을 유지하면서도, 메뉴나 원두 같은 도움 요청에는 더 구체적으로 답할 수 있다.

검색 대상은 인터넷이 아니라 내부 벡터 DB다

이번 구조에서 RAG는 인터넷 검색이 아니다.

SayNow의 목표는 실제 카페 정보를 맞히는 것이 아니라, 영어 회화 연습을 자연스럽게 이어가는 것이다. 따라서 검색 대상은 웹이 아니라 SayNow 내부에 쌓인 질문과 답변이다.

검색 흐름은 단순하다.

비슷한 답변이 있으면 재사용한다. 없으면 gpt-4o-mini가 역할극에 맞는 일반 답변을 만든다.

예를 들어 What beans do you use?에 검색 결과가 없으면 아래처럼 답한다.

{
  "turnClassification": "ASSISTANCE_REQUEST",
  "filledSlots": [],
  "nextQuestion": "We usually use medium-roasted Arabica beans. What would you like to order?",
  "translatedQuestion": "보통 중간 로스팅 아라비카 원두를 사용해요. 무엇을 주문하시겠어요?"
}

이 답변은 실제 매장의 사실을 보장하려는 답변이 아니다. 역할극 안에서 사용자가 다음 발화를 이어갈 수 있게 돕는 답변이다.

저장하는 데이터

벡터 DB에는 최종 답변만 저장하지 않는다. 질문이 어떤 시나리오에서 나왔는지 같이 저장해야 재사용할 수 있다.

{
  "scenarioTitle": "카페에서 주문하기",
  "scenarioGoal": "원하는 음료를 자연스럽게 주문할 수 있다.",
  "originalQuestion": "What would you like to order?",
  "userUtterance": "What beans do you use?",
  "assistantAnswer": "We usually use medium-roasted Arabica beans. What would you like to order?",
  "turnClassification": "ASSISTANCE_REQUEST",
  "answerSource": "generated",
  "qualityStatus": "generated",
  "usageCount": 1
}

qualityStatus는 세 단계로 나눴다.

상태	의미
`generated`	방금 AI가 만든 답변이다
`candidate`	반복되었거나 품질이 괜찮아 검색 재사용 후보로 볼 수 있다
`approved`	운영자가 재사용해도 된다고 판단한 답변이다

MVP에서는 처음부터 모든 답변을 검수하지 않는다. 대신 생성된 도움 요청을 저장하고, 같은 시나리오 안에서 같은 질문이 반복되면 candidate로 자동 승격한다.

기준은 단순하게 잡았다.

같은 scenario_title 안에서 정규화된 user_utterance가 2회 이상 generated로 저장되면 candidate가 된다. 정규화할 때는 대소문자, 연속 공백, 문장부호 차이를 제거한다.

예를 들어 아래 두 문장은 같은 반복 질문으로 본다.

Can I see the menu?
can   i see the menu

이 기준이 운영 데이터에서 너무 느슨하거나 빡빡한지는 계속 봐야 한다.

API 경계는 유지했다

이번 변경에서 중요하게 본 것은 백엔드와 AI 서버의 계약을 크게 흔들지 않는 것이었다.

백엔드는 기존처럼 질문, 사용자 발화, 시나리오 정보, 슬롯 상태를 넘긴다.

{
  "originalQuestion": "What would you like to order?",
  "userUtterance": "What beans do you use?",
  "scenarioTitle": "카페에서 주문하기",
  "scenarioGoal": "원하는 음료를 자연스럽게 주문할 수 있다.",
  "slots": [
    {
      "slotName": "drink",
      "filled": false
    }
  ]
}

응답도 기존 구조를 유지한다.

{
  "nextQuestion": "We usually use medium-roasted Arabica beans. What would you like to order?",
  "translatedQuestion": "보통 중간 로스팅 아라비카 원두를 사용해요. 무엇을 주문하시겠어요?",
  "filledSlots": [],
  "turnClassification": "ASSISTANCE_REQUEST"
}

백엔드는 turnClassification만 보면 된다.

값	처리
`ANSWER`	새로 충족된 슬롯을 반영한다
`ASSISTANCE_REQUEST`	하트를 깎지 않고 AI 응답을 보여준다
`INVALID_RESPONSE`	하트 차감 정책을 적용한다

RAG 검색, fallback 생성, 저장은 AI 서버 내부 책임이다.

구현과 검증

벡터 DB는 Supabase의 pgvector를 사용했다. 백엔드가 이미 Supabase DB를 쓰고 있었기 때문에, 별도 Vector DB를 새로 운영하지 않고 같은 DB 안에 ai_rag.assistance_knowledge 테이블을 두는 방향으로 잡았다.

AI 서버는 백엔드와 같은 DB_URL, DB_USERNAME, DB_PASSWORD로 접속할 수 있게 했다. 다만 백엔드 JDBC URL에 들어 있는 prepareThreshold 같은 JDBC 전용 파라미터는 psycopg 연결 전에 제거했다.

live 검증에서는 다음을 확인했다.

도움 요청 6건이 ai_rag.assistance_knowledge에 저장됐다.
모든 row에 embedding이 채워졌다.
generated row 하나를 candidate로 올린 뒤 같은 메뉴 질문을 다시 호출하니 answer_source=retrieved row가 새로 저장됐다.
같은 임시 도움 요청을 두 번 저장하자 두 row가 모두 quality_status=candidate로 자동 승격됐다.
검증용 row는 확인 뒤 삭제했다.

Prompt 9 테스트에서는 NQ-01부터 NQ-10, RAG-01부터 RAG-03, FB-01부터 FB-10까지 실제 gpt-4o-mini live 호출로 봤다.

Agent Loop를 쓰지 않은 이유

Agent Loop도 후보가 될 수 있다. 하지만 지금 문제에는 과했다.

사용자는 메뉴를 보거나 원두를 묻고 싶어 한다. AI는 짧게 답하고 다시 원래 질문으로 돌아오면 된다. 여러 도구를 반복 호출하면서 계획을 세울 필요가 없다.

Agent Loop를 넣으면 지연 시간이 늘고, 실패 지점도 늘어난다. 지금 단계에서는 ASSISTANCE_REQUEST 전용 RAG 분기가 더 작고 명확하다.

정리하며

이번 개선의 방향은 “모든 상황을 미리 모델링하지 않기”였다.

처음에는 메뉴 문제처럼 보였지만, 실제로는 사용자가 도움을 요청하는 모든 상황의 문제였다. 그걸 availableOptions 필드로 계속 확장하면 시나리오가 늘어날수록 관리가 어려워진다.

그래서 AI 서버 내부에서 일반화했다.

슬롯 답변은 그대로 처리한다. 실패 발화는 하트 정책으로 보낸다. 도움 요청만 RAG로 보내고, 비슷한 답변이 없으면 역할극 답변을 생성한다. 생성된 질문과 답변은 다시 벡터 DB에 쌓는다.

아직 남은 일도 있다. candidate 자동 승격 기준을 운영 데이터로 확인해야 하고, 어떤 답변을 approved로 올릴지 운영 정책도 필요하다. 추천 요청에 한 가지 메뉴를 줄지, 두세 가지 선택지를 줄지도 제품 UX로 정해야 한다.

그래도 방향은 정리됐다. 백엔드 계약은 크게 흔들지 않고, AI 서버 내부 workflow만 확장한다. 지금 SayNow에는 이 정도의 분리가 가장 현실적인 선택이었다.

[Saynow] 프롬프트 개선기 - Prompt 1에서 9까지

pp8817 — Wed, 5 Aug 2026 00:58:59 +0900

이 글은 Velog에서 이전한 글입니다. Velog 원문 보기

SayNow는 영어 회화 상황을 연습하는 서비스다. 사용자가 AI의 질문에 답하면, AI 서버는 그 발화가 시나리오에 필요한 정보를 채웠는지 판단한다. 백엔드는 그 결과를 보고 다음 질문을 이어가거나, 세션을 끝내거나, 하트를 깎는다.

처음에는 단순한 슬롯 채우기 문제처럼 보였다. 카페 주문 시나리오라면 drink, size 같은 슬롯이 있고, 사용자가 Small iced Americano, please.라고 말하면 두 슬롯을 채우면 된다.

문제는 사용자가 항상 슬롯 값만 말하지 않는다는 점이었다.

Can you recommend a menu?
Can I see the menu?
What beans do you use?
That’s all.

이런 말은 틀린 답이 아니다. 대화 흐름 안에서 충분히 자연스러운 발화다. 그런데 초기 구조에서는 이런 발화가 filledSlots=[]로 떨어졌고, 백엔드는 이것을 동문서답처럼 볼 수 있었다.

결과적으로 사용자는 메뉴를 물어봤을 뿐인데 하트가 깎이거나, 커스텀 음료 제작에서 That’s all.이라고 말했는데도 옵션을 더 고르라는 질문을 다시 받았다.

이 글은 그 문제를 Prompt 1부터 Prompt 9까지 고치면서 정리한 기록이다.

출발점은 `filledSlots=[]`였다

초기 next-question 응답은 대략 이런 형태였다.

{
  "filledSlots": [],
  "nextQuestion": "What drink would you like to order?",
  "translatedQuestion": "어떤 음료를 주문하시겠어요?"
}

이 구조만 보면 filledSlots=[]가 무엇을 뜻하는지 알기 어렵다.

정말로 사용자가 엉뚱한 말을 한 것일 수도 있다. 아직 슬롯을 채우지는 않았지만 메뉴나 추천을 물어본 것일 수도 있다. 또는 That’s all.처럼 더 이상 추가할 옵션이 없다는 뜻일 수도 있다.

서로 다른 상황이 같은 모양으로 내려오니 백엔드도 구분할 수 없었다. 그래서 처음 고친 지점은 슬롯 판단과 발화 성격 판단을 분리하는 것이었다.

{
  "filledSlots": [],
  "nextQuestion": "We have coffee, tea, and smoothies. What drink would you like to order?",
  "translatedQuestion": "커피, 차, 스무디가 있어요. 어떤 음료를 주문하시겠어요?",
  "turnClassification": "ASSISTANCE_REQUEST"
}

filledSlots는 여전히 “이번 발화로 새로 채운 슬롯”만 나타낸다. 대신 turnClassification이 생기면서 이 발화가 어떤 종류인지 따로 볼 수 있게 됐다.

최종적으로는 세 가지 상태만 남겼다.

상태	의미	백엔드 처리
`ANSWER`	사용자가 질문에 답했고 슬롯 판단이 가능하다	새로 채워진 슬롯을 반영한다
`ASSISTANCE_REQUEST`	메뉴, 추천, 원두, 정책처럼 추가 정보를 물었다	하트를 깎지 않고 AI 응답을 보여준다
`INVALID_RESPONSE`	오프토픽, 무의미한 발화, 거절, 불완전한 답변이다	하트 차감 후보로 본다

이 흐름을 그림으로 보면 아래와 같다.

처음에는 더 세분화된 상태도 생각했다. 추천 요청과 정보 요청을 나누거나, 옵션 완료 발화를 별도 상태로 빼는 식이었다. 하지만 실제 정책 경계는 그렇게 복잡하지 않았다. 백엔드가 알아야 하는 것은 “슬롯 답변인가”, “도움을 요청했는가”, “실패 발화인가”였다.

상태를 많이 만들수록 모델에게 맞혀야 할 라벨만 늘어난다. 그래서 의사결정에 필요한 최소 상태만 남겼다.

프롬프트를 길게 막기보다 방향을 잡았다

중간에 배운 프롬프트 원칙도 적용했다.

초기에는 “이런 표현은 슬롯으로 채우지 말라”, “저런 표현은 실패로 봐라” 같은 금지 규칙이 계속 늘어났다. 그 방식은 당장은 버그 하나를 막을 수 있지만, 프롬프트가 점점 딱딱해진다. 모델은 대화의 의도를 보지 못하고 금지 목록을 맞히는 쪽으로 움직이기 쉽다.

그래서 Prompt 8부터는 프롬프트를 섹션으로 나눴다.

역할
출력 스키마
판단 순서
슬롯 정책
도움 요청 정책
응답 정책
few-shot 예시

중요한 것은 모델에게 답을 억지로 강제하는 것이 아니라, 먼저 무엇을 판단해야 하는지 알려주는 것이었다. 예를 들어 “사용자 발화를 슬롯 답변, 도움 요청, 실패 발화 중 하나로 먼저 분류하라”는 식이다.

출력은 JSON 스키마를 유지했다.

{
  "filledSlots": [
    {
      "slotName": "drink"
    }
  ],
  "nextQuestion": "What size would you like?",
  "translatedQuestion": "어떤 사이즈로 드릴까요?",
  "turnClassification": "ANSWER"
}

이 구조 덕분에 prompt-only 실험을 해도 백엔드 계약과 맞춰서 볼 수 있었다.

테스트는 next-question과 feedback을 같이 봤다

처음에는 next-question만 보면 된다고 생각하기 쉽다. 하지만 실제 사용자 경험은 마지막 피드백까지 이어진다.

예를 들어 사용자가 That’s all.이라고 말했을 때 next-question에서는 세션이 잘 끝나도, feedback에서 “더 자연스럽게 말해보세요” 같은 교정이 붙으면 사용자 입장에서는 또 다른 버그처럼 느껴진다.

그래서 모든 프롬프트는 같은 입력으로 반복 측정했다.

next-question 10개
feedback 10개
필요할 때 추가 smoke test
실제 OpenAI gpt-4o-mini live 호출 결과만 결과 표에 반영
mocked unittest는 프롬프트 구조와 회귀 검증 용도로만 사용

공통 next-question 입력에는 이런 케이스가 들어갔다.

ID	입력	관찰 포인트
NQ-01	`Can you recommend a menu?`	추천 요청에서 하트가 깎이지 않는가
NQ-03	`Can I see the menu?`	메뉴 확인 요청을 실패로 보지 않는가
NQ-05	`I want drink.`	generic object를 실제 음료로 채우지 않는가
NQ-07	`That’s all.`	추가 옵션 없음으로 처리하는가
NQ-10	`Oat milk and no sugar, please.`	복합 옵션도 하나의 슬롯 답변으로 처리하는가

feedback도 별도로 봤다.

좋은 응답에는 불필요한 피드백이 없어야 한다. 어색한 표현은 한 단계만 자연스럽게 고쳐야 한다. 그리고 오프토픽이나 nonsense는 뜻을 억지로 주문 상황에 끼워 맞추면 안 된다.

이 기준을 같이 보지 않으면 next-question은 고쳤는데 feedback에서 다시 어색해지는 일이 생긴다.

Prompt 8은 절반만 맞았다

Prompt 8에서는 availableOptions를 도입했다. 백엔드가 메뉴 옵션을 넘겨주면, AI는 그 옵션을 근거로 메뉴를 보여주는 방식이다.

예를 들어 I need a menu가 들어오고 drink: iced Americano, latte, tea가 같이 들어오면 이런 응답이 나왔다.

{
  "filledSlots": [],
  "turnClassification": "ASSISTANCE_REQUEST",
  "nextQuestion": "The drink options are iced Americano, latte, and tea. What would you like to order?"
}

이 결과만 보면 괜찮았다. 사용자는 AI 응답 텍스트만 보고 실제 메뉴 후보를 알 수 있었다. 메뉴 요청이 INVALID_RESPONSE로 빠지지도 않았다.

하지만 곧 한계가 보였다.

사용자가 묻는 것은 메뉴만이 아니었다.

What beans do you use?
Do you have decaf?
Is this drink sweet?
Can I get it with oat milk?

이 질문까지 대비하려면 백엔드 DB에 메뉴, 원두, 디카페인, 재료, 맛, 정책 정보를 계속 넣어야 한다. 카페 하나만 보면 가능해 보이지만, 앞으로 공항, 호텔, 식당으로 시나리오가 늘어나면 관리 방식이 무거워진다.

그래서 availableOptions를 키우는 방향은 버렸다.

Prompt 9는 도움 요청을 RAG 분기로 보냈다

Prompt 9의 방향은 다르다.

백엔드 API 계약에는 새 필드를 늘리지 않는다. 대신 AI 서버 내부에서 ASSISTANCE_REQUEST로 분류된 발화만 별도 RAG workflow로 보낸다.

검색 결과가 있으면 그 답변을 근거로 사용한다. 검색 결과가 없으면 gpt-4o-mini가 역할극에 맞는 짧은 답변을 생성한다. 그 뒤에는 반드시 원래 시나리오 질문으로 돌아온다.

프롬프트에는 이 원칙을 넣었다.

The user can only use information that appears in your nextQuestion, so when the user asks for a menu, recommendation, options, rules, ingredients, policy, or details, answer the request briefly before asking the next short scenario question.
If retrieved assistance context is provided, use it as the factual basis for the assistance answer.
If no retrieved assistance context is provided, generate a plausible role-play answer that fits the scenario, then return to the current scenario question.

핵심은 “메뉴 옵션은 이렇습니다”처럼 빈 문장을 만들지 않는 것이다. 사용자는 AI 응답 텍스트만 본다. 따라서 도움 요청에 답할 때는 실제로 쓸 수 있는 정보를 응답 안에 넣어야 한다.

Prompt 9 live 테스트 결과는 이렇게 나왔다.

케이스	입력	결과
메뉴 추천	`Can you recommend a menu?`	`ASSISTANCE_REQUEST`, `We have coffee, tea, and smoothies...`
추천 요청	`What do you recommend?`	`ASSISTANCE_REQUEST`, `I recommend a latte or an iced coffee...`
메뉴 확인	`Can I see the menu?`	`ASSISTANCE_REQUEST`, `We have coffee, tea, and smoothies...`
메뉴 요청 추가 표현	`I need a menu`	`ASSISTANCE_REQUEST`, `We have Americano, latte, and tea...`
원두 질문	`What beans do you use?`	`ASSISTANCE_REQUEST`, `We usually use medium-roasted Arabica beans...`
디카페인 질문	`Do you have decaf?`	`ASSISTANCE_REQUEST`, `We do have decaf coffee...`

That’s all. 문제도 해결됐다.

입력	결과
`That’s all.`	`filledSlots=[customOptions]`, `turnClassification=ANSWER`, `nextQuestion=null`
`That's all.`	`filledSlots=[customOptions]`, `turnClassification=ANSWER`, `nextQuestion=null`

STT나 키보드 입력 때문에 apostrophe 모양이 달라져도 같은 정책으로 처리된다.

feedback도 같이 보정했다

Prompt 9에서는 feedback prompt도 조금 고쳤다.

이전에는 모든 턴이 좋은 응답이어도 summary가 교정처럼 읽히는 경우가 있었다. 사용자는 이미 잘 답했는데 “더 자연스럽게 고쳐보세요”라는 뉘앙스를 받게 된다.

그래서 모든 턴이 feedbackRequired=false인 세션에서는 summary도 교정처럼 쓰지 않도록 했다.

When every turn has feedbackRequired=false, feedbackSummary must not imply that the user needs correction; tell the user to maintain the clear expression instead.

live 테스트에서 좋은 주문 응답은 이렇게 정리됐다.

케이스	결과
`I would like a small iced Americano, please.`	`score=90`, `feedbackRequired=false`, `자연스러운 표현을 계속 유지하세요.`
성공 세션 전체	`score=92`, 모든 턴 `feedbackRequired=false`

다만 아직 남은 정책도 있다. Can you recommend a menu?는 대화 진행상 자연스러운 도움 요청이다. 하지만 feedback에서는 더 간결한 요청 표현인 What do you recommend?를 제안한다.

이걸 학습 피드백으로 볼지, 대화 진행을 위한 도움 요청으로 보고 피드백을 줄일지는 제품 정책으로 남겨뒀다.

지금 구조에서 얻은 것

Prompt 9 기준으로 얻은 변화는 분명하다.

문제	이전	이후
메뉴 추천 요청	`filledSlots=[]`만 보고 하트 차감 가능	`ASSISTANCE_REQUEST`로 분류하고 정보 제공
메뉴 확인 요청	옵션이 없으면 실질적 답변 부족	역할극 답변 또는 RAG 답변 제공
`That’s all.`	추가 옵션 없음으로 처리하지 못함	`customOptions` 완료 답변으로 처리
피드백 summary	좋은 응답에도 교정처럼 보일 수 있음	좋은 응답은 유지 방향으로 안내
예상 밖 질문	미리 넣은 옵션이 없으면 대응 어려움	RAG 검색 후 없으면 역할극 답변 생성

pgvector 저장도 확인했다. Supabase develop DB의 ai_rag.assistance_knowledge에 도움 요청 6건이 저장됐고, embedding도 채워졌다. Can I see the menu? row 하나를 candidate로 올린 뒤 다시 호출했을 때는 새 row가 answer_source=retrieved, quality_status=candidate로 저장됐다.

같은 임시 도움 요청을 두 번 저장했을 때 두 row가 모두 quality_status=candidate로 자동 승격되는 것도 확인했다.

정리하며

이번 작업에서 가장 크게 배운 점은 filledSlots=[] 하나로 너무 많은 의미를 표현하면 안 된다는 것이다.

슬롯을 채우지 않았다는 사실과 사용자가 틀렸다는 판단은 다르다. 메뉴를 물어보는 사용자는 실패한 사용자가 아니다. 커스텀 음료에서 That’s all.이라고 말하는 것도 옵션을 모르는 게 아니라, 더 추가할 게 없다는 뜻이다.

그래서 프롬프트는 더 많은 금지 규칙을 넣는 방향이 아니라, 모델이 먼저 봐야 할 판단 축을 분리하는 방향으로 바뀌었다.

다음으로 볼 것은 운영 데이터다. 반복 질문을 자동으로 candidate로 올리는 기준이 너무 느슨하지 않은지 봐야 한다. 그리고 도움 요청을 feedback에서 얼마나 교정할지도 정해야 한다.

프롬프트 실험은 한 번에 끝나지 않는다. 그래도 이제는 무엇을 봐야 하는지 조금 선명해졌다. next-question만 보지 않고 feedback까지 같이 보고, mocked test가 아니라 실제 gpt-4o-mini live 결과로 확인하는 흐름을 계속 유지하려고 한다.

[특강] AI 프로젝트를 위한 AI 모델 선택 노하우

pp8817 — Wed, 5 Aug 2026 00:58:40 +0900

이 글은 Velog에서 이전한 글입니다. Velog 원문 보기

영어 회화 서비스에 Realtime API를 써도 될까?

2026.05.23.
온라인 강의, 박성준 멘토님.

영어 회화 서비스에서 중요한 건 결국 두 가지다.
사용자가 실제로 대화하고 있다는 느낌을 받아야 하고, 피드백도 빠르게 돌아와야 한다.

기존에는 이 지점에서 병목이 컸다. 음성을 텍스트로 바꾸고, LLM이 답변을 만들고, 다시 음성으로 변환하는 과정을 순서대로 거치면 아무래도 느릴 수밖에 없다. 사용자는 “대화하고 있다”기보다 “응답을 기다리고 있다”는 느낌을 받게 된다.

그런데 이제는 상황이 조금 달라졌다. OpenAI Realtime API 같은 선택지가 생기면서, 초반 PoC 단계에서는 직접 모델을 띄우지 않고도 꽤 자연스러운 음성 대화 경험을 만들 수 있게 됐다.

직접 만들 것인가, API를 쓸 것인가

AI 서비스를 만들 때 보통 세 가지 선택지가 있다.

첫 번째는 모델을 직접 개발하는 방식이다. 성능과 구조를 가장 깊게 통제할 수 있지만, GPU 인프라와 학습 코드, 데이터가 모두 필요하다. 기간도 수주에서 수개월 단위로 잡아야 한다.

두 번째는 파인튜닝이다. 직접 모델을 만드는 것보다는 가볍지만, 그래도 학습 데이터와 튜닝 도구가 필요하다. 비용 최적화나 특정 도메인 말투, 출력 포맷을 맞추는 데는 의미가 있다.

세 번째는 API 활용이다. 비용은 사용량에 따라 나가지만, SDK만 붙이면 바로 시작할 수 있다. SW Maestro처럼 기간이 제한된 프로젝트에서는 대부분 이 선택지가 현실적이다.

강의에서도 결론은 명확했다. 4개월 안에 PoC와 MVP를 만들어야 한다면, 처음부터 모델 개발에 들어가기보다 API로 빠르게 검증하는 편이 낫다.

모델 학습이 적합한 경우도 분명 있다. 프로젝트 목표 자체가 새로운 아키텍처나 학습 기법을 연구하는 것이라면 모델을 직접 다루는 게 맞다. 기존 API가 도저히 해결하지 못하는 태스크이거나, 모델 자체가 결과물인 경우도 마찬가지다.

하지만 그 외의 대부분의 서비스형 프로젝트는 API부터 시작하는 것이 안전하다. 프론티어 모델 성능이 이미 충분히 높고, 프롬프트 수정만으로 개선할 수 있는 문제를 굳이 재학습으로 풀 필요는 없다.

음성 서비스의 병목

음성 기반 서비스에는 보통 세 가지 모델이 필요하다.

STT.
LLM.
TTS.

문제는 이 세 단계를 모두 파이프라인으로 처리하면 속도가 느려진다는 점이다. STT가 끝나야 LLM이 시작되고, LLM이 끝나야 TTS가 시작된다. 이렇게 직렬로 이어지면 사용자는 매 턴마다 대기 시간을 느낀다.

영어 회화 서비스에서는 이 지연이 더 크게 체감된다. 회화는 텍스트 QA보다 리듬이 중요하기 때문이다. 답변이 조금 늦어지는 것만으로도 실제 대화감이 깨진다.

그래서 우리 서비스에서는 초반부터 Realtime API 같은 실시간 음성 인터페이스를 적극적으로 고려할 만하다. 직접 STT, LLM, TTS를 모두 붙이는 구조보다 빠르게 대화 경험을 검증할 수 있다.

비용도 설계의 일부다

강의에서 인상적이었던 부분은 비용을 꽤 현실적으로 봐야 한다는 점이었다. GPU를 직접 빌려 모델을 띄우는 비용과 API 비용은 성격이 다르다.

GPU는 계속 켜두는 순간 고정비가 된다. A100, H100 같은 GPU를 쓰면 시간당 비용이 계속 쌓인다. 반면 API는 사용량 기반이라 초반 트래픽이 적을 때는 훨씬 관리하기 쉽다.

물론 API도 싸기만 한 것은 아니다. 사용량이 커지면 금방 비용이 올라간다. 그래서 처음에는 API로 시작하되, 나중에 비용 최적화가 필요해지는 시점에 파인튜닝이나 모델 라우팅을 고민하는 흐름이 자연스럽다.

비용을 줄이는 방법도 몇 가지가 있다. 쉬운 작업은 더 저렴한 모델로 보내고, 어려운 추론만 고성능 모델에 맡기는 모델 라우팅을 쓸 수 있다. 같은 시스템 프롬프트를 반복해서 쓴다면 프롬프트 캐싱도 고려할 수 있다. 실시간 처리가 필요 없는 작업은 Batch API를 쓰는 것도 방법이다.

결국 비용 관리는 모델 선택 하나로 끝나지 않는다. 어떤 작업을 실시간으로 처리할지, 어떤 작업은 나중에 처리해도 되는지까지 같이 설계해야 한다.

좋은 AI 프로젝트 주제의 조건

좋은 프로젝트 주제가 결과의 80%를 결정한다는 말도 기억에 남았다. AI 프로젝트는 단순히 “AI를 붙였다”만으로 좋은 주제가 되지 않는다.

좋은 주제에는 몇 가지 조건이 있다.

첫째, AI가 없으면 불가능하거나 비현실적인 가치가 있어야 한다. AI 없이도 쉽게 만들 수 있는 기능이라면 AI 프로젝트로서의 설득력이 약하다.

둘째, 4개월 안에 프로토타입이 나올 수 있어야 한다. 범위가 너무 크면 반드시 쪼개야 한다.

셋째, 성공과 실패를 측정할 수 있어야 한다. “잘 되는 것 같다”는 평가 방법이 아니다. 무엇이 잘 된 것이고, 무엇이 실패인지 구체적으로 정의해야 한다.

넷째, 데이터에 접근할 수 있어야 한다. 데이터가 없으면 테스트도 어렵고, 태스크를 조정하기도 어렵다.

다섯째, 실제 사용자가 있어야 한다. 사용자 피드백이 없으면 방향을 잡기 어렵다.

나쁜 주제와 좋은 주제의 차이도 결국 구체성에서 갈린다. “AI 챗봇 만들기”는 너무 넓고 ChatGPT와 차별화하기 어렵다. 반면 “대학생 수강신청 전략 추천 Agent”처럼 대상과 문제를 좁히면 훨씬 좋은 프로젝트가 된다.

우리 서비스도 마찬가지다. “영어 회화 AI”라고 하면 너무 넓다. 특정 상황, 특정 사용자, 특정 피드백 기준을 잡아야 한다. 예를 들어 면접 영어, 여행 영어, 발표 연습처럼 태스크를 좁히면 평가 기준도 더 분명해진다.

MVP 아키텍처는 어떻게 잡을까

강의에서는 MVP 아키텍처 패턴을 네 가지로 나눴다.

가장 단순한 구조는 단일 모델이다. 입력을 넣고 LLM 응답을 받아 출력한다. 텍스트 생성, 요약, 분류처럼 단순한 작업에는 이 방식이 적합하다.

두 번째는 멀티스탭 구조다. 하나의 LLM이 모든 걸 처리하게 하지 않고, 중간에 검증이나 후처리를 넣는다. 실패 지점을 파악하기 쉽고, 각 단계별 테스트도 가능하다.

세 번째는 RAG다. 외부 문서나 지식을 벡터 DB에 넣고, 검색 결과를 바탕으로 LLM이 답변하게 만드는 방식이다. Q&A나 검색 보강이 필요한 서비스에 잘 맞는다.

네 번째는 Agent Loop다. 질문을 받고, 계획을 세우고, 도구를 호출하고, 관찰한 뒤 다시 반복하는 구조다. 외부 도구를 써야 하거나 복잡한 자동화가 필요한 경우에 맞지만 난이도도 가장 높다.

우리 서비스는 단일 모델에서 시작하되, 점점 멀티스탭 구조로 가는 흐름이 맞아 보인다. 실시간 대화는 빠르게 처리하고, 자세한 피드백은 별도 단계에서 검증하거나 저장하는 식으로 나눌 수 있다.

프롬프트 엔지니어링에서 조심할 점

프롬프트 엔지니어링에서 중요한 원칙도 있었다. 모델에게 답을 억지로 강제하기보다, 모델이 생각해야 할 방향을 잡아주는 것이 낫다는 점이다.

예를 들어 “이런 스타일로 말하지 마”라고 금지 목록을 길게 주는 방식은 오히려 성능을 떨어뜨릴 수 있다. 대신 역할, 맥락, 목표, 출력 형식을 분명히 주는 편이 더 안정적이다.

시스템 프롬프트와 Few-shot 예시는 가장 기본적인 방법이다. Zero-shot으로 잘 안 되는 경우에는 입출력 예시 2~3개만 넣어도 결과가 꽤 좋아질 수 있다.

출력 형식이 중요하다면 Structured Output이나 Tool Use를 쓰는 편이 낫다. 단순히 “JSON으로 출력해”라고 말하는 것보다 스키마를 강제하는 방식이 훨씬 안정적이다.

또 하나 흥미로웠던 건 LLM-as-Judge다. AI가 만든 결과를 다시 AI가 평가하게 하는 방식인데, 평가 기준을 잘 정의하면 사람 평가의 상당 부분을 대체할 수 있다. 우리 서비스에서도 영어 피드백의 품질을 자동으로 점검하는 데 활용할 수 있을 것 같다.

우리 서비스에 적용해 보면

이번 강의를 들으면서 우리 영어 회화 서비스의 방향도 조금 더 선명해졌다.

초반에는 API 중심으로 가는 게 맞다. 직접 모델을 서빙하려면 인프라와 운영 부담이 크고, 팀 안에 AI 모델링 경험이 충분하지 않다면 시행착오가 길어질 가능성이 높다.

Realtime API는 대화감 검증에 쓰고, STT나 TTS도 처음부터 직접 서빙하기보다 API를 붙여 빠르게 실험하는 쪽이 현실적이다. 정확도가 걱정된다면 먼저 평가 기준과 테스트 케이스를 만들어야 한다. 파인튜닝은 그다음이다.

또한 모든 피드백을 실시간으로 처리할 필요는 없다. 대화 중에는 짧고 빠른 반응을 주고, 세부 피드백은 세션이 끝난 뒤 정리해서 제공하는 식으로 나누면 속도와 정확도를 함께 챙길 수 있다.

결론

오늘 강의의 결론은 네 가지로 정리할 수 있다.

첫째, 모델을 직접 만들지 API를 쓸지 먼저 결정해야 한다. 대부분의 4개월 프로젝트는 API부터 시작하는 것이 현실적이다.

둘째, 주제를 좁혀야 한다. AI-native하고, 4개월 안에 만들 수 있고, 측정 가능한 문제여야 한다.

셋째, 스택은 단순하게 시작해야 한다. SDK 직접 호출부터 시작하고, 필요할 때 멀티스탭, RAG, Agent Loop로 확장하는 편이 낫다.

넷째, 구현은 Playground, PoC, MVP, Production 순서로 가야 한다. Stage 0에서 가능성을 먼저 확인하고, 그다음에 제품화를 고민해야 한다.

AI 프로젝트는 기술만의 문제가 아니라 의사결정의 문제라는 말이 가장 크게 남았다. 무엇을 직접 만들고, 무엇을 빌려 쓰고, 어디까지를 MVP로 볼 것인지 정하는 과정이 프로젝트의 성패를 좌우한다.

[Saynow] 스피킹 서비스에서 STT와 TTS는 어디에 둬야 할까?

pp8817 — Wed, 5 Aug 2026 00:58:22 +0900

이 글은 Velog에서 이전한 글입니다. Velog 원문 보기

들어가며

소프트웨어 마에스트로 17기 연수생으로 참여하며, 팀원들과 서비스를 기획했다.
우리 팀이 찾은 핵심 가치는 영어를 완벽하게 말해야 한다는 부담감, 강박증을 없애주기이다.
캐치프라이즈로는 "내 영어를 진짜 외국인이 알아들을 확률은?"를 잡았다.

따라서, 핵심 가치를 기능으로 구현하기 위해서 스피킹 서비스를 만들기로 결정했다.
자연스럽게 따라오는 질문이 있다.

사용자의 음성은 어디에서 텍스트로 바꿀까?
AI가 만든 다음 질문은 어디에서 음성으로 바꿀까?

처음에는 단순해 보였다.
사용자가 말하면 음성 파일을 서버로 보내고 -> AI 서버가 STT로 텍스트를 만들고 -> 답변을 분석한 뒤 다음 질문을 만들고 -> 그 질문을 TTS로 음성 파일로 변환해 S3 같은 저장소에 올린다.
프론트는 그 URL을 받아 재생하면 된다.

흐름만 보면 자연스럽다. 하지만 실제 대화 경험을 생각하면 문제가 생긴다.
한 턴이 끝날 때마다 STT, 분석, 다음 질문 생성, TTS 생성, 파일 업로드, URL 반환까지 모두 기다려야 하기 때문이다.
사용자는 말을 끝냈는데 다음 질문이 늦게 나오면 대화가 끊긴 것처럼 느낀다.

이 글은 Saynow의 음성 대화 흐름을 설계하면서 STT와 TTS를 어디에 둘지 고민한 내용을 정리한 글이다. Speak 같은 스피킹 서비스의 구조도 참고했지만, 결론은 지금 단계에서 가장 단순하고 빠르게 검증할 수 있는 MVP 구조를 선택하는 쪽으로 기울었다.

첫 번째 생각: 서버에서 TTS까지 모두 처리하기

가장 먼저 떠올린 구조는 서버 중심 구조였다.

사용자 음성
-> 백엔드
-> AI 서버 STT
-> 답변 분석
-> 다음 질문 생성
-> TTS 생성
-> S3 업로드
-> 프론트에서 ttsUrl 재생

시나리오를 시작할 때도 같은 방식이다. 첫 질문의 TTS 파일을 미리 만들어 S3에 저장해 두고, 백엔드는 첫 질문 텍스트와 ttsUrl을 프론트에 내려준다. 프론트는 그 URL로 음성 파일을 가져와 재생한다.

턴이 진행될 때는 사용자가 말한 음성 파일을 백엔드로 업로드한다. 백엔드는 세션 정보, 시나리오 정보, 현재 턴 정보를 붙여 AI 서버로 보낸다. AI 서버는 음성을 텍스트로 바꾸고, 사용자의 답변을 분석하고, 다음 질문을 만든다. 이후 그 질문에 대한 TTS 파일을 생성해 S3에 올리고, 최종적으로 nextQuestion과 ttsUrl을 백엔드에 반환한다.

그림으로 보면 이렇다.

장점도 있다. 음성 품질을 서버에서 통제할 수 있고, 모든 클라이언트에서 같은 목소리를 들려줄 수 있다. 나중에 캐릭터 음성이나 특정 발음 품질이 중요해질 때도 유리하다.

하지만 MVP에는 부담이 크다. 특히 한 턴의 응답이 아래 과정에 모두 묶인다.

STT -> 답변 분석 -> 다음 질문 생성 -> TTS 생성 -> S3 업로드 -> ttsUrl 반환

질문 텍스트는 이미 만들어졌는데 TTS 생성이나 업로드 때문에 프론트 응답이 늦어질 수 있다. 스피킹 서비스에서 이 지연은 꽤 치명적이다. 사용자는 텍스트가 조금 늦는 것보다 대화 리듬이 끊기는 것을 더 크게 느낄 수 있다.

두 번째 생각: TTS를 비동기로 분리하기

서버 TTS를 유지하면서 지연을 줄이는 방법도 있다. TTS 생성을 턴 응답의 필수 조건에서 빼는 것이다.

1. STT와 분석을 먼저 끝낸다.
2. 다음 질문 텍스트를 먼저 프론트에 반환한다.
3. TTS는 뒤에서 생성한다.
4. 준비되면 ttsUrl만 따로 갱신한다.

응답은 이런 형태가 된다.

{
  "nextQuestion": "What size would you like?",
  "understoodScore": 85,
  "ttsStatus": "PENDING",
  "ttsUrl": null
}

프론트는 질문 텍스트를 먼저 보여주고, TTS가 준비되면 polling, callback, websocket 같은 방식으로 ttsUrl을 받아 음성을 재생한다.

이 방식은 서버 TTS의 장점을 유지하면서도 텍스트 응답은 빨리 줄 수 있다. 다만 구현 복잡도가 올라간다. ttsStatus를 관리해야 하고, TTS URL을 나중에 갱신하는 API나 이벤트 흐름도 필요하다.

MVP에서 이 정도 복잡도를 감수할 만한지 고민이 됐다. 아직 검증해야 할 핵심은 “사용자가 말하면 AI가 잘 이해하고 적절한 다음 질문을 주는가”이지, “서버가 자연스러운 음성 파일을 만들어 주는가”가 아니기 때문이다.

스픽(Speak)는 어떻게 접근하고 있을까?

스피킹 서비스를 기획하며 유사 서비스인 '스픽(Speak)'을 많이 분석했다.
Speak의 공개 자료를 보면, 대략적인 구조는 다음과 같다.

모바일 앱
-> WebRTC / LiveKit
-> Voice Agent Server
-> ASR / LLM / TTS provider 또는 Speech-to-Speech provider
-> 모바일 앱으로 음성 스트리밍

조금 더 풀면 이렇다.

여기서 눈여겨볼 점은 Speak이 모든 기능을 하나의 방식으로 처리하지 않는다는 것이다.

의미 중심의 롤플레이: ASR, LLM, TTS를 조합하는 Cascade 구조
발음이나 억양처럼 음성 자체의 정보가 중요한 기능:Speech-to-Speech 방식

을 선택할 수 있다.

OpenAI Realtime API 같은 기술도 이런 흐름과 맞닿아 있다.
기존에는 외부에서 STT, LLM, TTS를 각각 조립해야 했다면, Realtime API는 하나의 실시간 세션에서 음성 입력과 음성 출력을 처리할 수 있게 해 준다.

기존 Cascade:
음성 -> STT -> LLM -> TTS -> 음성

Realtime:
음성 입력 -> 실시간 모델 세션 -> 음성 출력

다만 이 구조를 MVP에 바로 적용하기에는 무겁다.
WebRTC, LiveKit, Voice Agent Server, 실시간 세션 관리까지 들어가면 제품 검증보다 인프라 구현에 더 많은 시간을 쓰게 될 수 있기 때문이다.

그래서 MVP에서는 클라이언트 TTS를 선택한다

그래서 SayNow의 현재 MVP에서는 TTS를 서버에서 처리하지 않기로 했다.

MVP의 핵심 흐름은 이렇게 잡을 수 있다.

사용자 음성 파일 업로드
-> AI 서버 STT
-> 답변 분석
-> 다음 질문 텍스트 생성
-> 백엔드 저장/응답
-> 프론트 클라이언트 TTS 재생

역할도 단순해진다.

이 구조에서는 ttsUrl이 필수값이 아니다. 서버는 질문 텍스트를 내려주고, 프론트는 그 텍스트를 클라이언트 TTS로 읽어 준다.

예를 들면 응답은 이렇게 단순해질 수 있다.

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "turnId": 1,
  "transcript": "I want an iced americano.",
  "understoodScore": 85,
  "status": "IN_PROGRESS",
  "babsaeText": "What size would you like?",
  "babsaeTtsUrl": null,
  "followUpCount": 1,
  "maxFollowUpCount": 5
}

babsaeText는 필수다. babsaeTtsUrl은 제거하거나 nullable로 둔다. MVP에서는 프론트가 babsaeText를 클라이언트 TTS로 재생하면 된다.

클라이언트 TTS의 단점은 없을까?

당연히 있다. 클라이언트 TTS는 기기와 브라우저에 따라 품질이 다르다.
iOS, Android, Chrome, Safari에서 목소리와 발음이 달라질 수 있고, 영어 억양도 기대만큼 자연스럽지 않을 수 있다.

그래도 MVP에서는 이 단점이 치명적이지 않다고 봤다. SayNow의 초기 검증 포인트는 고품질 음성 합성이 아니라, 사용자가 말한 내용을 AI가 잘 이해하고 다음 질문으로 대화를 이어 갈 수 있는지다. 질문 텍스트를 화면에 함께 보여준다면, TTS가 조금 어색해도 사용자는 흐름을 이해할 수 있다.

반대로 서버 TTS를 처음부터 넣으면 응답 지연과 구현 복잡도가 먼저 커진다. 품질 문제를 해결하려다 제품의 핵심 흐름 검증이 늦어질 수 있다.

나중에 어떤 방향으로 고도화할까?

MVP 이후에는 실제 사용 데이터를 보고 판단하면 된다.

사용자가 “음성이 너무 어색하다”고 느끼면 서버 TTS나 외부 TTS provider를 붙이면 된다. 사용자가 “대화가 너무 느리다”고 느끼면 WebRTC와 실시간 Voice Agent 구조를 검토할 수 있다. 발음, 억양, 톤까지 평가해야 한다면 Speech-to-Speech나 음성 특성 분석이 필요해진다.

결국 처음부터 최종 구조를 만들려고 하지 않는 것이 중요하다. Speak 같은 서비스의 현재 구조는 오랜 시간 제품을 운영하며 도달한 결과에 가깝다. 우리는 먼저 가볍게 검증하고, 실제 문제가 확인되는 지점부터 고도화하는 편이 낫다.

결론

SayNow의 MVP에서는 다음 구조가 가장 현실적이다.

Frontend
- 음성 녹음
- 질문 텍스트 표시
- 클라이언트 TTS 재생

Backend
- 세션 상태 관리
- 턴 저장
- AI 서버 호출
- 응답 정규화

AI Server
- STT
- 답변 분석
- 슬롯/목표 달성 판단
- 다음 질문 텍스트 생성

한 턴의 응답을 TTS 생성과 S3 업로드 완료에 묶지 않는다. 먼저 텍스트 기반 대화 흐름을 빠르게 만들고, TTS 품질이나 실시간성이 실제 문제로 드러났을 때 서버 TTS나 Realtime 구조로 확장한다.

지금 필요한 건 완성형 음성 인프라가 아니라, 사용자가 말하고 AI가 이어서 질문하는 핵심 루프를 빠르게 검증하는 것이다.

참고 링크

알고리즘 스터디 1주차

pp8817 — Tue, 4 Aug 2026 12:56:48 +0900

이 글은 Velog에서 이전한 글입니다. Velog 원문 보기

1번 문제: BFS

문제: https://leetcode.com/problems/minesweeper/description/
풀이 소요 시간: 30분
알고리즘: BFS

from collections import deque
d = [[-1,-1], [-1,0], [0,-1], [1,1], [1,0], [0,1], [1,-1], [-1,1]]

class Solution:
    def updateBoard(self, board: List[List[str]], click: List[int]) -> List[List[str]]:
        R, C = len(board), len(board[0])
        q = deque([(click[0], click[1])])

        if board[click[0]][click[1]] == 'M': 
            board[click[0]][click[1]] = 'X'
            return board

        while q:
            x, y = q.popleft() 

            if board[x][y] != 'E':
                continue

            cnt = 0 
            for dx, dy in d:
                nx, ny = x+dx, y+dy
                if 0<=nx<R and 0<=ny<C:
                    if board[nx][ny] == 'M':
                        cnt += 1

            if cnt > 0: # 주변에 폭탄이 1개 이상 있는 경우
                board[x][y] = str(cnt)
            else: # 주변에 지뢰가 없는 경우 (재귀적으로 주변 확장)
                board[x][y] = 'B'
                for dx, dy in d:
                    nx, ny = x+dx, y+dy
                    if 0<=nx<R and 0<=ny<C:
                        if board[nx][ny] == 'E':
                            q.append((nx, ny))

        return board

풀이 사고 흐름

우선 크게 2가지 경우로 분류해서 생각
- 주변에 폭탄이 1개 이상 있는 경우
- 주변에 지뢰가 없는 경우

현재 칸 주변 8방향 지뢰 개수를 체크
지뢰 개수(cnt) > 0 이면 현재 칸을 cnt로 변경하고 끝
cnt == 0이면 현재 칸을 'B'로 바꾸고, 주변 'E'만 큐에 삽입

if board[x][y] != 'E':
이미 처리된 값은 continue로 스킵

멘토님 피드백

M, B 같은 문제에서 의미를 가지는 값은 별도 상수로 관리하는 것을 추천
- 상수로 관리해야 재사용 할 때 실수를 안한다.
x+dx 같은 부분 띄어쓰기 추가해서 x + dx로 표기 -> 사소해보이지만 가독성에 큰 차이를 줌
cnt 같은 변수명 boom_cnt로 의미가 명확하게 변경
x, y = q.popleft(): 큐에 들어가는 값에 대한 설명 주석을 작성해야 한다.
시간복잡도 생각해보기 (worst case까지)

2번 문제: DP

문제: https://leetcode.com/problems/remove-boxes/description/
풀이 소요 시간: x
알고리즘: DP

처음에는 문제 이해가 어려웠다.
문제는 여러 개의 박스가 주어지며, 각 박스는 서로 다은 양의 정수로 구분한다.
같은 양의 정수로 이루어진 연속된 박스들을 선택할 수 있고,
선택한 박스의 개수를 k라고 할 때 이 박스들을 제거하면 k * k (k**2) points를 얻는다.

문제의 예시로 이해를 해보면

Input: boxes = [1,3,2,2,2,3,4,3,1]
Output: 23
Explanation:

[1, 3, 2, 2, 2, 3, 4, 3, 1] 
----> [1, 3, 3, 4, 3, 1] (3*3=9 points) 
----> [1, 3, 3, 3, 1] (1*1=1 points) 
----> [1, 1] (3*3=9 points) 
----> [] (2*2=4 points)

1단계

[1, 3, 2, 2, 2, 3, 4, 3, 1] 
-> (2,2,2) 제거: k=3
[1, 3, 3, 4, 3, 1]

points = 3**2 = 9

가운데 2들의 묶음을 제거해서 3들이 가까워짐

2단계
여기서 가운데에 있는 3의 묶음이 아닌 4를 지워야 한다.
4를 제거하면 3의 묶음이 3개가 되어 k=3이 된다.

[1, 3, 3, 4, 3, 1]
-> (4) 제거: k=1
[1, 3, 3, 3, 1]

points = 1**2 = 1

3단계

[1, 3, 3, 3, 1]
-> (3,3,3) 제거: k=3
[1, 1]

points = 3**2 = 9

4단계

[1, 1]
(1,1) 제거: k=2
[]

points = 2**2 = 4

Result = 9+1+9+4 = 23

논리적으로는 이해했으나, 코드로 구현하는 것에 실패.

끄적이는 개발 log

푸시 알림 서버까지 만들고도 로컬 알림을 선택한 이유

푸시 알림 서버까지 만들고도 로컬 알림을 선택한 이유

매일 20시 알림 하나에서 시작했다

Expo API를 호출하는 일보다 그 앞뒤가 더 복잡했다

Token은 사용자 ID가 아니라 앱 설치를 기준으로 관리했다

별도 Worker는 만들지 않았지만 서버의 책임은 여전히 컸다

500명씩 계산하고 100건씩 발송했다

SQS가 같은 메시지를 다시 줘도 알림은 한 번만 보내야 했다

Expo Ticket은 기기 전달 완료가 아니었다

기술적으로 올바른 구조와 지금 필요한 구조는 달랐다

첫 배포는 로컬 알림으로 방향을 바꿨다

로컬 알림이 항상 더 좋은 선택은 아니다

서버 푸시 구현은 낭비였을까?

마치며

참고 자료

Sentry 500은 서버 장애가 아니었다. WAF Count 뒤에 있던 취약점 스캐너

Sentry 500은 서버 장애가 아니었다. WAF Count 뒤에 있던 취약점 스캐너

20시 5분에 무슨 일이 있었나

두 종류의 깨진 요청

ALB 460이 원인을 좁혀 줬다

왜 WAF가 1,647건을 통과시켰나

5분당 2,000회를 어떻게 정했나

WAF 로그를 켠 뒤 판단이 달라졌다

Common Rule Set은 왜 Count로 남겼나

Athena 테이블은 만들어졌지만 처음에는 쓸 수 없었다

애플리케이션에서도 500을 줄여야 한다

적용할 때 지킨 순서

이번 조사에서 얻은 교훈

애플리케이션 TPS만 보면 놓칠 수 있다

Count는 차단이 아니라 관찰이다

테이블 생성과 데이터 활용은 다른 완료 조건이다

관리형 규칙도 그룹별로 판단해야 한다

마무리

참고 자료

Spring Boot 4에서 사라진 ObjectMapper Bean

Spring Boot 4에서 사라진 ObjectMapper Bean

ECS에서는 무슨 일이 벌어지고 있었을까

새 태스크가 시작되지 못한 이유

그런데 왜 테스트는 통과했을까

Jackson 2 ObjectMapper를 명시적으로 등록했다

배포 검증 로직도 실패를 놓치고 있었다

이번 장애에서 배운 점

참고 자료

테스트 주도 개발 | 켄트 백

테스트가 코드를 이끄는 방식

TDD가 해결하려는 문제

TDD의 핵심 사이클

간단한 예제로 이해하기

세 가지 구현 전략

테스트가 설계를 이끄는 방식

TDD의 장점

TDD의 한계와 오해

실제 프로젝트에 적용하는 방법

책을 읽고 남는 태도

결론

앱 웹뷰 도입 후 Refresh Token 구조를 다시 설계한 이유

들어가며

기존 구조의 문제

1차 완화책: Refresh Token을 매번 갱신하지 않기

근본 해결책: Refresh Token을 로그인 세션 단위로 저장하기

토큰 재발급 API는 어떻게 바뀌나

왜 deviceId를 쓰지 않았나

기존 Refresh Token 호환

테스트로 확인한 것

정리

[Saynow] LLM Workflow 개선기 - availableOptions를 버리고 RAG로 간 이유

모든 LLM 작업을 같은 구조로 묶지 않았다

기존 구조의 한계

왜 availableOptions를 버렸나

새 구조는 ASSISTANCE_REQUEST만 RAG로 보낸다

검색 대상은 인터넷이 아니라 내부 벡터 DB다

저장하는 데이터

API 경계는 유지했다

구현과 검증

Agent Loop를 쓰지 않은 이유

정리하며

[Saynow] 프롬프트 개선기 - Prompt 1에서 9까지

출발점은 filledSlots=[]였다

프롬프트를 길게 막기보다 방향을 잡았다

왜 `availableOptions`를 버렸나

새 구조는 `ASSISTANCE_REQUEST`만 RAG로 보낸다

출발점은 `filledSlots=[]`였다