refactor: PathFinding 폴더 구조 개선 및 도킹 에러 기능 추가

- PathFinding 폴더를 Core, Validation, Planning, Analysis로 세분화 - 네임스페이스 정리 및 using 문 업데이트 - UnifiedAGVCanvas에 SetDockingError 메서드 추가 - 도킹 검증 시스템 인프라 구축 - DockingValidator 유틸리티 클래스 추가 - 빌드 오류 수정 및 안정성 개선 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-16 14:46:53 +09:00
parent debbf712d4
commit ef72b77f1c
37 changed files with 1085 additions and 2796 deletions
--- a/Cs_HMI/AGVNavigationCore/README.md
+++ b/Cs_HMI/AGVNavigationCore/README.md
@@ -1,225 +1,155 @@
-# AGVNavigationCore 프로젝트 기능 설명
+# AGVNavigationCore
+
+ENIG AGV 시스템을 위한 핵심 네비게이션 및 경로 탐색 라이브러리

 ## 📋 개요
-AGVNavigationCore는 AGV(Automated Guided Vehicle) 시스템을 위한 전문적인 경로 계산 및 네비게이션 라이브러리입니다. 실제 AGV의 물리적 제약사항과 운영 요구사항을 고려한 지능형 경로 탐색 기능을 제공합니다.

-## 🏗️ 핵심 구조
+AGVNavigationCore는 자동 유도 차량(AGV) 시스템의 경로 계획, 맵 편집, 시뮬레이션, 실시간 모니터링 기능을 제공하는 .NET Framework 4.8 라이브러리입니다.

-### **Models 패키지**
- **MapNode**: 맵의 논리적 노드 정보 (위치, 타입, 연결 정보, RFID 매핑)
- **RfidMapping**: RFID와 논리적 노드 ID 간의 매핑 정보
- **Enums**: 노드 타입, AGV 방향, 도킹 방향, 장비 타입 등 열거형 정의
+## 🏗️ 프로젝트 구조

-### **PathFinding 패키지**
-경로 계산의 핵심 엔진들이 포함된 패키지
+### 📁 Controls/
+**AGV 관련 사용자 인터페이스 컨트롤 및 AGV 추상화 계층**
+
+- **AGVState.cs** - AGV 상태 열거형 (Idle, Moving, Rotating, Docking, Charging, Error)
+- **IAGV.cs** - AGV 인터페이스 정의 (가상/실제 AGV 통합)
+- **UnifiedAGVCanvas.cs** - 통합 AGV 캔버스 컨트롤 메인 클래스
+- **UnifiedAGVCanvas.Events.cs** - 그리기 및 렌더링 로직 (AGV, 노드, 경로 시각화)
+- **UnifiedAGVCanvas.Mouse.cs** - 마우스 이벤트 처리 (클릭, 드래그, 줌, 팬)
+
+### 📁 Models/
+**데이터 모델 및 핵심 비즈니스 엔티티 정의**
+
+- **Enums.cs** - 핵심 열거형 정의 (NodeType, DockingDirection, AgvDirection, StationType)
+- **MapNode.cs** - 맵 노드 엔티티 클래스 (논리적 노드 ID, 위치, 타입, 연결 정보, RFID 정보)
+- **MapLoader.cs** - 맵 파일 로딩/저장 유틸리티 (JSON 직렬화, 데이터 마이그레이션, 검증)
+
+### 📁 PathFinding/
+**AGV 경로 탐색 및 계산 알고리즘**
+
+#### 🟢 활발히 사용되는 클래스
+- **AGVPathfinder.cs** - 메인 AGV 경로 계획기 (물리적 제약사항 고려)
+- **AGVPathResult.cs** - 경로 계산 결과 데이터 클래스
+- **DockingValidationResult.cs** - 도킹 검증 결과 데이터 클래스
+
+#### 🟡 내부 구현 클래스
+- **AStarPathfinder.cs** - A* 알고리즘 기반 기본 경로 탐색
+- **DirectionChangePlanner.cs** - AGV 방향 전환 경로 계획 시스템
+- **JunctionAnalyzer.cs** - 교차점 분석 및 마그넷 센서 방향 계산
+- **NodeMotorInfo.cs** - 노드별 모터방향 정보 (방향 전환 지원 포함)
+- **PathNode.cs** - A* 알고리즘용 경로 노드
+
+### 📁 Utils/
+**유틸리티 및 계산 헬퍼 클래스**
+
+- **DockingValidator.cs** - AGV 도킹 방향 검증 유틸리티
+- **LiftCalculator.cs** - AGV 리프트 방향 계산 유틸리티
+
+### 📁 Properties/
+- **AssemblyInfo.cs** - 어셈블리 정보 및 버전 관리

 ## 🎯 주요 기능

