⚙️[기능추가][Debug] 테스트 빌드 전용 앱 내 디버그 오버레이 구현

[Cassiiopeia]

📝 현재 문제점

• 테스트 APK/TestFlight 빌드에서 앱 로그를 확인하려면 시뮬레이터 콘솔이나 별도 디버깅 환경이 필요함
• 실기기에서 테스트할 때 로그를 실시간으로 볼 수 없어 문제 파악이 어려움
• HTTP 요청/응답, 에러 로그 등을 확인하기 위해 매번 PC에 연결해야 하는 불편함

🛠️ 해결 방안 / 제안 기능

• .env에 TEST_BUILD=true 플래그를 추가하여 테스트 빌드에서만 디버그 도구 활성화
• 앱 내 드래그 가능한 플로팅 디버그 버튼 제공
• 플로팅 버튼 탭 시 메뉴 표시 (로그 뷰어 + 향후 확장 메뉴)
• 리사이즈/이동 가능한 로그 뷰어 패널에서 실시간 로그 확인

⚙️ 작업 내용

1. 디버그 플래그 시스템

• .env에서 TEST_BUILD 값을 읽어 디버그 모드 활성화 여부 결정
• 프로덕션 빌드에는 일절 영향 없음

2. CI 워크플로우 변경

• ROMROM-ANDROID-TEST-APK 워크플로우: .env 생성 시 TEST_BUILD=true 추가
• ROMROM-IOS-TEST-TESTFLIGHT 워크플로우: .env 생성 시 TEST_BUILD=true 추가
• 프로덕션 워크플로우(ROMROM-IOS-TESTFLIGHT)는 변경 없음

3. 로그 캡처 시스템

• 기존 Logger.root.onRecord 구독하여 앱 전체 로그 캡처
• 링버퍼(최근 1000개)로 메모리 보호
• Stream broadcast로 실시간 전달

4. 플로팅 디버그 버튼

• 화면 위에 떠있는 원형 버튼
• 드래그하여 자유롭게 위치 이동 가능
• 탭하면 디버그 메뉴 표시

5. 디버그 메뉴

• 로그 뷰어 (1차 구현)
• 자동 로그인 (추후 구현, 비활성 표시)
• 서버 로그 (추후 구현, 비활성 표시)

6. 로그 뷰어 패널

• 리사이즈/드래그 가능한 플로팅 패널
• 실시간 로그 스트리밍 (자동 스크롤)
• 카테고리별 필터 (체크박스)
• 로그 레벨 필터 (INFO/WARNING/SEVERE)
• 텍스트 검색
• 로그 클리어
• 클립보드 복사

📋 참고 자료

• 설계 문서: docs/superpowers/specs/2026-03-27-debug-overlay-design.md

🙋‍♂️ 담당자

• 백엔드: @Cassiiopeia
• 프론트엔드: 이름
• 디자인: 이름

[Cassiiopeia]

Guide by SUH-LAB

브랜치

20260327_#715_테스트_빌드_전용_앱_내_디버그_오버레이_구현

커밋 메시지

테스트 빌드 전용 앱 내 디버그 오버레이 구현 : feat : {변경 사항에 대한 설명} https://github.com/TEAM-ROMROM/RomRom-FE/issues/715

[Cassiiopeia]

Debug Overlay 설계 문서

작성일: 2026-03-27

1. 개요

테스트 빌드(CI)에서만 활성화되는 앱 내 디버그 도구.
플로팅 버튼을 통해 로그 뷰어를 열고, 향후 자동 로그인/서버 로그 등 디버그 기능을 확장할 수 있는 구조.

목적

• 테스트 APK/TestFlight 빌드에서 시뮬레이터 콘솔 없이 앱 내에서 로그를 실시간으로 확인
• 프로덕션 빌드에는 일절 영향 없음

활성화 조건

• .env 파일에 TEST_BUILD=true가 있을 때만 동작
• CI 워크플로우(Android 테스트 APK, iOS 테스트 TestFlight)에서 .env 생성 시 자동 추가
• 프로덕션 워크플로우(ROMROM-IOS-TESTFLIGHT.yaml)에는 추가하지 않음

