dashboard data model

관제 화면 데이터 모델

Dashboard 데이터 모델을 storage model, API model, UI model로 나누어 정리한다. 현재 구현 기준은 DynamoDB AEGIS-DynamoDB-FactoryStatus, S3 aegis-bucket-data, RDS PostgreSQL metadata, Redis Pub/Sub이다.

---

모델 계층

계층	목적	Source
Storage model	수집/처리/조회 저장소의 물리 key와 보존 단위	DynamoDB, S3, RDS
API model	FastAPI endpoint가 반환하는 JSON/Markdown shape	apps/dashboard-backend/routers, services
UI model	Dashboard 화면이 카드, 차트, timeline, report로 소비하는 형태	Dashboard Web

Dashboard는 준실시간 관제 화면이다. 상태를 빠르게 보여주지만 실시간 제어 명령 모델을 포함하지 않는다.

---

Storage Model

DynamoDB FactoryStatus

공식 hot store는 AEGIS-DynamoDB-FactoryStatus다.

Item	Key	용도
Factory latest	pk=FACTORY#{factory_id}, sk=LATEST	공장별 최신 상태
Factory raw history	pk=FACTORY#{factory_id}, sk=HISTORY#STATE#{iso_timestamp}	1시간 이하 chart/timeline
Factory aggregate	pk=FACTORY#{factory_id}, sk=GRAPH#5M#{bucket_start_iso}	6h/12h/24h chart
Cloud latest	pk=CLOUD#infra, sk=LATEST	cloud/system 최신 상태
Cloud history fast	pk=CLOUD#infra, sk=HISTORY#FAST#{timestamp}	빠른 system metric history
Cloud history slow	pk=CLOUD#infra, sk=HISTORY#SLOW#{timestamp}	느린 inventory/config history

Factory LATEST 주요 필드

factory_id              string
environment_type        string
factory_state           map
infra_state             map
latest_image_snapshot   map
risk                    map
pipeline_status         map
dashboard               map
updated_at              timestamp
last_image_snapshot_at  timestamp
schema_version          string

risk:

score                   number
level                   "safe" | "warning" | "danger"
top_causes              list
calculated_at           timestamp
calculation_version     string

pipeline_status:

status                  "normal" | "warning" | "critical"
latest_infra_state_age_seconds number

factory_state와 infra_state는 수집 source별 nested shape를 유지할 수 있다. Backend는 화면용으로 필요한 값을 추출하되 storage item 전체를 단일 공장 latest API에서 반환한다.

HISTORY#STATE

HISTORY#STATE# item은 raw snapshot history다. GET /factories/{factory_id}/history에서 window<=1h일 때 사용한다. Backend는 최신순으로 제한 조회한 뒤 응답은 시간 오름차순으로 정렬한다.

GRAPH#5M

GRAPH#5M# item은 5분 집계 bucket이다. 긴 window chart에서 raw history 대신 사용한다.

주요 aggregate field:

sensor.temperature_celsius.{mean,min,max}
sensor.humidity_percent.{mean,min,max}
sensor.pressure_hpa.{mean,min,max}
risk.score.{mean,min,max,count}
ai_detection.by_type.fire_score.{mean,max}
ai_detection.by_type.fall_score.{mean,max}
ai_detection.by_type.bend_score.{mean,max}
infra.cpu_usage_percent.mean
infra.memory_usage_percent.mean
infra.disk_usage_percent.last
infra.nodes[]
quality.source_count

12h window는 5분 bucket 2개를 10분으로, 24h window는 4개를 20분으로 Backend에서 재집계할 수 있다.

S3

Dashboard Backend는 S3를 read-only로 사용한다.

processed/{factory_id}/{dataset}/yyyy=YYYY/mm=MM/dd=DD/hh=HH/{message_id}.json
image_snapshot/factory_id={factory_id}/yyyy=YYYY/mm=MM/dd=DD/hh=HH/{object}
reports/daily/yyyy=YYYY/mm=MM/dd=DD/{target}/report.md

target은 factory-a|factory-b|factory-c 같은 공장 ID 또는 cloud-infra다. 현재 report API는 reports/daily/ prefix를 list/get한다. image snapshot API는 S3 image_snapshot/ 객체를 presigned GET으로 제공한다. S3 raw 원본은 Dashboard 카드의 직접 조회 모델이 아니다.

RDS PostgreSQL Metadata

RDS는 관제 데이터가 아니라 Dashboard metadata/RBAC 저장소다.

Table	용도
factory	공장 metadata, active 여부
app_user	Cognito sub와 Dashboard 사용자 연결
user_factory_access	사용자별 공장 접근 권한
audit_log	사용자 관리 작업 audit

세부 role 정책과 화면 UX는 RBAC 문서에서 다룬다. 이 문서에서는 API 인가가 RDS metadata를 기준으로 한다는 점만 정의한다.

Redis

Redis는 저장 모델이 아니라 갱신 신호 모델이다.

channel = factory:update:{factory_id}
payload = DynamoDB LATEST item JSON

Redis payload는 내구 저장소가 아니므로 화면은 필요 시 REST로 DynamoDB latest/history를 다시 읽는다.

---

API Model

Factory Summary

Endpoint:

GET /factories

Backend는 각 LATEST item에서 UI 목록에 필요한 값을 추출한다.

factory_id
environment_type
risk_level
risk_score
top_causes
updated_at
pipeline_status
display_status
last_factory_state_at
last_infra_state_at
node_ready
node_total
workload_ready
workload_total

응답은 principal의 공장 접근 권한으로 필터링된다. 전체 목록에는 10초 in-process cache가 적용된다.

