ES /docs

TransferManager::failTask | path: /tmp/workspace/rabren.739490_result/rabren.739490_1463351_ref_plan

Fix Plan: TransferManager::failTask — HttpError observability 개선

Scope#

사용자가 선택한 옵션은 RCA의 "### 단기 개선 (1주 이내)" 섹션이다. 해당 섹션은 두 항목을 포함한다.

# 항목 자동 반영 여부 사유
1 Tesla POST /api/v1/pointclouds/:id/resources 를 Idempotency-Key 헤더 기반으로 idempotent 하게 개조 제외 tesla 서버 컨트랙트 변경 + agent 측 UUID 발급 로직 + pointcloud 외 resourcable(capture, pano 등) 전반 concern 수정이 얽혀 있어 cross-team 조율이 선행되어야 한다. RCA 본문도 "concern 레벨에서 통일하는 편이 낫다" 로 서술. 별도 트랙에서 진행.
2 Agent HttpError 로깅 개선: failTask 가 error?.statusCode 와 error?.response?.body 요약을 포함 반영 pure agent-side change, breaking change 없음. 순수 observability 개선.

본 계획은 항목 2 만 다룬다.

Changes#

cupixworks: applications/agents/packages/base/src/manager/transfer.manager.ts#

  • What: BaseTransferManager.failTask 의 logger.error 포맷 문자열에 statusCode, response.body 요약을 추가한다. 현재는 path, url, count, code, message 만 로깅되어, HttpError 처럼 code 필드가 없고 statusCode 만 있는 SDK 에러의 경우 code: undefined, message: HTTP request failed 라는 무의미한 라인이 남는다. 확장 후에는 statusCode 와 response?.body (Buffer/객체는 문자열로 안전하게 요약) 가 함께 남아 tesla 응답의 domain error(ARG10001 Duplicate kind: plane 등) 를 표면 로그만으로도 식별할 수 있다.
  • Why: RCA Root Cause Summary — SDK HttpError 는 error.code 를 세팅하지 않고 error.statusCode(=400) 와 error.message("HTTP request failed") 만 세팅하므로, 현재 로그로는 400 vs 5xx vs network abort 를 구분할 수 없다. 이 로깅 개선으로 후속 동일 fingerprint 발생 시 즉시 원인(Duplicate kind, 400 등) 을 파악할 수 있다.
  • Lines: failTask 메서드 (약 148-157 라인 부근). 단일 logger.error 호출과 body 요약 헬퍼 1개 추가.

Out of Scope (같은 섹션이나 별도 트랙)#

  • Tesla POST /api/v1/pointclouds/:id/resources 에 Idempotency-Key 추가 및 multiple_resourcable_controller concern 리팩터. 후속 Jira 를 별도로 발급하여 tesla + agent 양쪽 조율 필요. 본 PR 에서는 다루지 않는다.
  • RCA의 "즉시 조치 (Critical)" 섹션 (renew 로직 아이덤포턴시). 사용자가 선택한 옵션이 아니므로 out of scope.
  • RCA의 "장기 개선" (axios 통일, chaos test). 사용자가 선택한 옵션이 아니므로 out of scope.

Acceptance Criteria#

  • applications/agents/packages/base/src/manager/transfer.manager.ts 의 failTask 로그가 statusCode 와 response.body 요약을 포함한다.
  • error 인자가 null/undefined/Error 인스턴스인 경우에도 안전하게 로깅되어야 한다 (optional chaining 유지, JSON.stringify 실패 시 fallback).
  • tsc --noEmit (base package) 이 통과한다.
  • pnpm exec eslint applications/agents/packages/base/src/manager/transfer.manager.ts 통과.
  • 기존 failTask 호출부의 시그니처 변경이 없다 (외부 API 변경 없음).

Tests#

  • 기존 테스트: applications/agents/packages/base/src/util/transfer.spec.ts (직접 관련되지는 않으나 util layer 변경 아님).
  • 신규 테스트: failTask 는 private 메서드라 직접 unit test 대상이 아님. 로그 포맷은 관찰 가능성 개선 목적으로 별도 스펙 추가 없이 배포 후 로그 확인으로 검증.