2. 아키텍처

┌─ CI 워크플로우 ─────────────────────┐
│ .env에 TEST_BUILD=true 한 줄 추가    │
└─────────────────────────────────────┘
              ↓
┌─ DebugConfig ───────────────────────┐
│ dotenv.get('TEST_BUILD') 읽기       │
│ → static bool isTestBuild 제공       │
└─────────────────────────────────────┘
              ↓
┌─ MyApp (main.dart) ─────────────────┐
│ if (DebugConfig.isTestBuild)         │
│   → DebugOverlayManager 초기화       │
│   → 플로팅 버튼 Overlay에 삽입        │
└─────────────────────────────────────┘
              ↓
┌─ DebugOverlayManager ──────────────┐
│ ├─ DebugFloatingButton (드래그 이동) │
│ └─ DebugMenuPanel (메뉴 목록)        │
│    ├─ 로그 뷰어 ← 1차 구현           │
│    ├─ 자동 로그인 ← 추후             │
│    └─ 서버 로그 ← 추후               │
└─────────────────────────────────────┘
              ↓
┌─ LogCapture ────────────────────────┐
│ Logger.root.onRecord 구독            │
│ 링버퍼(최근 1000개) 저장              │
│ StreamController.broadcast 실시간 전달│
└─────────────────────────────────────┘
              ↓
┌─ DebugLogPanel (리사이즈 패널) ──────┐
│ ├─ 실시간 스트리밍 (자동 스크롤)       │
│ ├─ 카테고리 필터 (체크박스)            │
│ ├─ 레벨 필터 (INFO/WARNING/SEVERE)   │
│ ├─ 텍스트 검색                       │
│ ├─ 로그 클리어                       │
│ └─ 클립보드 복사                     │
└─────────────────────────────────────┘

3. 파일 구조

lib/debug/
├─ debug_config.dart              # TEST_BUILD 플래그 읽기/관리
├─ debug_overlay_manager.dart     # Overlay 진입점 (버튼+메뉴+패널 생명주기)
├─ log_capture.dart               # Logger.root.onRecord 구독, 링버퍼, Stream
├─ widgets/
│  ├─ debug_floating_button.dart  # 드래그 가능한 원형 플로팅 버튼
│  ├─ debug_menu_panel.dart       # 메뉴 팝업 (로그뷰어/자동로그인/서버로그)
│  └─ debug_log_panel.dart        # 리사이즈 가능한 로그 뷰어 패널

4. 컴포넌트 상세

4.1 DebugConfig (debug_config.dart)

• dotenv.get('TEST_BUILD', fallback: 'false') 읽기
• static bool isTestBuild 제공
• 앱 초기화(AppInitializer) 시 1회 세팅, 이후 읽기 전용
• TEST_BUILD=true가 아닌 모든 경우 false

4.2 LogCapture (log_capture.dart)

• Logger.root.onRecord.listen()으로 전체 로그 캡처
• 링버퍼 (최근 1000개, 오래된 것부터 자동 제거 → 메모리 보호)
• StreamController<LogRecord>.broadcast()로 실시간 전달
• 각 LogRecord에서 사용하는 정보:
  • time — 타임스탬프
  • level — 로그 레벨 (INFO, WARNING, SEVERE 등)
  • loggerName — 카테고리 (http, app 등)
  • message — 로그 메시지
  • error — 에러 객체 (있을 경우)
  • stackTrace — 스택트레이스 (있을 경우)
• start() / dispose() 메서드로 구독 생명주기 관리
• clear() 메서드로 링버퍼 비우기

4.3 DebugFloatingButton (debug_floating_button.dart)

• 원형 버튼 (벌레 아이콘)
• GestureDetector + Positioned로 드래그 이동
• 화면 밖으로 나가지 않도록 clamp 처리
• 탭 → DebugMenuPanel 토글
• 초기 위치: 화면 우측 하단

4.4 DebugMenuPanel (debug_menu_panel.dart)

