[ 데이터 품질 관리 ] (1) 기획 : 페이지 시나리오

전체 워크플로우와 사용자 시나리오

이 글에서는 실제 운영 중인 데이터 품질 관리 시스템의 전체 워크플로우를 Frontend부터 Backend까지 상세히 다룹니다. 자동 감지, 중앙 관리, 신속한 해결의 3단계 프로세스를 통해 데이터 품질 문제를 어떻게 관리하는지 실제 사용자 시나리오와 함께 설명합니다.

 

📋 시스템 개요

데이터 품질 관리 시스템은 자동 감지, 중앙 관리, 신속한 해결의 3단계 프로세스를 통해 데이터 품질 문제를 관리합니다. 이 시스템의 핵심은 사용자 경험을 방해하지 않으면서도 데이터 품질 문제를 실시간으로 감지하고 체계적으로 관리하는 것입니다.

1

자동 감지 (Frontend)
사용자가 대시보드를 사용하는 동안 백그라운드에서 API 응답 데이터를 자동으로 검증합니다.

2

중앙 관리 (Backend + Admin)
감지된 문제들을 중앙 집중식으로 수집하고 관리자가 체계적으로 관리할 수 있는 인터페이스를 제공합니다.

3

신속한 해결 (Team Collaboration)
Slack 연동과 관리 페이지를 통해 빠른 문제 해결과 팀 간 협업을 지원합니다.

🎯 시스템 페르소나

시스템을 사용하는 세 가지 주요 사용자 그룹의 역할과 관심사를 정의하여 각각에게 최적화된 경험을 제공합니다.

👤 일반 사용자

• 역할: 대시보드 조회 및 데이터 확인
• 관심사: 정확한 데이터 확인, 빠른 화면 로딩
• 시스템 인지: 백그라운드 검증 시스템을 인지하지 못함

👨‍💼 데이터 관리자

• 역할: 데이터 품질 모니터링 및 1차 대응
• 관심사: 문제 신속 파악과 초기 대응
• 권한: 조회, 상태 변경, 코멘트 작성

👩‍💻 개발자

• 역할: 데이터 품질 문제 근본 해결
• 관심사: 문제 원인 파악, API 수정
• 권한: 전체 시스템 접근, 코드 수정

🔄 전체 시스템 플로우

시스템의 전체적인 데이터 흐름을 Frontend부터 Backend까지 단계별로 살펴보겠습니다.

전체 시스템 아키텍처 플로우

사용자 대시보드 접속

→

API 응답 수신

→

백그라운드 검증

→

에러 로그 생성

→

배치 로그 수집

→

Spring Boot 수신

→

DB 저장

→

Slack 알림

Frontend 처리 과정

Frontend에서는 사용자 경험을 방해하지 않으면서 데이터 품질을 검증하는 것이 핵심입니다.

// Frontend: 백그라운드 검증 프로세스
1. 사용자가 대시보드에서 데이터 요청
2. API 호출 및 응답 수신 (사용자는 즉시 데이터 확인 가능)
3. 백그라운드에서 Zod 스키마 검증 수행
4. 검증 실패 시 BatchLogger 큐에 에러 추가
5. 30초 간격 또는 20개 누적 시 Backend로 배치 전송

Backend 처리 과정

Backend에서는 수집된 데이터 품질 이슈를 체계적으로 관리하고 알림을 전송합니다.

// Backend: Spring Boot 처리 과정
1. Frontend에서 배치 로그 수신
2. 데이터 검증 및 DB 저장
3. 중복 제거 및 통계 생성
4. Slack Webhook을 통한 실시간 알림 전송
5. Admin API를 통한 관리 인터페이스 제공

📊 상세 사용자 시나리오

시나리오 1: 일반 사용자의 대시보드 사용

일반 사용자가 대시보드를 사용하는 과정에서 어떻게 백그라운드 검증이 이루어지는지 살펴보겠습니다.

1

대시보드 접속
사용자가 로그인 후 모니터링 대시보드에 접속하고 원하는 지역이나 카테고리를 선택합니다.

2

데이터 조회
실시간 데이터 확인, 차트 조회, 현황 위젯 등을 통해 필요한 정보를 확인합니다.

3

백그라운드 처리
사용자가 인지하지 못하는 사이에 자동 검증이 수행되고, 문제 발견 시 로그가 생성됩니다.

실제 발생 예시

1. 사용자가 실시간 데이터 위젯에서 현재 수치를 확인
2. API 응답에서 totalValue: null 수신 (예상: number)
3. 백그라운드에서 Zod 검증 실패 감지
4. BatchLogger가 에러를 큐에 추가
5. 30초 후 또는 20개 누적 시 Backend로 배치 전송

시나리오 2: 데이터 관리자의 문제 해결

데이터 관리자가 Slack 알림을 받고 문제를 해결하는 전체 과정을 순차적으로 살펴보겠습니다.

데이터 관리자 문제 해결 플로우

Slack 알림 수신

→

관리 페이지 접속

→

문제 로그 확인

상태 "진행중"으로 변경

→

문제 분석 및 대응

→

상태 "해결완료"로 변경

관리자의 주요 액션

• GET /validation/management/logs: 페이지네이션된 로그 목록 조회
• GET /logs/{logId}: 특정 로그의 상세 정보 확인
• POST /logs/{logId}/resolve: 로그 상태 변경 및 코멘트 추가
• Slack 알림: 상태 변경 시 팀에 자동 알림 전송

