memgraph-poc/docs/PRD.md

Memgraph 기반 터널 시공 관리 의사결정 프레임워크 PoC: PRD (Product Requirements Document)

1. 개요 (Overview)

본 문서는 터널 시공 과정에서 발생하는 복잡한 작업(Job)과 객체(Object) 간의 관계를 그래프 데이터베이스인 Memgraph를 활용하여 모델링하고, 모든 job을 완료 상태로 만들 수 있는 시나리오들을 비교해 프로젝트의 Critical Path를 분석하여 효율적인 공정 관리를 지원하는 의사결정 프레임워크 PoC(Proof of Concept)의 요구사항을 정의합니다.

1.1. 문제 정의 (Problem Statement)

터널 시공 프로젝트는 수많은 작업과 객체가 복잡한 선후행 및 종속 관계로 얽혀 있어, 전통적인 RDB나 표(Spreadsheet) 기반의 관리 방식으로는 전체 공정의 흐름과 병목 현상을 직관적으로 파악하기 어렵습니다. 이로 인해 특정 작업의 지연이 전체 프로젝트에 미치는 영향을 예측하고 선제적으로 대응하는 데 한계가 있으며, 자원 배분의 최적화를 이루기 어렵습니다.

1.2. 제안 해결책 (Proposed Solution): 하이브리드 데이터 아키텍처

자주 변경되지 않는 마스터 데이터(JobType, ObjectType 등)와 동적으로 변하는 공정 시나리오 데이터를 분리하는 하이브리드 아키텍처를 채택합니다. 본 PoC에서는 Memgraph 내에서 이 개념을 시뮬레이션합니다.

• 베이스 데이터 (Base Data): Job 노드는 base_duration, base_cost 등 원본 데이터를 속성으로 가집니다. 모든 Job 간의 기본적인 선후행 관계(PRECEDES)는 ‘base’ 시나리오로 정의됩니다.
• 시나리오와 변경점 (Scenario & Delta):
  • 별도의 Scenario 노드를 두어 “TBM 지연 가정“과 같은 분석 시나리오를 정의합니다.
  • MODIFIES 관계를 사용하여, 특정 Scenario가 특정 Job의 속성(예: duration)을 어떻게 변경하는지에 대한 ‘변경점(Delta)’ 정보만을 저장합니다.
  • 이를 통해 전체 그래프를 복제하지 않고도, 최소한의 데이터로 수많은 “What-if” 시나리오를 효율적으로 관리하고 분석할 수 있습니다.

PoC의 최종 목표는, 특정 시나리오를 분석할 때 **베이스 데이터에 이 ’변경점’들을 실시간으로 적용(override)**하여 Critical Path를 계산하고, 이를 통해 가장 최적화된 공정을 찾는 동적 의사결정 지원 과정을 검증하는 것입니다.

2. PoC 목표 및 성공 기준 (Goals & Success Criteria)

2.1. 목표

• 목표 1: ‘베이스 데이터 + 변경점(Delta)’ 개념을 포함한 하이브리드 그래프 데이터 모델을 성공적으로 설계하고 구축한다.
• 목표 2: 특정 시나리오(변경점 세트)가 주어졌을 때, 베이스 데이터에 변경점을 동적으로 적용하여 해당 시나리오의 Critical Path를 정확하게 계산하는 쿼리를 개발한다.
• 목표 3: 여러 시나리오의 분석 결과를 비교하여, 프로젝트 관리자가 최적의 공정(가장 짧은 Critical Path를 가진)을 선택할 수 있는 의사결정 과정을 시뮬레이션한다.

2.2. 성공 기준

• 정량적 기준:
  • 정의된 Job 및 Object 속성을 90% 이상 포함하는 그래프 스키마를 완성한다.
  • 최소 20개 이상의 Job 노드와 10개 이상의 Object 노드로 구성된 샘플 데이터셋을 Memgraph에 삽입 완료한다.
  • 작업 기간(duration) 속성을 기반으로, 단일 Cypher 쿼리 실행을 통해 가장 긴 경로(Critical Path)를 10초 이내에 반환한다.
• 정성적 기준:
  • Memgraph Lab을 통해 시각화된 그래프가 시공 프로세스의 관계를 직관적으로 표현한다.
  • 도출된 Critical Path가 논리적으로 타당하며, 프로젝트 관리자가 이를 기반으로 의사결정을 내릴 수 있음을 설명할 수 있다.

3. PoC 범위 (Scope)

3.1. 포함되는 범위 (In-Scope)

• 데이터 모델링:
  • Job, Object 노드 정의 (제시된 속성 기반)
  • 노드 간의 관계(PRECEDES, DEPENDS_ON 등) 엣지 정의
• 데이터 수명주기:
  • 샘플 데이터셋(CSV 또는 JSON) 정의 및 생성
  • Cypher 쿼리를 이용한 데이터 삽입(Create) 및 조회(Read)
• 핵심 기능 개발:
  • Critical Path 분석을 위한 Cypher 쿼리 작성
• 검증:
  • Memgraph Lab을 이용한 데이터 시각화 및 확인
  • 쿼리 결과 분석 및 자원 재배치 시뮬레이션 시나리오 문서화

3.2. 제외되는 범위 (Out-of-Scope)

