SafeCrowd UI 기준

이 문서는 SafeCrowd 앱에서 사용자가 실제로 만나는 화면, 기능 기준, 후속 UI 개선 대상을 한곳에 정리한다. 세부 작업 단위와 상태 추적은 GitHub Issues와 Project에서 관리하고, 이 문서는 팀원이 "현재 어떤 화면 흐름이 기준인지", "이 버튼이 무엇을 하는지", "다음 Sprint에서 무엇을 보완해야 하는지"를 빠르게 확인하는 기준으로 쓴다.

domain의 import, validation, simulation 객체는 UI 디자인 대상이 아니다. UI는 src/application/에서 Qt Widgets로 구현하고, domain 결과를 화면에 표시한다.

1. 앱 전체 흐름

Sprint 1 기준 사용자 흐름은 다음 순서를 따른다.

앱 시작
Project Navigator에서 새 프로젝트 생성 또는 최근 프로젝트 열기
DXF 파일을 프로젝트 layout으로 import
Layout Review Workspace에서 구조와 issue 확인
필요한 경우 layout 수동 보정
blocking issue가 없으면 layout 승인
Scenario Authoring Workspace에서 baseline 시나리오 작성
보행자 배치와 운영 이벤트 목록 확인
실행 대상으로 stage
Run Workspace에서 실행, 일시정지, 재개, 정지
완료 후 Result Summary에서 핵심 결과 확인

Sprint 1 시연에서 가장 중요한 기준은 도면 불러오기 -> 검토/보정 -> 시나리오 작성 -> 실행이 끊기지 않는 것이다.

2. 공통 UI 구조

2.1 Workspace Shell

프로젝트가 열린 뒤 사용하는 공통 작업 화면 구조다. Layout Review, Scenario Authoring, Run, Analysis 화면은 같은 workspace shell 안에서 단계적으로 확장한다.

현재 구현 책임:

상단 프로젝트 메뉴
좌측 상태/이슈/작성 패널
중앙 canvas
우측 review/inspector/scenario/run/results 패널
하단 상태/요약 패널
Workspace Shell 옵션에 따라 left rail, left panel, right panel을 숨기거나 표시하며, 숨긴 영역은 폭을 남기지 않는다.
Project Navigator를 제외한 Workspace Shell 기반 화면은 상단 오른쪽 Hide Panel / Show Panel 버튼으로 우측 패널을 접고 펼칠 수 있다.

기본 레이아웃:

Top Bar
Left Panel
Center Canvas
Right Panel
Bottom Panel

상단바 현재 동작:

Project 버튼
Project > Save Project 드롭다운 액션
Tool 버튼 자리

저장 동작:

프로젝트 폴더에 safecrowd-project.json 저장
프로젝트 폴더에 layout.dxf 복사
layout review 상태 저장 시 프로젝트 폴더에 layout-review.json 저장
import provenance와 reimport 비교 정보 저장 시 프로젝트 폴더에 import-artifacts.json 저장
workspace shell 상태 저장 시 프로젝트 폴더에 workspace-state.json 저장
앱 데이터 경로에 최근 프로젝트 인덱스 저장
다음 앱 실행 시 Project Navigator 목록에 표시

저장 위치 정책:

기본 위치는 <사용자 Documents>/SafeCrowd Projects/<프로젝트 이름>이며, 새 프로젝트 화면에서 프로젝트 이름을 입력하면 폴더 경로가 이 규칙으로 자동 제안된다.
자동 제안 경로가 이미 비어 있지 않은 폴더와 충돌하면 (2), (3) 같은 접미를 붙여 사용 가능한 경로를 찾는다.
사용자가 Browse로 직접 고른 경로는 사용자의 의사로 보고, 이후 프로젝트 이름을 바꿔도 자동 갱신하지 않는다.
폴더명은 OS 금지 문자(\\ / : * ? " < > |)를 _로 치환해 정규화한다.
저장 시점에 다음 조건을 만족하지 않으면 거부한다.
- 드라이브 또는 볼륨의 루트가 아니어야 한다.
- 심볼릭 링크 또는 Windows 정션이 아니어야 한다.
- 비어 있거나, SafeCrowd 관리 파일(safecrowd-project.json, layout.dxf, layout-review.json, import-artifacts.json, workspace-state.json)만 존재해야 한다.
최근 프로젝트 인덱스는 QStandardPaths::AppDataLocation 아래에 저장한다. QApplication의 organization name과 application name을 모두 SafeCrowd로 고정하므로, Windows 기준 경로는 %APPDATA%/SafeCrowd/SafeCrowd/recent-projects.json이 된다.

3. 화면별 기능 기준

3.1 Project Navigator

앱을 처음 켰을 때 보이는 시작 화면이다. 예시 프로젝트 목록을 두지 않고, 실제 저장된 프로젝트 목록과 built-in 데모 프로젝트를 보여준다.

현재 기능:

최근 프로젝트 목록 표시
built-in Demo, Evacuation Scenario Demo, Two-floor Evacuation Demo 프로젝트 표시
프로젝트 목록이 없을 때 빈 상태 표시
+ New Project로 새 프로젝트 생성 화면 진입
최근 프로젝트 row 클릭 시 해당 프로젝트 열기
일반 프로젝트 row의 삭제 버튼으로 프로젝트 삭제
삭제 전 확인 다이얼로그 표시
삭제 확인 시 실제 프로젝트 폴더 삭제 및 최근 목록 갱신
built-in 데모 프로젝트 삭제 방지

현재 UI 요소:

SafeCrowd 제목
저장된 프로젝트 리스트
프로젝트명
마지막 저장 시각
+ New Project 버튼
Open Folder 버튼

아직 기준 기능이 아닌 것:

Open Folder 버튼은 현재 Sprint 1 핵심 흐름이 아니다.
최근 목록에 없는 폴더를 직접 선택해 여는 기능은 별도 작업으로 다룬다.
프로젝트 검색, 정렬, 상태 badge는 후속 기능이다.

3.2 New Project

새 프로젝트를 만들고 DXF layout을 import하기 위한 화면이다. 이 화면에서 시뮬레이션 설정까지 받지 않고, 프로젝트 생성과 layout import에 필요한 최소 정보만 받는다.

현재 기능:

프로젝트명 입력
layout DXF 파일 선택
layout 파일 확장자가 .dxf가 아니면 프로젝트 생성을 거부
프로젝트 저장 폴더 선택
Done 클릭 시 프로젝트 메타데이터 저장
Done 클릭 시 DXF를 프로젝트 폴더에 layout.dxf로 복사
저장 후 Layout Review Workspace로 이동
Cancel 클릭 시 Project Navigator로 복귀
프로젝트명, layout 파일, 폴더 중 하나라도 비어 있으면 경고 표시

현재 UI 요소:

New Project 제목
Project Name 입력 필드
Layout 파일 선택 버튼
선택된 DXF 경로 표시
Folder 선택 버튼
선택된 저장 폴더 경로 표시
Cancel
Done

현재 입력 기준:

직접 import 대상은 .dxf이다.
.dwg는 직접 import하지 않는다.
DWG 도면은 외부 도구에서 DXF로 변환한 뒤 사용한다.

3.3 Layout Review Workspace

DXF import 결과를 검토하고 시뮬레이션 가능한 layout인지 확인하는 화면이다.

현재 기능:

DXF import 결과 표시
import 상태와 raw/canonical/layout/issue 요약 표시
원본 DXF가 남아 있는 일반 프로젝트에서 Reimport Layout 실행
reimport 이후 이전 review layout과 새 import layout의 added/removed/changed 요약 표시
중앙 canvas에 import 결과 기반 2D preview 렌더링
좌측 패널에서 issue와 layout 요소 목록 전환
issue를 Blocking, Warnings, Info로 구분
issue 클릭 시 관련 대상 focus 및 우측 inspector 상세 표시
issue inspector에서 source/target, confidence, repair suggestion 표시
layout 요소 클릭 시 canvas에서 해당 요소 focus
우측 패널에 inspector와 approval 상태 표시
하단 패널에 현재 review/project context 표시
blocking issue가 있으면 Approve Layout 비활성화
blocking issue가 없으면 layout 승인 후 Scenario Authoring Workspace로 이동

현재 UI 요소:

Workspace Shell 상단바
좌측 Blocking / Warnings / Info issue 목록
좌측 layout element 목록
중앙 Layout Preview
우측 선택 inspector
우측 import status summary
우측 Reimport Layout action
우측 approval action
하단 review 상태 영역

현재 중앙 preview 표시 대상:

walkable area / zone polygon
obstacle polygon
wall segment
opening segment
layout connection
barrier polyline

현재 좌측 issue 목록 표시 대상:

issue code
severity
message
source id
target id

현재 우측 issue inspector 표시 대상:

issue code와 severity
message
source id와 target id
confidence
repair suggestion

현재 수동 보정 기능:

active floor 선택 및 floor 추가
room 그리기
exit 그리기
wall 그리기
door/opening 그리기
stair/ramp 층간 연결 그리기
ㄷ자형 stair 층간 연결 그리기. 진입 방향 기준 오른쪽 half-lane은 출발 층, 왼쪽 half-lane은 목표 층 geometry로 생성한다.
connection 또는 barrier 삭제
undo
보정 후 live validation 재실행

3.4 Layout Canvas

Layout Review의 중앙 작업 영역이다. 현재는 import 결과와 수동 보정 결과를 QPainter로 렌더링하는 preview와 authoring canvas 역할을 한다.

현재 표시 대상:

import된 layout geometry
layout 요소 focus 상태
active floor에 속한 layout 요소
보정 중인 room, exit, wall, door/opening, stair/ramp, ㄷ자형 stair
선택적으로 활성화하는 grid mode. 0.1 m, 0.5 m, 1.0 m 간격을 제공하며, 켜진 동안 보정 중인 좌표와 선택 이동을 grid에 맞춘다.
공통 canvas surface는 직각 모서리의 white rendering section으로 캔버스 영역 전체를 채운다.
hotspot overlay는 Result Summary에서 사용한다.

3.5 Scenario Authoring Workspace

승인된 layout 위에서 baseline 시나리오를 만들고 실행 준비를 하는 화면이다.

현재 기능:

Layout Review에서 blocker가 사라진 뒤 Approve Layout 클릭 시 진입
최초 진입 시 baseline 시나리오 이름 입력
Workspace Shell 재사용
상단바 오른쪽 Scenario / Run 토글로 오른쪽 패널 내용 전환
두 토글을 모두 해제하면 오른쪽 패널을 숨기고 중앙 canvas 확장
Scenario 패널에서 현재 시나리오 요약 표시
Scenario switcher로 baseline/alternative 전환
New Scenario from Current로 현재 시나리오를 복제해 alternative 생성
Run 패널에서 실행 대상으로 staged 된 시나리오 목록 표시
Layout, Crowd, Events 좌측 탭 제공
중앙 canvas에서 보행자 배치 작성
select, individual occupant placement, rectangular group placement 지원
시나리오를 run 대상으로 stage
우측 Scenario panel에서 baseline 대비 변경 요약과 readiness 표시

현재 UI 요소:

좌측 Layout 요약 및 zone 목록
좌측 Crowd 배치/그룹 요약
좌측 Events 목록
Scenario switcher
New Scenario from Current
Top-right Scenario / Run panel toggles
Run staged scenario list
Run Staged Scenarios button
Scenario name 입력 팝업
승인 layout canvas
Select tool
Add Individual Occupant tool
Add Occupant Group tool
Add exit closure
Add staged release
Readiness Panel

현재 보행자 배치 기능:

individual occupant placement
rectangular group placement
group count 설정
배치된 인원을 scenario draft의 population.initialPlacements로 반영

현재 약한 부분:

운영 이벤트 editor는 최소 구조만 있고 실제 입력 UI가 부족하다.
readiness panel은 요약 수준이며 실행 불가 사유를 충분히 모아 보여주지 않는다.
environment와 execution 상세 입력은 아직 제한적이다.
scenario 저장/로드는 Sprint 1 핵심 시연 범위 밖이지만 후속 보완이 필요하다.

3.6 운영 이벤트

운영 이벤트는 앱 실행 버튼을 멈추는 기능이 아니라, 시뮬레이션 안의 현장 조건을 바꾸는 기능이다.

예시:

특정 시간 이후 출구 폐쇄
특정 구역에서 staged release
임시 장애물 활성화
안내 방향 또는 접근 가능 대상 변경

Sprint 1 최소 기준:

이벤트 목록 표시
시간 기반 trigger 입력
출구나 연결부 같은 target 선택
이벤트를 scenario draft의 control plan에 반영

현재 상태:

Events 탭과 event draft 구조는 있다.
사용자가 직접 이벤트를 추가, 수정, 삭제하는 editor UI는 아직 부족하다.

3.7 Run Workspace

stage된 baseline 시나리오를 실제로 실행하고 진행 상태를 보는 화면이다.

현재 기능:

Scenario Authoring의 Run panel에서 staged baseline scenario 실행
Workspace Shell 재사용
Workspace Shell은 navigation 없이 top bar, simulation canvas, right run panel만 사용
중앙 live simulation canvas에 agent 위치와 속도 방향 표시
우측 Run panel에 실행 상태와 주요 위험 지표 표시
pause/resume 지원
stop/reset 지원
elapsed time 표시
elapsed time 기준 시간 진행률 표시
evacuated/total, active agents 표시
evacuated/total 기준 대피 진행률 표시
completion risk, stalled agents, hotspot, bottleneck 요약 표시
run이 complete되면 Result Summary 진입 버튼 활성화
risk, stalled, hotspot, bottleneck 기준 툴팁 표시

현재 UI 요소:

Pause / Resume icon button
Stop icon button
View Results
elapsed time
time progress
evacuated / total
evacuation progress
active agents
completion risk
stalled agents
hotspot count
worst bottleneck summary

현재 약한 부분:

run queue는 staged list 수준이다.
여러 staged scenario를 순차 실행하는 batch queue는 아직 아니다.
실행 전 readiness 조건과 실행 불가 사유 표시가 부족하다.
batch queue와 persisted result artifact가 아직 연결되어 있지 않다.

3.8 Result Summary / Analysis Workspace

실행 완료 후 핵심 결과를 요약해 보여주는 화면이다. 현재는 Sprint 1용 Result Summary가 먼저 구현되어 있고, 비교/추천/내보내기 중심의 전체 Analysis Workspace는 후속 구현 상태다.

현재 기능:

완료된 run의 final simulation frame 표시
Workspace Shell은 left reports panel, simulation canvas, right summary panel 구성 사용
상단/우측 summary panel에 completion time, time margin, peak density, worst bottleneck, slowest group 표시
time margin은 v1에서 scenario.execution.timeLimitSeconds 기준 목표 시간 대비 여유로 계산
slowest group은 v1에서 보행자 배치 그룹별 마지막 완료시간을 표시하며, 별도 취약자 속성 모델이 들어오면 취약자 완료시간 카드로 확장
중앙 simulation canvas에서 result overlay 선택 제공: peak density, bottleneck, hotspot, none
hotspot overlay 표시
bottleneck overlay 표시
peak density overlay는 peak 시점의 전체 density field를 사용해 보행 가능 영역 안에 부드러운 heatmap으로 표시
peak density heatmap 색상 범례 표시
누적 대피 곡선 표시
하단 graph panel에 Remaining, Exits, Compare 탭 제공
Exits 탭에 출구별 이용 인원, 비율, 마지막 통과 시각 표시
Compare 탭은 v1 placeholder이며 baseline/alternative 비교 계산은 후속 Analysis Workspace 범위
Batch Result 우측 패널에 완료 결과 아티팩트 기반 Recommendations v1 제공
- 차단 해제, 출구 분산 유도, 병목/압박 hotspot 완화 후보를 표시
- Create Recommended Scenario는 Recommended 시나리오 초안만 만들고 자동 재실행하지 않음
상세 탭에 Zones, Groups, Criteria 표시
Zones 탭에 구역별 초기 인원, 대피 인원, 마지막 완료시각 표시
Groups 탭에 배치 그룹별 초기 인원, 대피 인원, 마지막 완료시각 표시
Criteria 탭에 고밀도, stalled, bottleneck 계산 기준 표시
T90/T95 대피 완료 시각 표시
evacuated count 표시
elapsed time 표시
risk level 표시
stalled count 표시
왼쪽 reports panel에 bottleneck 목록 표시
왼쪽 reports panel에 hotspot 목록 표시
bottleneck 목록 클릭 시 canvas focus 표시
hotspot 목록 클릭 시 canvas focus 표시
hotspot 색 강도 범례 표시
우측 summary panel에서 핵심 metric card와 액션 표시

현재 UI 요소:

Evacuated
Time
Completion
Time Margin
Peak Density
Worst Bottleneck
Slowest Group
T90
T95
Risk
Stalled
Result Reports
Evacuation Progress
Remaining / Exits / Compare tabs
Zones / Groups / Criteria detail tabs
Bottlenecks
Hotspots
Hotspot intensity legend
Peak Density heatmap legend
Run Again
Edit Scenario
risk/stalled/hotspot/bottleneck 기준 툴팁
Run Again은 같은 scenario 조건으로 Run Workspace를 새로 열어 시뮬레이션을 다시 시작한다.

현재 약한 부분:

baseline 대비 alternative 비교는 Sprint 2 범위다.
persisted result artifact 기반 analysis는 Sprint 2 이후 범위다.
export는 Sprint 3 범위다.
ASET/FED/연기 노출 기반 안전여유는 아직 없고, 현재 margin은 시나리오 목표시간 대비 여유다.
이동약자/지원 필요자 전용 결과는 아직 없고, 현재는 가장 늦게 완료한 placement group을 표시한다.

4. 상태별 화면 흐름

4.1 No Project

표시 화면:

Project Navigator

가능한 액션:

New Project
저장된 프로젝트 열기
폴더에서 프로젝트 열기

4.2 New Project Draft

표시 화면:

New Project

가능한 액션:

프로젝트명 입력
DXF 선택
저장 폴더 선택
Cancel
Done

4.3 Layout Needs Review

표시 화면:

Layout Review Workspace

가능한 액션:

blocking issue 확인
layout preview 확인
layout 수동 보정
Project > Save Project

제한:

blocker가 남아 있으면 simulation run은 비활성화한다.

4.4 Layout Ready

표시 화면:

Scenario Authoring Workspace

가능한 액션:

scenario 생성
scenario 편집
run readiness 확인

4.5 Scenario Ready

표시 화면:

Run Workspace

가능한 액션:

staged baseline simulation 실행
pause/resume
stop/reset
complete 이후 Result Summary 열기

후속 액션:

batch 실행

4.6 Results Available

표시 화면:

Result Summary
후속 Analysis Workspace

가능한 액션:

결과 확인

후속 액션:

대안 비교
추천 검토
export

5. 기능 상태 요약

영역	현재 상태	Sprint 1 판단
Project Navigator	최근 프로젝트, 새 프로젝트, 삭제 가능	핵심 흐름 가능
Open Folder	버튼만 있고 동작 없음	후순위
New Project	DXF 선택과 프로젝트 생성 가능	핵심 흐름 가능
DXF Import	DXF 파싱과 layout 생성 가능	핵심 흐름 가능
Layout Review	issue 확인과 승인 가능	핵심 흐름 가능
Layout 보정	기본 drawing/editing 가능	핵심 흐름 가능
Scenario 생성	baseline 생성과 전환 가능	핵심 흐름 가능
Crowd 배치	개인/그룹 배치 가능	핵심 흐름 가능
운영 이벤트	구조는 있으나 editor 부족	보완 필요
Run	실행, pause/resume, stop 가능	핵심 흐름 가능
Result Summary	기본 결과 요약 가능	시연 보조 가능

6. Sprint별 UI 개선 체크리스트

6.1 Sprint 1 보완

6.2 Sprint 2 개선

6.3 Sprint 3 이후 확장

7. 문서 유지 규칙

앱 화면의 의미나 사용자 흐름이 바뀌면 이 문서를 갱신한다.
UI 화면 목록, 기능 기준, 후속 개선 체크리스트는 이 문서만 기준으로 삼는다.
Sprint별 시연 기준은 docs/product/Sprint 시연 계획.md를 따른다.
작업 단위, 상태, PR 연결은 GitHub Issues와 Project를 기준으로 관리한다.
이 문서는 임시 TODO 목록이 아니라 앱 기능 이해를 위한 기준 문서로 유지한다.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

SafeCrowd UI 기준

1. 앱 전체 흐름

2. 공통 UI 구조

2.1 Workspace Shell

3. 화면별 기능 기준

3.1 Project Navigator

3.2 New Project

3.3 Layout Review Workspace

3.4 Layout Canvas

3.5 Scenario Authoring Workspace

3.6 운영 이벤트

3.7 Run Workspace

3.8 Result Summary / Analysis Workspace

4. 상태별 화면 흐름

4.1 No Project

4.2 New Project Draft

4.3 Layout Needs Review

4.4 Layout Ready

4.5 Scenario Ready

4.6 Results Available

5. 기능 상태 요약

6. Sprint별 UI 개선 체크리스트

6.1 Sprint 1 보완

6.2 Sprint 2 개선

6.3 Sprint 3 이후 확장

7. 문서 유지 규칙

FilesExpand file tree

UI.md

Latest commit

History

UI.md

File metadata and controls

SafeCrowd UI 기준

1. 앱 전체 흐름

2. 공통 UI 구조

2.1 Workspace Shell

3. 화면별 기능 기준

3.1 Project Navigator

3.2 New Project

3.3 Layout Review Workspace

3.4 Layout Canvas

3.5 Scenario Authoring Workspace

3.6 운영 이벤트

3.7 Run Workspace

3.8 Result Summary / Analysis Workspace

4. 상태별 화면 흐름

4.1 No Project

4.2 New Project Draft

4.3 Layout Needs Review

4.4 Layout Ready

4.5 Scenario Ready

4.6 Results Available

5. 기능 상태 요약

6. Sprint별 UI 개선 체크리스트

6.1 Sprint 1 보완

6.2 Sprint 2 개선

6.3 Sprint 3 이후 확장

7. 문서 유지 규칙