• 플로팅 버튼 옆에 나타나는 작은 메뉴 팝업
• 메뉴 항목:
  • "로그 뷰어" — 1차 구현, 탭 시 DebugLogPanel 열림
  • "자동 로그인" — 추후 구현 (비활성/회색 표시)
  • "서버 로그" — 추후 구현 (비활성/회색 표시)
• 메뉴 외부 탭 시 자동 닫힘

4.5 DebugLogPanel (debug_log_panel.dart)

• Positioned + GestureDetector로 드래그 이동 + 리사이즈 가능
• 최소 크기 제한 (가로 280, 세로 200)

레이아웃

┌─ 상단 바 ──────────────────────────┐
│ [드래그 핸들]  "로그 뷰어"  [최소화][닫기] │
├─ 필터 영역 ────────────────────────┤
│ 카테고리: [✓http] [✓app] [✓...]    │
│ 레벨: [INFO ▼]  검색: [________]   │
├─ 로그 영역 ────────────────────────┤
│ 12:34:56 [INFO] http: GET /api...  │
│ 12:34:57 [SEVERE] app: Error...    │
│ ...                                │
│          (자동 스크롤)              │
├─ 하단 바 ──────────────────────────┤
│ [클리어]  로그 수: 142    [전체 복사] │
└────────────────────────────────────┘

기능 상세

기능	설명
실시간 스트리밍	LogCapture.stream 구독, 새 로그 추가 시 자동 스크롤
카테고리 필터	loggerName 기준 체크박스, 동적으로 카테고리 수집
레벨 필터	ALL/INFO/WARNING/SEVERE 드롭다운 선택
텍스트 검색	메시지 내용 contains 필터링
로그 클리어	링버퍼 + UI 모두 비움
클립보드 복사	현재 필터링된 로그 전체를 텍스트로 복사

로그 색상

레벨	색상
INFO	흰색
WARNING	노란색
SEVERE	빨간색
FINE/FINER/FINEST	회색

5. 데이터 흐름

[앱 시작]
  → AppInitializer.loadEnv()
  → DebugConfig.init()          // TEST_BUILD=true 확인
  → LogCapture.start()          // Logger.root.onRecord 구독 시작
  → MyApp build
    → if (DebugConfig.isTestBuild)
      → DebugOverlayManager를 Overlay에 삽입

[런타임]
  Logger.log("...") → Logger.root.onRecord
    → LogCapture 링버퍼에 저장
    → StreamController.broadcast
      → DebugLogPanel이 구독하여 UI 갱신

[플로팅 버튼 탭]
  → DebugMenuPanel 열림
    → "로그 뷰어" 탭 → DebugLogPanel 열림/닫힘
    → 필터/검색/클리어/복사 조작

6. 기존 코드 수정 포인트 (최소한)

파일	변경 내용	수정량
lib/services/app_initializer.dart	DebugConfig.init() + LogCapture.start() 호출	2줄
lib/main.dart	DebugOverlayManager 초기화 (조건부)	3~4줄
.github/workflows/ROMROM-ANDROID-TEST-APK.yaml	.env에 TEST_BUILD=true 추가	1줄
.github/workflows/ROMROM-IOS-TEST-TESTFLIGHT.yaml	.env에 TEST_BUILD=true 추가 (생성 + 재생성 스텝)	2줄

기존 Logger, ApiClient, 화면 코드는 수정 없음.

7. CI 워크플로우 변경

ROMROM-ANDROID-TEST-APK.yaml

# Create .env file 스텝
- name: Create .env file
  run: |
    echo "${{ secrets.ENV_FILE }}" > .env
    echo "TEST_BUILD=true" >> .env    # 추가
    echo ".env file created"

ROMROM-IOS-TEST-TESTFLIGHT.yaml

# Create .env file 스텝
- name: Create .env file
  run: |
    echo "${{ secrets.ENV_FILE }}" > .env
    echo "TEST_BUILD=true" >> .env    # 추가
    echo ".env file created"

