로봇 커스텀 데모는 프로젝트를 수용하기 불가능한 상태에서도 작동할 수 있습니다.

SDK 명령이 로봇을 움직입니다. ROS 2 토픽이 센서 데이터를 발행합니다. 대시보드가 작업 상태를 대기 중(queued)에서 실행 중(running)으로 변경합니다. 하지만 이러한 관찰 결과 중 그 어느 것도 통합된 시스템이 재현(reproduced), 복구(recovered), 감사(audited), 업그레이드(upgraded)되거나 안전하게 운영(operated safely)될 수 있음을 입증하지는 못합니다.

따라서 구매자에게 맞춤형 로봇 개발의 단위는 스크린샷 모음이나 일회성 데모가 아니라, **명시적인 인터페이스 계약(interface contract), 실패 동작(failure behavior), 인수 증거(acceptance evidence) 및 지원 범위(support boundary)를 갖춘 버전 관리된 기능(versioned capability)**이어야 합니다.

이 체크리스트는 로봇 소프트웨어, SDK 및 ROS 2 통합, 인지(perception) 또는 AI 기능, 페이로드 제어(payload control), 비즈니스 시스템 연결성, 또는 현장 대표 증명(representative-site proof of concept)을 의뢰하는 팀을 위한 것입니다.

GUMA Robot Studio product interface showing point-cloud mapping, route points, robot status and task selection.

GUMA 제품 인터페이스 참조 자료입니다. 이는 고객 사이트, 실제 고객 데이터, 완료된 로봇 통합의 증거 또는 보장된 인도 결과가 아닙니다.

1. 정확한 버전 인벤토리 동결 (Freeze the exact version inventory)

제품군 이름 이상의 것을 기록하십시오. 유용한 기준점에는 다음이 포함됩니다:

• 로봇 모델, 하드웨어 에디션 및 설치된 페이로드(payloads);
• 컨트롤러, 펌웨어(firmware) 및 벤더 애플리케이션 버전;
• SDK, ROS 배포판(distribution), 미들웨어(middleware) 및 메시지 정의(message definitions);
• 운영 체제(operating system), 아키텍처(architecture), GPU 또는 가속기(accelerator), 드라이버 및 런타임(runtime);
• 어댑터(adapter), 애플리케이션, 모델 및 구성(configuration) 리비전;
• 지도(map), 캘리브레이션(calibration), 작업 및 비즈니스 인터페이스 스키마(schema) 버전.

버전 인벤토리는 기계가 읽을 수 있어야 하며(machine readable) 모든 인수 실행(acceptance run)과 연결되어야 합니다. "이 브랜드와 호환됨"은 지원 매트릭스(support matrix)가 아닙니다.

통과 증거: 불변의 자재 명세서(bill of materials), 호환성 매트릭스(compatibility matrix) 및 실행 중인 버전을 내보내는 명령.

2. 제어 및 책임 경계 설정 (Draw the control and responsibility boundary)

각 결정을 소유하는 구성 요소를 지정하십시오:

• 저수준 동작 (low-level motion) 및 보호 동작 (protective behavior);
• 내비게이션 (navigation) 및 위치 추정 (localization);
• 페이로드 작동 (payload actuation);
• 미션 및 태스크 상태 (mission and task state);
• 공유 자원 조정 (shared-resource coordination);
• 비즈니스 권한 부여 (business authorization);
• 비상 정지 (emergency stop), 일시 정지 (pause), 제어권 인수 (takeover) 및 제어된 재개 (controlled resume).

AI 에이전트, 비즈니스 워크플로우(business workflow) 또는 플릿 플랫폼(fleet platform)이 동작 권한을 조용히 상속받아서는 안 됩니다. 계약에는 어떤 명령이 권고 사항(advisory)인지, 어떤 명령이 실행 가능(executable)한지, 그리고 어떤 명령이 승인 또는 벤더 컨트롤러(vendor controller)를 필요로 하는지를 명시해야 합니다.

