RCA: RefinementService::loadFloorplan | end - not a bim drawing, floorplan type: pdf

Overview#

What Happened#

2026-05-30 00:03 KST에 cupixworks-capture-refinement-arm-instance 서비스에서 refinement 작업 중 floorplan 로딩 단계에서 에러가 발생했다. TSLA-12199 커밋으로 추가된 BIM drawing 타입 검증 로직이 pdf 타입 floorplan을 거부하면서 refinement job이 실패했다.

Quick Facts#

Timeline#

1. 2026-05-20 13:57 KST — TSLA-12199 배포 후 최초 "not a bim drawing" 에러 발생 시작
2. 2026-05-20 14:00~17:11 KST — 동일 에러 20건 이상 연속 발생
3. 2026-05-30 00:03 KST — 본 클러스터 대상 에러 발생 (floorplan type: pdf)
4. 2026-05-30 00:03 KST — RefinementService::run catch block에서 job error 처리

Error Log#

Datadog Logs

RefinementService::loadFloorplan | end - not a bim drawing, floorplan type: pdf

Impact#

• Service: cupixworks-capture-refinement-arm-instance
• Team: gilbaneco
• 발생 횟수: 1 (본 클러스터), 20건+ (5/20 배포 이후 전체)
• 최초 발생: 2026-05-30 00:03 KST
• 최근 발생: 2026-05-30 00:03 KST

Root Cause Summary#

TSLA-12199 (4e4f50a4d) 커밋에서 loadFloorplan 메서드에 BIM 타입 floorplan만 허용하는 검증 로직이 추가되었다. 이 변경으로 기존에 정상 처리되던 pdf 타입 floorplan이 에러로 거부된다. 원래 createParamsJson 메서드는 BIM과 non-BIM(pdf 등) 모두를 지원하도록 분기 처리(floorplan_meta_json_filepath vs bim_drawings_meta_json_filepath)하고 있었으나, 새로 추가된 검증이 createParamsJson 도달 전에 실행을 중단시킨다.

Technical Analysis#

Code Path#

• Entry point: refinement-service.ts:46 — this.run() 호출
• run() 내부에서 loadFloorplan(cpCapture) 호출 (line 90)
• loadFloorplan에서 floorplan 조회 후 타입 검증 (line 204, deployed version)
• Failure point: refinement-service.ts:204 (deployed) — newCPFloorplan.floorplanType !== TESLA.FloorplanType.Bim 조건 충족 시 에러 throw

기존 코드 (develop/master):

private loadFloorplan = async (cpCapture: CPCapture): Promise<void> => {
    logger.debug('RefinementService::loadFloorplan | begin');
    const floorplanId = cpCapture.cpCluster?.getUsedFloorplanIdFromMeta();
    if (floorplanId == undefined) {
        logger.error('RefinementService::loadFloorplan | end - not found floorplan id');
        this.jobManager.setErrorCode(ErrorCode.ScenemapperUtils.RefinerNotFoundFloorplan);
        throw new Error('not found floorplan id');
    }

    const srvFloorplan = await this.cupixApi.floorplan.get(floorplanId);
    const newCPFloorplan = new CPFloorplan(srvFloorplan, cpCapture);
    cpCapture.setCPFloorplan(newCPFloorplan);
    const isSuccess = await newCPFloorplan.downloadImage(this.cupixAuth.accessToken as string);
    if (!isSuccess) {
        logger.error('RefinementService::loadFloorplan | end - download image failed');
        this.jobManager.setErrorCode(ErrorCode.ScenemapperUtils.RefinerNotFoundFloorplan);
        throw new Error('download floorplan image failed');
    }

    newCPFloorplan.exportMetaJson(true);
    logger.debug('RefinementService::loadFloorplan | end');
};

배포된 버전에서 추가된 검증 (commit 4e4f50a4d):

 const srvFloorplan = await this.cupixApi.floorplan.get(floorplanId); const newCPFloorplan = new CPFloorplan(srvFloorplan, cpCapture);+if (newCPFloorplan.floorplanType !== TESLA.FloorplanType.Bim) {+    logger.error('RefinementService::loadFloorplan | end - not a bim drawing, floorplan type: %s', newCPFloorplan.floorplanType);+    this.jobManager.setErrorCode(ErrorCode.ScenemapperUtils.RefinerNotFoundBimDrawing);+    throw new Error('not a bim drawing');+} cpCapture.setCPFloorplan(newCPFloorplan);