-### 1. **기본 경로 탐색 (A* 알고리즘)**
+### 🗺️ 맵 관리
+- **논리적 노드 시스템**: 물리적 RFID와 분리된 논리적 노드 ID 관리
+- **노드 타입**: Normal, Rotation, Docking, Charging 등 다양한 노드 타입 지원
+- **연결 관리**: 노드 간 방향성 연결 관리
+- **JSON 저장/로드**: 표준 JSON 형식으로 맵 데이터 관리

-**AStarPathfinder 클래스**:
- 표준 A* 알고리즘 구현으로 최적 경로 탐색
- 유클리드 거리 기반 휴리스틱 사용
- 설정 가능한 파라미터:
-  - `HeuristicWeight`: 휴리스틱 가중치 (기본 1.0)
-  - `MaxSearchNodes`: 최대 탐색 노드 수 (기본 1000개)
+### 🧭 경로 탐색
+- **A* 알고리즘**: 효율적인 최단 경로 탐색
+- **AGV 물리적 제약**: 전진/후진 모터 방향, 회전 제약 고려
+- **방향 전환 계획**: 마그넷 센서 위치에서의 방향 전환 최적화
+- **도킹 검증**: 목적지 타입에 따른 도킹 방향 검증

-**제공 기능**:
-```csharp
-// 단일 경로 탐색
-PathResult FindPath(string startNodeId, string endNodeId)
+### 🎮 시각화 및 편집
+- **통합 캔버스**: 맵 편집, 시뮬레이션, 모니터링 모드 지원
+- **실시간 렌더링**: AGV 위치, 경로, 상태 실시간 표시
+- **인터랙티브 편집**: 드래그앤드롭 노드 편집, 연결 관리
+- **줌/팬**: 대형 맵 탐색을 위한 줌/팬 기능

-// 다중 목표 중 최단 경로 탐색
-PathResult FindNearestPath(string startNodeId, List<string> targetNodeIds)
+## 🔧 아키텍처 특징

-// 노드 연결 상태 확인
-bool AreNodesConnected(string nodeId1, string nodeId2)
-```
+### ✅ 장점
+- **계층화 아키텍처**: Models → Utils → PathFinding → Controls 의존성 구조
+- **관심사 분리**: 각 폴더별 명확한 책임 분담
+- **인터페이스 기반**: IAGV 인터페이스로 가상/실제 AGV 통합
+- **확장성**: 새로운 알고리즘, AGV 타입 추가 용이