통과 증거: 로봇 벤더, 통합업체(integrator) 및 구매자가 검토한 책임 매트릭스(responsibility matrix), 명령 경로(command path) 및 정지 권한 다이어그램(stop-authority diagram).

3. 모든 인터페이스를 계약으로 명시하십시오

ROS 2는 연속적인 스트림을 위한 토픽(topics), 짧은 요청-응답 상호작용을 위한 서비스(services), 그리고 피드백이 포함된 장기 실행 작업을 위한 액션(actions)을 구분합니다. 이러한 구분은 프로젝트가 구체적인 계약(contract)을 확정할 때만 유용합니다.

모든 인터페이스에 대해 다음 사항을 기록하십시오:

• 이름, 네임스페이스(namespace) 및 버전;
• 메시지(message), 서비스(service) 또는 액션(action) 정의;
• 단위(units), 범위(ranges), 열거형(enums) 및 좌표계(coordinate frame);
• 업데이트 속도(update rate), 타임아웃(timeout) 및 최신성 제한(freshness limit);
• 인증(authentication) 및 인가(authorization) 경계;
• 에러 코드(error codes), 취소(cancellation) 및 재시도 동작(retry behavior);
• 하위 호환성(backward-compatibility) 및 폐기 정책(deprecation policy).

동일한 규율이 벤더 SDK 호출, WebSocket 이벤트, REST API, 파일 및 데이터베이스 레코드에도 적용됩니다.

통과 증거: 버전 관리된 인터페이스 카탈로그와 대표적인 페이로드(payloads) 및 잘못된 입력값(invalid inputs)에 대한 계약 테스트(contract tests).

4. 시계(clocks), 단위(units) 및 좌표계(coordinate frames)를 명시적으로 설정하십시오

많은 통합 결함은 알고리즘적인 문제라기보다 의미론적(semantic)인 문제입니다. 포즈(pose)가 수치적으로는 유효하더라도 잘못된 좌표계, 시간 또는 단위를 참조할 수 있습니다.

정의하십시오:

• 시계 소스(clock source) 및 동기화 방법;
• 캡처 시간(capture time), 명령 시간(command time) 및 도착 시간(arrival time);
• 최대 연령(maximum age), 스큐(skew), 지터(jitter) 및 드리프트(drift);
• SI 단위 또는 벤더 단위 및 변환 책임(conversion ownership);
• 축 방향(axis directions), 손 방향(handedness) 및 쿼터니언 순서(quaternion order);
• 맵(map), 오도메트리(odometry), 베이스(base), 센서(sensor), 툴(tool) 및 비즈니스 위치(business-location) 프레임;
• 변환(transform) 유효성 및 변환 정보가 오래되었거나 누락되었을 때의 동작.

통과 증거 (Pass evidence): 프레임 트리(frame tree), 시계 다이어그램(clock diagram), 변환 테스트(conversion tests) 및 관측값(observations), 명령(commands), 변환(transforms)이 정렬된 상태로 유지되는 재생(replay).

5. 건강한 LAN뿐만 아니라 QoS 및 네트워크 동작 테스트

ROS 2 서비스 품질(Quality of Service, QoS) 프로필은 신뢰성(reliability), 내구성(durability), 히스토리(history), 깊이(depth), 데드라인(deadline) 및 수명(lifespan)과 같은 정책을 결합합니다. 요청된(requested) 프로필과 제공된(offered) 프로필이 서로 호환되지 않으면 두 노드가 모두 실행 중이더라도 메시지 전달이 차단될 수 있습니다.

프로젝트는 인터페이스별 정책을 정의하고 다음을 테스트해야 합니다:

• 지연(delayed), 중복(duplicated), 순서 변경(reordered) 및 드롭(dropped)된 메시지;
• 낮은 대역폭(low bandwidth) 및 일시적인 연결 끊김;
• 재연결 후 오래된 데이터(stale data);
• 큐 증가(queue growth) 및 리소스 고갈(resource exhaustion);
• 기록된 QoS가 라이브 시스템과 다를 때의 재생(replay) 동작.

통과 증거 (Pass evidence): 합의된 QoS 프로필, 호환성 체크, 네트워크 결함 결과 및 기록된 메시지 손실 또는 연령(age) 지표.

6. 라이프사이클(lifecycle) 및 복구 상태 정의

ROS 2 관리형 노드(managed-node) 설계는 감독된 전이(supervised transitions) 및 오류 처리를 포함하여 미설정(unconfigured), 비활성(inactive), 활성(active) 및 종료(finalized)와 같은 명시적인 상태를 제공합니다. 상용 프로젝트는 다른 메커니즘을 사용할 수 있지만, 여전히 관찰 가능한 상태가 필요합니다.

각 구성 요소에 대해 다음을 정의하십시오:

• 구성 및 활성화 전제 조건;
• 상태(health) 및 준비(readiness) 신호;
• 안전한 비활성 동작;
• 종료(shutdown) 및 리소스 정리(resource cleanup);
• 복구 가능한 오류(recoverable errors) 대 치명적 오류(terminal errors);
• 누가 구성 요소를 재시작하거나 교체할 수 있는지;
• 재시작 후 어떤 상태를 재구성해야 하는지.

프로세스를 시작하는 것은 기능을 준비 상태로 만드는 것과 동일하지 않습니다.

통과 증거 (Pass evidence): 라이프사이클 상태 다이어그램 (lifecycle state diagram), 전환 로그 (transition logs), 재시작 테스트, 그리고 완료되지 않은 명령이 사라지거나 두 번 실행되지 않는다는 증명.

7. 명령의 멱등성 (Idempotency) 확보 및 작업의 조정 가능성 (Reconcilability) 보장

네트워크는 재시도(retry)를 합니다. 클라이언트는 재연결(reconnect)합니다. 운영자는 버튼을 두 번 클릭합니다. 안전한 통합 시스템은 단순히 동일한 요청이 두 번 전달되었다는 이유만으로 두 번의 물리적 동작을 생성해서는 안 됩니다.

안정적인 명령 또는 작업 식별자 (identifiers)를 사용하고 다음을 정의하십시오:

• 수락됨 (accepted), 거부됨 (rejected), 대기 중 (queued), 발송됨 (dispatched), 실행 중 (running), 일시 중지됨 (paused), 완료됨 (completed), 실패함 (failed), 취소됨 (cancelled) 상태;
• 중복 명령 (duplicate-command) 동작;
• 타임아웃 (timeout) 대 알 수 없는 결과 (unknown-result) 처리;
• 클라이언트, 어댑터(adapter) 또는 플랫폼 재시작 후의 권위 있는 상태 (authoritative state);
• 비즈니스 상태와 로봇 상태 간의 조정 (reconciliation);
• 자동 복구가 안전하지 않을 때의 인간 결정 지점 (human decision points).

통과 증거 (Pass evidence): 중복 및 순서가 잘못된 요청 테스트, 지속성 있는 상태 전환 (persisted state transitions), 그리고 모든 최종 상태를 설명하는 복구 보고서.

8. 보호 동작과 기능적 성공의 분리

내비게이션(navigation) 또는 조작(manipulation) 기능이 명목상의 작업은 완수하더라도, 현장 규칙, 페이로드(payload) 제약 조건 또는 인간의 승인 요구 사항을 위반할 수 있습니다.

인수 계획(acceptance plan)은 다음을 구분해야 합니다:

• 공급업체의 보호 기능 (protective functions) 및 문서화된 한계치;
• 프로젝트 수준의 운영 규칙;
• 기능적 성공 기준 (functional success criteria);
• 정지 및 개입 기준;
• 금지된 자율 복구;
• 잔류 위험 (residual risk) 및 운영자 책임.

