제로웍스 연동 개발 시나리오

제로웍스 로봇이 비스캣 관제와 결합해 한 사이클을 도는 동작 흐름입니다. 토픽·페이로드 상세는 연동 API 문서를, 메인은 개발 가이드를 참조하세요.

1. 등록·인증 (최초 1회)

비스캣 관제에 robotCode(예: R-001)가 사전 등록된 뒤, 로봇은 robotCode와 공개키를 제출합니다. 관제는 robotCode로 로봇을 조회해 내부 식별자 robotId(UUID)를 회신하고 HMAC 비밀키를 발급하며, 로봇은 X.509 인증서 번들(다운로드 URL)을 내려받습니다. 이후 로봇은 인증·MQTT에 robotId를 사용합니다. 등록·인증 요청은 REST로 진행하고, 인증서를 설치한 뒤 MQTT에 연결합니다. 이후 미션·상태·알람 메시지는 모두 MQTT로 주고받습니다.

• 재발급: 이미 발급(활성화)된 로봇이 /key·/cert를 다시 호출하면 409 ROBOT_ALREADY_ACTIVATED로 거절됩니다. 재발급(인증서 회전)이 필요하면 관제 관리자 초기화 후 다시 발급받습니다.
• REST 인증 요청 헤더: X-Robot-ID, X-Robot-Ts(ISO8601, +09:00 KST), X-Robot-Signature(HMAC-SHA256). timestamp는 ±60초 윈도우.
• 인증서 설치 후 MQTT 연결. 로봇은 자신의 토픽(r2s/{robotId}/# publish, s2r/{robotId}/# subscribe)만 사용할 수 있습니다.

2. 맵 등록 (REST · 로봇 UI 버튼)

로봇이 보유한 지도와 의미 거점 노드(매장·하역장·충전소·대기 등 goal.type 거점)를 siteId 기준으로 관제에 등록합니다. 운영자가 로봇 UI의 업로드 버튼을 누르면 로봇이 보유 맵을 자동 업로드합니다. 등록 개시 시 siteId·제시 mapId와 업로드할 파일 목록을 선언하면 관제가 파일별 업로드 URL을 발급하고, 로봇은 지도 이미지·메타(yml)·노드(json)를 각각 해당 URL로 올립니다(압축하지 않음). 흐름은 등록 개시 → 파일 업로드 → 등록 확정 3단계입니다.

1. 등록 개시: 로봇이 siteId·제시 mapId와 업로드할 파일 목록을 관제에 전송. 관제가 mapVersion과 파일별 업로드 URL을 발급.
2. 파일 업로드: 로봇이 지도 이미지·메타(yml)·노드(json)를 각 업로드 URL로 개별 전송(압축하지 않음). uploadExpiresIn 내 완료.
3. 등록 확정: 로봇이 commit 호출 → 관제가 선언 파일이 모두 업로드됐는지 확인하고 검증해 통과 시 활성화(이전 버전 비활성). 누락 시 오류, 선언에 없는 파일은 미반영·삭제. 이후 MQTT location.map_id가 활성 mapId를 가리키고, 관제는 등록된 노드 좌표로 goal을 내립니다.

3. MQTT 입찰·배차 (offer → bid → result)

미션이 생기면 관제가 수행 가능한 후보 로봇에게 미션(goal 배열)을 제시합니다. 흐름은 입찰 요청 → 입찰 응답 → 배차 결과 3단계입니다. 각 로봇은 예상 도착시간을 입찰하고, 어느 로봇이 수행할지의 최종 배차 결정은 관제가 단독으로 내려(최소 도착시간 기준, 추후 적재공간 포함) result로 통보합니다.

1. 입찰 요청(offer): 관제가 후보 로봇에게 goal 전체 정의를 제시합니다(API 문서 §5.1 본문). 낙찰 로봇은 이 본문을 그대로 수행하므로, offer 는 사실상 조건부 goal 부여입니다. 식별은 관제가 발급한 goal id 단위입니다.
2. 입찰 응답(bid): 각 로봇이 goal별 수행 가능 여부(available)와 도착 예상 시각(estArrival — occurredAt과 동일 포맷의 절대 시각, API 문서 §5.2 규약)을 자체 계산해 회신. 본문은 견적 응답(quote/bid)과 동일 스키마입니다.
3. 배차 결과(result): 관제가 입찰을 받아 남은 시간(마지막 goal 도착 예상 시각 기준) 최소로 배차를 결정하고(적재 칸을 배정할 수 없는 로봇은 채택 단계에서 제외) goal별 claimed·reason으로 통보. claimed=true 통보가 곧 주행 개시 신호이며, 관제는 별도의 출발 지시를 보내지 않습니다.

3.1 배송 가능여부 견적 (quote) 운영 적용됨

주문이 확정되기 전, 관제가 후보 로봇에게 "지금 이 배송을 수행할 수 있는지"를 미리 물어 가용성과 예상 도착시간을 받아 두는 사전 견적 흐름입니다. 미션(goal)을 만들지 않는 비구속 질의라 배차 입찰(goals/*)과 토픽을 분리해 quote/*로 운영하며, 낙찰(result) 없이 질의 → 견적 2단계로 끝납니다.

1. 견적 질의(offer): 관제가 후보 로봇에게 축약 본문을 제시(s2r/{robot_id}/quote/offer) — quoteId·deliveryType과 목적지 요약(type·location·boxCount)뿐입니다. 아직 주문이 확정되지 않아 goal id·PIN·주문번호가 없습니다. 라운드 상관은 토픽의 robot_id로 합니다.
2. 견적 응답(bid): 각 로봇이 goal별 수행 가능 여부(available)와 도착 예상 시각(estArrival, 불가 시 null·사유)을 회신(r2s/{robot_id}/quote/bid). 배차 입찰 응답(goals/bid)과 완전히 동일한 스키마이며, id는 빈 문자열로 둡니다.

4. 배송 미션 전체 시나리오

배차 이후의 한 사이클입니다(mode: delivery). 한 오더(mission.id)는 매장 goal(type:store, mission.type:pickup)과 고객 goal(type:customer, mission.type:dropoff)로 구성됩니다. 로봇은 goal 배열을 arrivalOrder 순으로 수행하며, 진행 상태를 r2s/{robot_id}/goals로 발행합니다. 상태값은 세 계층 모두 standby·doing·done 한 벌을 씁니다(API 문서 §1). PIN은 mission.PIN으로 선전달되어 로봇이 로컬 검증하고, 사용 결과를 관제에 감사 이벤트로 보고합니다. 열 칸은 mission.door로 관제가 지정합니다.

1. 매장 이동: 배차 후 매장(goal.type:store)으로 주행 — goal status가 standby → doing.
2. 매장 도착: 인증 대기 단계가 시작되면(mission.type:auth · status:doing) 관제가 오토메타에 매장 도착을 통지.
3. 점주 PIN 검증(로컬): 점주가 PIN 입력 → 로봇이 mission.PIN으로 로컬 검증 → mission.door로 지정된 칸 개방. 개방 시점에 pickup mission 이 doing으로 전이.
4. 상차·박스 닫힘: 점주 상차 후 박스를 닫으면 pickup mission 이 done으로 전이. 이 전이가 배달 출발 트리거이며, 관제가 오토메타에 배달 출발을 통지. (종전 box/loaded 토픽은 폐지 — API 문서 §6.1)
5. 세대 이동·도착: 세대(goal.type:customer)로 주행(goal doing), 도착은 매장과 같이 auth:doing으로 판정. 관제가 도착 통지.
6. 고객 수령: 방식은 mission의 autoDropOff·PIN으로 결정 — 비대면(autoDropOff=true)은 도착 즉시 하차 후 복귀, WEB 버튼 인증(기본)은 관제 → 로봇 문열림 지시로 개방, 로봇 PIN 입력(예외 fallback)은 로컬 검증 후 개방. 개방 시점에 dropoff mission 이 doing.
7. 완료·복귀: 하차 후 박스를 닫으면 dropoff mission 이 done, 해당 goal 도 done이 됩니다. 미션의 모든 goal·mission 이 done이면 관제가 미션을 종료하고 state.status=done. 이후 처리는 아래 갈래.

5. 쓰레기 수거 시나리오

mode: trash_pickup. 흐름은 배송과 동일한 MQTT 입찰·배차·주행 구조(goal 배열)를 따르되, 매장↔세대 대신 세대(goal.type:customer, mission.type:pickup) → 수거장(goal.type:unloading, mission.type:dropoff) 경로입니다.

• PIN 없음 · 전 구간 비대면 — 세대 상차와 수거장 하역 모두 PIN: null·autoDropOff: true로 내려갑니다(로봇의 비대면 지원 설정과 무관하게 강제).
• 출발 지점이 다릅니다 — 배송은 매장부터, 수거는 세대부터 시작합니다. arrivalOrder 순서와 quote/offer의 deliveryType: "trash_pickup"으로 구분됩니다.
• 그 밖의 상태 어휘·완료 판정·박스 개폐 처리는 배송과 동일합니다.

6. 단지 인프라(E/V·로비폰) 처리

실패 시나리오(호출 실패·문 안 열림·층 오인식) 대응은 별도 협의합니다. 참고로 sourceFloor·destinationFloor를 빈 문자열로 보내면 콜이 계속 실패하며, 로봇이 층을 실을 때까지 재시도가 멈추지 않습니다(2026-08 실사례).

7. 알람·에러·재시도

• 미낙찰: goals/result에서 claimed=false + 사유(reason) 수신 시 해당 입찰은 종료(재오퍼 없음). 현재 사유 값은 outbid(더 빠른 로봇이 낙찰) 한 가지입니다.
• 미션 수행 중 취소: 로봇이 goal·mission 을 canceled로 전이하면서 reason(path-blocked·robot-fault·battery-low·elevator-unavailable·door-not-opened·timeout·operator-cancel·unknown)을 함께 발행합니다. 관제는 이 사유로 재배차 여부를 판단하고 운영자 화면(보류 미션)에 올립니다 — 사유 없는 취소는 기록되지 않습니다. 상세는 로봇 발행 항목 §6.
• 인프라 요청 실패: resource/ready가 failed로 오면 로봇은 대기·재시도합니다. 같은 실패가 연속되면 관제가 자동으로 보류 미션 큐에 올려 운영자에게 노출합니다.
• 엘베 콜 취소: 로봇이 탑승에 실패하면 resource 에 status: "cancelByRobot" 을 보내 콜을 끊습니다. 관제는 MIRI 취소를 대신 수행하고 result: "canceled" 로 회신합니다. 재호출은 5초 이상 띄웁니다.
• 통신 실패: MQTT 전송 실패·미수신 시 재시도(행위 이벤트는 requestId 중복 흡수로 안전). 텔레메트리(상태)는 occurredAt 기준 최신값만 반영하므로 누락에 강건.
• PIN 불일치·만료: 로컬 검증 실패 시 칸을 열지 않고 재입력 대기, 사용·실패 결과를 감사 이벤트로 보고.
• 알람: 로봇 이상은 r2s/{robot_id}/alarm으로 code·level(warn|error|fatal)·msg를 발행 → 관제가 레벨별로 대응(자동/수동 리셋). 레벨별 관제 대응 매핑은 시나리오 협의로 확정.

8. 배송 통신 플로우 예시 (메시지 레벨)

배송 두 케이스의 토픽·메시지 흐름을 단계별로 보입니다 — ① 단건 배송과 ② 주행 중 추가 주문(묶음 배송). 토픽 규약(s2r/r2s)·메시지 envelope·필드 정의는 API 문서 §5를 따릅니다. 등장 주체는 관제·로봇 Robot1이며, 주문 인입·앱 표출(오토메타)은 맥락 노트로만 표시합니다.

mode는 로봇이 어느 서비스로 활용되는지를 나타내는 상태값입니다. 배송 로봇은 배차 전 대기·이동, 그리고 다음 배송으로의 연속 배차까지 mode: delivery를 유지하며, 일감 유무·활동 진행은 state.status·goal.status로 표현합니다(mode로 나타내지 않음). 단 미션 완료 후 충전소로 복귀할 때는 delivery가 아니라 mode: navi + goal.type=charging으로 전이합니다(관제 지시 또는 로봇 timeout 자동 회차). 완료 후 처리 갈래는 §4 참조.

8.1 단건 배송 (Order1)

고객 Order1 주문 → 입찰 → Robot1 확정 → 매장 도착·상차 → 배송 → Order1 도착·배송 완료. 한 주문(mission_Order1)이 매장 goal(goal_s1, pickup)과 고객 goal(goal_c1, dropoff) 두 goal에 같은 mission.id로 걸칩니다.

① 입찰 요청 (offer) — s2r/Robot1/goals/offer · 관제 → Robot1

관제가 goal 전체(location 포함)를 제시합니다. location 좌표는 로봇이 사전 등록한 맵 노드 기준으로 관제가 채웁니다(§2 맵 등록). 낙찰되면 이 본문을 그대로 수행하므로 goal 재전송은 없습니다.

아래 예시의 goal_s1·mission_Order1은 읽기 쉬운 가짜 값입니다. 실제 발급 형식은 g-{미션UUID}-{goal.type}·m-{미션UUID}이며, 로봇은 받은 id 를 그대로 되돌려 보내야 합니다(API 문서 §5.1).

{
  "requestId": "req-offer-Order1",
  "occurredAt": "2026-06-17T10:00:00+09:00",
  "payload": {
    "goals": [
      {
        "id": "goal_s1", "type": "store", "status": "standby", "arrivalOrder": 1,
        "location": { "x": 12.4, "y": 8.1, "th": 0.0, "map_id": "apt1023-b1" },
        "mission": [
          { "id": "mission_Order1", "type": "pickup", "status": "standby", "atomic": false,
            "PIN": null, "door": [ { "name": "door1", "status": "closed" } ], "orderId": "Order1",
            "address": "", "addressDetail": "", "phoneNumber": "", "message": "" }
        ]
      },
      {
        "id": "goal_c1", "type": "customer", "status": "standby", "arrivalOrder": 2,
        "location": { "x": 40.2, "y": 22.7, "th": 1.57, "map_id": "apt1023-3f" },
        "mission": [
          { "id": "mission_Order1", "type": "dropoff", "status": "standby", "atomic": false,
            "PIN": "1482", "door": [ { "name": "door1", "status": "closed" } ], "orderId": "Order1",
            "address": "103동", "addressDetail": "302호", "phoneNumber": "010-0000-1234", "message": "문 앞" }
        ]
      }
    ]
  }
}

② 입찰 응답 (bid) — r2s/Robot1/goals/bid · Robot1 → 관제

Robot1이 goal별 수행 가능 여부(available)와 도착 예상 시각(estArrival — occurredAt과 동일 포맷의 절대 시각)을 자체 계산해 회신. 식별은 관제가 발급한 goal id이며 그대로 되돌려 보냅니다. 본문 형식은 견적 응답(quote/bid)과 동일합니다.

{
  "requestId": "req-bid-Order1",
  "occurredAt": "2026-06-17T10:00:03+09:00",
  "payload": {
    "goals": [
      { "id": "goal_s1", "arrivalOrder": 1, "available": true, "estArrival": "2026-06-17T10:04:00+09:00", "reason": null },
      { "id": "goal_c1", "arrivalOrder": 2, "available": true, "estArrival": "2026-06-17T10:11:00+09:00", "reason": null }
    ]
  }
}

③ 배차 결과 (result) — s2r/Robot1/goals/result · 관제 → Robot1

{
  "requestId": "req-result-Order1",
  "occurredAt": "2026-06-17T10:00:05+09:00",
  "payload": {
    "goals": [
      { "id": "goal_s1", "claimed": true, "reason": null },
      { "id": "goal_c1", "claimed": true, "reason": null }
    ]
  }
}

④ 수행 — 모드·goal 진행 발행 (r2s/Robot1/state, r2s/Robot1/goals) · Robot1 → 관제

배송 로봇이므로 mode는 delivery로 계속 유지되고, 일감을 잡으면 state.status가 standby → doing으로 전이합니다. 매장 goal 은 standby → doing으로 발행되고, 도착 시 인증 대기 단계(auth)가 doing이 됩니다. (텔레메트리는 requestId 생략)

// r2s/Robot1/state — 모드 전이
{ "occurredAt": "2026-06-17T10:00:06+09:00",
  "payload": { "mode": "delivery", "status": "doing",
    "location": { "x": 12.5, "y": 8.0, "th": 0.0, "map_id": "apt1023-b1" } } }

// r2s/Robot1/goals — 매장 도착(auth doing) → 관제가 매장 도착으로 판정
{ "occurredAt": "2026-06-17T10:04:00+09:00",
  "payload": { "goals": [
    { "id": "goal_s1", "status": "doing", "progress": 100,
      "mission": [
        { "id": "…move…", "type": "move",   "status": "done" },
        { "id": "…auth…", "type": "auth",   "status": "doing" },
        { "id": "mission_Order1", "type": "pickup", "status": "standby" }
      ] }
  ] } }

⑤ 상차·박스 닫힘 → 픽업 완료 (r2s/Robot1/goals) · Robot1 → 관제

점주가 PIN을 입력하면 Robot1이 mission.PIN으로 로컬 검증 후 지정 칸(door1)을 개방하고, pickup mission 을 doing으로 발행합니다 — 관제는 이 전이를 박스 열림으로 처리합니다. 상차 후 박스를 닫으면 같은 mission 이 done이 되고, 이 전이가 배달 출발 트리거입니다. 매장 goal 도 함께 done이 됩니다.

// r2s/Robot1/goals — 박스 닫힘 → 픽업 완료 · 매장 goal 완료
{ "occurredAt": "2026-06-17T10:05:11+09:00",
  "payload": { "goals": [
    { "id": "goal_s1", "status": "done",
      "mission": [ { "id": "mission_Order1", "type": "pickup", "status": "done" } ] }
  ] } }

PIN 사용·검증 결과의 감사 이벤트(r2s) 토픽·페이로드는 여전히 협의 대상입니다(API 문서 §6).

⑥ 배송·완료 (r2s/Robot1/goals) · Robot1 → 관제

세대 goal이 standby → doing, 도착 시 auth:doing, 고객 수령 후 dropoff mission이 done이 되고 goal 도 done이 됩니다. 고객 수령은 기본 WEB 버튼 인증(관제 → 로봇 문열림 지시), 예외 시 로봇 PIN 입력입니다(§4 참조). 미션의 모든 goal·mission 이 done이면 관제가 오토메타에 배송 완료를 통지합니다. 이후 연속 배차가 있으면 mode=delivery를 유지한 채 새 goal을 받고, 없으면 충전소로 복귀합니다(mode=navi·goal.type=charging — §4).

// r2s/Robot1/goals — 하차 완료 → 미션 종료
{ "occurredAt": "2026-06-17T10:10:40+09:00",
  "payload": { "goals": [
    { "id": "goal_s1", "status": "done",
      "mission": [ { "id": "mission_Order1", "type": "pickup",  "status": "done" } ] },
    { "id": "goal_c1", "status": "done",
      "mission": [ { "id": "mission_Order1", "type": "dropoff", "status": "done" } ] }
  ] } }

완료 판정은 그 미션에 속한 goal 이 배열에 모두 실려 전부 done일 때입니다. 여러 미션을 동시에 수행 중이면 한 배열에 함께 실어 보내며, 관제는 goal id 접두로 미션을 갈라 각각 판정합니다.

8.2 주행 중 추가 주문 — 묶음 배송 (Order1 → Order2)

Order1 배차 후 Robot1이 매장1로 이동하는 중 고객 Order2 주문이 들어와 같은 Robot1에 추가됩니다. 낙찰 후 Robot1이 Order1·Order2 goal을 직접 통합·정렬해 매장1 상차 → 매장2 상차 → Order1 배송 → Order2 배송 순서로 수행합니다(관제의 plan 재주입 없음). Order2는 다른 매장(goal_s2)·다른 세대(goal_c2), 적재 칸은 door2를 씁니다.

① Order1 배차·매장1 이동 — 8.1의 ①~④와 동일

Order1 주문 → offer → bid → result(claimed=true) → Robot1이 goal_s1로 이동(doing). 형식은 8.1과 같아 생략합니다.

② Order2 입찰 요청 (offer) — s2r/Robot1/goals/offer · 관제 → Robot1

Robot1 주행 중 Order2 주문이 인입되면, 관제가 Order2의 두 goal만 제시합니다(Order1 goal은 Robot1이 이미 보유). arrivalOrder는 단건 주문과 동일하게 주문 내 순서(픽업 1·하차 2)로 보내며, 병합 시 관제가 전체 plan 기준으로 재배정합니다(④).

{
  "requestId": "req-offer-Order2",
  "occurredAt": "2026-06-17T10:01:00+09:00",
  "payload": {
    "goals": [
      {
        "id": "goal_s2", "type": "store", "status": "standby", "arrivalOrder": 1,
        "location": { "x": 18.9, "y": 6.4, "th": 0.0, "map_id": "apt1023-b1" },
        "mission": [
          { "id": "mission_Order2", "type": "pickup", "status": "standby", "atomic": false,
            "PIN": null, "door": [ { "name": "door2", "status": "closed" } ], "orderId": "Order2",
            "address": "", "addressDetail": "", "phoneNumber": "", "message": "" }
        ]
      },
      {
        "id": "goal_c2", "type": "customer", "status": "standby", "arrivalOrder": 2,
        "location": { "x": 44.0, "y": 30.1, "th": 3.14, "map_id": "apt1023-5f" },
        "mission": [
          { "id": "mission_Order2", "type": "dropoff", "status": "standby", "atomic": false,
            "PIN": "7035", "door": [ { "name": "door2", "status": "closed" } ], "orderId": "Order2",
            "address": "105동", "addressDetail": "501호", "phoneNumber": "010-0000-5678", "message": "" }
        ]
      }
    ]
  }
}

③ Order2 입찰 응답·배차 결과 (bid, result)

Robot1이 현재 부하(Order1 수행 중)를 반영해 입찰하고, 관제가 낙찰을 통보합니다(형식은 8.1 ②③과 동일, goalId는 goal_s2·goal_c2).

④ Robot1 통합·정렬 (로봇 자체 재계획)

낙찰(③) 후 Robot1은 이미 보유한 Order1 goal과 새로 받은 Order2 goal을 자체적으로 통합·정렬해 수행 순서를 정합니다. goal 정의는 offer 본문으로 이미 전달됐으므로, 관제는 별도 통합 plan을 주입하지 않습니다(goals/set 미사용) — 경로 최적화·재정렬은 로봇이 담당합니다. 각 주문의 내부 순서(픽업 → 하차)와 atomic 제약은 보존되며, Order1·Order2 모두 atomic: false라 픽업끼리·하차끼리 묶는 순서(A,C,B,D)가 허용되어 Robot1은 아래 수행 순서를 잡습니다.

Robot1이 정한 수행 순서는 r2s/Robot1/goals 진행 발행의 arrivalOrder(1~4)로 반영되어, 관제가 Robot1의 계획을 파악합니다.

⑤ 수행 — 상차 2회 → 배송 2회 (r2s/Robot1/goals) · Robot1 → 관제

Robot1이 arrivalOrder 순으로 수행하며 각 단계 완료를 mission done으로 발행합니다. 매장2 상차 완료 시점에 두 주문(door1·door2)을 모두 적재한 상태가 됩니다.

// 매장1 상차 완료
{ "occurredAt": "2026-06-17T10:04:30+09:00",
  "payload": { "goals": [
    { "id": "goal_s1", "status": "done",
      "mission": [ { "id": "mission_Order1", "type": "pickup", "status": "done", "door": [ { "name": "door1", "status": "closed" } ] } ] }
  ] } }

// 매장2 상차 완료
{ "occurredAt": "2026-06-17T10:07:20+09:00",
  "payload": { "goals": [
    { "id": "goal_s2", "status": "done",
      "mission": [ { "id": "mission_Order2", "type": "pickup", "status": "done", "door": [ { "name": "door2", "status": "closed" } ] } ] }
  ] } }

// Order1 배송 완료 → 관제가 오토메타에 통지
{ "occurredAt": "2026-06-17T10:12:10+09:00",
  "payload": { "goals": [
    { "id": "goal_c1", "status": "done",
      "mission": [ { "id": "mission_Order1", "type": "dropoff", "status": "done", "door": [ { "name": "door1", "status": "closed" } ] } ] }
  ] } }

// Order2 배송 완료 → 관제가 오토메타에 통지. 전 mission done → state.status=done (연속 배차=delivery 유지 / 충전 복귀=navi·charging)
{ "occurredAt": "2026-06-17T10:16:40+09:00",
  "payload": { "goals": [
    { "id": "goal_c2", "status": "done",
      "mission": [ { "id": "mission_Order2", "type": "dropoff", "status": "done", "door": [ { "name": "door2", "status": "closed" } ] } ] }
  ] } }

8.3 상태 전이 요약

세 계층 모두 standby·doing·done 한 벌을 씁니다 — 종전의 ready·going·arrived·paused 표기는 폐지되었습니다(API 문서 §1). 도착·해당 지점 완료가 goal 의 done이며, 미션 종료는 그 미션에 속한 모든 goal·mission 이 done일 때입니다. 중도 취소는 goal/mission canceled + reason(로봇 발행 항목 §6). 복귀=충전은 delivery가 아니라 navi 모드이며, 다음 일감을 바로 받는 연속 배차에서만 delivery를 유지합니다.

9. 지오펜스 배포·적용

지오펜스는 관제 콘솔에서 단지 운영자가 정의하는 다각형 영역입니다. 로봇은 이 영역을 내려받아 보유하고, 경로 계획·주행 중 스스로 판정합니다. 로봇이 발행하는 항목은 로봇 발행 항목 §9를 따릅니다.

9.1 전체 흐름

영역 진입·이탈 판정은 관제가 위치 발행으로 수행합니다. 로봇은 예방(경로에서 배제·우회·감속)을 담당하고, 진입 기록은 관제가 남깁니다.

9.2 버전 알림 — s2r/{robot_id}/geofence/version

• QoS 1 · retain true — 재접속 시 마지막 버전을 자동으로 수신합니다. 별도 따라잡기 절차가 필요 없습니다.
• 발행 시점 버전이 바뀔 때마다 그 단지의 모든 로봇 토픽에 발행합니다.

{
  "occurredAt": "2026-09-22T10:00:00+09:00",
  "payload": {
    "siteId": "APT-GOCHEOK-001",
    "version": 42
  }
}

다른 s2r 토픽과 같은 공통 envelope(§1)을 씁니다 — 최상위 occurredAt + payload.

• 비교는 일치 여부로 합니다. 수신 버전이 보유 버전보다 작아도 내려받습니다(되돌림 배포가 있을 수 있습니다).
• 영역 본문은 이 메시지에 싣지 않습니다. 브로커 페이로드 한계와 무관하게 동작해야 합니다.
• MQTT 수신이 불가한 구간을 대비해 주기 확인을 병행할 수 있습니다. 주기 협의

9.3 영역 조회 — GET /v1/robot/geofences

인증은 맵 등록(API 문서 §7)과 동일한 로봇 HMAC 서명 방식을 사용합니다. 요청·응답·에러 코드의 정식 정의는 API 문서 §8입니다.

{
  "result": "SUCCESS",
  "data": {
    "siteId": "APT-GOCHEOK-001",
    "version": 42,
    "geofences": [
      {
        "id": "GF-01a0c3ef",
        "kind": "no-go",
        "env": "indoor",
        "mapId": "ground",
        "vertices": [
          { "x": 46.3, "y": 193.9 },
          { "x": 52.3, "y": 193.9 },
          { "x": 52.3, "y": 199.9 },
          { "x": 46.3, "y": 199.9 }
        ],
        "effectiveFrom": null,
        "effectiveTo": null
      },
      {
        "id": "GF-01a0c318",
        "kind": "hazard",
        "env": "outdoor",
        "vertices": [
          { "lat": 37.4983392, "lng": 126.8599869 },
          { "lat": 37.4978070, "lng": 126.8595129 },
          { "lat": 37.4971505, "lng": 126.8605206 }
        ],
        "effectiveFrom": "2026-09-22T09:00:00+09:00",
        "effectiveTo": "2026-09-30T18:00:00+09:00"
      }
    ]
  }
}

• 전량 교체입니다. 응답에 없는 영역은 삭제된 것으로 간주하고 보유 목록에서 제거합니다. 증분이 아닙니다.
• 응답의 version이 §9.2 알림의 값과 다르면 그 사이 다시 바뀐 것입니다 — 응답 값을 적용하고 다음 알림을 기다립니다.

9.4 영역 종류별 거동 · 적용 시점

적용 시점

• hazard가 포함된 변경 — 즉시 적용합니다.
• 그 외 — 미션 경계(적재·하차·대기 진입 시점)에 적용합니다. 주행 중 영역이 바뀌면 수행 중인 경로가 즉시 무효가 되어 급정지·재계산이 반복됩니다.
• 어느 경우든 state.geofence.version 회신은 적용을 마친 뒤에 합니다.

효력 기간

effectiveFrom·effectiveTo는 로봇이 자체 시계로 매 판정 시점에 대조합니다. 기간이 시작·종료되어도 버전은 바뀌지 않으므로, 버전 알림만으로는 반영되지 않습니다.

9.5 좌표계

위성 음영 구간(실내·지하)은 indoor 영역으로 등록됩니다. 해당 구간에서 outdoor 영역은 판정되지 않습니다.