Pathfinder 조사 반영

Author: learncold

docs/architecture/프로젝트 구조.md

@@ -100,13 +100,14 @@ Project/
 - 공간 구조
 - 시나리오 데이터
 - `FacilityLayout`, `PopulationSpec`, `EnvironmentState`, `ControlPlan`, `ExecutionConfig` 입력 계약
+- `FacilityLayout` 안의 `Room`, `Door`, `Connector`, `ControlZone`, `MeasurementRegionSpec` 같은 실행 계약
 - baseline과 대안 비교를 위한 `ScenarioVariation`
 - 시나리오 보정(`ScenarioCalibrationService`)
 - 단일 실행 세션(`SimulationSession`)과 배치 실행(`ScenarioBatchRunner`)
 - 시뮬레이션 규칙
 - 위험 계산
-- run/variation/cumulative 단위 결과 아티팩트(`RunResult`, `VariationSummary`, `CumulativeArtifact`)
-- 결과 요약 및 비교 집계(`ResultAggregator`)
+- run/variation/comparison/cumulative 단위 결과 아티팩트(`RunResult`, `VariationSummary`, `ScenarioComparison`, `CumulativeArtifact`)
+- persisted 결과 아티팩트 생성/갱신(`ResultAggregator`)
 - 운영 대안 추천(`AlternativeRecommendationService`)
 
 넣지 말아야 할 것:
@@ -167,11 +168,11 @@ Qt viewport가 엔진 렌더러와 직접 연결되어야 하면 `application ->
 - `uml/engine-runtime-core.puml` : runtime, scheduling, resource, reproducibility
 - `uml/engine-ecs-core.puml` : ECS storage와 `EngineWorld` 접근면
 - `uml/domain-import-module.puml` : 오픈소스 import 스택의 domain 중심 구조와 import -> layout -> bake 흐름
-- `uml/domain-scenario-model.puml` : `ScenarioDefinition`을 이루는 입력 계약과 variation 구조
-- `uml/domain-control-model.puml` : 행동, 트리거, occupant tag, route choice policy 구조
-- `uml/engine-routing-and-connectors.puml` : topology snapshot, connector, path cost, measurement 경계 구조
-- `uml/domain-result-artifacts.puml` : run, variation, cumulative 결과 아티팩트 구조
-- `uml/application-run-results-workflow.puml` : 작성, 실행, 비교, 내보내기, 추천 흐름
+- `uml/domain-scenario-model.puml` : `ScenarioDefinition`을 이루는 입력 계약, `PopulationSpec`, `ControlZone`, variation 구조
+- `uml/domain-control-model.puml` : 행동, 트리거, occupant tag, route choice policy, `ControlZone` 대상 제어 구조
+- `uml/engine-routing-and-connectors.puml` : topology snapshot, connector, path cost, `ControlZone` access override, measurement 경계 구조
+- `uml/domain-result-artifacts.puml` : run, variation, comparison, cumulative 결과 아티팩트 구조
+- `uml/application-run-results-workflow.puml` : persisted artifact 기준의 작성, 실행, 비교, 내보내기, 추천 흐름
 
 각 UML 해설 문서는 다음 파일에 둔다.
 - `uml/project-structure.puml 해설.md`

docs/process/Pathfinder 조사 기반 반영 계획.md

@@ -21,7 +21,7 @@
 - 제품 요구와 사용자 노출 위험 체계는 [위험 정의.md](../product/%EC%9C%84%ED%97%98%20%EC%A0%95%EC%9D%98.md)를 우선 기준으로 삼는다.
 - 상세 물리 모델과 연구 근거는 [고급 위험 모델.md](../product/%EA%B3%A0%EA%B8%89%20%EC%9C%84%ED%97%98%20%EB%AA%A8%EB%8D%B8.md)에 둔다.
 - 단, [고급 위험 모델.md](../product/%EA%B3%A0%EA%B8%89%20%EC%9C%84%ED%97%98%20%EB%AA%A8%EB%8D%B8.md)는 `Pathfinder 정합 확장`과 `연구 후보`를 함께 담는 참고 문서이며, 두 범주를 같은 우선순위로 취급하지 않는다.
-- backlog, UML, issue 제목/본문에서는 `병목/정체/탈출 지연`, `시야 제한 및 길찾기 저하`, `근접도 및 압박 전조`, `운영 갈등`의 4축과 `FacilityLayout/PopulationProfile/EnvironmentState/ControlPlan/ExecutionConfig` 입력 계약을 우선 용어로 사용한다.
+- backlog, UML, issue 제목/본문에서는 `병목/정체/탈출 지연`, `시야 제한 및 길찾기 저하`, `근접도 및 압박 전조`, `운영 갈등`의 4축과 `FacilityLayout/PopulationSpec/EnvironmentState/ControlPlan/ExecutionConfig` 입력 계약을 우선 용어로 사용한다.
 - 단, `추천 기능` 자체는 범위에서 빼지 않는다. 별도 문서로 분리하는 것은 추천 엔진의 상세 규칙과 최적화 로직이다.
 - 압사, 낙상, 역방향/교차류 독립 모델은 별도 설계 문서가 생기기 전까지 UML/issue 기본 범위에 올리지 않는다.
 
@@ -44,11 +44,12 @@
 | --- | --- | --- |
 | 공간 토폴로지 정규화 | `E1` | `Floor/Room/Wall/Door/Obstruction/Obstacle` 구분을 story 수준으로 명시 |
 | 커넥터 모델 | `E1`, `E3` | `stairs/ramp/escalator/walkway` 공통 connector + modifier 구조를 acceptance 기준에 반영 |
+| 통제 가능 구역 | `E1`, `E2` | `ControlZone`을 named room/door/connectors group으로 두고 구역 통제 구조를 acceptance/UML에 반영 |
 | 프로필 제약과 분포 파라미터 | `E2`, `E3` | usable connector restriction, 속도/가속/간격 분포, seed 재현성 보강 |
 | 출구 선택 비용 | `E2`, `E3` | 단순 nearest exit가 아니라 이동 시간/대기/잔여 경로 비용 구조를 명시 |
 | 행동/트리거/태그 | `E2` | 운영 이벤트를 단순 on/off가 아니라 행동 전환 모델로 구체화 |
 | 동적 인원 유입 | `E3` | 초기 배치 외에 source 기반 유입 story 추가 또는 `US-07` 확장 |
-| 결과 아티팩트 | `E4`, `E5`, `E7` | `door history`, `room history`, `measurement regions`, `cumulative JSON`, 선택적 `occupant history` 명시 |
+| 결과 아티팩트 | `E4`, `E5`, `E7` | `door history`, `room history`, `measurement regions`, persisted `ScenarioComparison`, `cumulative JSON`, 선택적 `occupant history` 명시 |
 | 반복 실행 | `E3`, `E5` | run/variation 구조와 Monte Carlo 요약 구분 보강 |
 | results viewer | `E5`, `E7` | 1차 확장 범위로 별도 story 후보 분리 |
 
@@ -102,11 +103,11 @@
 ### 추가할 UML 후보
 | 파일 | 목적 | 중심 레이어 |
 | --- | --- | --- |
-| `uml/domain-scenario-model.puml` | `FacilityLayout`, `Scenario`, `Variation`, `ExecutionConfig`, `PopulationSpec` 관계 고정 | `domain` |
-| `uml/domain-control-model.puml` | `Behavior`, `Trigger`, `OccupantTag`, `OperationalEvent`, `RouteChoicePolicy` 관계 정의 | `domain` |
-| `uml/engine-routing-and-connectors.puml` | room/door/connectors, path cost, dynamic obstacle, flow measurement 구조 정리 | `engine + domain boundary` |
-| `uml/domain-result-artifacts.puml` | `RunResult`, `DoorHistory`, `RoomHistory`, `MeasurementRegionSeries`, `OccupantHistory`, `CumulativeArtifact` 정리 | `domain` |
-| `uml/application-run-results-workflow.puml` | 시나리오 실행에서 결과 확인/비교/내보내기까지 UI 흐름 정리 | `application` |
+| `uml/domain-scenario-model.puml` | `FacilityLayout`, `ControlZone`, `Scenario`, `Variation`, `ExecutionConfig`, `PopulationSpec` 관계 고정 | `domain` |
+| `uml/domain-control-model.puml` | `Behavior`, `Trigger`, `OccupantTag`, `OperationalEvent`, `RouteChoicePolicy`, zone-targeted control 관계 정의 | `domain` |
+| `uml/engine-routing-and-connectors.puml` | room/door/connectors, `ControlZone`, path cost, dynamic obstacle, flow measurement 구조 정리 | `engine + domain boundary` |
+| `uml/domain-result-artifacts.puml` | `RunResult`, `DoorHistory`, `RoomHistory`, `MeasurementRegionSeries`, `OccupantHistory`, `ScenarioComparison`, `CumulativeArtifact` 정리 | `domain` |
+| `uml/application-run-results-workflow.puml` | 시나리오 실행에서 persisted result artifact 확인/비교/내보내기까지 UI 흐름 정리 | `application` |
 
 ### 도면 작성 순서
 1. `domain-scenario-model`
@@ -126,11 +127,11 @@
   - 정적 obstruction과 동적 obstacle을 어떻게 분리할 것인가
   - connector 공통 모델에 어떤 modifier를 둘 것인가
 - `domain-result-artifacts`
-  - run 단위, variation 단위, cumulative 단위를 어떻게 분리할 것인가
+  - run 단위, variation 단위, comparison 단위, cumulative 단위를 어떻게 분리할 것인가
   - 상세 occupant history를 항상 둘지 선택적으로 둘지
 - `application-run-results-workflow`
   - 작성/실행과 재생/분석을 같은 화면에 둘지 분리할지
-  - comparison, export, recommendation을 어느 화면 흐름으로 묶을지
+  - comparison, export, recommendation이 persisted artifact를 어떻게 읽을지
 
 ### UML 산출 규칙
 - 새 `.puml` 파일마다 대응 `해설.md`를 같이 만든다.

docs/product/Product Backlog - Pathfinder 반영안.md

@@ -137,21 +137,21 @@ SafeCrowd는 건물 관리자, 행사장 운영자, 안전관리자, 건축·공
   - 기준 시나리오가 저장되면, 시나리오 목록을 열면, 해당 시나리오가 비교 기준 시나리오로 구분되어 보인다.
   - 필수 입력이 빠졌을 때, 저장을 시도하면, 누락된 항목을 사용자에게 알려준다.
   - 기준 시나리오가 준비되면, 사용자가 실행 준비 상태를 확인하면, 실행 가능 여부가 표시된다.
-  - 기준 시나리오를 만들 때, `PopulationProfile`, usable connector restriction, 기본 route choice rule을 함께 설정할 수 있다. (추가)
+- 기준 시나리오를 만들 때, `PopulationSpec`(초기 배치, 동적 유입, `PopulationProfile`)과 usable connector restriction, 기본 route choice rule을 함께 설정할 수 있다. (추가)
 - **Priority:** Must
 - **Estimate (SP):** 5SP
 
 #### US-04A 시나리오 템플릿 기반 빠른 시작
 - **User Story**  
   도메인 지식이 많지 않은 운영자로서 대표 템플릿을 골라 시나리오 초안을 빠르게 만들고 싶다. 그래야 어떤 변수부터 설정해야 하는지 몰라서 시나리오 작성을 중단하지 않을 수 있다.
 - **Template Scope Note:**  
-  템플릿은 `docs/product/사용자 시나리오.md`의 대표 사용 맥락과 `FacilityLayout`, 인원 배치/프로필, `EnvironmentState`, `ControlPlan`, `ExecutionConfig` 입력 계약을 기준으로 구성한다. 초기 템플릿 묶음은 `기준 대피`, `출구 일부 폐쇄`, `구역별 순차 퇴장`, `일방통행/동선 분리`, `행사 종료 후 분산`, `설계안 비교 기준 조건`으로 둔다.
+  템플릿은 `docs/product/사용자 시나리오.md`의 대표 사용 맥락과 `FacilityLayout`, `PopulationSpec`, `EnvironmentState`, `ControlPlan`, `ExecutionConfig` 입력 계약을 기준으로 구성한다. 초기 템플릿 묶음은 `기준 대피`, `출구 일부 폐쇄`, `구역별 순차 퇴장`, `일방통행/동선 분리`, `행사 종료 후 분산`, `설계안 비교 기준 조건`으로 둔다.
 - **Acceptance Criteria**
   - 시뮬레이션 가능한 레이아웃이 있을 때, 사용자가 새 시나리오를 만들면, 템플릿 목록에서 목적, 추천 사용 상황, 필요한 레이아웃 조건을 확인할 수 있다.
   - 템플릿을 선택하면, 시스템은 인원 배치/유입, 환경 조건, 운영 이벤트, 실행 설정의 권장 기본값을 한 번에 채우고 사용자가 먼저 수정할 핵심 항목만 우선 노출한다.
   - 템플릿 카드와 편집 화면에는 `기본 인원 규모`, `시작 구역`, `주요 출구/목적지`, `통제 시점`, `가시성/안내 수준`, `반복 실행 여부` 같은 비전문가용 설명이 함께 표시된다.
   - 각 템플릿은 주로 확인하려는 위험 축을 함께 표시해, 사용자가 `병목/정체/탈출 지연`, `시야 제한 및 길찾기 저하`, `근접도 및 압박 전조`, `운영 갈등` 중 무엇을 검토하는 시나리오인지 이해할 수 있다.
-  - 레이아웃에 다중 출구, connector, 통제 가능 구역 같은 필수 요소가 부족하면, 시스템은 적용 전에 부족한 조건을 경고하고 더 단순한 템플릿이나 수동 생성으로 전환할 수 있게 안내한다.
+  - 레이아웃에 다중 출구, connector, 통제 가능 구역(`ControlZone`) 같은 필수 요소가 부족하면, 시스템은 적용 전에 부족한 조건을 경고하고 더 단순한 템플릿이나 수동 생성으로 전환할 수 있게 안내한다.
   - 템플릿으로 생성한 시나리오는 기준안 또는 대안으로 저장할 수 있고, 템플릿 출처와 사용자가 수정한 항목이 시나리오 차이 기록에 함께 남는다.
 - **Priority:** Should
 - **Estimate (SP):** 5SP

docs/product/개요서.md

@@ -40,7 +40,7 @@ SafeCrowd: 군중 안전 시뮬레이터
 - 다양한 시나리오와 운영 대안을 UI에서 생성·수정·저장할 수 있는 인터페이스 구현
 - 출구 폐쇄, 인원 밀집, 특정 구역 통제, 장애물 추가 등 상황 변화 시뮬레이션 기능 구현
 - 시뮬레이션 결과를 기준 시나리오 대비 비교 가능하게 시각화하고, 의사결정에 필요한 핵심 위험 지표를 제공하는 기능 구현
-- 핵심 위험 구간과 지표를 근거로 출구 추가 개방, 순차 퇴장, 통제 구역 조정 같은 운영 대안을 추천하는 기능 구현
+- 핵심 위험 구간과 지표를 근거로 출구 추가 개방, 순차 퇴장, 통제 구역(`ControlZone`) 조정 같은 운영 대안을 추천하는 기능 구현
 
 ## 기대 결과물 및 기능
 

docs/product/사용자 시나리오.md

@@ -73,7 +73,7 @@
 - 행사 종료 시점의 예상 인원 규모와 구역별 분포가 정리되어 있다.
 
 ### 주요 흐름
-1. 사용자는 행사장 구조를 불러오고 주요 출구, 복도, 계단, 펜스 구역, 통제 가능 구역을 확인한다.
+1. 사용자는 행사장 구조를 불러오고 주요 출구, 복도, 계단, 펜스 구역, 통제 가능 구역(`ControlZone`)을 확인한다.
 2. 사용자는 행사 종료 직후를 기준으로 구역별 인원 규모와 이동 방향을 설정한다.
 3. 사용자는 출구 일부 폐쇄, 구역별 순차 퇴장, 유도 펜스 설치, 특정 통로 일방화, 안전요원 배치 같은 인파 분산 대안을 여러 개 생성한다.
 4. 시스템은 각 운영 대안을 기반으로 대규모 군중 이동 시뮬레이션을 실행한다.

docs/product/위험 정의.md

@@ -169,17 +169,19 @@ MVP에서는 `고밀도 체류`, `압박 hotspot`, `혼잡 전이` 위주로 시
 
 위험 문서는 사용자가 실제로 설정하는 입력 단위를 먼저 정의해야 한다. 기본 입력 계약은 다음 다섯 묶음으로 유지한다.
 
-- `FacilityLayout`: 방, 복도, 계단, 출구, 장애물, 펜스, 통제 가능 구역
-- `PopulationProfile`: 인원 수, 초기 배치, 이동 약자 비율, 기본 이동 성향, 필요 시 그룹 분포
+- `FacilityLayout`: 방, 복도, 계단, 출구, 장애물, 펜스, 통제 가능 구역(`ControlZone`)
+- `PopulationSpec`: 초기 배치, 동적 유입, `PopulationProfile`(이동 약자 비율, 기본 이동 성향, 필요 시 그룹 분포)
 - `EnvironmentState`: 시야, 친숙도, 조명, 표지 가시성, 유도 인력, 필요 시 연기/FED 연동
 - `ControlPlan`: 출구 개방/폐쇄, 일방통행, 접근 제한, 순차 퇴장, 임시 장애물, 유입 통제
 - `ExecutionConfig`: 제한시간, 샘플링 주기, 반복 실행 수, 난수 seed
 
+제품 문서에서 `PopulationProfile`은 독립 top-level 입력 계약이 아니라 `PopulationSpec`의 하위 구성요소로 취급한다.
+
 초기 제품 문서에서는 `DesiredSpeed`, `FollowingWeight`, `CompressionExposure`, `OrderParameter` 같은 내부 파라미터를 직접 계약의 일부로 두지 않는다.
 
 단계 적용 기준은 다음과 같다.
 
-- `MVP`: `FacilityLayout`, 기본 `PopulationProfile`, `ControlPlan`, `ExecutionConfig`
+- `MVP`: `FacilityLayout`, 기본 `PopulationSpec`, `ControlPlan`, `ExecutionConfig`
 - `1차 확장`: 그룹 분포, 시야/친숙도/유도 신호 입력
 - `중기 확장`: 연기/FED/FDS 연동
 

uml/application-run-results-workflow.puml

@@ -22,7 +22,7 @@ package "domain" {
   [ScenarioBatchRunner\n(spawn baseline / variations)] as BatchRunner
   [SimulationSession\n(single run lifecycle)] as SimulationSession
   [ResultRepository\n(load / persist artifacts)] as ResultRepository
-  [ResultAggregator\n(summary / compare)] as ResultAggregator
+  [ResultAggregator\n(build persisted artifacts)] as ResultAggregator
   [AlternativeRecommendationService\n(candidate generation)] as RecommendationService
 }
 
@@ -32,6 +32,7 @@ package "engine" {
 }
 
 Workspace --> ScenarioEditor : author scenario family
+Workspace --> ResultRepository : reopen saved project
 ScenarioEditor --> RunControl : submit baseline / variation set
 RunControl --> BatchRunner : execute batch
 BatchRunner --> SimulationSession : spawn run
@@ -40,19 +41,19 @@ EngineRuntime --> RenderBridge : live frame snapshots
 RenderBridge --> LiveViewport : present runtime state
 
 BatchRunner --> ResultRepository : persist run artifacts
-ResultRepository --> RunResultsPanel : load run / variation summaries
+BatchRunner --> ResultAggregator : update higher-level artifacts
+ResultAggregator --> ResultRepository : persist variation / comparison / cumulative artifacts
+RunResultsPanel --> ResultRepository : load run / variation summaries
 RunResultsPanel --> ComparisonView : open baseline comparison
-ComparisonView --> ResultAggregator : refresh deltas
-ResultAggregator --> ResultRepository : read cumulative artifacts
+ComparisonView --> ResultRepository : load comparison / cumulative artifacts
 
 ComparisonView --> ExportDialog : export selected artifact bundle
 ExportDialog --> ResultRepository : resolve files
 
 ComparisonView --> RecommendationPanel : inspect recommendation evidence
-RecommendationPanel --> RecommendationService : generate candidates
-RecommendationService --> ResultRepository : read cumulative artifact
-RecommendationService --> ScenarioEditor : create recommended variation
-Workspace --> ResultRepository : reopen saved project
+RecommendationPanel --> RecommendationService : read evidence / scenarioize
+RecommendationService --> ResultRepository : read ScenarioComparison / CumulativeArtifact
+RecommendationPanel --> ScenarioEditor : open recommended variation draft
 
 note bottom of Workspace
   Authoring and analysis live in one project workspace,
@@ -67,6 +68,12 @@ note bottom of RunResultsPanel
   not direct engine state readers.
 end note
 
+note bottom of ComparisonView
+  Comparison reads persisted comparison artifacts.
+  It should not trigger ad hoc domain-side
+  delta calculation as part of basic rendering.
+end note
+
 note bottom of RecommendationPanel
   Recommendation stays after the result pipeline.
   It should consume stable cumulative artifacts and