X-Reach Welder HMI UI의 Linux Qt6 포팅 개발 계획서 — 멀티 에이전트 분업 및 단계별 실행 로드맵

작성: Antigravity (Google DeepMind Team)
공동저자: Moojoco
타겟 환경: Linux (Ubuntu x86_64, Qt 6.9.2, CMake, C++17/20, OpenGL)
일자: 2026년 8월 21일

1. 개요 및 포팅 목적 (Overview & Goals)

1.1 배경 및 목적

• 현황: 기존 X-Reach Welder HMI UI 시스템은 .NET Framework 4.8 / WPF로 구현되어 있어 Windows OS 종속적이며, Linux 기반 산업용 제어 PC에서 직접 실행 및 렌더링이 불가능함.
• 목표: Linux 환경에서 네이티브로 실행 가능한 C++ Qt 6.9 (CMake 기반) 기반의 고성능·저지연 크로스플랫폼 HMI UI 시스템으로 재구축.
• 핵심 이식 대상:
• 1280×800 해상도 산업용 다크 HMI 메인 인터페이스 및 터치 UX
• HelixToolkit.Wpf 기반 6축 로봇 키네마틱스 & STL 모재 3D 뷰포트 -> QOpenGLWidget / OpenGL Shaders
• ROS 로봇 제어기 비동기 통신 브리지 (TCP Port 55000) -> QTcpServer / QTcpSocket
• Fronius 용접기 Base64 JSON 텔레메트리 디코더 및 엣지 알람 상태 머신 -> QJsonDocument & Event Dispatcher
• JSON 기반 Job 저장/불러오기 및 파라미터 제어 파이프라인

2. 멀티 에이전트 분업 아키텍처 (Multi-Agent Division of Labor)

단일 에이전트의 컨텍스트 토큰 고갈 및 세션 단절 리스크를 원천 차단하기 위해, 각 에이전트의 고유 전문성을 기반으로 4대 작업 영역을 분할하고 독립 인터페이스(JSON/헤더 명세)를 통해 협업한다.

graph TD
    subgraph Agent_Aegis["[ Aegis (시스템 코어 & 3D OpenGL) ]"]
        style Agent_Aegis fill:#1e293b,stroke:#3b82f6,color:#fff
        A1["CMake 프로젝트 빌드 구조 구축"]
        A2["QOpenGLWidget 3D 로봇 뷰포트 구현"]
        A3["6축 순운동학(FK) & STL 메시 로더"]
    end

    subgraph Agent_Moojoco["[ Moojoco (HMI UI & 터치 위젯) ]"]
        style Agent_Moojoco fill:#1e293b,stroke:#10b981,color:#fff
        M1["MainWindow QMainWindow 레이아웃 구현"]
        M2["작업 리스트(QTableView) & 파라미터 패널"]
        M3["가상 키패드 및 다크 스타일시트(QSS)"]
    end

    subgraph Agent_Hermes["[ Hermes (통신 & 하드웨어 텔레메트리) ]"]
        style Agent_Hermes fill:#1e293b,stroke:#f59e0b,color:#fff
        H1["QTcpServer ROS Bridge (Port 55000)"]
        H2["Fronius Status Alarm Tracker 디코더"]
        H3["E-Stop / Protective Stop 안전 핸들러"]
    end

    subgraph Agent_Antigravity["[ Antigravity (총괄 통합 & 검증) ]"]
        style Agent_Antigravity fill:#1e293b,stroke:#a855f7,color:#fff
        AN1["전체 인터페이스 통합 및 신호(Signal/Slot) 연결"]
        AN2["실행 검증 및 스트레스 테스트"]
        AN3["최종 결과 보고서 작성 및 thesis 배포"]
    end

    Agent_Aegis -->|3D Viewport 위젯 제공| Agent_Antigravity
    Agent_Moojoco -->|UI 컨트롤 & 다이얼로그 제공| Agent_Antigravity
    Agent_Hermes -->|통신/알람 코어 라이브러리 제공| Agent_Antigravity
    Agent_Antigravity -->|빌드/실행 및 통합 검증| TargetApp["X-Reach Welder Qt6 Binary"]

에이전트별 상세 R&R (Roles & Responsibilities)

3. 단계별 상세 실행 일정 (Phased Milestone Roadmap)

총 4단계(Stage 1 ~ Stage 4)로 구성하며, 각 단계 완료 시 산출물 빌드 및 독립 검증을 통과해야 다음 단계로 진입한다.

