# CLAUDE.md (AGVLogic 폴더)

이 파일은 AGVLogic 폴더에서 개발 중인 AGV 관련 프로젝트들을 위한 개발 가이드입니다.

**현재 폴더 위치**: `C:\Data\Source\(5613#) ENIG AGV\Source\Cs_HMI\AGVLogic\`
**맵데이터**: `../Data/NewMap.agvmap` 파일을 기준으로 사용

---

## 프로젝트 개요

현재 AGVLogic 폴더에서 다음 3개의 독립 프로젝트를 개발 중입니다:

### 1. AGVMapEditor (맵 에디터)
**위치**: `./AGVMapEditor/`
**실행파일**: `./AGVMapEditor/bin/Debug/AGVMapEditor.exe`

#### 핵심 기능
- **맵 노드 관리**: 논리적 노드 생성, 연결, 속성 설정
- **RFID 매핑**: 물리적 RFID ID ↔ 논리적 노드 ID 매핑
- **시각적 편집**: 드래그앤드롭으로 노드 배치 및 연결
- **JSON 저장**: 맵 데이터를 JSON 형식으로 저장/로드
- **노드 연결 관리**: 연결 목록 표시 및 직접 삭제 기능

#### 핵심 클래스
- **MapNode**: 논리적 맵 노드 (NodeId, 위치, 타입, 연결 정보)
- **RfidMapping**: RFID 물리적 ID ↔ 논리적 노드 ID 매핑
- **NodeResolver**: RFID ID를 통한 노드 해석기
- **MapCanvas**: 시각적 맵 편집 컨트롤

### 2. AGVNavigationCore (경로 탐색 라이브러리)
**위치**: `./AGVNavigationCore/`

#### 핵심 기능
- **A* 경로 탐색**: 최적 경로 계산 알고리즘
- **방향 제어**: 전진/후진 모터 방향 결정
- **도킹 검증**: 충전기/장비 도킹 방향 검증
- **리프트 계산**: AGV 리프트 각도 계산
- **경로 최적화**: 회전 구간 회피 등 고급 옵션

#### 핵심 클래스
- **PathFinding/Core/AStarPathfinder.cs**: A* 알고리즘 구현
- **PathFinding/Planning/AGVPathfinder.cs**: 경로 탐색 메인 클래스
- **PathFinding/Planning/DirectionChangePlanner.cs**: 방향 변경 계획
- **Utils/LiftCalculator.cs**: 리프트 각도 계산
- **Utils/DockingValidator.cs**: 도킹 유효성 검증
- **Controls/UnifiedAGVCanvas.cs**: 맵 및 AGV 시각화

### 3. AGVSimulator (AGV 시뮬레이터)
**위치**: `./AGVSimulator/`
**실행파일**: `./AGVSimulator/bin/Debug/AGVSimulator.exe`

#### 핵심 기능
- **가상 AGV 시뮬레이션**: 실시간 AGV 움직임 및 상태 관리
- **맵 시각화**: 맵 에디터에서 생성한 맵 파일 로드 및 표시
- **경로 실행**: 계산된 경로를 따라 AGV 시뮬레이션
- **상태 모니터링**: AGV 상태, 위치, 배터리 등 실시간 표시

#### 핵심 클래스
- **VirtualAGV**: 가상 AGV 동작 시뮬레이션 (이동, 회전, 도킹, 충전)
- **SimulatorCanvas**: AGV 및 맵 시각화 캔버스
- **SimulatorForm**: 시뮬레이터 메인 인터페이스
- **SimulationState**: 시뮬레이션 상태 관리

#### AGV 상태
- **Idle**: 대기
- **Moving**: 이동 중
- **Rotating**: 회전 중
- **Docking**: 도킹 중
- **Charging**: 충전 중
- **Error**: 오류

---

## AGV 방향 제어 및 도킹 시스템

### AGV 하드웨어 레이아웃
```
LIFT --- AGV --- MONITOR
  ↑       ↑        ↑
후진시   AGV본체   전진시
도달위치          도달위치
```

### 모터 방향과 이동 방향
- **전진 모터 (Forward)**: AGV가 모니터 방향으로 이동 (→)
- **후진 모터 (Backward)**: AGV가 리프트 방향으로 이동 (←)

### 도킹 방향 규칙
- **충전기 (Charging)**: 전진 도킹 (Forward) - 모니터가 충전기 면
- **장비 (Docking)**: 후진 도킹 (Backward) - 리프트가 장비 면

### 핵심 계산 파일들
1. **LiftCalculator.cs** - 리프트 방향 계산
   - `CalculateLiftAngleRadians(Point currentPos, Point targetPos, AgvDirection motorDirection)`

2. **DirectionChangePlanner.cs** - 도킹 방향 결정
   - `GetRequiredDockingDirection(string targetNodeId)` - 노드타입별 도킹 방향 반환

3. **VirtualAGV.cs** - AGV 위치/방향 관리
   - `SetPosition(Point newPosition)` - AGV 위치 및 방향 설정

---

## AGVNavigationCore 프로젝트 구조

### 📁 폴더 구조
```
AGVNavigationCore/
├── Controls/
│   ├── UnifiedAGVCanvas.cs          # AGV 및 맵 시각화 메인 캔버스
│   ├── UnifiedAGVCanvas.Events.cs   # 그리기 및 이벤트 처리
│   ├── UnifiedAGVCanvas.Mouse.cs    # 마우스 인터랙션
│   ├── AGVState.cs                  # AGV 상태 정의
│   └── IAGV.cs                      # AGV 인터페이스
│
├── Models/
│   ├── MapNode.cs                   # 맵 노드 데이터 모델
│   ├── MapLoader.cs                 # JSON 맵 파일 로더
│   └── Enums.cs                     # 열거형 정의 (NodeType, AgvDirection 등)
│
├── Utils/
│   ├── LiftCalculator.cs            # 리프트 각도 계산
│   └── DockingValidator.cs          # 도킹 유효성 검증
│
└── PathFinding/
    ├── Analysis/
    │   └── JunctionAnalyzer.cs      # 교차점 분석
    │
    ├── Core/
    │   ├── AStarPathfinder.cs        # A* 알고리즘
    │   ├── PathNode.cs              # 경로 노드
    │   └── AGVPathResult.cs          # 경로 계산 결과
    │
    ├── Planning/
    │   ├── AGVPathfinder.cs          # 경로 탐색 메인 클래스
    │   ├── AdvancedAGVPathfinder.cs  # 고급 경로 탐색
    │   ├── DirectionChangePlanner.cs # 방향 변경 계획
    │   ├── NodeMotorInfo.cs          # 노드별 모터 정보
    │   └── PathfindingOptions.cs     # 경로 탐색 옵션
    │
    └── Validation/
        ├── DockingValidationResult.cs # 도킹 검증 결과
        └── PathValidationResult.cs    # 경로 검증 결과
