ENIG/Cs_HMI/AGVLogic/CLAUDE.md

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 폴더 기준으로 정리