gantt
    title X-Reach Welder Qt6 포팅 프로젝트 로드맵
    dateFormat  YYYY-MM-DD
    section Stage 1 - 골격 및 인터페이스
    CMake 환경 구성 및 Qt6 기본 골격       :done, s1_1, 2026-08-21, 1d
    공통 데이터 모델 및 시그널 인터페이스 정의 :done, s1_2, 2026-08-21, 1d
    section Stage 2 - 병렬 모듈 구현
    Aegis - 3D QOpenGLWidget 및 STL 로더   :active, s2_1, 2026-08-22, 2d
    Moojoco - 메인 HMI UI 및 작업 리스트   :active, s2_2, 2026-08-22, 2d
    Hermes - ROS TCP Server 및 알람 엔진  :active, s2_3, 2026-08-22, 2d
    section Stage 3 - 통합 연동 및 시그널 결합
    모듈 통합 빌드 및 Signal-Slot 결합   :s3_1, 2026-08-24, 2d
    E-Stop 및 실시간 텔레메트리 루프 테스트 :s3_2, 2026-08-25, 1d
    section Stage 4 - 실환경 검증 및 배포
    Linux GUI 창 실행 검증 (DISPLAY 0번)  :s4_1, 2026-08-26, 1d
    성능 측정 (60 FPS 렌더링, CPU 점유율) :s4_2, 2026-08-26, 1d
    최종 보고서 작성 및 thesis 등록       :s4_3, 2026-08-27, 1d

Stage 1: 프로젝트 뼈대 및 공통 인터페이스 규격화 (D-Day)

• 목표: 독립 컴파일이 가능한 CMake 모듈 분할 및 공통 헤더(CommonTypes.h) 확정.
• 주요 작업:
• CMakeLists.txt 작성 (Qt6 Core, Gui, Widgets, OpenGL, Network, Concurrent 연결).
• JobItem, WeldParameters, AlarmEvent 등 핵심 C++ 구조체 정의.
• 검증 기준: 빈 메인 윈도우 생성 및 cmake --build 성공.

Stage 2: 3대 핵심 서브시스템 독립 구현 (D+1 ~ D+2)

• Aegis 파트:
• C++ OpenGL 쉐이더 파이프라인 및 두산 로봇 STL 링크 순운동학 행렬 연산 구현.
• Rapid/Weld 경로 3D 라인 렌더링 및 TCP 궤적 버퍼링.
• Moojoco 파트:
• 1280×800 해상도 메인 윈도우 QSS 다크 테마 적용.
• 조그/팬던트 제어 버튼 및 작업 리스트 QTableView 모델 바인딩.
• Hermes 파트:
• QTcpServer 포트 55000 리스너 및 패킷 시퀀스 트래커 구현.
• Base64 JSON 디코더 및 엣지 트리거 알람 상태 머신 구현.

Stage 3: 시스템 통합 및 Signal/Slot 이벤트 연동 (D+3 ~ D+4)

• 목표: 3대 에이전트 산출물을 main.cpp 및 MainWindow 컨트롤러에 결합.
• 주요 작업:
• 로봇 조그 버튼 클릭 시 -> RosMotionProxy 명령 송신 -> 가상 모션 피드백 -> Robot3DViewport 관절각 갱신.
• 용접기 알람 발생 시 -> EmergencyStopDialog 모달 팝업 및 안전 정지 트리거.
• 검증 기준: Mock 텔레메트리 스트림 주입 시 UI 수치 변경 및 3D 로봇 동기화 확인.

Stage 4: Linux 런타임 실측 검증 및 배포 (D+5 ~ D+6)

• 목표: Linux 네이티브 GUI 실행, 성능 벤치마크 및 최종 배포.
• 주요 작업:
• DISPLAY=:0 환경에서 GUI 렌더링 60 FPS 유지 및 CPU 점유율 최적화.
• build_verify 스크립트를 통한 1-Click 자동 빌드 환경 구성.
• 최종 완료 보고서 작성 및 thesis 등록.

4. 장애 대응 및 토큰 세션 분실 방지 수칙 (Fail-safe Protocol)

1. 원자적 커밋 및 모듈 격리:
2. 각 에이전트는 담당 모듈을 단일 독립 폴더(src/ui/, src/gl3d/, src/network/)에 작성하여 파일 충돌 방지.
3. 명세 기반 핸드오프 (Specification-driven Handoff):
4. 에이전트 교체 시 이전 컨텍스트 전체를 읽을 필요 없이, 공통 헤더 파일(CommonTypes.h)과 CMake 타깃 정보만 참조하여 즉시 작업 승계.
5. 증분 검증 (Incremental Verification):
6. 모듈 단위 단위 테스트(ctest)를 통해 단계별 성공 여부를 확인한 후 통합.

5. 결론 (Conclusion)

본 개발 계획서는 WPF에 종속되어 있던 X-Reach Welder HMI 시스템을 오픈 표준 기술인 C++ Qt6로 이식하여 Linux 환경에서의 완벽한 실시간성 및 확장성을 확보하기 위한 청사진이다. 4대 에이전트 분업 체계를 통해 토큰 한계를 극복하고 빠르고 견고하게 완성을 달성할 것이다.