# Ensure .env file exists 스텝 (재생성 시에도 추가)
- name: Ensure .env file exists
  run: |
    if [ ! -f .env ]; then
      echo "${{ secrets.ENV_FILE }}" > .env
      echo "TEST_BUILD=true" >> .env  # 추가
    fi

프로덕션 워크플로우 (변경 없음)

• ROMROM-IOS-TESTFLIGHT.yaml — 수정하지 않음
• .env에 TEST_BUILD 키가 없으면 DebugConfig.isTestBuild = false

8. 확장 계획 (추후)

기능	설명	우선순위
자동 로그인	테스트 계정으로 소셜 로그인 스킵	2차
서버 로그	서버 로그 API 연동하여 앱에서 확인	3차
네트워크 인스펙터	HTTP 요청/응답 상세 뷰 (Alice 스타일)	3차

9. 제약 사항

• 링버퍼 크기 1000개 — 메모리 보호를 위해 제한, 필요 시 조정 가능
• TEST_BUILD=true가 아닌 빌드에서는 LogCapture, DebugOverlayManager 모두 초기화하지 않음
• 플로팅 버튼/패널은 Overlay 기반이므로 앱의 모든 화면 위에 표시됨

[Cassiiopeia]

📌 작업 개요

테스트 빌드(APK/TestFlight)에서 앱 내 플로팅 디버그 버튼을 통해 서버 로그를 실시간으로 확인할 수 있도록 SSE(Server-Sent Events) 기반 서버 로그 스트리밍 API 엔드포인트 추가

🎯 구현 목표

• SSE 프로토콜을 사용한 실시간 서버 로그 스트리밍 엔드포인트 구현
• 기존 @SecuredAPI (HMAC-SHA256 + Timestamp) 보안 메커니즘 적용
• Logback 커스텀 Appender로 com.romrom 패키지 로그만 SSE로 발행
• 5분 자동 타임아웃, 최대 10명 동시 접속, 초당 100건 rate limiting

✅ 구현 내용

SSE 로그 이벤트 DTO

• 파일: RomRom-Common/src/main/java/com/romrom/common/dto/DebugLogEvent.java
• 변경 내용: SSE로 전송할 로그 이벤트 DTO 생성 (timestamp, level, loggerName, message, threadName)
• 이유: 로그 이벤트를 JSON 직렬화하여 클라이언트에 전송하기 위한 구조체

SSE 구독자 관리 및 브로드캐스트 서비스

• 파일: RomRom-Common/src/main/java/com/romrom/common/service/SseLogBroadcaster.java
• 변경 내용: SSE 구독자 등록/제거, 로그 이벤트 브로드캐스트 기능 구현
• 이유: 스레드 안전한 구독자 관리(CopyOnWriteArrayList) 및 서버 리소스 보호를 위한 rate limiting 적용

Logback 커스텀 Appender

• 파일: RomRom-Common/src/main/java/com/romrom/common/logging/SseLogAppender.java
• 변경 내용: AppenderBase<ILoggingEvent>를 확장한 커스텀 Appender 구현. com.romrom 패키지 로그만 필터링하여 SSE 구독자에게 발행
• 이유: Logback Appender는 Spring Bean이 아니므로 ApplicationContext를 통한 지연 초기화(lazy init) 방식으로 SseLogBroadcaster 빈 조회

Logback Appender 초기화 컴포넌트

• 파일: RomRom-Common/src/main/java/com/romrom/common/logging/SseLogAppenderInitializer.java
• 변경 내용: ContextRefreshedEvent 리스너로 Spring Context를 SseLogAppender에 주입
• 이유: Logback Appender(비-Spring 객체)가 Spring ApplicationContext에 접근할 수 있도록 브릿지 역할

디버그 컨트롤러

• 파일: RomRom-Web/src/main/java/com/romrom/web/controller/api/DebugController.java
• 변경 내용: GET /api/app/debug/log-stream SSE 엔드포인트 구현. @SecuredAPI 적용, 5분 타임아웃
• 이유: 클라이언트 SSE 연결을 수립하고 구독자 등록/정리 생명주기 관리