정확한 시스템과 주장에 대한 최신 서면 증거가 없는 한, 소프트웨어 통합이 인증되었거나 안전 등급(safety-rated)을 받았다고 기술하지 마십시오.

통과 증거 (Pass evidence): 위험 인지 테스트 케이스 (hazard-informed test cases), 정지 상태 (stop-state) 증거, 제어권 전환 절차 (takeover procedure), 그리고 제외되거나 검증되지 않은 조건이 명시된 서명된 목록.

9. 작업, 로봇 이벤트 및 비즈니스 트랜잭션의 상관관계 분석

별도의 시스템에 저장된 로그는 작업이 실패했을 때 활용하기 어렵습니다. OpenTelemetry 컨텍스트 전파 (context propagation)는 서비스 경계를 가로질러 트레이스 (traces), 메트릭 (metrics), 로그 (logs)를 상관 분석하기 위한 유용한 공개 참조 모델입니다.

로봇 프로젝트는 민감하지 않은 식별자(identifiers)를 사용하여 동일한 원칙을 적용할 수 있습니다:

• 프로젝트 및 배포 버전 (project and deployment version);
• 작업 및 명령 ID (task and command ID);
• 로봇 및 어댑터 ID (robot and adapter ID);
• 지도 및 경로 개정 (map and route revision);
• 비즈니스 트랜잭션 또는 작업 지시서 참조 (business transaction or work-order reference);
• 트레이스 및 스팬 관계 (trace and span relationship);
• 타임스탬프 및 결과 분류 (timestamps and result classification).

트레이스 배이지 (trace baggage)나 공개 로그에 자격 증명 (credentials), 개인 데이터 또는 기밀 페이로드 (confidential payloads)를 절대 포함하지 마십시오.

통과 증거 (Pass evidence): 수동적인 타임스탬프 추측 없이 비즈니스 시스템, 플랫폼, 어댑터 및 로봇 로그 전체에서 하나의 대표적인 작업이 재구성됨.

10. 빌드 및 배포의 재현성 (reproducible) 증명

“개발자가 다시 빌드할 수 있다”는 것은 인도 (delivery)의 증거가 아닙니다.

요구 사항:

• 소스 및 의존성 개정 (source and dependency revisions);
• 라이선스 및 재배포 검토 (license and redistribution review);
• 환경 또는 컨테이너 정의 (environment or container definition);
• 빌드 명령 및 아티팩트 체크섬 (build command and artifact checksums);
• 구성 스키마 및 비밀 정보 처리 경계 (configuration schema and secret-handling boundary);
• 모델, 캘리브레이션 (calibration) 및 지도 아티팩트 버전 (model, calibration and map artifact versions);
• 클린 머신 설치 (clean-machine installation);
• 롤백 패키지 및 데이터베이스 마이그레이션 계획 (rollback package and database migration plan).

구매자는 코드, 구성 (configuration), 모델 가중치 (model weights), 고객 데이터 및 런타임 상태 (runtime state)를 구분할 수 있어야 합니다.

통과 증거 (Pass evidence): 전달된 지침에 따라 수행된 클린 환경에서의 빌드 및 배포, 그리고 이어서 진행되는 체크섬 검증.

11. 장애 주입 (Inject failures) 및 결과 재생

인수 테스트 (Acceptance)에는 의도된 환경과 일치하는 장애 상황이 포함되어야 합니다:

• 센서 스트림 누락 또는 지연 (sensor stream missing or stale);
• 변환 (transform) 또는 위치 추정 (localization) 불가;
• 로봇에 의해 명령이 거부됨;
• 페이로드 (payload) 또는 비즈니스 API 타임아웃;
• 작업 중 네트워크 손실;
• 어댑터, 애플리케이션 또는 데이터베이스 재시작;
• 배터리 부족 또는 사용 불가능한 리소스;
• 잘못된 구성 또는 호환되지 않는 버전;
• 운영자의 일시 정지, 제어권 인수 (takeover) 및 중단 (abort).