• 애플리케이션/UI 개발: 별도의 웹/앱 UI 개발은 진행하지 않으며, 모든 작업은 Memgraph Lab 또는 CLI 환경에서 수행합니다.
• 실시간 데이터 연동: 외부 시스템과의 실시간 데이터 연동은 고려하지 않습니다.
• LLM 연동: 자연어 처리 및 LLM 연동은 본 PoC의 범위를 벗어나며, 성공적인 완료 후 다음 단계 과제로 고려합니다.
• 상세 속성 전체 모델링: Object의 ’수많은 타입별 세부 속성’은 PoC의 복잡도를 고려하여, 대표적인 2~3개 타입의 핵심 속성만 모델링에 포함합니다.

4. 기능 명세 (Feature Specifications)

FS-1: 그래프 데이터 모델 설계

• 노드 (Nodes):
  • Job: 작업 정보를 담는 노드.
    • 주요 속성: job_no, name, id, start_date, end_date, duration (Critical Path 계산을 위한 핵심 속성, end_date - start_date로 계산), status (계획, 확인, 승인 등) 등
  • Object: 시공 객체 정보를 담는 노드.
    • 주요 속성: obj_no, name, id, type, bim_model_id, version 등
• 엣지 (Edges):
  • PRECEDES: Job 간의 선후행 관계. (A Job -> B Job)
  • HAS_OBJECT: Job이 특정 Object와 연관됨을 나타내는 관계. (A Job -> B Object)
  • PARENT_OF: Object 간의 계층 구조 관계. (A Object -> B Object)

FS-2: 데이터 삽입 및 조회

• 미리 정의된 샘플 데이터(CSV)를 LOAD CSV Cypher 구문을 사용하여 Memgraph에 일괄 삽입하는 스크립트를 작성합니다.
• 기본적인 노드 및 관계 조회 쿼리를 작성하여 데이터가 정상적으로 삽입되었는지 확인합니다.

FS-3: Critical Path 분석

• Job 노드의 duration 속성의 합이 가장 큰 경로를 찾는 Cypher 쿼리를 작성합니다.
• 쿼리는 PRECEDES 엣지를 따라 순차적으로 연결된 Job 노드들의 경로를 탐색해야 합니다.
• 예시 쿼리 골격:

  MATCH path = (start_node:Job)-[:PRECEDES*]->(end_node:Job)
  WHERE NOT ()-[:PRECEDES]->(start_node) AND NOT (end_node)-[:PRECEDES]->()
  WITH nodes(path) AS path_nodes
  UNWIND path_nodes as node
  WITH path_nodes, sum(node.duration) as total_duration
  RETURN path_nodes, total_duration
  ORDER BY total_duration DESC
  LIMIT 1;

FS-4: 시나리오 기반 What-if 분석

• FS-3에서 도출된 Critical Path 상의 Job들과, 그렇지 않은 Job(Slack이 있는 Job)들을 구분합니다.
• “만약 Slack이 있는 B작업의 자원을 Critical Path에 있는 A작업으로 재배치한다면, A작업의 duration이 단축되어 전체 프로젝트 기간이 줄어들 수 있다“는 가설을 세우고, 이를 설명하는 시나리오를 문서로 작성합니다. (실제 데이터 변경 없이 개념 증명)

FS-5: 시나리오 관리 (스냅샷)

• 기존에 존재하는 특정 시나리오(예: ‘scenario-A’)의 모든 PRECEDES 관계를 복제하여 새로운 시나리오(예: ‘scenario-B’)를 생성하는 Cypher 쿼리를 작성합니다.
• 생성된 신규 시나리오 내에서 특정 Job의 속성(예: duration)을 변경하거나, PRECEDES 관계를 수정하여 공정 변화를 시뮬레이션할 수 있어야 합니다.

5. 검증 시나리오 (Validation Scenario)

1. 준비: docker-compose.yml을 사용하여 Memgraph 인스턴스를 실행합니다.
2. 데이터 로딩: 작성된 데이터 삽입 스크립트를 실행하여 샘플 데이터를 Memgraph에 로드합니다.
3. 데이터 확인: Memgraph Lab에 접속하여 노드와 엣지가 의도한 대로 생성되었는지 시각적으로 확인합니다.
4. Critical Path 실행: 작성된 Critical Path 분석 쿼리를 실행하고, 가장 긴 경로와 총 소요 기간을 확인합니다.
5. 결과 분석:
   • 쿼리 결과로 나온 Job 리스트가 프로젝트의 병목 구간임을 확인합니다.
   • 해당 경로에 포함되지 않은 다른 작업 중, 유사한 자원을 사용하거나 대기 시간이 긴 작업을 식별합니다.
   • 식별된 작업을 기반으로 자원 재배치 시나리오를 설명하고, 이를 통해 얻을 수 있는 기대효과(공정 단축)를 제시하며 PoC의 유용성을 증명합니다.

6. 기술 스택 (Tech Stack)

• Database: Memgraph
• Orchestration: Docker, Docker Compose
• Query & Visualization: Cypher, Memgraph Lab
• Data Format: CSV or JSON

7. 향후 계획 (Next Steps)

본 PoC가 성공적으로 완료되면, 다음 단계를 통해 프레임워크를 고도화할 수 있습니다.

• Phase 2 (Application Layer): 데이터 조회 및 수정을 위한 API 서버 및 간단한 대시보드 UI 개발
• Phase 3 (Advanced Analysis): What-if 시뮬레이션(특정 작업 지연 시 영향도 분석), 병목 현상 예측 등 고급 분석 기능 추가
• Phase 4 (LLM Integration): 자연어 질의(예: “현재 가장 중요한 작업이 뭐야?”)를 통해 분석 결과를 얻거나, 분석 리포트를 자동 생성하는 LLM 연동 기능 개발