Theme D — 벡터 인덱스(D-2) + 스키마 동기화(D-4) QA 가이드 (#1151)
이 문서는 거버넌스 벡터 인덱스 상태/재색인(D-2) 과 스키마 동기화 이력/실행(D-4) 화면을 QA가 화면에서 직접 따라 검증할 수 있도록 단계별 스크린샷과 함께 정리한 것입니다. 모든 화면은 실제 GenD prod 환경의 데모 워크스페이스에서 캡처했습니다.
개요
Theme D는 백엔드/런타임 상태를 정직하게 노출하는 두 개의 거버넌스 관리 화면을 제공합니다.
- D-2 벡터 인덱스(
/governance/vector-index) — Weaviate/Milvus/Oracle/Elasticsearch 백엔드별 상태 카드(사용 가능 여부·정상 여부·벡터 수)와 백엔드별 재색인(Reindex) 버튼. - D-4 스키마 동기화(
/governance/schema-sync) — 데이터 소스 스키마 동기화 실행 이력 표(상태 배지·소스 참조·시작/종료·변경 감지 수·실패 사유 툴팁)와 동기화 실행(Trigger) 버튼.
정직한 스켈레톤(honest-skeleton) 불변식
두 화면 모두 "데이터가 아직 없거나 미구성"인 상태를 가짜 값으로 위장하지 않는다는 단 하나의 원칙을 공유합니다.
- 벡터 인덱스: 백엔드가 미구성(
available=false) 이거나 장애로 카운트를 알 수 없을 때(vector_count=null), 카드는 muted "미구성/대기 중(Pending)" 상태로 렌더됩니다 — 절대 가짜0을 표시하지 않습니다. (실제로 비어 있지만 도달 가능한 인덱스의0과는 구분됩니다.) - 스키마 동기화: 이력이 없으면 "동기화 이력이 없습니다" 빈 스켈레톤을 보여줍니다 — 빈 표를 그대로, 정직하게 노출합니다.
권한: 상태 조회(
stats)·이력 조회(history)는 뷰어가 읽을 수 있습니다. 재색인(reindex) 과 동기화 실행(trigger) 은 워크스페이스 admin(글로벌admin역할 또는 Keycloak/tenants/<slug>/admins멤버) 만 가능하며, 서버에서 시행됩니다. 비-admin 의 재색인/실행 차단(403)은 E2E 계정이 admin 이라 화면으로 재현할 수 없어(아래 참고) API/단위 테스트로 검증합니다.
사전 준비 / 시드
별도 시드 스크립트는 필요 없습니다.
- 계정: 워크스페이스 admin 계정(글로벌
admin역할이면 충족) — 재색인/실행 버튼이 보이려면 필요합니다. - D-4 동기화 실행은 실제
schema_sync이력 행을 새로 생성합니다(검증 절차 자체가 데이터를 만듭니다). E2E 스펙(ui/tests/theme-d-vector-schema-e2e.spec.ts)도 동일하게 시나리오에서 직접 트리거합니다. - D-2 재색인은 백엔드 잡을 best-effort 로 기동할 뿐, 목록 행을 남기지 않습니다. 환경에 도달 가능한 백엔드가 없으면 재색인 대신 오류 토스트가 뜨며, 이 또한 정직한(가짜 성공이 아닌) 결과입니다.
- 백엔드 미구성 환경: prod 에서 특정 백엔드가 구성되어 있지 않으면, 그 백엔드의 muted "미구성/대기 중" 상태가 곧 기대하는 캡처입니다.
1. 벡터 인덱스 — 백엔드별 상태 카드 (S1)
좌측 사이드바 거버넌스 → 벡터 인덱스 로 들어가면, 알려진 벡터 백엔드(Weaviate/Milvus/Oracle/Elasticsearch)별 상태 카드가 그리드로 표시됩니다. 각 카드는 다음 세 가지 상태 중 하나입니다.
- 정상(Healthy) —
available=true && healthy=true. 우상단에 초록색 "정상" 배지, 본문에 벡터 수(숫자) 가 보입니다. - 비정상(down) —
available=true && healthy=false. 구성은 되어 있으나 오프라인 — muted 카드 + "대기 중". - 미구성(unconfigured) —
available=false. 자격증명/배선이 없음 — muted 카드 + 우상단 "미구성" + 본문 "대기 중(Pending)".
확인 포인트(QA, 핵심 불변식): 미구성/장애 백엔드 카드의 벡터 수 칸이 "대기 중(Pending)" 으로 표기되고, 절대 가짜
0이 아닌지 확인합니다. 구성된(정상) 백엔드만 실제 숫자 벡터 수를 보여줍니다. 환경에 구성된 백엔드가 하나도 없으면 "구성된 벡터 백엔드가 없습니다" 빈 카드가 정직하게 표시됩니다.
2. 벡터 인덱스 — 재색인 → 토스트 (S2)
각 카드의 우하단(워크스페이스 admin 에게만 노출)에 재색인(Reindex) 버튼이 있습니다. 미구성 백엔드에서는 비활성화되어 있습니다(가짜 재색인 방지). 사용 가능한 백엔드의 재색인 버튼을 누르면 POST /ai/index/reindex 가 호출되고, sonner 토스트가 뜹니다.
- 도달 가능한 백엔드 → "
{{backend}}재색인을 시작했습니다 (run: …)" 성공 토스트({{backend}}자리에 실제 백엔드 이름이 들어갑니다). - 도달 불가/오류 백엔드 → "재색인 실행에 실패했습니다" 오류 토스트(조용한 no-op 금지 — 어느 쪽이든 정직하게 노출).
확인 포인트(QA): 사용 가능한 백엔드의 재색인 버튼이 활성화되어 있고, 클릭 시 성공/실패 토스트 중 하나가 분명히 뜨는지 확인합니다. 환경에 사용 가능한 백엔드가 없으면 모든 재색인 버튼이 비활성(또는 미노출)이며, 그 muted 카드 자체가 정직한 캡처입니다.
3. 스키마 동기화 — 이력 표 + 상태 배지 (S3)
좌측 사이드바 거버넌스 → 스키마 동기화 로 들어가면, schema_sync 실행 이력 표가 보입니다. 각 행은 상태 배지(색상으로 구분), 소스 참조, 시작/종료 시각, 변경 감지 수, 실행자를 보여줍니다.
- 성공(succeeded) — 초록 배지.
- 실행 중(running) — 파랑 배지.
- 실패(failed) — 빨강 배지.
- 대기(pending) — 노랑 배지.
확인 포인트(QA): 이력 행마다 상태 배지가 상태에 맞는 색으로 렌더되는지 확인합니다. 이력이 없으면 "동기화 이력이 없습니다" 빈 스켈레톤이 정직하게 표시됩니다(빈 표를 위장하지 않음).
4. 스키마 동기화 — 실행(Trigger) → 새 이력 행 (S4)
화면 우상단(워크스페이스 admin 에게만 노출)의 동기화 실행(Trigger) 버튼을 누르면 POST /schema-sync/trigger 가 호출되어 동기화가 기동되고, 이력 표 맨 위에 새 이력 행(실행 중) 이 추가됩니다. 새 행은 실행 중 → 성공/실패 로 진행되며 변경 감지 수를 함께 보여줍니다.
⏱ 동기화 실행은 동기(synchronous)·장시간 작업입니다 (검증된 동작):
POST /schema-sync/trigger는 카탈로그 동기화를 요청 안에서 동기적으로 끝까지 수행한 뒤 응답합니다. prod 에서 전체 동기화는 수 분(관측상 ~4–5 분) 걸리므로, 라우터가 응답하기 전까지 HTTP 요청이 블록됩니다. 따라서 "동기화를 시작했습니다" 성공 토스트는 그 블로킹 응답이 돌아온 뒤에야 뜹니다(즉시 안 뜸). 다만 라우터는 느린 동기화 전에 "실행 중" 이력 행을 즉시 커밋하므로, 새 행은 ~1 초 내에 이력에 나타납니다. QA E2E 는 이 이유로 (느린 토스트 대신) 이력에 새 행이 생기는지를 신호로 검증합니다. 아래 스크린샷은 실행 직후 맨 위에 추가된 "실행 중" 행을 보여줍니다(이전 트리거들이 끝나며 성공 으로 전이된 행들도 함께 보입니다).
4-1. 실패 행의 오류 툴팁
실패(failed) 행의 상태 배지는 키보드 포커스 가능한 <button> 으로 렌더되어(a11y), 마우스 호버 또는 Tab/포커스 시 실패 사유(error_msg) 툴팁이 나타납니다. 실패 사유를 화면에서 바로 확인할 수 있습니다. (위 §4 스크린샷의 이력 표에는 현재 실패 행이 없으므로(전부 실행 중/성공) 툴팁을 캡처할 수 없으며 — 이는 "실패 없음"이라는 정직한 결과입니다. 실패 행의 포커스 가능한 배지 + 오류 툴팁 렌더는 단위 테스트 ui/src/components/governance/SchemaSyncPage.test.tsx 가 검증합니다.)
확인 포인트(QA): 동기화 실행 직후 새 "실행 중" 행이 이력 표 맨 위에 추가되는지, 새 행의 상태 배지가 실행 중/성공/실패 중 하나로 정확히 표시되며 변경 감지 수가 숫자(또는 실행 중이면 "—")로 나오는지 확인합니다. 성공 토스트는 동기화가 끝난 뒤에야 뜨므로(수 분 소요) 즉시 안 떠도 정상입니다. 실패 행이 있으면 배지에 포커스/호버 시 오류 툴팁이 보이는지 확인합니다.
QA 체크리스트 요약
| # | 화면 | 시나리오 | 기대 결과 |
|---|---|---|---|
| S1 | 벡터 인덱스 | 백엔드별 상태 카드 | 구성=숫자 벡터 수, 미구성/장애=muted "대기 중"(가짜 0 금지) |
| S2 | 벡터 인덱스 | 재색인(ws-admin) | 사용 가능 백엔드 재색인 → 성공/실패 토스트 |
| S3 | 스키마 동기화 | 이력 표 + 상태 배지 | 행별 상태 배지(성공/실행 중/실패 색), 이력 없으면 정직한 빈 스켈레톤 |
| S4 | 스키마 동기화 | 실행(ws-admin) | Trigger → 새 행(실행 중→성공/실패) + 변경 감지 수, 실패 행 오류 툴팁 |
| — | 공통 | 비-admin 재색인/실행 403 | (화면 불가) API/단위 테스트로 검증 |
비-admin 403은 화면으로 검증 불가: E2E 계정이 admin 이라 비-admin 의 재색인/실행 차단(403)은 브라우저로 재현할 수 없습니다.
stats/history는 뷰어가 읽고,reindex/trigger는 서버에서 ws-admin 으로 시행됩니다. 이는/ai/index/reindex·/schema-sync/trigger의 API/단위 테스트가 검증합니다.
알아두기
- 정직한 스켈레톤이 핵심: 두 화면의 모든 "데이터 없음/미구성" 상태는 가짜 값으로 위장하지 않습니다 — 벡터 인덱스는 muted "대기 중", 스키마 동기화는 빈 이력 스켈레톤으로 정직하게 노출합니다. 가짜
0은 회귀(regression) 입니다. - 재색인은 best-effort: D-2 재색인은 백엔드 잡을 기동할 뿐 목록 행을 남기지 않습니다. 성공/실패 토스트가 유일한 즉시 피드백입니다.
- 실행은 실제 이력 생성: D-4 동기화 실행은 진짜
schema_sync이력 행을 만듭니다(changes_detected포함). 실행 직후 새로고침으로 새 행이 보입니다. - 권한 분리: 조회(stats/history)는 뷰어, 변경(reindex/trigger)은 ws-admin — UI 버튼 노출은 UX 게이트이고 실제 차단은 백엔드가 시행합니다.
- 상태 배지 색: 성공=초록, 실행 중=파랑, 실패=빨강, 대기=노랑.