Swagger 문서화

• 파일: RomRom-Web/src/main/java/com/romrom/web/controller/api/DebugControllerDocs.java
• 변경 내용: @apichangelog 및 @operation으로 인증 방식, SSE 이벤트 포맷, 동작 설명, 에러코드 문서화
• 이유: 프로젝트 컨벤션에 따라 API 문서 인터페이스 분리

Logback 설정 파일

• 파일: RomRom-Web/src/main/resources/logback-spring.xml
• 변경 내용: SSE_LOG Appender 추가, 기존 application.yml 로깅 설정을 XML로 통합
• 이유: 커스텀 Appender는 logback-spring.xml에서만 등록 가능

보안 URL 등록

• 파일: RomRom-Domain-Auth/src/main/java/com/romrom/auth/dto/SecurityUrls.java
• 변경 내용: SECURED_API_URLS에 /api/app/debug/log-stream 추가
• 이유: JWT 인증을 건너뛰고 @SecuredAPI HMAC 검증만 적용하기 위해

🔧 주요 변경사항 상세

SseLogBroadcaster — 스레드 안전성 및 Rate Limiting

• CopyOnWriteArrayList<SseEmitter>로 동시 접근 안전한 구독자 관리
• AtomicInteger + AtomicLong으로 근사치 초당 100건 rate limiting 구현 (멀티스레드 환경에서 대략적 제한)
• rate limit 초과 시 "[N건 생략]" 알림 메시지를 다음 초 시작 시 전송
• 자체 ObjectMapper(JavaTimeModule 등록)로 LocalDateTime JSON 직렬화

특이사항:

• rate limiting은 근사치(approximate) 방식 — 디버그 용도이므로 정확한 초당 제한이 아닌 대략적 제한으로 충분
• volatile 키워드를 applicationContext(static)와 sseLogBroadcaster(instance) 모두에 적용하여 멀티스레드 가시성 보장

DebugController — SSE 생명주기 관리

• onCompletion: 구독자 제거 (최종 정리 담당)
• onTimeout: 로그 기록 후 complete() 호출 → onCompletion 트리거
• onError: 로그 기록 후 complete() 호출 → onCompletion 트리거
• 이 순서로 중복 removeSubscriber 호출 방지

logback-spring.xml — 기존 설정과의 공존

• 기존 application.yml의 logging.level.* 설정은 logback-spring.xml과 공존 가능 (application.yml이 추가 오버라이드)
• Spring Boot 기본 콘솔 포맷 유지 (defaults.xml + console-appender.xml include)

📦 의존성 변경

• 없음 (Spring Boot 기본 SSE 지원 + Logback 기본 API만 사용)

🧪 테스트 및 검증

• SSE 연결 수립 후 com.romrom 패키지 로그가 실시간 스트리밍되는지 확인
• 5분 경과 후 자동 연결 종료 확인
• 10명 초과 접속 시 503 에러 반환 확인
• 초당 100건 초과 시 "[N건 생략]" 메시지 전송 확인
• @SecuredAPI HMAC 인증 없이 접근 시 401 에러 반환 확인

📌 참고사항

• logback-spring.xml이 프로젝트에 처음 추가됨 — 기존 application.yml의 logging.file.name, logging.level.* 설정은 그대로 유효
• SseLogAppender는 Spring Bean이 아닌 Logback 객체이므로 SseLogAppenderInitializer를 통한 간접 주입 방식 사용
• 프론트엔드에서 EventSource API 또는 Flutter SSE 라이브러리로 연결 시 X-Timestamp, X-Signature 헤더 필요

[Cassiiopeia]

디버그 API — 서버 로그 실시간 스트리밍 (SSE)

엔드포인트

GET /api/app/debug/log-stream

Content-Type: text/event-stream (SSE)

---

인증: @SecuredAPI (HMAC + Timestamp)

기존 버전 동기화 API와 동일한 방식

헤더	값
X-Timestamp	밀리초 단위 타임스탬프 (예: 1711526400000)
X-Signature	HMAC-SHA256(timestamp, secretKey) Hex 인코딩

