dashboard screen design

Dashboard 화면 설계

오래된 Grafana wireframe이 아니라 apps/dashboard-web/src의 실제 구현 화면을 기준으로 정리한다. 현장 Grafana는 별도 운영 화면이며 이 SPA의 route가 아니다.

공통 Shell

데스크톱은 좌측 Sidebar와 상단 TopBar, 본문으로 구성한다.

Sidebar:

Fleet
  전체 개요
Factories
  허용된 factory 목록
System
  클라우드 인프라   # can_view_system
  사용자 관리       # can_manage_users
Workspace
  AI 채팅
  일간 보고서
  이미지 스냅샷
  로그아웃

공장 항목은 risk dot과 score를 표시한다. Cloud Infra 항목은 overall status dot을 표시한다. Sidebar는 접기/펴기가 가능하고 상태를 브라우저에 보존한다.

TopBar는 breadcrumb, WebSocket 상태, refresh interval selector, 수동 refresh, 현재 시각을 화면 기능에 따라 표시한다.

Login과 Callback

Login은 Aegis-π 식별자, Cognito 인증 안내, 단일 로그인 버튼으로 구성한다. Callback은 인증 처리 spinner를 표시하고 실패 시 오류와 재시도 동작을 제공한다.

Fleet /

Fleet Safety Pulse

0~100 safety score 축을 위험 0~49, 주의 50~84, 안전 85~100 band로 표시한다. 공장 점과 label이 겹치지 않도록 위치를 보정하며, 상단에 전체/위험/ 주의/안전 공장 수를 표시한다.

Factory Card

각 카드는 다음 정보를 같은 위치에 둔다.

• 환경 유형과 factory ID
• risk level badge
• safety score와 band marker
• node ready/total
• pipeline badge
• 최근 10분 trend chart
• 상위 원인 3개

카드 전체가 공장 상세 이동 버튼이며 keyboard focus와 접근 가능한 label을 가진다.

Recent Changes

최근 10분 risk level 변화 중 악화 event를 표시한다. 전체/공장 selector가 있고, 새 event가 없을 때와 로딩 중을 구분한다.

Factory Detail /factory/:factoryId

Hero

safety score, risk/pipeline/stale badge, 10분 trend, node ready, 갱신 시각을 상단에서 한 번에 비교한다.

Tabs

Tab	주요 내용
Overview	top causes, 현재 센서/AI, node/workload/device/heartbeat 요약
Environment History	안전 점수, 온도/습도/기압, AI history chart
Infrastructure	node table, 자원 chart, workload와 pipeline 상세
Timeline	risk level/score 변화 event

History selector는 1H/6H/12H/24H다. Timeline selector는 10M/1H/6H/24H/CUSTOM이며 Custom은 최근 24시간 범위의 날짜/시간 selector를 제공한다.

Chart는 loading, empty, raw snapshot, bucket aggregate를 구분한다. 장기 history는 평균선, 최소/최대 또는 변동 범위, threshold, sample/bucket 정보를 사용한다.

Cloud Infra /cloud-infra

공장 화면과 분리된 System 화면이다.

상단:

• overall status
• fast/slow 수집 age
• fast/slow stale badge
• 수동/자동 refresh

본문:

1. 핵심 상태 Health strip
2. component matrix
3. dependency rail
4. 비즈니스 파이프라인
5. Dashboard runtime: ECS, ALB
6. 데이터 저장소: Redis, RDS
7. 공장 최신성
8. 관리 플레인: EKS node/pod, ArgoCD
9. 스토리지 최신성
10. 최근 1시간 상태 흐름

normal, warning, critical, unknown을 각각 정상, 주의, 위험, 미확인으로 표시한다. reasons[]는 상태 근거 chip, errors[]는 수집 실패 정보로 표시한다. LATEST가 없으면 available:false empty state를 사용한다.

Reports /reports

상단 selector 영역:

• 허용된 공장 segmented selector
• System 권한 사용자용 별도 cloud-infra selector
• 날짜 picker와 최근 날짜 shortcut
• PDF, Word, refresh action

본문은 Markdown의 제목, 문단, 목록, 표, bold, inline code를 렌더링한다. PDF는 인쇄 dialog, Word는 실제 .docx 다운로드다. 보고서가 ready 상태일 때만 내보내기 action이 활성화된다.

상태는 로딩, 보고서 없음, API 오류, 공장 미선택, 정상 본문을 구분한다.

AI Chat /chat

하단 composer 중심의 대화형 화면이다. 공장 selector, 응답 모드 selector(자동/빠른 답변/정밀 분석), 추천 질문, Markdown 답변, Evidence 패널을 제공한다.

질문은 POST /chat/query로 보내며 Backend가 intent, 시간 범위, 공장 범위를 해석한다. 데이터 조회 전 RBAC를 강제하고, 답변에는 확인값/추정/데이터 한계를 분리해 표시한다. 이미지 관련 질문은 image_ref의 presigned 이미지 목록을 함께 보여준다.

Image Snapshots /image-snapshots

System 권한 사용자가 AI 이벤트 증빙 이미지를 확인하는 갤러리 화면이다. 공장, 탐지 유형, 시각 범위 기준으로 S3 image_snapshot/ 객체를 조회하고 presigned URL로 이미지를 렌더링한다. 이미지 binary는 IoT Core가 아니라 S3 직접 업로드 경로를 사용한다.