안전하지 않은 물리적 시나리오를 인위적으로 만들지 마십시오. 적절한 경우 시뮬레이션 (simulation), 인터페이스 스텁 (interface stubs), 통제된 조건 또는 벤더가 승인한 테스트를 사용하십시오.

통과 증거 (Pass evidence): 결함 주입 매트릭스 (fault-injection matrix), 예상되는 안전 상태 (expected safe state), 유지된 텔레메트리 (retained telemetry), 모든 테스트에 대한 복구 경로 (recovery path) 및 재현 가능한 결과 (replayable result).

12. 인수 매트릭스, 롤백 및 지원 경계 전달

최종 패키지는 약속된 각 기능을 다음 항목에 매핑해야 합니다:

• 정확한 지원 버전 (exact supported versions);
• 구매자 입력값 및 현장 가정 사항 (buyer inputs and site assumptions);
• 기능 및 실패 테스트 (functional and failure tests);
• 요구되는 증거 (required evidence);
• 통과 (pass), 조건부 통과 (conditional pass) 또는 실패 (fail) 결과;
• 해결되지 않은 제한 사항 (unresolved limitations);
• 변경 관리 규칙 (change-control rule);
• 롤백 방법 (rollback method);
• 보증 또는 지원 담당자 및 대응 경로 (warranty or support owner and response path).

가격, 인도 시간 및 지속적인 지원은 이 서면 범위(scope)를 참조해야 합니다. 그렇지 않으면 견적서에는 한 프로젝트를 설명하고, 인수 테스트는 다른 프로젝트를 측정하는 상황이 발생할 수 있습니다.

통과 증거 (Pass evidence): 서명된 인수 매트릭스 (signed acceptance matrix), 알려진 문제 레지스터 (known-issues register), 릴리스 노트 (release notes), 롤백 훈련 (rollback drill) 및 지원 인수인계 (support handover).

전체 배포 전 대표 파일럿 수행

통합 리스크 (integration risk)를 드러낼 수 있는 가장 작은 엔드 투 엔드 (end-to-end) 경로부터 시작하십시오:

1. 하나의 정확한 로봇 및 소프트웨어 스택 (software stack);
2. 하나의 대표적인 작업 (task);
3. 하나의 페이로드 (payload) 또는 비즈니스 시스템 인터페이스 (business-system interface);
4. 하나의 통제된 네트워크 성능 저하 (network degradation);
5. 작업 중 하나의 구성 요소 재시작 (component restart);
6. 하나의 운영자 개입 (operator takeover) 및 통제된 재개 (controlled resume);
7. 하나의 전체 트레이스 (trace), 재생 (replay) 및 증거 패키지;
8. 하나의 클린 환경 배포 (clean-environment deployment) 및 롤백.

해당 루프가 수용된 후에만 로봇, 현장, 작업 또는 자율성 (autonomy)을 확장하십시오.

체크리스트를 프로젝트 브리프로 전환하기

공개된 GitHub 양식은 개인 연락처 정보를 요청하지 않고도 운영 시나리오, 대표 작업, 로봇 또는 페이로드, 시스템 인터페이스, 인수 우선순위, 파일럿 규모 및 구매 단계를 캡처합니다:

구조화된 로봇 프로젝트 브리프 열기.

공개 이슈(public issue)에 전화번호, 이메일 주소, 정확한 개인 현장 주소, 기밀 지도, 자격 증명 (credentials), 고객 이름 또는 미공개 상업적 세부 정보를 기재하지 마십시오.

비공개 인터페이스 문서 및 서면 프로젝트 범위(project scope)를 위해서는 지정된 연락 경로를 이용하십시오:

비공개 로봇 맞춤형 개발 문의 보내기.