기대 동작: TSLA-12199 의도는 BIM drawing이 아닌 floorplan으로 refinement를 시도할 때 조기에 실패 처리하는 것. 그러나 createParamsJson (line 284-288)에서 이미 BIM/non-BIM 분기를 지원하고 있어, pdf 타입 floorplan으로도 refinement가 동작할 수 있다.

if (cpCapture.cpFloorplan?.floorplanType == TESLA.FloorplanType.Bim) {
    bimDrawingsMetaJsonFilepath = cpCapture.cpFloorplan?.localMetaJsonFilePath;
} else {
    floorplanMetaJsonFilepath = cpCapture.cpFloorplan?.localMetaJsonFilePath;
}

실제 동작: pdf 타입 floorplan이 할당된 capture에 대해 refinement job이 실행되면, loadFloorplan 단계에서 BIM 타입 검증에 실패하여 즉시 에러 throw → job 실패.

Log Evidence#

사용한 쿼리:

service:cupixworks-capture-refinement-arm-instance "RefinementService" from:2026-05-29T14:50:00Z to:2026-05-29T15:10:00Z

에러 발생 시 실행 흐름:

2026-05-30 00:03:47 [info]  RefinementService::init
2026-05-30 00:03:47 [info]  RefinementService::authenticate | begin
2026-05-30 00:03:47 [info]  RefinementService::authenticate | end
2026-05-30 00:03:47 [info]  RefinementService::run | begin
2026-05-30 00:03:48 [error] RefinementService::loadFloorplan | end - not a bim drawing, floorplan type: pdf
2026-05-30 00:03:48 [error] RefinementService::run | end - {}
2026-05-30 00:03:49 [info]  RefinementService::terminateService | force shutdown after 10 seconds

배포 직후 에러 폭증 (5/20):

service:cupixworks-capture-refinement-arm-instance "not a bim drawing" from:2026-05-16T00:00:00Z to:2026-05-30T00:00:00Z

결과: 5/20 13:57 KST부터 20건 이상의 동일 에러 발생. 모두 floorplan type: pdf.

Hypotheses Considered#

Fix Recommendation#

즉시 조치 (Critical)#

• applications/agents/packages/cupix-capture-refinement-agent/src/refinement-service.ts (deployed version, loadFloorplan 내 BIM 검증 분기)
• 에러 레벨을 warn으로 하향하고 graceful exit 처리 검토. pdf 타입 floorplan은 기존에 정상 처리되던 시나리오이므로, 의도된 검증이라면 error가 아닌 warn으로 기록하여 알림 폭증을 방지해야 함.
• 혹은 업스트림(job 생성 측)에서 BIM floorplan이 있는 capture에만 refinement job을 생성하도록 필터링.

단기 개선 (1주 이내)#

• TSLA-12199 feature의 의도를 확인: refinement가 BIM 전용으로 변경된 것인지, 아니면 Lambda 좌표변환이 BIM에만 필요하여 검증을 추가한 것인지 팀과 확인 필요.
• 의도된 동작이라면 로그 레벨을 warn으로 변경하고, job 상태를 error가 아닌 적절한 종료 상태로 업데이트.
• 의도되지 않은 제한이라면 BIM 검증을 제거하고 기존 createParamsJson의 분기 로직으로 복원.

장기 개선 (재발 방지)#

• Refinement job 생성 시점에서 floorplan 타입 사전 검증을 추가하여, 지원하지 않는 타입의 capture에 대해 job 자체를 생성하지 않도록 함.
• Agent 서비스의 "expected rejection" (지원 불가 입력) vs "unexpected error" (버그) 구분을 로깅 체계에 반영.

Monitoring#

• service:cupixworks-capture-refinement-arm-instance "not a bim drawing" 쿼리로 발생 빈도 모니터링
• 추가 메트릭: refinement job 실패율을 error code별로 분류 (AGT3018 = RefinerNotFoundBimDrawing)

Risk Assessment#

• Risk level: low
• 예상 복잡도: trivial (로그 레벨 변경) 또는 standard (업스트림 필터링 추가)