---

SSE 이벤트 포맷

연결 성공 후 서버 로그가 아래 JSON 형식으로 실시간 전송됨:

{
  "timestamp": "2026-03-27T14:30:00.123",
  "level": "DEBUG",
  "loggerName": "com.romrom.web.controller.api.ItemController",
  "message": "물품 조회 요청 - memberId: 123",
  "threadName": "http-nio-8080-exec-1"
}

필드	타입	설명
timestamp	String (ISO 8601)	로그 발생 시간
level	String	DEBUG / INFO / WARN / ERROR
loggerName	String	로그 출처 클래스 (com.romrom.* 만)
message	String	로그 메시지
threadName	String	처리 스레드명

---

Rate Limit 초과 시 알림

초당 100건 초과 시 다음 메시지가 전송됨:

{
  "level": "WARN",
  "message": "[42건 생략 — rate limit 초과]"
}

---

제약사항

항목	값
연결 타임아웃	5분 (300초) 후 자동 종료
최대 동시 접속	10명 (초과 시 503 반환)
초당 최대 이벤트	100건 (초과분 생략 후 알림)
로그 범위	com.romrom.* 패키지만 (프레임워크 로그 제외)

---

에러 응답

상황	HTTP 코드	설명
서명 헤더 누락	401	MISSING_SIGNATURE_HEADER
타임스탬프 만료	401	EXPIRED_SIGNATURE_TIMESTAMP
서명 불일치	401	INVALID_SIGNATURE
동시 접속 초과	503	"최대 동시 접속 수 초과"

---

Flutter 연결 예시

// 1. HMAC 서명 생성
final timestamp = DateTime.now().millisecondsSinceEpoch.toString();
final signature = hmacSha256(timestamp, secretKey); // Hex 인코딩

// 2. SSE 연결 (EventSource 또는 SSE 라이브러리 사용)
// GET /api/app/debug/log-stream
// Headers:
//   X-Timestamp: {timestamp}
//   X-Signature: {signature}

// 3. 이벤트 수신
// data: {"timestamp":"2026-03-27T14:30:00.123","level":"INFO","loggerName":"com.romrom...","message":"...","threadName":"..."}

주의사항

• SSE는 단방향 스트림 — 서버 → 클라이언트만 전송

• 5분 후 자동 종료되므로 필요 시 재연결 로직 구현

• 클라이언트에서 연결을 닫으면 서버에서 즉시 정리됨

• X-Timestamp, X-Signature 헤더는 연결 시점에만 검증 (스트리밍 중 재검증 없음)

• ⚙️[기능추가][Debug] 테스트 빌드용 SSE 서버 로그 스트리밍 엔드포인트 추가 RomRom-BE#607
  백엔드 개발 내용 공유드립니다

[Cassiiopeia]

@suh-lab app build

[github-actions]

🤖 ✅ Android APK 빌드 완료!

단계	상태	소요 시간
🔧 준비	✅ 완료	-
🔨 APK 빌드	✅ 완료	-
📤 업로드	✅ 완료	7분 49초

📦 빌드 결과

항목	값
앱 버전	0.0.0(71501)
브랜치	20260327_#715_테스트_빌드_전용_앱_내_디버그_오버레이_구현
커밋	54ee169
총 소요 시간	7분 49초

📦 아티팩트 다운로드
🔗 워크플로우 실행 로그

[github-actions]

🍎 ✅ iOS TestFlight 빌드 완료!

단계	상태	소요 시간
🔧 준비	✅ 완료	3분 36초
🔨 IPA 빌드	✅ 완료	10분 57초
📤 TestFlight 배포	✅ 완료	18분 4초

📦 빌드 결과

항목	값
앱 버전	0.0.0(71501)
브랜치	20260327_#715_테스트_빌드_전용_앱_내_디버그_오버레이_구현
커밋	54ee169
총 소요 시간	18분 4초

📱 TestFlight에서 테스트 앱을 다운로드할 수 있습니다.
🔗 워크플로우 실행 로그