diff --git a/.github/ISSUE_TEMPLATE/lightweight-task.yml b/.github/ISSUE_TEMPLATE/lightweight-task.yml index c778a6d..a017bc7 100644 --- a/.github/ISSUE_TEMPLATE/lightweight-task.yml +++ b/.github/ISSUE_TEMPLATE/lightweight-task.yml @@ -53,7 +53,7 @@ body: label: Deliverable description: State what concrete output or change should exist when the task is done. placeholder: | - - Add `docs/GitHub Project.md` + - Add `docs/process/GitHub Project.md` - Capture the expected team workflow validations: required: true diff --git a/AGENTS.md b/AGENTS.md index 26a4214..a7707fa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -68,7 +68,7 @@ - `Epic` for larger parent work - `Implementation Task` for `Engine` / `Domain` / `Application` / `Build` work - `Lightweight Task` for `Docs` / `Chore` / `Analysis` work -- GitHub Project guidance is documented in `docs/GitHub Project.md`. +- GitHub Project guidance is documented in `docs/process/GitHub Project.md`. - PR titles must follow `[Area] short summary`. - Allowed PR areas: - `Engine` @@ -93,9 +93,10 @@ ## Docs - After any changes to the project, ensure the documents remain consistent. -- Architecture notes: `docs/프로젝트 구조.md` -- Project workflow notes: `docs/GitHub Project.md` -- Requirements and overview docs are under `docs/`. +- Architecture notes: `docs/architecture/프로젝트 구조.md` +- Project workflow notes: `docs/process/GitHub Project.md` +- Requirements and overview docs are under `docs/product/`. +- Use `docs/README.md` as the entry point for the document map. ## Review Priorities - Broken build or preset mismatch diff --git a/README.md b/README.md new file mode 100644 index 0000000..6560412 --- /dev/null +++ b/README.md @@ -0,0 +1,55 @@ +# SafeCrowd + +SafeCrowd는 ECS 기반 군중 시뮬레이션과 안전 의사결정 지원을 목표로 하는 Qt 데스크톱 애플리케이션입니다. +건물, 행사장, 대피 시나리오 같은 실제 운영 환경을 가정해 군중 흐름, 병목, 위험 징후를 비교 가능한 형태로 분석하는 것을 목표로 합니다. + +## 핵심 목표 + +- 실제 공간 구조를 바탕으로 시뮬레이션 가능한 레이아웃을 구성한다. +- 여러 운영 대안을 시나리오로 비교해 위험 차이를 확인한다. +- Qt 기반 UI와 분리된 ECS 엔진 구조를 유지한다. + +## 아키텍처 + +프로젝트는 `application -> domain -> engine` 계층을 유지합니다. + +- `src/application`: Qt UI와 애플리케이션 조립 +- `src/domain`: SafeCrowd 도메인 로직 +- `src/engine`: 재사용 가능한 ECS 엔진 + +상세 구조는 [docs/architecture/프로젝트 구조.md](docs/architecture/프로젝트 구조.md)를 기준 문서로 사용합니다. + +## 빠른 시작 + +전체 앱 빌드: + +```powershell +cmake --preset windows-debug +cmake --build --preset build-debug +ctest --preset test-debug +``` + +Qt 앱 없이 빠르게 검증: + +```powershell +cmake --preset windows-debug-no-app +cmake --build --preset build-engine-debug +cmake --build --preset build-engine-domain-debug +cmake --build --preset build-no-app-debug +ctest --preset test-no-app-debug +``` + +앱 빌드에는 `vcpkg.json`의 `qtbase` 의존성이 필요합니다. + +## 문서 + +- [docs/README.md](docs/README.md): 문서 전체 안내 +- [docs/product/개요서.md](docs/product/개요서.md): 프로젝트 개요와 이해당사자 +- [docs/product/사용자 시나리오.md](docs/product/사용자 시나리오.md): 대표 사용자 흐름 +- [docs/product/위험 정의.md](docs/product/위험 정의.md): 위험 및 사고 모델 정의 +- [docs/process/GitHub Project.md](docs/process/GitHub Project.md): 이슈, 프로젝트, PR 운영 규칙 + +## 기여 방식 + +기본 흐름은 `issue -> branch -> PR -> merge`입니다. +문서와 저장소 운영 규칙은 [CONTRIBUTING.md](CONTRIBUTING.md)를 따릅니다. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..655a8bc --- /dev/null +++ b/docs/README.md @@ -0,0 +1,28 @@ +# SafeCrowd 문서 안내 + +`docs/`는 기준 문서를 모아 두는 위치다. 진행 중 메모, 임시 TODO, 작업 상태 추적은 GitHub Issues와 Project에서 관리한다. + +## 문서 구조 + +- `architecture/`: 계층 구조, 책임, 디렉터리 규칙 같은 오래 유지할 설계 기준 +- `process/`: GitHub Project, 이슈/PR 규칙 같은 협업 절차 +- `product/`: 개요, 사용자 시나리오, 위험 정의, 백로그 같은 제품 요구와 범위 +- `references/`: 외부 조사 자료와 튜토리얼. 기준 문서의 보조 근거로만 사용 +- `제출용/`: 학교 제출 산출물. 저장소 운영 기준 문서와 분리해 보관 + +## 시작점 + +- [architecture/프로젝트 구조.md](architecture/프로젝트 구조.md) +- [process/GitHub Project.md](process/GitHub Project.md) +- [product/개요서.md](product/개요서.md) +- [product/사용자 시나리오.md](product/사용자 시나리오.md) +- [product/위험 정의.md](product/위험 정의.md) +- [product/Product Backlog.md](product/Product Backlog.md) + +## 유지 규칙 + +- 한 사실은 한 문서만 기준으로 삼는다. +- 구조 변경은 `architecture/`, 협업 규칙 변경은 `process/`, 요구 변경은 `product/`를 먼저 갱신한다. +- 외부 링크, 조사 메모, 튜토리얼은 `references/`로 보낸다. +- 제출 양식과 산출물은 `제출용/`에 두고 기준 문서처럼 직접 참조하지 않는다. +- 이 저장소는 별도 `adr/` 폴더를 두지 않는다. 구조 결정은 `architecture/프로젝트 구조.md`에, 협업 규칙 결정은 `process/GitHub Project.md`와 `CONTRIBUTING.md`에 반영한다. diff --git "a/docs/\354\204\244\352\263\204 \352\265\254\354\241\260.md" "b/docs/architecture/\355\224\204\353\241\234\354\240\235\355\212\270 \352\265\254\354\241\260.md" similarity index 100% rename from "docs/\354\204\244\352\263\204 \352\265\254\354\241\260.md" rename to "docs/architecture/\355\224\204\353\241\234\354\240\235\355\212\270 \352\265\254\354\241\260.md" diff --git a/docs/GitHub Project.md b/docs/process/GitHub Project.md similarity index 100% rename from docs/GitHub Project.md rename to docs/process/GitHub Project.md diff --git a/docs/Product Backlog.md b/docs/product/Product Backlog.md similarity index 99% rename from docs/Product Backlog.md rename to docs/product/Product Backlog.md index 4e84722..6c93fa6 100644 --- a/docs/Product Backlog.md +++ b/docs/product/Product Backlog.md @@ -1,7 +1,7 @@ # Product Backlog ## Project Name -**SafeCrowd: ECS 게임 엔진 기반 군중 행동 시뮬레이션 및 의사결정 지원 시스템** +**SafeCrowd: 군중 안전 시뮬레이터** 02조 202002520 은민수 @@ -21,7 +21,7 @@ | 항목 | 내용 | | --- | --- | -| Project Name | SafeCrowd: ECS 게임 엔진 기반 군중 행동 시뮬레이션 및 의사결정 지원 시스템 | +| Project Name | SafeCrowd: 군중 안전 시뮬레이터 | | Version | v1.0 | | 작성일 / 수정일 | 2026/04/01 / 2026/04/03 | | Product Owner (PO) | 02조 공동 | diff --git "a/docs/\352\260\234\354\232\224\354\204\234.md" "b/docs/product/\352\260\234\354\232\224\354\204\234.md" similarity index 97% rename from "docs/\352\260\234\354\232\224\354\204\234.md" rename to "docs/product/\352\260\234\354\232\224\354\204\234.md" index 2e4dd13..2b19142 100644 --- "a/docs/\352\260\234\354\232\224\354\204\234.md" +++ "b/docs/product/\352\260\234\354\232\224\354\204\234.md" @@ -1,6 +1,6 @@ # SafeCrowd 개요 ## SafeCrowd란? -ECS 게임 엔진 기반 군중 행동 시뮬레이션 및 의사 결정 지원 시스템 +SafeCrowd: 군중 안전 시뮬레이터 ## 대상 이해당사자 (stakeholder) - 건물 관리자 및 안전 관리자 diff --git "a/docs/\352\263\265\352\260\234 \354\204\261\353\212\245 \352\262\200\354\246\235 \353\215\260\354\235\264\355\204\260 \354\241\260\354\202\254.md" "b/docs/product/\352\263\265\352\260\234 \354\204\261\353\212\245 \352\262\200\354\246\235 \353\215\260\354\235\264\355\204\260 \354\241\260\354\202\254.md" similarity index 100% rename from "docs/\352\263\265\352\260\234 \354\204\261\353\212\245 \352\262\200\354\246\235 \353\215\260\354\235\264\355\204\260 \354\241\260\354\202\254.md" rename to "docs/product/\352\263\265\352\260\234 \354\204\261\353\212\245 \352\262\200\354\246\235 \353\215\260\354\235\264\355\204\260 \354\241\260\354\202\254.md" diff --git "a/docs/\354\202\254\354\232\251\354\236\220 \354\213\234\353\202\230\353\246\254\354\230\244.md" "b/docs/product/\354\202\254\354\232\251\354\236\220 \354\213\234\353\202\230\353\246\254\354\230\244.md" similarity index 100% rename from "docs/\354\202\254\354\232\251\354\236\220 \354\213\234\353\202\230\353\246\254\354\230\244.md" rename to "docs/product/\354\202\254\354\232\251\354\236\220 \354\213\234\353\202\230\353\246\254\354\230\244.md" diff --git "a/docs/\354\234\204\355\227\230 \354\240\225\354\235\230.md" "b/docs/product/\354\234\204\355\227\230 \354\240\225\354\235\230.md" similarity index 100% rename from "docs/\354\234\204\355\227\230 \354\240\225\354\235\230.md" rename to "docs/product/\354\234\204\355\227\230 \354\240\225\354\235\230.md" diff --git "a/docs/references/Pathfinder_MassMotion_\354\241\260\354\202\254.md" "b/docs/references/Pathfinder_MassMotion_\354\241\260\354\202\254.md" deleted file mode 100644 index fc03495..0000000 --- "a/docs/references/Pathfinder_MassMotion_\354\241\260\354\202\254.md" +++ /dev/null @@ -1,75 +0,0 @@ -# Pathfinder - -예. `Pathfinder`는 공식적으로 대피(egress) 시뮬레이션을 수행할 수 있습니다. Thunderhead는 Pathfinder를 `crowd movement and egress software`로 소개하고, `Emergency Preparedness` 문서에서는 기본 시뮬레이션이 `Egress`이며 각 agent가 가장 빠른 경로로 출구로 이동한다고 설명합니다. 또한 `assisted evacuation`, `threat awareness`, `delayed/probabilistic reactions`도 지원합니다. -근거: [Pathfinder 제품 페이지](https://www.thunderheadeng.com/pathfinder/), [Emergency Preparedness](https://www.thunderheadeng.com/pathfinder/emergency-preparedness/) - -다만 범위를 정확히 보면, Pathfinder의 기본 축은 `사람 이동/대피 모델링`입니다. 화재·연기 자체의 물리 해석은 `PyroSim(FDS)`와 연동해 `FED`(독성 노출량), `visibility`(가시성), 연기 속 보행속도 저하 등을 평가하는 구조입니다. 공식 튜토리얼은 `full coupling`이 아직 완료되지 않았고, 연기 반응을 반영하는 일부 워크플로는 현재도 수동 coupling 방식이라고 설명합니다. -근거: [Coupling with PyroSim (FDS)](https://www.thunderheadeng.com/docs/2025-1/pathfinder/advanced/coupling-fds/), [Manual smoke coupling tutorial](https://www.thunderheadeng.com/docs/2025-1/pathfinder/examples/how-to/manually-coupling-fds/) - -대피 시뮬레이션 절차는 공식 문서 기준으로 보통 이렇게 진행됩니다. - -1. 공간 모델 작성 -CAD/BIM을 가져오거나 직접 모델링한 뒤, `floor extraction`으로 navigation mesh를 만들고 `room`, `door`, `stair`, `exit`를 정의합니다. Pathfinder에서 `exit`는 모델 경계에 놓인 door입니다. -근거: [Fundamentals 튜토리얼](https://www.thunderheadeng.com/docs/2025-1/pathfinder/examples/fundamentals/), [Generating Geometry from CAD](https://www.thunderheadeng.com/docs/2025-1/pathfinder/geometry/generating-from-cad/), [Doors / Exits](https://www.thunderheadeng.com/docs/2025-1/pathfinder/geometry/doors/) - -2. 인원 배치 -방 안에 occupant를 직접 배치하거나, `occupant source`로 시간대별 유입 인원을 생성할 수 있습니다. -근거: [Fundamentals 튜토리얼](https://www.thunderheadeng.com/docs/2025-1/pathfinder/examples/fundamentals/), [Occupant Sources](https://www.thunderheadeng.com/docs/2026-1/pathfinder/occupants/occupant-source/) - -3. 보행 특성과 대피 규칙 설정 -`Profile`로 속도, 체격, 분포 등을 정의하고, `Behavior`로 대피 로직을 줍니다. 기본 behavior인 `Goto Any Exit`는 가장 빠른 경로로 아무 출구나 향하게 합니다. 필요하면 특정 출구, refuge room, elevator, assisted evacuation 동선도 구성할 수 있습니다. -근거: [Profiles](https://www.thunderheadeng.com/docs/2025-1/pathfinder/profiles/), [Behaviors](https://www.thunderheadeng.com/docs/2026-1/pathfinder/behaviors/), [Assisted Evacuation](https://www.thunderheadeng.com/docs/2025-1/pathfinder/advanced/assisted-evacuation/) - -4. 비상상황 반응 모델링 -단순 최단대피 외에도 `familiar routes`, `triggers`, `delayed/probabilistic reactions`로 익숙한 출구 선호, 경보 전파, 일부 인원의 지연 반응 등을 반영할 수 있습니다. -근거: [Evacuation Using Familiar Paths](https://www.thunderheadeng.com/docs/2025-1/pathfinder/examples/how-to/familiar-routes/), [Triggers](https://www.thunderheadeng.com/docs/2025-1/pathfinder/examples/how-to/evacuation-using-triggers/) - -5. 시뮬레이션 실행 -`Run Simulation`으로 시나리오를 실행하고, 필요하면 Monte Carlo variation으로 여러 랜덤 케이스를 반복 실행할 수 있습니다. -근거: [Fundamentals 튜토리얼](https://www.thunderheadeng.com/docs/2025-1/pathfinder/examples/fundamentals/), [Simulation](https://www.thunderheadeng.com/docs/2026-1/pathfinder/simulation/), [Pathfinder 2025.1](https://www.thunderheadeng.com/docs/2025-1/pathfinder/) - -6. 결과 분석 -결과 뷰어와 CSV에서 `exit time`, `congestion time`, `distance`, `safe time` 등을 확인합니다. PyroSim/FDS 결과를 연동하면 `FED`와 `visibility`도 함께 평가할 수 있습니다. -근거: [Occupant Summary output](https://www.thunderheadeng.com/docs/2025-1/pathfinder/output/occupant-summary/), [Coupling with PyroSim (FDS)](https://www.thunderheadeng.com/docs/2025-1/pathfinder/advanced/coupling-fds/), [Results 2025.1](https://www.thunderheadeng.com/docs/2025-1/results/) - -원하시면 다음 답변에서 `MassMotion vs LEGION vs Pathfinder`를 `대피성능평가 관점`으로 비교해드리겠습니다. - - -# MassMotion - -예. MassMotion은 공식적으로 대피 시뮬레이션을 수행할 수 있습니다. Oasys/Arup의 2024 검증 문서는 MassMotion을 “pedestrian movement and evacuation simulation program”으로 설명하고, 제품 페이지도 `Evacuate`를 기본 스케줄링 옵션 중 하나로 제시합니다. -근거: [MassMotion 제품 페이지](https://www.oasys-software.com/products/massmotion/), [2024 Fire Evacuation Verification & Validation](https://www.oasys-software.com/wp-content/uploads/2024/07/Fire-Evacuation-VV.pdf) - -다만 범위를 정확히 보면, 공식 문서는 MassMotion이 사람의 대피 행동, 출구 선택, 혼잡, 이동시간 같은 `egress` 분석을 하는 도구라고 설명합니다. 반면 화재나 연기 자체를 직접 모델링하지는 않는다고 명시합니다. -근거: [2024 Fire Evacuation Verification & Validation](https://www.oasys-software.com/wp-content/uploads/2024/07/Fire-Evacuation-VV.pdf) - -대피 시뮬레이션 절차는 보통 이렇게 이해하면 됩니다. - -1. 공간 모델을 만든다. -CAD/BIM을 가져오거나 직접 3D 환경을 만들고, 바닥, 문/링크, 계단, 램프, 에스컬레이터, 출입 포털, 장애물 등을 보행 네트워크로 분류합니다. -근거: [MassMotion 제품 페이지](https://www.oasys-software.com/products/massmotion/), [2024 Fire Evacuation Verification & Validation](https://www.oasys-software.com/wp-content/uploads/2024/07/Fire-Evacuation-VV.pdf) - -2. 대피 인원과 출구 조건을 정의한다. -Entry portal로 에이전트를 생성하고, Exit portal을 목표 출구로 지정합니다. 인원수, 생성 시간/속도, origin-destination, exit zone 등을 설정할 수 있습니다. -근거: [MassMotion 제품 페이지](https://www.oasys-software.com/products/massmotion/), [2024 Fire Evacuation Verification & Validation](https://www.oasys-software.com/wp-content/uploads/2024/07/Fire-Evacuation-VV.pdf) - -3. `Evacuate` 이벤트를 설정한다. -공식 User Guide에 따르면 `Evacuate` 이벤트는 에이전트에게 일정 대기시간을 준 뒤 출구 쪽으로 이동시키며, 필요하면 zone을 순차적으로 비우도록 설정할 수 있습니다. -근거: [MassMotion User Guide 11.8 PDF](https://www.oasys-software.com/wp-content/uploads/2024/07/Oasys-MassMotion-User-Guide-11-8.pdf) - -4. 경로 선택과 행동 규칙을 준다. -에이전트는 `Least Cost` 방식으로 가장 유리한 출구를 찾거나, 특정 출구를 지정받아 그쪽으로 이동할 수 있습니다. 공식 검증 문서는 혼잡과 출구 가용성 변화에 따라 경로를 재평가할 수 있다고 설명합니다. -근거: [2024 Fire Evacuation Verification & Validation](https://www.oasys-software.com/wp-content/uploads/2024/07/Fire-Evacuation-VV.pdf) - -5. 여러 시나리오를 돌리고 결과를 비교한다. -MassMotion은 그래프, 맵, 필터 기반 분석으로 혼잡 구간, 대기시간, 이동시간, 문/계단 유량 등을 비교할 수 있습니다. 실제 공식 사례에서도 여러 대피 전략 시나리오를 비교해 최적안을 찾는 방식으로 사용됐습니다. -근거: [MassMotion 제품 페이지](https://www.oasys-software.com/products/massmotion/), [Cendana 대피 사례](https://www.oasys-software.com/case-studies/evacuation-modelling-of-cendana-building-using-oasys-massmotion/) - -참고용 공식 링크 모음: -- [MassMotion Documentation 허브](https://www.oasys-software.com/support/massmotion/massmotion-documentation/) -- [MassMotion 제품 페이지](https://www.oasys-software.com/products/massmotion/) -- [2024 Fire Evacuation Verification & Validation](https://www.oasys-software.com/wp-content/uploads/2024/07/Fire-Evacuation-VV.pdf) -- [MassMotion User Guide 11.8 PDF](https://www.oasys-software.com/wp-content/uploads/2024/07/Oasys-MassMotion-User-Guide-11-8.pdf) - -원하시면 다음 답변에서 `대피성능평가 관점에서 MassMotion으로 뽑아볼 수 있는 주요 지표`만 따로 정리해 드리겠습니다. - diff --git "a/docs/Qt Widgets Designer \354\264\210\352\270\260 \354\204\270\355\214\205 \355\212\234\355\206\240\353\246\254\354\226\274.md" "b/docs/references/Qt Widgets Designer \354\264\210\352\270\260 \354\204\270\355\214\205 \355\212\234\355\206\240\353\246\254\354\226\274.md" similarity index 100% rename from "docs/Qt Widgets Designer \354\264\210\352\270\260 \354\204\270\355\214\205 \355\212\234\355\206\240\353\246\254\354\226\274.md" rename to "docs/references/Qt Widgets Designer \354\264\210\352\270\260 \354\204\270\355\214\205 \355\212\234\355\206\240\353\246\254\354\226\274.md" diff --git "a/docs/\354\234\240\354\202\254\354\240\234\355\222\210.md" "b/docs/\354\234\240\354\202\254\354\240\234\355\222\210.md" deleted file mode 100644 index 3785d18..0000000 --- "a/docs/\354\234\240\354\202\254\354\240\234\355\222\210.md" +++ /dev/null @@ -1,87 +0,0 @@ -# SafeCrowd 유사 제품 조사 및 차별화 포인트 - -## 문서 목적 -본 문서는 SafeCrowd와 유사한 군중 시뮬레이션 및 대피 분석 소프트웨어를 조사하고, 각 제품의 한계와 SafeCrowd의 차별화 가능성을 정리한 문서이다. 교수님 발표에서 "이미 유사 제품이 있는데 왜 이 프로젝트가 의미가 있는가"에 답할 수 있도록 작성한다. - -## 조사 기준 -- 조사일 기준: 2026-03-16 -- 기준 축: 군중 흐름 시뮬레이션, 대피 시나리오 분석, 혼잡/위험 시각화, 의사결정 지원 -- 단점은 제품 비방이 아니라 SafeCrowd와 비교했을 때의 상대적 한계로 해석한다. -- 일부 항목은 공식 사이트 설명을 바탕으로 한 합리적 추론이다. - -## SafeCrowd의 비교 기준 -SafeCrowd는 다음 특성을 핵심으로 한다. - -- ECS 기반 대규모 군중 시뮬레이션 -- 건물/행사장 구조 반영 -- 비전문가도 다룰 수 있는 시나리오 생성 및 수정 UI -- 병목, 압력 집중, 압사 위험, 낙상 연쇄, 역방향/교차 흐름, 시야 저하를 비교 가능한 위험 지표로 제공 -- 분석 결과를 바탕으로 운영 대안 후보를 직접 추천 -- 설계자, 행사 운영자, 안전 관리자, 재난 대응 담당자의 의사결정 지원 - -## 경쟁 제품 비교표 - -### 1. 직접 경쟁군 - -| 제품 | 주요 특징 | 발표에서 짚을 한계 | SafeCrowd 차별화 포인트 | -|---|---|---|---| -| MassMotion | BIM/CAD 연동, 군중 흐름 분석, hotspot 분석, 시각화, SDK 제공 | 엔지니어링/설계 워크플로 중심이라 안전관리자나 행사 운영자가 바로 쓰기에는 상대적으로 무겁다. 위험 표현도 혼잡/이동성 분석 쪽이 중심으로 보인다. | SafeCrowd는 설계 툴보다 안전 의사결정 툴에 가깝다. 비전문가용 UI, 시나리오 복제/수정, 위험 히트맵, 시나리오 비교, 운영 대안 추천을 전면에 둘 수 있다. | -| LEGION | 철도역, 공항, 경기장 등 대형 인프라 대상 보행 시뮬레이션, 대피 전략 검토, 보고 기능 | 대형 인프라 분석에 강하지만 도입 장벽이 높고, 위험 메커니즘 설명이 사용자 입장에서는 상대적으로 블랙박스형일 수 있다. | SafeCrowd는 병목, 압력 집중, 낙상, 역류를 분리해 보여주므로 "왜 위험한지"를 설명하기 쉽다. 결과 해석과 의사결정 근거 제시에 유리하다. | -| Pathfinder | 비상 대피, 화재 조건 노출, 그룹 행동, 민감도 분석 지원 | 화재 피난과 코드 검토에 매우 강하지만, 행사장 운영안 비교나 군중 압력/낙상 같은 군중 안전 전용 지표는 상대적으로 덜 전면적이다. | SafeCrowd는 대피 시간뿐 아니라 압력 노출, 낙상 연쇄, 교차/역방향 흐름 충돌까지 다루는 안전 리스크 중심 제품으로 차별화할 수 있다. | -| SimWalk PRO | 건물 대피, 이벤트, 도시 계획, hazard 이벤트, 멀티스레드 계산 | 매우 범용적이고 상용 솔루션 성격이 강해 대학 프로젝트 관점의 독자적 연구 질문이 흐려질 수 있다. | SafeCrowd는 문헌 기반 위험 정의를 직접 구현한 연구형 프로토타입이라는 점이 강점이다. 지표 설계와 실험 구조의 투명성을 강조할 수 있다. | -| buildingEXODUS | 화재, 연기, 표지, 친숙도, 리프트 등 피난공학 요소 반영 | 화재 피난공학 중심이며 공개 자료 기준 버전 정보가 오래된 편이다. 행사장 운영안 비교, 현대적 UI, 실시간 what-if 실험성은 상대적으로 약해 보인다. | SafeCrowd는 현대적인 UI와 실시간 시나리오 비교를 강조할 수 있다. 특히 군중 압력, 압사, 낙상 연쇄를 전면에 낼 수 있다. | -| SimCrowds | 쉬운 사용성, 실시간 환경 수정, 대규모 군중 처리, 3D 공간 활용 | 사용성과 실시간성은 강하지만 위험 정의의 엄밀성이나 문헌 기반 사고 모델은 상대적으로 약하게 보인다. | SafeCrowd는 쉬운 UX 방향을 유지하면서도 문헌 기반 위험 모델과 시나리오별 안전성 비교를 더 강하게 제시할 수 있다. | - -### 2. 플랫폼/연구용/인접군 - -| 제품 | 주요 특징 | 발표에서 짚을 한계 | SafeCrowd 차별화 포인트 | -|---|---|---|---| -| AnyLogic Pedestrian Library | 보행자 시뮬레이션 라이브러리, CAD 가져오기, 다른 라이브러리와 결합 가능 | 완성형 안전 제품이 아니라 플랫폼에 가깝다. 모델을 직접 조립해야 하므로 사용자보다 모델러 역량에 크게 의존한다. | SafeCrowd는 코딩 없이 바로 시나리오를 구성하는 도메인 특화 앱이라는 점을 강조할 수 있다. | -| JuPedSim | Python/C++ 기반 오픈소스 보행 시뮬레이션 프레임워크 | 연구자/개발자 도구에 가깝기 때문에 현업 안전관리자나 설계자가 바로 쓰기 어렵다. | SafeCrowd는 연구 결과를 실제 사용자용 UI로 연결한다는 점에서 차별화된다. | -| Vadere | 과학자용 오픈소스 프레임워크, 보행 동역학 실험과 연구 중심 | 학술 연구에는 적합하지만 운영자용 의사결정 제품과는 결이 다르다. | SafeCrowd는 건물/행사장 적용, 사용자 친화 UI, 의사결정용 대시보드를 전면에 둘 수 있다. | -| EVAGUIDE | 센서, 동적 표지, 앱, COP를 결합한 실시간 대피 유도 시스템 | 센서와 인프라 의존도가 커서 구축 비용이 높고, 설계 초기 검토나 독립형 시나리오 실험 도구로는 과한 구성이 될 수 있다. | SafeCrowd는 센서 인프라 없이도 사전 검토, 대안 비교가 가능한 경량 의사결정 도구라는 점이 강하다. | - -## 발표에서 강조할 핵심 메시지 - -### 1. 유사 제품이 있다는 것은 오히려 의미가 있다 -- 이미 시장에 유사 제품이 존재한다는 것은 이 문제가 실제 현장에서 중요한 문제라는 뜻이다. -- 즉, SafeCrowd는 필요 없는 기능을 만드는 것이 아니라 실제 수요가 있는 문제를 학술적·실용적으로 풀고 있다. - -### 2. 기존 제품은 주로 전문가용 범용 툴이다 -- 기존 상용 제품 다수는 엔지니어, 컨설턴트, 대형 인프라 분석가를 위한 범용 시뮬레이터 성격이 강하다. -- SafeCrowd는 안전 관리자, 행사 운영자, 설계자처럼 비전문가도 시나리오를 빠르게 바꾸고 비교할 수 있게 하는 데 더 초점을 둔다. - -### 3. SafeCrowd의 진짜 차별점은 위험을 더 잘 보이게 만들고, 다음 조치를 직접 제안하는 것이다 -- 단순히 "사람이 이동한다"를 보여주는 것이 아니라, 왜 위험한지 설명 가능한 지표를 제공한다. -- 병목, 정체, 압력 집중, 압사 위험, 낙상 연쇄, 역방향/교차 흐름, 시야 저하를 분리해 보여줄 수 있다. -- 더 나아가 시스템이 어떤 운영 대안을 우선 검토해야 하는지 직접 추천하면, 결과 해석과 의사결정, 발표 설득력 면에서 강점이 된다. - -### 4. 연구 프로젝트로서의 가치가 분명하다 -- 상용 툴은 강력하지만 내부 로직이 사용자에게 충분히 설명되지 않는 경우가 많다. -- SafeCrowd는 문헌 기반 위험 정의를 직접 모델링하고 지표를 설계하기 때문에 연구적 설명 가능성이 높다. -- 따라서 "새 툴을 또 만드는 것"이 아니라 "위험 중심적이고 설명 가능한 시뮬레이션 도구를 연구 목적으로 재구성한다"는 가치가 있다. - -## 교수님 발표용 요약 문장 - -### 짧은 버전 -기존 상용 제품들이 군중 시뮬레이션의 필요성을 이미 증명했다면, SafeCrowd는 그 기능을 안전 의사결정 목적에 맞게 더 가볍고, 더 설명 가능하고, 더 위험 중심적으로 재구성한 프로젝트이다. - -### 발표용 확장 버전 -유사 제품은 이미 존재하지만, 대부분 전문가용 범용 시뮬레이터이거나 특정 산업에 특화되어 있다. SafeCrowd는 비전문가도 시나리오를 쉽게 만들고 수정할 수 있으면서, 단순 대피 시간뿐 아니라 압력 집중, 압사 위험, 낙상 연쇄, 병목, 역방향 및 교차 흐름 같은 위험 요인을 비교 가능한 형태로 보여준다. 또한 시스템이 결과를 바탕으로 운영 대안 후보를 직접 추천하도록 설계해, 사용자가 "무엇이 위험한가"를 넘어서 "다음에 무엇을 해볼 것인가"까지 빠르게 이어지게 한다. 즉, SafeCrowd의 핵심 가치는 "군중을 움직이게 하는 것"이 아니라 "위험을 설명 가능하게 만들고, 대응안을 제안하는 것"에 있다. - -## 결론 -- SafeCrowd는 완전히 새로운 시장을 만드는 프로젝트라기보다, 이미 검증된 문제 영역에 대해 다른 관점의 해법을 제시하는 프로젝트다. -- 차별화의 핵심은 성능 자체보다도 위험 정의의 명확성, 시나리오 비교의 용이성, 운영 대안 추천 가능성, 비전문가 친화성, 연구적 설명 가능성에 있다. -- 따라서 발표에서는 "유사 제품이 있어도 왜 SafeCrowd가 필요한가"를 충분히 설득할 수 있다. - -## 참고 제품 공식 사이트 -- MassMotion: https://www.oasys-software.com/products/massmotion/ -- LEGION: https://www.bentley.com/software/legion/ -- Pathfinder: https://www.thunderheadeng.com/pathfinder/ -- SimWalk PRO: https://www.simwalk.com/ -- buildingEXODUS: https://fseg.gre.ac.uk/exodus/avail.html -- SimCrowds: https://ucrowds.com/simcrowds/ -- AnyLogic Pedestrian Library: https://www.anylogic.com/features/libraries/pedestrian-library/ -- JuPedSim: https://www.jupedsim.org/stable/ -- Vadere: https://www.vadere.org/ -- EVAGUIDE: https://www.evaguide.eu/ diff --git "a/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/Product_Backlog_2\355\214\200.docx" "b/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/Product_Backlog_2\355\214\200.docx" index c46d0a4..67770be 100644 Binary files "a/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/Product_Backlog_2\355\214\200.docx" and "b/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/Product_Backlog_2\355\214\200.docx" differ diff --git "a/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/Backlog \353\260\234\355\221\234.md" "b/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/Product_Backlog_\353\260\234\355\221\234_\353\214\200\353\263\270.md" similarity index 100% rename from "docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/Backlog \353\260\234\355\221\234.md" rename to "docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/Product_Backlog_\353\260\234\355\221\234_\353\214\200\353\263\270.md" diff --git "a/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/[\354\226\221\354\213\235 5] \354\213\234\354\212\244\355\205\234 \352\265\254\354\241\260 \354\204\244\352\263\204 \353\260\217 \352\260\234\353\260\234 \355\231\230\352\262\275 \354\226\221\354\213\235 (1).docx" "b/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/[\354\226\221\354\213\235 5] \354\213\234\354\212\244\355\205\234 \352\265\254\354\241\260 \354\204\244\352\263\204 \353\260\217 \352\260\234\353\260\234 \355\231\230\352\262\275 \354\226\221\354\213\235.docx" similarity index 100% rename from "docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/[\354\226\221\354\213\235 5] \354\213\234\354\212\244\355\205\234 \352\265\254\354\241\260 \354\204\244\352\263\204 \353\260\217 \352\260\234\353\260\234 \355\231\230\352\262\275 \354\226\221\354\213\235 (1).docx" rename to "docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/[\354\226\221\354\213\235 5] \354\213\234\354\212\244\355\205\234 \352\265\254\354\241\260 \354\204\244\352\263\204 \353\260\217 \352\260\234\353\260\234 \355\231\230\352\262\275 \354\226\221\354\213\235.docx" diff --git "a/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/[\354\226\221\354\213\235 5] \354\213\234\354\212\244\355\205\234 \352\265\254\354\241\260 \354\204\244\352\263\204 \353\260\217 \352\260\234\353\260\234 \355\231\230\352\262\275.md" "b/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/[\354\226\221\354\213\235 5] \354\213\234\354\212\244\355\205\234 \352\265\254\354\241\260 \354\204\244\352\263\204 \353\260\217 \352\260\234\353\260\234 \355\231\230\352\262\275.md" new file mode 100644 index 0000000..e1b789f --- /dev/null +++ "b/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/[\354\226\221\354\213\235 5] \354\213\234\354\212\244\355\205\234 \352\265\254\354\241\260 \354\204\244\352\263\204 \353\260\217 \352\260\234\353\260\234 \355\231\230\352\262\275.md" @@ -0,0 +1,382 @@ +# Project Document + +# System Architecture Design & Development Environment + +## Project Name + +**SafeCrowd: 군중 안전 시뮬레이터** + +02조 +202002520 은민수 +202102629 김준용 +202202546 금소현 +202302543 김학찬 +지도교수: 고영준 교수님 + +## Document Revision History + +| Rev# | Date | Affected Section | Author | +| --- | --- | --- | --- | +| 1 | 2026/04/06 | 초안 작성 및 Markdown 변환 | 02조 공동 | + +## 0. Meta Information + +| Item | Value | +| --- | --- | +| Project | SafeCrowd | +| Team | 02조 | +| Version | v1.0 | +| Framework | C++20, Qt6 Widgets, CMake, vcpkg, ECS runtime | +| Scope | Sprint 1 MVP(US-01~US-03, US-07~US-11) 중심 구조와 Sprint 2~3 확장 가능 아키텍처 | + +## 1. Project Overview + +### Vision + +SafeCrowd는 건물 관리자, 행사장 운영자, 안전관리자, 건축·공간 설계자, 재난 대응 담당자가 실제 공간 구조를 반영한 군중 시뮬레이션을 직접 다룰 수 있게 하는 데스크톱 시스템이다. +이 시스템은 실제 훈련을 반복하기 어려운 상황에서 병목, 정체, 압력 집중, 낙상, 탈출 지연 같은 위험을 사전에 식별하도록 돕는다. +사용자는 DXF 기반 공간 구조를 불러오고, 운영 조건을 바꾼 여러 시나리오를 비교하면서 더 안전한 대안을 찾을 수 있다. +SafeCrowd는 전문가 전용 범용 시뮬레이터가 아니라, 비전문가도 이해할 수 있는 UI와 설명 가능한 위험 지표를 갖춘 의사결정 지원 도구를 목표로 한다. + +### Scope + +#### In Scope + +- DXF 도면으로부터 보행 가능 영역, 벽, 출구, 장애물을 추출하는 시설 레이아웃 import 파이프라인 +- 임포트 결과를 `RawImportModel -> CanonicalGeometry -> FacilityLayout2D`로 정규화하는 도메인 모델 +- 출구 누락, 연결 단절, 최소 폭 미달을 검증하는 구조 검토 및 실행 가능 상태 판정 +- `application -> domain -> engine` 계층을 따르는 Qt 기반 데스크톱 애플리케이션 +- 고정 timestep 기반 ECS runtime과 시작, 일시정지, 정지, 상태 요약을 포함한 실행 제어 +- Sprint 2~3에서 결과 비교, 위험 분석, 추천 기능으로 확장 가능한 구조 설계 + +#### Out of Scope + +- 웹 서비스, 모바일 앱, 멀티유저 협업 기능 +- 결제, 사용자 계정, 권한 관리 같은 운영 지원 시스템 +- 실시간 IoT 센서 연동이나 외부 관제 시스템과의 온라인 통합 +- 서버 중심 REST API 아키텍처 +- 초기 버전에서의 3D 렌더링과 물리 기반 시각 효과 + +### Success Metrics + +- 하나의 공간 도면으로 기준안 1개와 대안 2개 이상을 구성하고 비교할 수 있다. +- 대표 시나리오에서 1,000명 규모의 군중 시뮬레이션을 안정적으로 실행할 수 있다. +- 총 대피 시간, 90%·95% 대피 시간, 최대 밀도, 압박 위험, 낙상, 미대피 인원 등 핵심 안전 지표 6종 이상을 자동 산출한다. +- 위험 히트맵으로 시나리오별 위험 구역과 변화 정도를 직관적으로 비교할 수 있다. +- 분석 결과를 바탕으로 운영 대안 3개 이상을 근거와 함께 제안할 수 있다. + +## 2. Architecture Design + +### System Context Diagram + +```mermaid +flowchart LR + U1["건물 관리자 / 안전관리자"] --> APP["SafeCrowd Desktop Application"] + U2["행사장 운영자 / 재난 대응 담당자"] --> APP + U3["건축·공간 설계자"] --> APP + + FILE["DXF 도면 파일"] --> APP + APP --> OUT1["레이아웃 검토 결과"] + APP --> OUT2["시뮬레이션 상태 및 위험 지표"] + APP --> OUT3["비교 결과 및 운영 대안"] +``` + +시스템의 1차 입력은 사용자의 공간 도면과 시나리오 조건이며, 1차 출력은 레이아웃 검토 결과, 시뮬레이션 상태, 위험 지표와 비교 결과이다. 초기 버전은 외부 온라인 API보다 동일 프로세스 내부의 계층 분리를 우선하며, 데스크톱 애플리케이션 하나 안에서 입력, 분석, 시각화를 모두 수행한다. + +### Logical Architecture + +```mermaid +flowchart LR + subgraph Application["application layer"] + MW["MainWindow"] + UI["Scenario / Import / Result UI (planned)"] + end + + subgraph Domain["domain layer"] + SD["SafeCrowdDomain"] + DXF["DxfImportService"] + FLB["FacilityLayoutBuilder"] + IVS["ImportValidationService"] + DM["Scenario / Risk / Recommendation modules (planned)"] + end + + subgraph Engine["engine layer"] + RT["EngineRuntime"] + FC["FrameClock"] + ER["EntityRegistry"] + PCS["PackedComponentStorage"] + SYS["EngineSystem / WorldQuery / CommandBuffer"] + end + + QT["Qt6 Widgets"] --> Application + FILESYS["DXF file system input"] --> DXF + + MW --> SD + UI --> DXF + UI --> IVS + SD --> RT + DXF --> FLB + DXF --> IVS + DM --> RT + RT --> FC + RT --> ER + RT --> PCS + RT --> SYS +``` + +### Layer Responsibilities + +| Layer | 주요 요소 | 책임 | 금지/제한 | +| --- | --- | --- | --- | +| `application` | `MainWindow`, Qt signal/slot, 향후 import/scenario/result UI | 사용자 입력 수집, 도메인 서비스 호출, 상태 표시 | ECS 내부 로직과 위험 계산식을 직접 가지지 않음 | +| `domain` | `SafeCrowdDomain`, `DxfImportService`, `FacilityLayoutBuilder`, `ImportValidationService`, 향후 시나리오/위험/추천 모듈 | SafeCrowd 문제 영역 규칙, 공간 구조 정규화, 실행 가능성 검토, 위험 지표 정의 | Qt UI 의존 금지 | +| `engine` | `EngineRuntime`, `FrameClock`, `EntityRegistry`, `ComponentRegistry`, `PackedComponentStorage`, `WorldQuery`, `CommandBuffer` | 범용 ECS runtime, fixed timestep, world 상태 관리, 시스템 실행 기반 제공 | SafeCrowd 도메인 지식 의존 금지 | + +핵심 의존 방향은 아래 한 줄로 요약된다. + +`application -> domain -> engine` + +### Core Flow 1: 시뮬레이션 시작 및 프레임 업데이트 + +```mermaid +sequenceDiagram + participant User as User + participant MW as MainWindow + participant Domain as SafeCrowdDomain + participant Runtime as EngineRuntime + participant Clock as FrameClock + + User->>MW: Start 클릭 + MW->>Domain: start() + Domain->>Runtime: play() + + loop every 16ms + MW->>Domain: update(1/60) + Domain->>Runtime: stepFrame(deltaSeconds) + Runtime->>Clock: accumulate delta + Clock-->>Runtime: fixed step count + alpha + Runtime-->>Domain: EngineStats 갱신 + MW->>Domain: summary() + Domain-->>MW: SimulationSummary + MW-->>User: 상태 / Frames / Fixed Steps 표시 + end +``` + +현재 Qt 애플리케이션은 `Start`, `Pause`, `Stop` 버튼과 `QTimer`를 사용해 실행 루프를 구동한다. `SafeCrowdDomain`은 application과 engine 사이의 얇은 파사드 역할을 수행하며, `EngineRuntime`은 프레임 누적과 상태 관리의 실제 책임을 가진다. + +### Core Flow 2: DXF 도면 import 및 실행 가능 레이아웃 생성 + +```mermaid +sequenceDiagram + participant User as User + participant App as Application UI + participant Importer as DxfImportService + participant Builder as FacilityLayoutBuilder + participant Validator as ImportValidationService + participant Result as ImportResult + + User->>App: DXF 파일 선택 + App->>Importer: importFile(ImportRequest) + Importer->>Importer: DXF ASCII parse + Importer->>Importer: RawImportModel 생성 + Importer->>Importer: CanonicalGeometry 정규화 + Importer->>Builder: build(canonicalGeometry) + Builder-->>Importer: FacilityLayout2D + build issues + Importer->>Validator: validate(layout) + Validator-->>Importer: validation issues + Importer-->>App: ImportResult + App->>Result: readyForSimulation() + Result-->>App: 실행 가능 / 차단 사유 + App-->>User: 검토 결과, 경고, 차단 이슈 표시 +``` + +이 흐름은 Sprint 1의 핵심 가치인 `도면 불러오기 -> 구조 검토 -> 실행 가능 여부 판단`을 담당한다. `DxfImportService`는 파일 포맷 처리와 정규화를 담당하고, `FacilityLayoutBuilder`는 시뮬레이션 입력에 가까운 레이아웃 객체를 만들며, `ImportValidationService`는 출구 연결성과 최소 조건을 검증한다. 현재 저장소에는 domain 중심의 import 파이프라인이 구현되어 있고, application의 전용 import 화면 연결은 후속 작업으로 남아 있다. + +## 3. 데이터 설계 and/or API 설계 + +본 프로젝트는 데이터베이스 중심 CRUD 시스템이 아니라 데스크톱 시뮬레이션 시스템이므로, 전통적인 ERD 대신 도메인 데이터 모델과 내부 인터페이스를 설계 기준으로 사용한다. + +### Data Model Diagram + +```mermaid +classDiagram + class ImportRequest { + sourcePath + requestedFormat + preserveRawModel + runValidation + } + + class RawImportModel { + format + unit + sourceDocumentId + levelId + entities[] + } + + class CanonicalGeometry { + levelId + walkableAreas[] + walls[] + openings[] + obstacles[] + verticalLinks[] + } + + class FacilityLayout2D { + id + name + levelId + zones[] + connections[] + barriers[] + controls[] + } + + class ImportIssue { + severity + code + message + isBlocking + } + + class ImportResult { + rawModel + canonicalGeometry + layout + issues[] + traceRefs[] + reviewStatus + readyForSimulation() + } + + class SafeCrowdDomain { + start() + pause() + stop() + update(deltaSeconds) + summary() + } + + class EngineRuntime { + play() + pause() + stop() + stepFrame(deltaSeconds) + stats() + state() + } + + ImportRequest --> ImportResult : importFile() + ImportResult o--> RawImportModel + ImportResult o--> CanonicalGeometry + ImportResult o--> FacilityLayout2D + ImportResult o--> ImportIssue + SafeCrowdDomain --> EngineRuntime +``` + +### Integrity / Consistency Rules + +- `FacilityLayout2D`에는 최소 1개의 `Exit` zone이 있어야 한다. +- 모든 non-exit zone은 적어도 1개의 exit zone으로 연결되는 경로를 가져야 한다. +- `Connection2D.effectiveWidth`가 데모 최소 폭 0.9m보다 작으면 경고를 발생시킨다. +- blocking import issue가 존재하면 시뮬레이션은 시작할 수 없다. +- `ImportResult.reviewStatus`는 `Approved` 또는 `NotRequired`이어야 실행 가능 상태가 된다. +- `engine` 레이어는 SafeCrowd 고유 타입을 모르고, `domain`은 Qt 타입을 모른다. + +### Internal Interface Catalog + +초기 버전은 외부 REST API를 주 인터페이스로 사용하지 않는다. 대신 동일 프로세스 내부에서 계층 간 계약을 명확히 하는 방식으로 설계한다. + +| Interface | Input | Output | Purpose | +| --- | --- | --- | --- | +| `DxfImportService::importFile` | `ImportRequest` | `ImportResult` | DXF 파일을 읽어 raw/canonical/layout 단계 결과와 이슈를 함께 반환 | +| `FacilityLayoutBuilder::build` | `CanonicalGeometry` | `FacilityLayoutBuildResult` | 추상 기하 정보를 시뮬레이션 친화적 레이아웃으로 변환 | +| `ImportValidationService::validate` | `FacilityLayout2D` | `std::vector` | 출구 누락, 단절 구역, 최소 폭 미달 검증 | +| `ImportResult::readyForSimulation` | 내부 상태 | `bool` | 검토 승인과 차단 이슈를 종합해 실행 가능 여부 판정 | +| `SafeCrowdDomain::start/pause/stop/update/summary` | 사용자 명령, `deltaSeconds` | `SimulationSummary` | application에서 engine 실행을 제어하는 도메인 파사드 | +| `EngineRuntime::play/pause/stop/stepFrame` | 실행 명령, 프레임 시간 | `EngineStats`, `EngineState` | 고정 timestep 기반 runtime 상태와 진행 통계 관리 | + +## 4. Development Environment + +### Environment Summary + +| Item | Value | +| --- | --- | +| OS | Windows x64 개발 환경 | +| Language | C++20 | +| Generator / Compiler | Visual Studio 17 2022 / MSVC | +| Build System | CMake 3.25+ | +| Package Manager | vcpkg | +| UI Library | Qt6 Widgets (`qtbase`, `widgets` feature) | +| Test | CTest + `safecrowd_tests` | +| Source Root | `src/application`, `src/domain`, `src/engine` | +| Main Targets | `ecs_engine`, `safecrowd_domain`, `safecrowd_app` | + +### Build / Test Commands + +```powershell +cmake --preset windows-debug +cmake --build --preset build-debug +ctest --preset test-debug +``` + +Qt 앱 없이 engine/domain/test만 빠르게 확인할 때는 아래 경로를 사용한다. + +```powershell +cmake --preset windows-debug-no-app +cmake --build --preset build-no-app-debug +ctest --preset test-no-app-debug +``` + +### Preset / Dependency Notes + +- `CMakePresets.json`은 `windows-debug`, `windows-debug-no-app`, `windows-release`, `windows-release-no-app` 구성을 제공한다. +- Qt를 포함하는 preset은 `VCPKG_ROOT`가 설정된 환경에서 `CMAKE_TOOLCHAIN_FILE=$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake`를 사용한다. +- `vcpkg.json`은 `qtbase`의 default feature를 끄고 `widgets` feature만 활성화한다. +- import stack은 `cmake/SafeCrowdImportStack.cmake`를 통해 domain 계층에서만 연결되며, 기본 경로는 CI와 로컬 최소 환경을 위해 보수적으로 유지한다. + +### Repository Structure + +```text +Project/ + CMakeLists.txt + CMakePresets.json + vcpkg.json + src/ + application/ + domain/ + engine/ + tests/ + docs/ + uml/ + external/ +``` + +### Development Conventions + +- include root는 `src/`이며, `#include "application/..."`, `#include "domain/..."`, `#include "engine/..."` 형식을 사용한다. +- `engine`은 `domain`이나 `application`을 참조하지 않는다. +- `domain`은 Qt UI 코드를 참조하지 않는다. +- CI는 빠른 피드백을 위해 우선 `SAFECROWD_BUILD_APP=OFF` 경로를 검증하고, 로컬에서는 전체 Qt 앱 빌드도 유지한다. + +## 5. Traceability + +### Requirement to Design Element Summary + +| Requirement | Design Element | Notes | +| --- | --- | --- | +| US-01 도면 불러오기 | `DxfImportService`, `RawImportModel`, `CanonicalGeometry`, `FacilityLayoutBuilder` | DXF 파일을 시뮬레이션 입력 구조로 변환하는 Sprint 1 핵심 흐름 | +| US-02 구조 검토 및 경고 확인 | `ImportValidationService`, `ImportIssue`, `ImportTraceRef`, `ImportResult.reviewStatus` | 차단 이슈와 추적 정보를 함께 제공해 검토 가능 상태 구성 | +| US-03 수동 보정 후 실행 가능 상태 확정 | `FacilityLayout2D`, `Connection2D`, `ControlPoint2D`, `ImportResult::readyForSimulation()` | 레이아웃 수정과 승인 결과를 반영해 실행 가능 여부 판정 | +| US-07 인원 배치 기반 실행 제어 | `MainWindow`, `SafeCrowdDomain`, `EngineRuntime::play/pause/stop/stepFrame` | Start/Pause/Stop 중심의 application-domain-engine 연결 | +| US-09 실시간 진행 상태 확인 | `SimulationSummary`, `EngineStats`, `MainWindow::refreshStatusLabel` | 상태, frame index, fixed step index, alpha 표시 | +| US-10 병목·정체 탐지 | `FacilityLayout2D.connections/zones`, 향후 `LocalDensityField`, `FlowMeasurementSystem`, `CongestionStateSystem` | 현재 레이아웃 기반 입력을 마련했고, 위험 탐지 로직은 `docs/위험 정의.md`를 기준으로 확장 설계 | +| US-11 압력 집중 위험 탐지 | 향후 `CompressionForce`, `CompressionExposure`, `CompressionLoadSystem`, `AsphyxiationRiskSystem` | 압박 위험 모델은 도메인 확장 설계 항목으로 정의됨 | +| US-15~US-17 결과 시각화 및 비교 | 향후 Result UI, 히트맵 레이어, 비교 요약 뷰 | 현재 계층 구조는 Sprint 2 비교/시각화 기능을 application layer에 추가할 수 있게 설계됨 | +| US-18~US-19 운영 대안 추천 | 향후 Recommendation module, scenario diff, rationale model | 현재 문서 구조와 위험 지표 정의를 기반으로 Sprint 3에서 연결 예정 | + +### Traceability Note + +현재 저장소에는 Sprint 1 중심의 import, 실행 제어, 상태 요약 구조가 구현되어 있으며, Sprint 2~3 기능은 백로그와 위험 정의 문서를 근거로 확장 설계가 정리되어 있다. 따라서 본 문서는 현재 구현 구조를 기준으로 하되, 이후 결과 비교와 운영 대안 추천까지 수용할 수 있는 계층 및 데이터 모델을 함께 제시한다. diff --git "a/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/\353\224\224\354\236\220\354\235\270\352\260\234\354\232\224\354\204\234_2\355\214\200.docx" "b/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/\353\224\224\354\236\220\354\235\270\352\260\234\354\232\224\354\204\234_2\355\214\200.docx" index 4c25216..344779d 100644 Binary files "a/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/\353\224\224\354\236\220\354\235\270\352\260\234\354\232\224\354\204\234_2\355\214\200.docx" and "b/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/\353\224\224\354\236\220\354\235\270\352\260\234\354\232\224\354\204\234_2\355\214\200.docx" differ diff --git "a/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/\353\254\270\354\240\234\354\240\225\354\235\230\354\204\234_2\355\214\200.docx" "b/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/\353\254\270\354\240\234\354\240\225\354\235\230\354\204\234_2\355\214\200.docx" index f681833..ed2f4d9 100644 Binary files "a/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/\353\254\270\354\240\234\354\240\225\354\235\230\354\204\234_2\355\214\200.docx" and "b/docs/\354\240\234\354\266\234\354\232\251/\354\242\205\355\225\251\354\204\244\352\263\204/\353\254\270\354\240\234\354\240\225\354\235\230\354\204\234_2\355\214\200.docx" differ