-### 2. **AGV 전용 지능형 경로 계산**
-
-**AGVPathfinder 클래스**:
-AGV의 실제 움직임 제약사항을 고려한 전문 경로 계산기
-
-**AGV 제약사항 고려**:
- **방향성 제약**: 전진/후진만 가능, 좌우 이동 불가
- **회전 제약**: 특정 노드(회전 가능 지점)에서만 180도 회전 가능
- **도킹 방향**: 
-  - 충전기: 전진 도킹만 가능
-  - 장비 (로더, 클리너 등): 후진 도킹만 가능
-
-**전용 기능**:
-```csharp
-// AGV 경로 계산 (방향성 고려)
-AGVPathResult FindAGVPath(string startNodeId, string endNodeId, AgvDirection? targetDirection)
-
-// 가장 가까운 충전소 경로
-AGVPathResult FindPathToChargingStation(string startNodeId)
-
-// 특정 장비 타입 도킹 스테이션 경로
-AGVPathResult FindPathToDockingStation(string startNodeId, StationType stationType)
-```
-
-### 3. **RFID 기반 경로 계산 (실제 운영용)**
-
-**RfidBasedPathfinder 클래스**:
-실제 AGV가 RFID를 읽어서 위치를 파악하는 현장 운영 방식에 최적화
-
-**RFID 기반 제약사항**:
- **물리적 RFID**: 의미 없는 고유 식별자 (현장 유지보수 편의성)
- **논리적 매핑**: RFID ↔ NodeId 분리로 맵 변경 시 유연성 확보
- **실시간 변환**: RFID 입력을 내부적으로 NodeId로 변환하여 처리
-
-**RFID 전용 기능**:
-```csharp
-// RFID 기반 AGV 경로 계산
-RfidPathResult FindAGVPath(string startRfidId, string endRfidId, AgvDirection? targetDirection)
-
-// RFID 기반 충전소 경로
-RfidPathResult FindPathToChargingStation(string startRfidId)
-
-// RFID 기반 도킹 스테이션 경로
-RfidPathResult FindPathToDockingStation(string startRfidId, StationType stationType)
-
-// RFID 매핑 관리
-RfidMapping GetRfidMapping(string rfidId)
-string GetNodeIdByRfid(string rfidId)
-string GetRfidByNodeId(string nodeId)
-```
-
-### 4. **상세한 결과 분석**
-
-**PathResult (기본 결과)**:
- 성공/실패 여부
- 노드 ID 시퀀스
- 총 거리 및 계산 시간
- 탐색한 노드 수
-
-**AGVPathResult (AGV 전용 결과)**:
- **실행 가능한 명령어 시퀀스**: `[전진, 전진, 우회전, 후진, 정지]`
- **상세 메트릭**:
-  - 회전 횟수 계산
-  - 예상 소요 시간 (이동 + 회전 시간)
-  - 명령어 요약 (`전진×3 → 우회전×1 → 후진×2`)
-
-**RfidPathResult (RFID 기반 결과)**:
- **RFID 경로 시퀀스**: `[RFID001, RFID045, RFID067, RFID123]`
- **AGV 명령어**: NodeId 기반 결과와 동일한 명령어 시퀀스
- **현장 친화적 정보**:
-  - RFID 경로 요약 (`RFID001 → ... (2개 경유) → RFID123`)
-  - 실행 정보 (`[실행준비] → [명령어] → [예상시간]`)
-  - 운영자용 상세 정보
-
-### 5. **실시간 검증 및 최적화**
-
-**경로 검증**:
-```csharp
-// 경로 유효성 실시간 검증
-bool ValidatePath(List<string> path)
-
-// 네비게이션 가능 노드 필터링 (라벨/이미지 노드 제외)
-List<string> GetNavigationNodes()
-```
-
-**성능 최적화**:
- 메모리 효율적인 노드 관리
- 조기 종료 조건으로 불필요한 탐색 방지
- 캐시된 거리 계산
-
-## 🔧 설정 가능한 파라미터
-
-**AGV 동작 파라미터**:
- `CurrentDirection`: AGV 현재 방향
- `RotationCostWeight`: 회전 비용 가중치 (기본 50.0)
- `DockingApproachDistance`: 도킹 접근 거리 (기본 100픽셀)
-
-**알고리즘 파라미터**:
- `HeuristicWeight`: A* 휴리스틱 강도
- `MaxSearchNodes`: 탐색 제한으로 무한루프 방지
-
-**RFID 매핑 파라미터**:
- `RfidMappings`: RFID ↔ NodeId 매핑 테이블
- `IsActive`: 매핑 활성화 상태
- `Status`: RFID 상태 (정상, 손상, 교체예정)
-
-## 🎯 실제 활용 시나리오
-
-### **시나리오 1: 일반 이동 (NodeId 기반)**
-```
-현재위치(N001) → 목적지(N010)
-결과: [N001, N003, N007, N010] + [전진, 전진, 전진]
-```
-
-### **시나리오 2: 일반 이동 (RFID 기반)**
-```
-현재위치(RFID123) → 목적지(RFID789)
-결과: [RFID123, RFID456, RFID789] + [전진, 우회전, 전진]
-AGV는 RFID를 읽으면서 실제 위치 확인 후 이동
-```
-
-### **시나리오 3: 충전 필요**
-```
-배터리 부족 → 가장 가까운 충전소 자동 탐색
-결과: 충전소까지 최단경로 + 전진 도킹 명령어
-```
-
-### **시나리오 4: 화물 적재**
-```
-로더 스테이션 접근 → 후진 도킹 필수
-결과: 로더까지 경로 + 후진 도킹 시퀀스
-```
-
-## 🌟 차별화 포인트
-
-1. **실제 AGV 제약사항 반영**: 이론적 경로가 아닌 실행 가능한 경로 제공
-2. **명령어 레벨 출력**: 경로뿐만 아니라 실제 AGV 제어 명령어 생성
-3. **RFID 기반 현장 운영**: 물리적 RFID와 논리적 노드 분리로 현장 유지보수성 향상
-4. **다양한 장비 지원**: 충전기, 로더, 클리너, 버퍼 등 각각의 도킹 요구사항 처리
-5. **이중 API 제공**: NodeId 기반(개발용) + RFID 기반(운영용) 동시 지원
-6. **확장성**: 새로운 AGV 타입이나 제약사항 쉽게 추가 가능
-7. **성능 최적화**: 실시간 운영에 적합한 빠른 응답속도
+### ⚠️ 개선 영역
+- **코드 크기**: 일부 클래스가 과도하게 큼 (UnifiedAGVCanvas.Events.cs: 1,699행)
+- **복잡도**: DirectionChangePlanner 등 복잡한 로직 포함
+- **분할 필요**: UnifiedAGVCanvas의 다중 책임 분리 필요

 ## 🚀 사용 방법

