RAG 기반 문서 검색 시스템 - 9(근거 문장 UI 콜랩스/확장 구현)

개요

앞선 글에서는 샘플문서 초기 탑재 작업 에 대해 다뤘다. 이번 글에서는 실제 사용자가 문서를 열람하거나 질문 응답 시 확인할 수 있는 근거 문장 UI를 어떻게 구성했는지를 다룬다. 근거 문장은 LLM 응답의 신뢰도를 강화하기 위한 핵심 요소로, 해당 기능은 콜랩스/확장, 메타데이터 표시, 페이지 이동, 접근성을 모두 지원하도록 설계되었다.

EvidenceUI 작업 흐름

이번 작업은 총 7단계의 서브태스크로 구성되었으며, UI 설계부터 접근성 준수, 통합 테스트 및 문서화까지 전 범위를 아우른다.

1. 요구사항 분석 및 UI/UX 설계
2. EvidenceDisplay 컴포넌트 설계 및 구현 (콜랩스/확장, 신뢰도, 메타데이터, 접근성)
3. DocumentViewer 컴포넌트 구현 (페이지 이동, 청크 하이라이트, 네비게이션)
4. EvidenceIntegrationDemo 통합 및 E2E 테스트
5. 반응형 및 접근성 개선 (WCAG 2.1 AA 기준)
6. 브라우저 호환성/터치 영역 등 문제 해결
7. 개발 가이드 및 문서화

기능 요약

카테고리	내용
근거 문장 표시	콜랩스/확장 UI, 신뢰도 배지, 메타데이터
문서 뷰어 연동	근거 문장 클릭 시 원문 페이지 이동 및 청크 하이라이트
접근성	키보드 내비게이션, ARIA 속성, 색상 대비 개선
반응형 UI	모바일/데스크톱 대응, 터치 최적화
E2E 테스트	근거 → 페이지 이동 → 청크 강조 전체 시나리오 자동 테스트
문서화	컴포넌트 사용 예제, 테스트 가이드, 배포 체크리스트

디자인 및 기술 이슈 해결

• 키보드 접근성 강화: Enter/Space 키로 토글, focus-visible 적용
• 스크린 리더 대응: ARIA role, aria-labelledby/aria-describedby 구조 설정
• 터치 영역 개선: 버튼 크기 확대, min-h/px 조정
• 페이지 이동/하이라이트: chunk-id 기반 자동 스크롤
• 애니메이션: Tailwind transition-all 적용으로 자연스러운 확장/축소

주요 코드 구조

1. 메타데이터 구조 정의

export interface EvidenceMetadata {
  documentId: string;
  documentTitle: string;
  pageNumber?: number;
  chunkIndex: number;
  confidenceScore: number;
  sourceText: string;
  timestamp: string;
}

2. 콜랩스/확장 및 키보드 토글

const handleKeyDown = useCallback((event: KeyboardEvent) => {
  if (event.key === 'Enter' || event.key === ' ') {
    event.preventDefault();
    onToggle();
  }
}, [onToggle]);

// transition 효과
const getAnimationClasses = () => {
  const base = 'transition-all duration-300 ease-in-out';
  return isExpanded ? `${base} max-h-96 opacity-100` : `${base} max-h-0 opacity-0`;
};

3. 페이지 이동 및 하이라이트

useEffect(() => {
  if (highlightedChunkId && containerRef.current) {
    const el = containerRef.current.querySelector(`[data-chunk-id="\${highlightedChunkId}"]`);
    if (el) el.scrollIntoView({ behavior: 'smooth', block: 'center' });
  }
}, [highlightedChunkId]);

4. 접근성 ARIA 속성

<article
  role="region"
  aria-labelledby="\${itemId}-title"
  aria-describedby={isExpanded ? contentId : undefined}
  tabIndex={0}
>
  <span
    role="status"
    aria-label={\`신뢰도: \${confidenceScore * 100}%\`}
    className={confidenceColor}
  >
    신뢰도: {confidenceScore * 100}%
  </span>
</article>

테스트 및 문서화

모든 기능은 EvidenceIntegrationDemo를 통해 통합되며, Jest 및 React Testing Library를 이용한 자동화 테스트를 완료하였다. 또한, docs/evidence-ui-components-guide.md 파일에 개발 가이드 및 사용 예제를 정리하였다.

관련 용어 정리

용어	설명
EvidenceDisplay	근거 문장을 표시하는 컴포넌트. 확장/축소 UI, 메타데이터, 신뢰도 배지를 포함함.
DocumentViewer	문서 내용을 페이지 단위로 보여주며, 특정 청크를 하이라이트할 수 있는 뷰어
WCAG	웹 콘텐츠 접근성 가이드라인(Web Content Accessibility Guidelines). 시각·청각 장애인을 포함한 모든 사용자 접근성 기준.
chunkIndex	문서 내 특정 청크(문단, 구간 등)의 순번
confidenceScore	LLM이 근거 문장으로 제시한 구절에 대한 신뢰도(0~1 사이의 값)

마무리

이번 작업을 통해 RAG 기반 문서 검색 시스템의 핵심 UX 요소인 근거 문장 UI를 완성했다. 콜랩스/확장, 메타데이터 구조화, 문서 뷰어 연동, 신뢰도 있는 답변 체계를 시각적으로 완성할 수 있었다. 다음 작업에서는 문서 메타데이터 및 버전 관리 기능 구현 에 대해 알아보겟다.