KOGAS 도메인 대시보드 QA 가이드 — 경영 현황 · 안전 관제
이 문서는 KOGAS 도메인 대시보드(경영 현황 / 안전 관제, #1156)를 QA가 화면에서 직접 따라 검증할 수 있도록 단계별 스크린샷과 함께 정리한 것입니다. 모든 화면은 실제 GenD prod 환경의 가스공사(energy-kogas) 워크스페이스에서 캡처했습니다.
개요
KOGAS 대시보드는 도메인 팩입니다 — 핵심(core) 플랫폼에 KOGAS 전용 화면이 박혀 있지 않고, 활성 워크스페이스가 가스공사(energy-kogas)일 때만 사이드바 진입점과 /portal/kogas 라우트가 노출됩니다. 다른 테넌트로 전환하면 이 팩은 완전히 사라집니다(메뉴 숨김 + 라우트 가드).
- 경영 현황(Executive) — 핵심 KPI 카드 5개 이상 + 핵심 지표 추세 차트.
- 안전 관제(Safety) — 설비 상태 타일 + (관리자) 활성 경보 목록 + 이상 징후 추세.
읽기 전용: 이 대시보드는 데이터를 조회만 합니다(생성/수정/삭제 없음). QA 중 어떤 리소스도 만들지 않습니다.
사전 준비 (Seed / 멤버십)
이 가이드의 유일한 전제 조건은 워크스페이스 멤버십입니다. 별도의 대시보드 시드 스크립트는 없습니다 — KPI/안전 데이터는 /api/v1/dashboard/kogas/* 가 읽기 전용으로 제공하며 화면에 렌더된 값을 그대로 검증합니다.
-
두 워크스페이스 멤버십: QA 계정이
energy-kogas(KOGAS) 그리고finance-invest(비-KOGAS) 모두의 멤버여야 합니다. W2 데모 시드로 함께 들어옵니다.python scripts/seed_w2_workspaces.py -
워크스페이스 전환: 상단 바의 워크스페이스 스위처(현재 워크스페이스 이름 버튼)에서 전환합니다. 두 워크스페이스가 드롭다운에 모두 보여야 합니다.
이 가이드의 스크린샷은 위 멤버십이 갖춰진 prod 데모 환경에서 캡처했습니다. 멤버십이 없으면 E2E 스펙(
ui/tests/kogas-dashboards-e2e.spec.ts)은 해당 시나리오를 graceful skip 합니다.
1. KOGAS 워크스페이스 활성화 → 사이드바 진입점
워크스페이스 스위처에서 한국가스공사(energy-kogas) 로 전환하면, 사이드바에 가스공사 대시보드 진입점이 나타납니다(비-KOGAS 워크스페이스에서는 보이지 않습니다).
확인 포인트(QA): 활성 워크스페이스가 KOGAS일 때만 가스공사 대시보드 메뉴가 보이는지 확인하세요. 도메인 팩이 다른 테넌트로 새지 않는 것이 핵심 수용 기준입니다.
1-1. 페이지 진입
가스공사 대시보드를 클릭하면 /portal/kogas 로 이동합니다. 페이지 제목은 가스공사 대시보드, 상단에 경영 현황 / 안전 관제 두 탭이 있습니다.
확인 포인트(QA): 제목(
가스공사 대시보드)과 두 탭이 보이고, 기본 활성 탭이 경영 현황인지 확인하세요. 두 탭 패널은 모두 마운트 상태로 유지되어(hidden-tab 패턴) 차트 크기가 0으로 붕괴하지 않습니다.
2. 경영 현황 (Executive)
경영 현황 탭은 핵심 KPI 카드와 추세 차트를 보여줍니다.
확인할 항목:
- KPI 카드 5개 이상이 실제 숫자로 렌더됩니다.
- 아직 연동되지 않은 지표는 가짜
0대신데이터 연동 대기 / Pending data플레이스홀더(점선 테두리 · 흐린 이탤릭)로 표시됩니다. - 핵심 지표 추세 차트(recharts 라인 차트)가 렌더됩니다.
확인 포인트(QA): "값이 진짜 0"(예: 사고 건수 0)과 "데이터 소스 미연동"이 시각적으로 구분되는지 확인하세요 — 미연동 지표는 반드시 데이터 연동 대기 문구로 표시되어야 하며
0으로 위장하면 안 됩니다(#1156 수용 기준).
3. 안전 관제 (Safety)
안전 관제 탭을 클릭하면 URL에 ?tab=safety 가 붙고(딥링크/새로고침 안전), 설비 상태 타일 · 이상 징후 추세 · (관리자) 활성 경보 목록이 보입니다.
확인할 항목:
- 설비 상태 타일 — 정상(초록)/주의(주황)/경보(빨강)/미연동(회색·
데이터 연동 대기) 색상 점. - 이상 징후 추세 차트(recharts). 데이터가 없으면 추세 플레이스홀더가 대신 표시됩니다.
- 활성 경보 목록 — 심각도 배지(낮음/중간/높음)와 메시지. 경보 목록은 서버에서 관리자에게만 노출되므로, 비-관리자 또는 활성 경보가 없으면 "활성 경보 없음" 빈 상태가 정상입니다.
확인 포인트(QA): 탭 클릭 후 주소창에
?tab=safety가 보이는지, 새로고침해도 안전 관제 탭이 유지되는지 확인하세요.
4. ✅ 엣지: 키보드 탭 이동
탭은 제어형 Radix Tabs 입니다 — 활성 탭은 ?tab= 쿼리로 관리되고, 마우스뿐 아니라 키보드로도 전환됩니다(중복 onClick 제거 후 Radix onValueChange 단일 경로).
탭에 포커스를 둔 뒤 →(ArrowRight) 를 누르면 안전 관제 로 이동하며 ?tab=safety 가 붙고, ←(ArrowLeft) 로 경영 현황 으로 돌아오면 파라미터가 사라집니다(경영 현황이 기본값).
확인 포인트(QA): 마우스 없이 키보드 화살표만으로 탭이 전환되고 URL 파라미터가 동기화되는지 확인하세요(접근성 경로).
5. ✅ 워크스페이스 게이팅 — 비-KOGAS 전환
워크스페이스 스위처에서 비-KOGAS 워크스페이스(예: finance-invest)로 전환하면, 사이드바의 가스공사 대시보드 진입점이 사라집니다.
메뉴만 숨기는 것이 아니라, 주소창에 직접 /portal/kogas 를 입력해도(딥링크/북마크) 라우트 가드(KogasWorkspaceRoute) 가 홈으로 리다이렉트합니다.
확인 포인트(QA): 비-KOGAS 워크스페이스에서 (1) 메뉴 진입점이 없고 (2)
/portal/kogas직접 접근 시 KOGAS 페이지(가스공사 대시보드제목)가 렌더되지 않고 홈으로 튕겨 나가는지 확인하세요. 멤버십이 비동기로 확정되는 동안에는 잠깐 로딩 스피너만 보이며, 확정 후에만 리다이렉트됩니다(유효한 KOGAS 딥링크를 잘못 튕기지 않기 위함).
QA 체크리스트 요약
| # | 시나리오 | 기대 결과 |
|---|---|---|
| 1 | KOGAS 워크스페이스 활성 | 사이드바에 가스공사 대시보드 진입점 노출 |
| 1-1 | /portal/kogas 진입 | 제목 가스공사 대시보드 + 경영/안전 탭 |
| 2 | 경영 현황 탭 | KPI 카드 ≥5(실값), 미연동 KPI = 데이터 연동 대기(0 아님), 추세 차트 |
| 3 | 안전 관제 탭 | 상태 타일 + 경보/빈상태 + 이상 추세, URL ?tab=safety |
| 4 | 키보드 탭 이동 | ←/→ 로 활성 탭 + ?tab= 동기화 |
| 5 | 비-KOGAS 전환 | 진입점 소거 + /portal/kogas 딥링크 홈 리다이렉트 |
알아두기
- 읽기 전용 도메인 팩: KPI/안전 데이터는
/api/v1/dashboard/kogas/*에서 조회만 하며, 서버 측 활성 워크스페이스 멤버십 미들웨어가 실제 데이터 격리를 강제합니다. UI 게이트는 메뉴/라우트 가시성 용도입니다. - 미연동 ≠ 0:
available=false지표는 항상데이터 연동 대기 / Pending data로 표시됩니다(가짜 0 금지). 값-단위의 전수 구분 매트릭스는 단위 테스트(ExecutiveDashboard.test.tsx)로도 검증됩니다. - 경보는 관리자 전용: 안전 경보 목록은 관리자에게만 노출됩니다 — 비-관리자/무경보 환경의 "활성 경보 없음" 빈 상태는 정상입니다.
- 자동화 스펙: 위 시나리오는
ui/tests/kogas-dashboards-e2e.spec.ts로 자동화돼 있으며,QA_CAPTURE=1로 실행하면 이 가이드의 스크린샷(/img/qa/kogas-dashboards/NN-*.png)을 그대로 생성합니다.