memgraph-poc/docs/PRD.md

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

1. 개요 (Overview)

본 문서는 터널 시공 과정에서 발생하는 복잡한 작업(Job)과 객체(Object) 간의 관계를 그래프 데이터베이스인 Memgraph를 활용하여 모델링하고, 이를 통해 프로젝트의 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 연동 기능 개발