// 관리자가 확인하는 문제 정보
{
  "logId": "12345",
  "apiEndpoint": "/api/dashboard/summary",
  "fieldName": "totalValue",
  "expectedType": "number",
  "actualValue": null,
  "occurredAt": "2025-01-15T10:30:00Z",
  "userAgent": "Chrome/96.0",
  "status": "PENDING"
}

시나리오 3: 관리 페이지 기능 활용

관리 페이지에서 제공하는 다양한 기능들을 통해 데이터 품질 문제를 체계적으로 관리할 수 있습니다.

📊 통계 및 필터링

• 상태별 로그 개수 카드
• 날짜, API, 상태별 필터링
• 페이지네이션된 로그 목록
• 검색 기능

🔍 상세 분석

• API 호출 정보 및 파라미터
• 필드별 검증 실패 내역
• 재수집 표시 기능
• 해결 히스토리 추적

상태 관리 워크플로우

PENDING (대기) ├── IN_PROGRESS (진행중) │ ├── 관리자가 문제 확인 및 분석 중 │ ├── 개발팀에 이슈 전달 │ └── 해결 조치 진행 └── RESOLVED (해결완료) ├── 근본 원인 해결 ├── 데이터 재수집 확인 └── 해결 내역 문서화

🔔 알림 시스템

Slack 연동 알림 플로우

데이터 품질 문제가 감지되면 즉시 팀에 알림을 전송하여 빠른 대응이 가능하도록 합니다.

// Slack 알림 메시지 예시
🚨 데이터 품질 문제 감지

📍 API: /api/dashboard/summary
🔍 필드: totalValue
❌ 문제: 예상 타입 number, 실제 값 null
⏰ 발생 시간: 2025-01-15 10:30:00
🔗 관리 페이지: [바로가기]

담당자는 즉시 확인 바랍니다.

1

에러 감지
Frontend에서 Zod 검증 실패 감지

2

배치 수집
BatchLogger가 에러들을 모아서 Backend로 전송

3

DB 저장
Spring Boot에서 로그 정보를 데이터베이스에 저장

4

Slack 알림
Webhook을 통해 전용 채널에 즉시 알림 전송

5

담당자 확인
관리자가 알림 확인 후 관리 페이지에서 문제 처리

🛠️ 기술 스택 및 구현

Frontend 구현

영역	기술 스택	주요 기능
데이터 검증	Zod, TypeScript	런타임 스키마 검증, 타입 안전성
로그 수집	BatchLogger Class	배치 처리, 메모리 효율성
API 통신	Axios, React Query	HTTP 요청, 캐싱, 재시도
관리 UI	React, Ant Design	관리 페이지, 테이블, 필터링

Backend 구현

영역	기술 스택	주요 기능
API 서버	Spring Boot, JPA	REST API, 데이터베이스 ORM
데이터베이스	PostgreSQL	로그 저장, 통계 쿼리
알림 시스템	Slack Webhook	실시간 알림, 팀 협업
배치 처리	Spring Batch	대용량 로그 처리, 통계 생성

🚀 베스트 프랙티스

✅ DO - 해야 할 것들

• 즉각적인 Slack 확인: 알림 수신 시 빠른 확인과 대응
• 상세한 코멘트 작성: 해결 시 원인과 조치사항을 명확히 기록
• 팀 공유: 반복되는 문제는 팀 전체와 공유하여 학습
• 예방 조치: 동일한 문제의 재발 방지책을 수립
• 문서화: 모든 해결 과정을 체계적으로 기록

❌ DON'T - 하지 말아야 할 것들

• 알림 무시: 모든 알림은 반드시 확인하고 대응
• 임시 조치만 진행: 근본 원인 해결이 필수
• 단독 처리: 복잡한 문제는 반드시 팀 협업
• 문서화 생략: 해결 과정 생략 시 동일 문제 재발 위험
• 상태 변경 누락: 작업 진행 상황을 반드시 업데이트

📈 시스템 효과 및 성과

정량적 효과

• 문제 감지 시간: 기존 수시간 → 실시간 (즉시)
• 해결 소요 시간: 평균 2-3일 → 수시간 내
• 사용자 영향도: 서비스 중단 → 무중단 서비스 유지
• 팀 협업 효율성: 개별 대응 → 체계적인 협업 체계

정성적 효과

• 개발자 경험 향상: 문제 상황을 구체적으로 파악할 수 있어 디버깅이 용이해졌습니다
• 데이터 신뢰성 증대: 지속적인 모니터링으로 데이터 품질이 전반적으로 향상되었습니다
• 팀 커뮤니케이션 개선: Slack 연동으로 투명하고 신속한 커뮤니케이션이 가능해졌습니다
• 예방적 관리 체계: 반응적 대응에서 예방적 관리 체계로 전환되었습니다

 

마무리

이 데이터 품질 관리 시스템은 Frontend의 사용자 경험부터 Backend의 안정적인 데이터 관리까지 전체 생태계를 아우르는 포괄적인 솔루션입니다. 단순히 문제를 감지하는 것을 넘어서, 팀 협업, 빠른 대응, 지속적인 개선을 통해 전체적인 서비스 품질 향상에 기여하고 있습니다.

특히 사용자 경험을 전혀 방해하지 않으면서도 백그라운드에서 지속적으로 데이터 품질을 모니터링하는 이 접근법은 실제 운영 환경에서 매우 효과적임이 입증되었습니다.