문서 뷰어 QA 가이드 — 시각 프리뷰 · 청크 위치 하이라이트
이 문서는 문서 뷰어(업로드한 문서를 시각적으로 미리보고, 청크를 선택하면 문서 내 위치를 하이라이트하는 기능)를 QA가 화면에서 직접 따라 검증할 수 있도록 단계별로 정리한 것입니다. 모든 화면은 실제 GenD prod 환경에서 캡처했습니다.
대상 포맷 (5종 전부 지원):
| 포맷 | 시각 렌더 방식 | 청크 하이라이트 방식 |
|---|---|---|
react-pdf (페이지 canvas) | 페이지 위 bbox 오버레이 (백엔드 PyMuPDF 좌표) | |
| HWP / HWPX | @rhwp/core (WASM → SVG) | SVG 위 <rect> 오버레이 (글자 좌표 매칭) |
| DOCX | mammoth (→ HTML) | 본문 텍스트 <mark> 래핑 |
| XLSX | SheetJS (→ 시트 표) | 매칭 셀 배경 강조 + 매칭 최다 시트 자동 전환 |
| PPTX | pptx-preview (→ 슬라이드) | 슬라이드 텍스트 <mark> 래핑 |
핵심 동작 원칙: 좌측은 문서를 시각적으로 렌더하고, 우측 청크 목록에서 청크를 클릭하면 그 청크의 텍스트가 문서의 어디에 있는지 좌측에 하이라이트됩니다. 좌표(bbox)가 필요한 건 PDF·HWP뿐이고, Office(DOCX/XLSX/PPTX)는 렌더된 텍스트를 청크 텍스트와 매칭해 표시합니다.
0. 사전 준비
0-1. 검증용 샘플 파일
각 포맷의 샘플 문서가 필요합니다. 직접 보유한 실파일을 써도 되고, 없으면 아래 스크립트로 생성할 수 있습니다(서버 apps/api 가상환경 기준).
# python-docx, openpyxl, python-pptx 필요
from docx import Document
from openpyxl import Workbook
from pptx import Presentation
doc = Document()
doc.add_heading("QA 테스트 문서", 0)
for i in range(30):
doc.add_paragraph(f"이 문단은 DOCX 시각 프리뷰 검증용 {i}번째 문단입니다.")
doc.save("qa-sample.docx")
wb = Workbook()
ws = wb.active
ws.title = "매출"
ws.append(["항목", "금액"])
for i in range(50):
ws.append([f"품목{i}", 1000 + i])
wb.save("qa-sample.xlsx")
prs = Presentation()
for i in range(5):
slide = prs.slides.add_slide(prs.slide_layouts[1])
slide.shapes.title.text = f"슬라이드 {i + 1} 제목"
slide.placeholders[1].text = f"PPTX 검증용 본문 {i + 1}"
prs.save("qa-sample.pptx")
PDF·HWP는 실파일을 준비하세요. (HWP는 HWPX도 가능하며, 텍스트 추출이 가능한 문서여야 합니다 — 스캔 이미지만 든 문서는 미지원.)
0-2. ⚠️ 중요 — 기존 문서는 재업로드 필요
문서 뷰어의 시각 렌더는 업로드 시점에 원본을 별도 저장합니다. 따라서 이 기능 배포 이전에 올라간 문서는 원본이 없어 시각 프리뷰가 뜨지 않고 텍스트 뷰로 fallback됩니다. QA 시에는 반드시 새로 업로드한 문서로 검증하세요.
0-3. 검증 위치
브라우저에서 경로 /ai/documents (상단 제목이 문서인 페이지)로 이동해 진행합니다.
1. UI 업로드 (전 포맷 공통)
- 문서 페이지 우상단 문서 업로드 버튼을 클릭합니다.
- 파일 선택 다이얼로그에서 샘플 파일을 고릅니다. 파일 선택기의 허용 확장자가
.pdf, .docx, .hwp, .xlsx, .pptx, .txt, .md인지 확인합니다. - 보안 등급(기본
PUBLIC)을 두고 업로드 + Ingest 를 클릭합니다. - 잠시 후 목록 표에 방금 올린 파일이 청크 수와 함께 나타나면 성공입니다.
✅ 체크포인트: PDF·DOCX·XLSX·PPTX·HWP 5종 모두 이 업로드 버튼으로 올라가야 합니다(드래그 우회가 아니라 실제 UI 업로드).
2. 포맷별 시각 프리뷰 + 청크 하이라이트 검증
각 포맷마다: ① 목록에서 파일 행 클릭 → 프리뷰 열기 → ② 좌측에 시각 렌더 확인 → ③ 우측 청크 목록에서 청크 클릭 → ④ 좌측에 하이라이트 표시 확인.
2-1. PDF
PDF 페이지가 이미지로 렌더되고, 청크 클릭 시 반투명 인디고 박스(bbox) 가 해당 텍스트 줄들을 덮습니다. 여러 줄에 걸친 청크는 줄마다 박스가 생기고 해당 페이지로 스크롤됩니다.
✅ 청크를 클릭하면 좌측 PDF에 인디고 박스가 뜨고 그 위치로 스크롤되어야 합니다.
2-2. HWP / HWPX
HWP가 SVG로 렌더되고(수식·표 포함), 청크 클릭 시 글자 위에 인디고 사각형 오버레이가 표시됩니다.
✅ 수식이 많은 문서는 일부 청크가 부분 매칭될 수 있으나(graceful), 본문 청크는 정상 하이라이트됩니다.
2-3. DOCX
Word 문서가 본문 HTML로 렌더되고, 청크 클릭 시 해당 문단 텍스트가 인디고 형광펜(<mark>) 으로 표시되며 그 위치로 스크롤됩니다.
✅ 만약 변환 결과가 비어 있는 문서(텍스트박스/헤더 위주)라면 자동으로 텍스트 뷰로 fallback 됩니다(빈 화면에 멈추지 않음).
2-4. XLSX
엑셀이 시트 탭 + 표로 렌더되고, 청크 클릭 시 매칭되는 셀의 배경이 인디고로 강조됩니다. 매칭이 가장 많은 시트로 자동 전환되며, 시트 탭에는 매칭 셀 수가 (N) 으로 표시됩니다. 사용자가 수동으로 다른 탭을 눌러도 강제 복귀되지 않습니다.
✅ 시트 탭 라벨에
매출 (153)처럼 매칭 수가 보이고, 해당 셀들이 강조되어야 합니다.
2-5. PPTX
파워포인트가 슬라이드로 렌더되고, 청크 클릭 시 해당 슬라이드 텍스트가 인디고 형광펜 으로 표시됩니다.
✅ 청크 본문 머리의
[Slide N]표기는 RAG용 내부 마커이며, 하이라이트는 마커를 제외한 실제 슬라이드 텍스트에 정확히 매핑되어야 합니다.
3. 엣지 케이스 체크리스트
| # | 시나리오 | 기대 동작 |
|---|---|---|
| 1 | 기능 배포 이전 업로드 문서 열기 | 시각 렌더 대신 텍스트 뷰로 표시(빈 화면 X) |
| 2 | 청크 선택 해제 후 같은 청크 재선택 | 다시 해당 위치로 스크롤됨 |
| 3 | 문서 A에서 청크 선택 → 문서 B 열고 같은 인덱스 청크 선택 | 문서 B의 올바른 위치로 스크롤됨 |
| 4 | 매칭되는 텍스트가 없는 청크(수식·이미지 위주) | 하이라이트 없이 렌더만 유지(에러 X) |
| 5 | 5MB(PPTX는 15MB) 초과 대용량 문서 | 텍스트 뷰로 fallback |
| 6 | DOCX 변환이 빈 결과 | 텍스트 뷰로 fallback(“변환 중…”에서 멈추지 않음) |
4. 통과 기준 (Definition of Done)
- PDF·HWP·DOCX·XLSX·PPTX 5종 모두 UI 업로드 → 시각 렌더 확인
- 5종 모두 청크 클릭 시 좌측에 하이라이트(bbox / rect / mark / 셀) 표시 + 해당 위치로 스크롤
- 기존(구) 문서는 텍스트 뷰로 안전하게 fallback
- 매칭 실패 청크에서도 화면이 깨지지 않음
참고: 본 기능의 설계 배경과 포맷별 구현은 내부 스펙
docs/superpowers/specs/2026-06-08-office-preview-design.md및2026-06-06-document-viewer-chunk-highlight-design.md를 참고하세요.