User Management /admin/users

2열 작업 화면이다.

• 왼쪽: active 사용자 table, 역할 filter, 수정/삭제 action
• 오른쪽: 생성/수정 editor

Editor는 이메일, 이름, 역할, 공장 배정, System 권한을 다룬다. 수정 시 이메일은 비활성화된다. super_admin은 전체 공장으로 표시되고, factory_admin은 공장별 checkbox를 사용한다. 삭제는 확인 dialog 후 수행한다.

좁은 화면에서는 table과 editor를 단일 열로 전환하고 table은 가로 스크롤한다.

화면별 데이터 소스 매핑

각 화면이 어떤 API와 read model을 소비하는지 정리한다. 필드 스키마 상세는 데이터 모델, 엔드포인트는 API 명세를 따른다.

화면	API	read model	화면을 채우는 주요 필드
Fleet /	GET /factories	LATEST (GSI LATEST / RISK# 정렬)	factory_id, risk.level·risk.score, risk.top_causes[0..2].name 또는 field(name 우선, 없으면 field), infra_state.node_summary.ready/total, pipeline_status.status, updated_at, last_factory_state_at·last_infra_state_at(stale 판단)
Factory Overview	GET /factories/{id}	LATEST (GetItem)	dashboard.display_status, risk.score/level, risk.top_causes[], factory_state.sensor.*_avg(온/습/기압), factory_state.ai_result.{fire,fall,bend}_score, infra_state.workload_summary, infra_state.device_summary.*_available
Environment History	GET /factories/{id}/history?window=	1H→HISTORY#STATE(원시, max 500), 6/12/24H→GRAPH#5M(집계)	timestamp, risk_score·risk_level, sensor *_avg, AI *_score, bucket_seconds(sampling note), top_cause_names[](1H 원시 구간만)
Infrastructure	GET /factories/{id} + history	LATEST.infra_state + GRAPH#5M/HISTORY#STATE	node table·node_summary, workload_summary/workloads status, device_summary, pipeline_status, 자원 차트(history)
Timeline	GET /factories/{id}/history?window=	≤1H→HISTORY#STATE 원시, >1H→GRAPH#5M	risk level 변경·score 10점 이상 급락/회복 event, top_cause_names(집계 item은 원인 필드 없어 top_causes 없음)
Cloud Infra /cloud-infra	cloud infra 조회	CLOUD#infra/LATEST(fast/slow), HISTORY#FAST/SLOW	status(normal/warning/critical/unknown), reasons[](근거 chip), errors[](수집 실패), fast/slow 수집 age, 최근 1시간 흐름(HISTORY)
Reports /reports	GET /reports, GET /reports/{date}/{id}	S3 reports/daily/	공장·날짜 selector, Markdown 본문, PDF/Word export(ready 상태일 때만)
AI Chat /chat	POST /chat/query	DynamoDB/S3/RDS read model + Bedrock 설명	질문, intent/time/factory 해석, Evidence, image_ref, 답변 mode
Image Snapshots /image-snapshots	GET /image-snapshots*	S3 image_snapshot/ + LATEST.latest_image_snapshot	이미지 metadata, 탐지 유형, presigned GET URL

핵심 규칙: window=1h는 원인(top_cause_names)이 있는 HISTORY#STATE를, 그보다 긴 구간은 원인 없는 GRAPH#5M 집계를 조회한다. null·미수신 값은 정상으로 해석하지 않고 -/미계산/수집 대기/미확인으로 표시한다.

상태와 데이터 신뢰도

화면 상태	시각 처리
loading	spinner
empty	원인에 맞는 빈 상태 문구
error	위험 tone, 오류 내용, 다시 시도
stale	warning badge와 age
unknown	회색 미확인, 필요 시 collection error
background refresh	기존 데이터를 유지
WebSocket reconnect	연결 상태 label

null 또는 미수신 값은 정상 값으로 해석하지 않고 -, 미계산, 수집 대기, 미확인 중 문맥에 맞는 label을 사용한다.

반응형과 접근성

• 800px 이하에서 Sidebar는 overlay drawer다.
• 1, 2, 3, 4열 grid는 viewport에 따라 축소된다.
• table, tab, selector, 보고서 표는 필요한 경우 가로 스크롤한다.
• icon-only button은 aria-label과 title을 가진다.
• 공장 카드는 실제 button으로 keyboard 실행이 가능하다.
• 주요 control에 focus-visible outline을 표시한다.
• 상태는 색만 쓰지 않고 badge text, dot, label을 함께 사용한다.
• prefers-reduced-motion에서는 transition과 animation을 줄인다.

현장 Grafana와의 구분

factory-a 현장 Grafana의 BME280 time series, AI stat, Node Exporter 1860은 로컬 운영 도구로 유지된다. 본 문서의 Dashboard Web은 Cognito 인증, 멀티 공장 Fleet, 공장 상세 history/Timeline, Cloud Infra, Reports, User Management를 제공하는 별도 SPA다.

관련 문서

• Dashboard Web
• Dashboard 사용자 흐름
• 인증과 RBAC