```

### 🎯 클래스 배치 원칙

#### PathFinding/Validation/
- **검증 결과 클래스**: `*ValidationResult.cs` 패턴 사용
- **패턴**: 정적 팩토리 메서드 (CreateValid, CreateInvalid, CreateNotRequired)
- **속성**: IsValid, ValidationError, 관련 상세 정보

#### PathFinding/Planning/
- **경로 계획 클래스**: 실제 경로 탐색 및 계획 로직
- **방향 변경 로직**: DirectionChangePlanner.cs
- **경로 최적화**: 경로 생성과 관련된 전략

#### PathFinding/Core/
- **핵심 알고리즘**: A* 알고리즘 등 기본 경로 탐색
- **기본 경로 탐색**: 단순한 점-to-점 경로 계산

#### PathFinding/Analysis/
- **경로 분석**: 생성된 경로의 품질 및 특성 분석
- **성능 분석**: 경로 효율성 및 최적화 분석

---

## 개발 워크플로우

### 권장 개발 순서
1. **맵 데이터 준비**: AGVMapEditor로 맵 노드 배치 및 RFID 매핑 설정
2. **경로 탐색 구현**: AGVNavigationCore에서 경로 계산 알고리즘 개발
3. **시뮬레이션 테스트**: AGVSimulator로 AGV 동작 검증
4. **메인 프로젝트 통합**: 개발 완료 후 부모 폴더(Cs_HMI)에 병합

### 중요한 개발 패턴
- **이벤트 기반 아키텍처**: UI 업데이트는 이벤트를 통해 자동화
- **상태 관리**: _hasChanges 플래그로 변경사항 추적
- **에러 처리**: 사용자 확인 다이얼로그와 상태바 메시지 활용
- **코드 재사용**: UnifiedAGVCanvas를 맵에디터와 시뮬레이터에서 공통 사용

### 주의사항
- **PathFinding 로직 변경시**: 반드시 시뮬레이터에서 테스트 후 적용
- **노드 연결 관리**: 물리적 RFID와 논리적 노드 ID 분리 원칙 유지
- **JSON 파일 형식**: 맵 데이터는 MapNodes, RfidMappings 두 섹션으로 구성
- **좌표 시스템**: 줌/팬 상태에서 좌표 변환 정확성 지속 모니터링

---

## 최근 구현 완료 기능

### ✅ 회전 구간 회피 기능 (PathFinding)
- **목적**: AGV 회전 오류를 피하기 위한 선택적 회전 구간 회피
- **파일**: `PathFinding/PathfindingOptions.cs`
- **UI**: AGVSimulator에 "회전 구간 회피" 체크박스

### ✅ 맵 에디터 마우스 좌표 오차 수정
- **문제**: 줌 인/아웃 시 노드 선택 히트 영역이 너무 작음
- **해결**: 최소 화면 히트 영역(20픽셀) 보장
- **파일**: `AGVNavigationCore/Controls/UnifiedAGVCanvas.Mouse.cs`

### ✅ 노드 연결 관리 시스템
- **기능**: 노드 연결 목록 표시 및 삭제
- **파일들**:
  - `AGVMapEditor/Forms/MainForm.cs` - UI 및 이벤트 처리
  - `UnifiedAGVCanvas.cs` - 편집 모드 및 이벤트 정의
  - `UnifiedAGVCanvas.Mouse.cs` - 마우스 연결 삭제 기능

---

## 향후 개발 우선순위

1. **방향 전환 기능**: AGV 현재 방향과 목표 방향 불일치 시 회전 노드 경유 로직
2. **맵 검증 기능**: 연결 무결성, 고립된 노드, 순환 경로 등 검증
3. **성능 최적화**: 대형 맵에서 경로 계산 및 연결 목록 표시 성능 개선
4. **실시간 동기화**: 맵 에디터와 시뮬레이터 간 실시간 맵 동기화

---

**최종 업데이트**: 2025-10-23 - AGVLogic 폴더 기준으로 정리