-### 기본 사용법
+### 기본 맵 로딩
+```csharp
+var mapLoader = new MapLoader();
+var mapNodes = mapLoader.LoadMap("path/to/map.json");
+```
+
+### 경로 계산
 ```csharp
-// 1. 경로 탐색기 초기화
 var pathfinder = new AGVPathfinder();
 pathfinder.SetMapNodes(mapNodes);

-// 2. AGV 경로 계산
-var result = pathfinder.FindAGVPath("N001", "N010");
-
-// 3. 결과 확인
+var result = pathfinder.FindPath("START_NODE", "TARGET_NODE", AgvDirection.Forward);
 if (result.Success)
 {
-    Console.WriteLine($"경로: {string.Join(" → ", result.Path)}");
-    Console.WriteLine($"명령어: {result.GetCommandSummary()}");
-    Console.WriteLine($"예상시간: {result.EstimatedTimeSeconds}초");
+    Console.WriteLine($"경로: {string.Join(" -> ", result.Path)}");
+    Console.WriteLine($"거리: {result.TotalDistance:F1}px");
 }
 ```

-### 충전소 경로 탐색
+### 캔버스 사용
 ```csharp
-var chargingResult = pathfinder.FindPathToChargingStation("N001");
-if (chargingResult.Success)
-{
-    // 충전소까지 자동 이동
-    ExecuteAGVCommands(chargingResult.Commands);
-}
+var canvas = new UnifiedAGVCanvas();
+canvas.Nodes = mapNodes;
+canvas.CurrentPath = result;
+canvas.CurrentEditMode = UnifiedAGVCanvas.EditMode.Select;
 ```

+## 📈 최근 업데이트 (2024.12)
+
+### ✅ 완료된 개선사항
+- **중복 코드 정리**: PathResult, RfidPathResult 등 중복 클래스 제거
+- **아키텍처 통합**: AdvancedAGVPathfinder → AGVPathfinder 통합
+- **좌표 정확성**: 줌/팬 시 노드 선택 정확도 개선
+- **미사용 코드 제거**: PathfindingOptions 등 미사용 클래스 삭제
+
+### 🔄 진행 중인 개선사항
+- **방향 계산 최적화**: 리프트 방향 계산 로직 개선
+- **도킹 검증**: 도킹 방향 검증 시스템 강화
+- **성능 최적화**: 대형 맵 처리 성능 개선
+
+## 🏃‍♂️ 향후 계획
+
+### 우선순위 1 (즉시)
+- UnifiedAGVCanvas 분할 (Rendering, Editing, Simulation 분리)
+- [완료] PathFinding 폴더 세분화 (Core, Validation, Planning, Analysis)
+
+### 우선순위 2 (중기)
+- 인터페이스 표준화 (I접두사 통일)
+- Utils 폴더 확장 (Calculations, Validators, Converters)
+
+### 우선순위 3 (장기)
+- 의존성 주입 도입
+- 성능 모니터링 시스템
+- 단위 테스트 확충
+
 ## 📦 의존성
 - .NET Framework 4.8
 - Newtonsoft.Json 13.0.3
 - System.Drawing
+- System.Windows.Forms

-## 🔗 통합 프로젝트
-이 라이브러리는 다음 프로젝트에서 사용됩니다:
- **AGVMapEditor**: 맵 편집 및 경로 시뮬레이션
- **AGV4**: 메인 AGV 제어 시스템
- **AGVSimulator**: AGV 동작 시뮬레이터
+## 🔗 관련 프로젝트

---
+- **AGVMapEditor**: 맵 편집 전용 애플리케이션
+- **AGVSimulator**: AGV 시뮬레이션 애플리케이션
+- **AGVCSharp**: 메인 AGV 제어 시스템

-*AGVNavigationCore는 ENIG AGV 시스템의 핵심 네비게이션 엔진입니다.*
+## 📞 연락처
+
+ENIG AGV 개발팀 - 2024년 12월 업데이트