Factory Latest

Endpoint:

GET /factories/{factory_id}

공장 접근 권한을 확인한 뒤 DynamoDB LATEST item을 반환한다. item이 없으면 404다.

Factory History

Endpoint:

GET /factories/{factory_id}/history?window=1h&limit=...&since=...

공통 응답 필드는 차트 소비를 위해 flat하게 추출된다.

timestamp
risk_score
risk_score_avg
risk_score_min
risk_score_max
temperature_celsius_avg/min/max
humidity_percent_avg/min/max
pressure_hpa_avg/min/max
fire_score
fall_score
bend_score
fire_score_max
fall_score_max
bend_score_max
ai_max_score
cpu_usage_percent_mean
memory_usage_percent_mean
disk_usage_percent_last
nodes_mean
quality

window<=1h는 HISTORY#STATE# raw snapshot을 사용한다. window>1h는 GRAPH#5M# aggregate를 사용한다. since가 있으면 timestamp > since인 신규분만 반환한다.

Cloud Infra

Endpoints:

GET /cloud-infra
GET /cloud-infra/history?window=1h&track=fast&limit=500

Cloud infra API는 AWS live API를 호출하지 않는다. collector가 DynamoDB에 쓴 CLOUD#infra read model을 읽는다. 접근은 system view 권한으로 제한된다.

Reports

Endpoints:

GET /reports
GET /reports/{report_date}/{target}

GET /reports 응답:

report_date
factory_id
s3_key
last_modified
size_bytes

GET /reports/{report_date}/{factory_id}는 text/markdown 본문을 반환한다. factory_id=cloud-infra report는 system view 권한으로 보호된다.

Image Snapshots

Endpoints:

GET /image-snapshots/range
GET /image-snapshots

이미지 binary는 IoT Core를 통과하지 않고 S3 image_snapshot/에 저장된다. Dashboard Backend는 range endpoint로 picker 가용 범위를 제공하고, 목록 endpoint에서 metadata와 S3 object key를 기준으로 presigned GET URL을 발급해 화면에 전달한다. LATEST.latest_image_snapshot와 last_image_snapshot_at은 최신 증빙 표시와 채팅 evidence 보강에 사용된다.

Auth/RBAC

Endpoints:

GET /auth/me
GET /admin/users
POST /admin/users
PATCH /admin/users/{user_id}
DELETE /admin/users/{user_id}

/auth/me는 현재 principal의 user id, email, display name, global role, 사용자 관리 가능 여부, system view 가능 여부, 허용 factory 목록을 반환한다.

사용자 관리 API는 Cognito와 RDS metadata를 함께 사용한다. 세부 role 정의는 RBAC 문서로 연결한다.

---

UI Model

Fleet 카드

GET /factories의 summary를 사용한다.

UI 값	API field
공장명/ID	factory_id
위험 점수	risk_score
위험 단계	risk_level 또는 display_status
원인	top_causes
데이터 freshness	updated_at, last_factory_state_at, last_infra_state_at
파이프라인 상태	pipeline_status

Factory 상세

GET /factories/{factory_id}와 history endpoint를 함께 사용한다.

UI 영역	데이터
Latest 상태	LATEST item의 risk, factory_state, infra_state, pipeline_status
환경 센서 chart	history temperature/humidity/pressure avg/min/max
AI 탐지 chart	history fire/fall/bend mean/max
Infra chart	history CPU/memory/disk/node mean
Timeline	raw history의 risk 변화와 top_causes

Cloud/System 화면

GET /cloud-infra와 /cloud-infra/history를 사용한다. CloudWatch/EKS/Kubernetes API를 화면 요청 시점에 직접 호출하지 않는다.

Reports 화면

S3 Markdown report 목록과 본문을 표시한다. report 객체가 아직 생성되지 않았으면 목록은 비거나 상세는 404가 될 수 있다.

Image Snapshots 화면

S3 image_snapshot/ 목록과 presigned image URL을 사용한다. 화면은 공장, 시각, 탐지 유형을 기준으로 필터링하고, 객체가 없으면 빈 갤러리 상태를 표시한다.

AI Chat 화면

POST /chat/query 응답의 answer, intent, time_scope, evidence, image_ref, generator, model_tier, router를 표시한다. 채팅은 DynamoDB/S3/RDS read model만 조회하며, 데이터 수정 API가 아니다.

---

Staleness와 반영 지연

준실시간 Dashboard는 수 초~수십 초 단위 반영 지연을 허용한다.

기준	의미
updated_at	latest item이 갱신된 시각
factory_state.source_timestamp	factory telemetry 기준 시각
infra_state.source_timestamp	infra collector 기준 시각
pipeline_status.status	수집/처리 지연 상태

화면은 위험 단계뿐 아니라 stale 가능성을 함께 보여줘야 한다. stale한 데이터는 현재 상태의 단정이 아니라 마지막으로 관측된 상태다.

---

Superseded 모델

초기 문서의 서버리스 Dashboard API와 GET /api/factories/summary 같은 /api/* 후보 경로는 현재 구현 기준으로 superseded다. 현재 Backend endpoint는 root prefix 없는 FastAPI 경로(/factories, /cloud-infra, /reports, /image-snapshots, /chat/query, /auth/me, /admin/users, /ws/...)다.

factory-a 로컬 Grafana/InfluxDB 모델은 edge 현장 대시보드의 과거/로컬 모델로 남지만, Data/Dashboard VPC Backend의 source model은 DynamoDB/S3/RDS/Redis다.

---

관련 문서

• Dashboard VPC 설계
• Dashboard Backend 컴포넌트
• Dashboard 실시간 갱신 구조