추출 실패 code 전수 매핑 + reason 을 운영 액션 기준으로 재분류

.github/workflows/ci.yml

@@ -66,6 +66,22 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      # 추출 실패 code 계약(정본은 infra)을 같은 러너에 둔다 — ExtractionErrorCatalogTest 가
+      # shared-infra/contracts/extraction-error-codes.yaml 을 읽어 translate 매핑·메트릭 reason 과 대조한다.
+      # 경로가 shared-infra 인 이유: infra 의 install.sh 도 로컬에 같은 경로로 설치해 로컬과 CI 가 같은 파일을 본다.
+      # 체크아웃이 없으면 그 테스트가 실패한다(skip 하면 계약 강제가 조용히 사라지므로 의도된 동작).
+      # 옵션은 extractor 쪽 같은 스텝과 일치시킨다(extractor#32) — 같은 목적으로 같은 repo 를 받는 두 소비자가
+      # 갈리면 한쪽만 손보게 된다. sparse-checkout 은 필요한 디렉터리만, persist-credentials=false 는 러너에
+      # 자격증명을 남기지 않게, ref 는 어느 브랜치가 정본인지 명시한다.
+      - name: Checkout extraction contract
+        uses: actions/checkout@v4
+        with:
+          repository: TeamPiKi/infra
+          ref: main
+          path: shared-infra
+          sparse-checkout: contracts
+          persist-credentials: false
+
       - uses: actions/setup-java@v4
         with:
           java-version: '25'

.gitignore

@@ -15,6 +15,10 @@
 .claude/commands/session-close.md
 .claude/rules/testing-principles.md
 
+# infra(TeamPiKi/infra) 체크아웃 자리 — 계약 카탈로그(contracts/*.yaml)를 로컬은 install.sh 가, CI 는 ci.yml 의
+# 체크아웃 스텝이 여기 둔다. 정본은 infra 이므로 이 repo 는 사본을 추적하지 않는다.
+shared-infra/
+
 # IDE - 개인 설정 제외
 .idea/*
 !.idea/codeStyles/

build.gradle.kts

@@ -152,6 +152,16 @@ tasks.withType<Test> {
     useJUnitPlatform()
     // JDK 21+부터 동적 에이전트 로딩이 제한됨. Mockito(ByteBuddy)가 런타임에 에이전트를 붙이므로 명시적 허용 필요.
     jvmArgs("-XX:+EnableDynamicAgentLoading")
+
+    // 추출 실패 code 계약 카탈로그(ExtractionErrorCatalogTest 가 읽는다)는 소스 트리 밖의 설치본이라
+    // Gradle 이 입력으로 보지 못한다. 명시하지 않으면 카탈로그만 바뀐 상황에서 test 가 UP-TO-DATE 로 건너뛰어
+    // 어긋난 채 초록불이 된다(실측). optional 인 이유: 미설치 환경에서 파일 부재로 task 구성이 깨지지 않게 —
+    // 부재 자체는 그 테스트가 실패로 판정한다.
+    inputs
+        .files(layout.projectDirectory.file("shared-infra/contracts/extraction-error-codes.yaml"))
+        .withPropertyName("extractionErrorCatalog")
+        .withPathSensitivity(PathSensitivity.RELATIVE)
+        .optional()
 }
 
 // Spring Boot 플러그인은 실행 가능한 boot jar 와 라이브러리용 plain jar 를 함께 만든다. 이 앱은 라이브러리로

src/main/kotlin/com/depromeet/piki/item/service/AsyncImageParsingWorker.kt

@@ -6,7 +6,6 @@ import com.depromeet.piki.common.exception.HttpMappable
 import com.depromeet.piki.common.storage.ImageStorage
 import com.depromeet.piki.image.service.ImageSnapshotExtractor
 import com.depromeet.piki.product.service.ProductSnapshot
-import com.depromeet.piki.product.service.ProductSnapshotException
 import io.micrometer.core.instrument.MeterRegistry
 import io.micrometer.observation.Observation
 import io.micrometer.observation.ObservationRegistry
@@ -153,7 +152,7 @@ class AsyncImageParsingWorker(
         }
         // 확정 실패 — 상품 아님·추출값 신뢰 불가 등. 다시 해도 결과가 같으니 즉시 FAILED + raw 회수.
         // 단 전이가 실제로 적용됐을 때만이다 — 좀비 폐기·전이 실패면 결과를 세지도, raw 를 지우지도 않는다.
-        val reason = reasonOf(e)
+        val reason = ItemParsingMetrics.reasonOf(e)
         if (!markFailedQuietly(itemId, snapshotId, attempt)) return
         log.info(
             "item.parse.result item={} type=image result={} reason={} latency={}ms",
@@ -167,12 +166,6 @@ class AsyncImageParsingWorker(
         deleteRawQuietly(imageKey)
     }
 
-    private fun reasonOf(e: Throwable): String =
-        when (e) {
-            is ProductSnapshotException -> ItemParsingMetrics.REASON_NOT_PRODUCT
-            else -> ItemParsingMetrics.REASON_PERMANENT_ERROR
-        }
-
     // raw 원본 회수는 best-effort — 삭제 실패가 파싱 결과(이미 READY/FAILED 확정)를 되돌리지 않는다.
     // 회수 못 한 raw 와 recover 상한 FAILED·유실분은 items/raw/ S3 lifecycle 이 백업으로 만료한다.
     private fun deleteRawQuietly(imageKey: String) {

src/main/kotlin/com/depromeet/piki/item/service/AsyncItemParsingWorker.kt

@@ -6,7 +6,6 @@ import com.depromeet.piki.common.exception.HttpMappable
 import com.depromeet.piki.product.domain.ProductLink
 import com.depromeet.piki.product.service.ProductLinkExtractor
 import com.depromeet.piki.product.service.ProductSnapshot
-import com.depromeet.piki.product.service.ProductSnapshotException
 import io.micrometer.core.instrument.MeterRegistry
 import io.micrometer.observation.Observation
 import io.micrometer.observation.ObservationRegistry
@@ -153,9 +152,9 @@ class AsyncItemParsingWorker(
             releaseQuietly(itemId, snapshotId, attempt)
             return
         }
-        // 확정 실패 — 상품 아님·추출값 신뢰 불가·호스트 차단·4xx 접근 불가 등. 같은 URL 을 다시 파싱해도 결과가
-        // 같으므로 즉시 FAILED 로 종결한다(사용자에게 빨리 알림). 클라이언트 입력 계약 위반이라 서버 입장에선 정상 동작(info).
-        val reason = reasonOf(e)
+        // 확정 실패 — 상품 아님·못 읽음·값 불신·대상 차단 등. 같은 URL 을 다시 파싱해도 결과가 같으므로
+        // 즉시 FAILED 로 종결한다(사용자에게 빨리 알림). 사유는 예외가 들고 온 bucket 에서 파생한다.
+        val reason = ItemParsingMetrics.reasonOf(e)
         // 전이가 실제로 적용됐을 때만 결과를 원장에 남긴다 — 좀비 폐기·전이 실패면 이 워커의 결과는 반영되지 않았다.
         if (!markFailedQuietly(itemId, snapshotId, attempt)) return
         log.info(
@@ -171,14 +170,6 @@ class AsyncItemParsingWorker(
         ItemParsingMetrics.record(meterRegistry, ItemParsingMetrics.RESULT_FAILED, reason)
     }
 
-    // 확정 실패의 메트릭 reason. 상품 아님·추출값 신뢰 불가(ProductSnapshotException)는 not_product 로 따로 센다
-    // (대시보드에서 "상품 아님"을 구분). 그 외 재시도 무의미 오류(원격 422 확정 실패 — 호스트 차단·4xx 등의 원격 번역)는 permanent_error.
-    private fun reasonOf(e: Throwable): String =
-        when (e) {
-            is ProductSnapshotException -> ItemParsingMetrics.REASON_NOT_PRODUCT
-            else -> ItemParsingMetrics.REASON_PERMANENT_ERROR
-        }
-
     // 소유권 반납 — 실패해도 흡수한다. 반납은 **지연 단축 장치이지 정합성 장치가 아니다**: 반납이 안 되면 그 행은
     // 예전처럼 stale 회수(마지막 박동 + 60s)가 늦게라도 잡고, 그래도 안 되면 마감이 끊는다. 그래서 여기서 던지지 않는다.
     // 레이스로 이미 마감 종결됐거나 소유권을 잃었으면 서비스가 false 를 주거나 entity check 가 던지고, 둘 다 정상 상황이다.

src/main/kotlin/com/depromeet/piki/item/service/ItemParsingMetrics.kt

@@ -1,5 +1,8 @@
 package com.depromeet.piki.item.service
 
+import com.depromeet.piki.common.exception.HttpMappable
+import com.depromeet.piki.product.service.ExtractionFailureBucket
+import com.depromeet.piki.product.service.ExtractionFailureCode
 import io.micrometer.core.instrument.MeterRegistry
 
 // 파싱 단건의 종결 결과(READY/FAILED)를 result·reason 라벨로 센다 — 추출 실패가 트래픽에서 얼마나·왜 나는지 관측한다(#506).
@@ -17,12 +20,24 @@ object ItemParsingMetrics {
     // 성공.
     const val REASON_NONE = "none"
 
-    // 워커 확정 실패 — 상품 페이지 아님·추출값 신뢰 불가(ProductSnapshotException). 클라이언트 입력 계약 위반.
+    // 워커 확정 실패 5종 — "이 숫자가 늘면 누가 무엇을 하는가"로 나눈다(#936). 값은 계약 카탈로그
+    // (shared-infra/contracts/extraction-error-codes.yaml)의 bucket 과 같은 문자열이어야 한다: 원격 code 를
+    // 우리 예외로 번역할 때 붙는 bucket 이 그대로 이 라벨이 되고, ExtractionErrorCatalogTest 가 셋을 대조한다.
+
+    // 사용자가 상품 아닌 걸 넣음. 정상 트래픽이라 할 일이 없다.
     const val REASON_NOT_PRODUCT = "not_product"
 
-    // 워커 확정 실패 — 재시도 무의미한 외부 오류(호스트 차단·4xx 접근 불가·redirect 비정상·Gemini 영구 오류).
-    // ErrorCategory 가 RETRYABLE 이 아니라 즉시 종결한 경우다. not_product(상품 아님)와 구분해 별도로 센다.
-    const val REASON_PERMANENT_ERROR = "permanent_error"
+    // 우리 구성으로 그 페이지를 못 읽음. 늘면 그 도메인의 허가 후보를 본다.
+    const val REASON_UNREADABLE = "unreadable"
+
+    // 대상이 우리를 막음. 늘면 UNSUPPORTED 정책 후보를 본다.
+    const val REASON_BLOCKED = "blocked"
+
+    // 추출은 됐는데 값을 믿을 수 없음. 늘면 모델·프롬프트·검증 규칙을 본다.
+    const val REASON_EXTRACT_QUALITY = "extract_quality"
+
+    // 우리 버그·방어 발동, 또는 매핑되지 않은 원격 code. 늘면 코드를 조사한다.
+    const val REASON_INTERNAL_ERROR = "internal_error"
 
     // 추출은 됐으나 READY 전이가 값 검증에 막힘(이름 없음 등).
     const val REASON_READY_REJECTED = "ready_rejected"
@@ -45,4 +60,22 @@ object ItemParsingMetrics {
     ) {
         registry.counter(METRIC, TAG_RESULT, result, TAG_REASON, reason).increment()
     }
+
+    // 확정 실패 예외 → reason 라벨. 분류의 정본은 예외가 참조하는 ErrorCode 의 bucket 이고(ExtractionFailureCode),
+    // 여기서는 그 bucket 을 라벨 문자열로 옮기기만 한다 — 원격 code 가 늘어도 이 함수는 그대로다.
+    // when 이 exhaustive 라, bucket 이 추가되면 라벨을 정하지 않은 채로는 컴파일되지 않는다.
+    //
+    // bucket 을 못 얻는 경우(분류 밖 예외 — 코드 버그성 NPE·JVM Error, 또는 매핑되지 않은 원격 code)는
+    // internal_error 다. 그 자리는 "우리가 이름을 아는 실패"가 아니라 조사 대상이라는 뜻이므로, 이름 없는
+    // 실패를 다른 바구니에 섞지 않는다. 링크·이미지 두 워커가 같은 함수를 쓴다(같은 메트릭 모집단).
+    fun reasonOf(e: Throwable): String {
+        val bucket = ((e as? HttpMappable)?.errorCode as? ExtractionFailureCode)?.bucket ?: return REASON_INTERNAL_ERROR
+        return when (bucket) {
+            ExtractionFailureBucket.NOT_PRODUCT -> REASON_NOT_PRODUCT
+            ExtractionFailureBucket.UNREADABLE -> REASON_UNREADABLE
+            ExtractionFailureBucket.BLOCKED -> REASON_BLOCKED
+            ExtractionFailureBucket.EXTRACT_QUALITY -> REASON_EXTRACT_QUALITY
+            ExtractionFailureBucket.INTERNAL_ERROR -> REASON_INTERNAL_ERROR
+        }
+    }
 }

src/main/kotlin/com/depromeet/piki/product/service/ExtractionFailureBucket.kt

@@ -0,0 +1,34 @@
+package com.depromeet.piki.product.service
+
+import com.depromeet.piki.common.exception.ErrorCode
+
+// 확정 실패(원격 422)를 **운영 액션 축**으로 나눈 분류(#936). "이 숫자가 늘면 누가 무엇을 하는가"가 기준이라,
+// 실패의 기술적 원인이 아니라 대응이 같은 것끼리 묶인다.
+// 계약 카탈로그(shared-infra/contracts/extraction-error-codes.yaml)의 bucket 과 1:1 이고, 파싱 메트릭의
+// reason 라벨(ItemParsingMetrics)도 여기서 파생한다 — 셋(카탈로그·예외·메트릭)이 어긋나면
+// ExtractionErrorCatalogTest 가 잡는다.
+enum class ExtractionFailureBucket {
+    // 사용자가 상품 아닌 걸 넣었다. 정상 트래픽이라 할 일이 없다.
+    NOT_PRODUCT,
+
+    // 우리 구성으로 그 페이지를 못 읽었다(빈 셸·추출할 본문 없음). 늘면 도메인 허가 후보를 본다.
+    UNREADABLE,
+
+    // 대상이 우리를 막았다. 늘면 UNSUPPORTED 정책 후보를 본다.
+    BLOCKED,
+
+    // 추출은 됐는데 값을 믿을 수 없다. 늘면 모델·프롬프트·검증 규칙을 본다.
+    EXTRACT_QUALITY,
+
+    // 우리 버그이거나 우리 방어가 발동했다. 늘면 코드를 조사한다.
+    INTERNAL_ERROR,
+}
+
+// 확정 실패 예외가 자기 bucket 을 스스로 밝히게 하는 ErrorCode. 예외 클래스가 늘어도 워커는 이 인터페이스만
+// 보므로 reason 파생 경로가 한 줄로 유지되고, bucket 은 code 정의 옆(single source)에 박힌다.
+//
+// bucket 이 nullable 인 이유: 일시(transient) code 는 bucket 이 없다(카탈로그도 같은 모양). 일시 실패는
+// 소유권 반납으로 되살아나 종결 집계(reason)에 닿지 않고, 상한을 소진하면 recover 가 retry_exhausted 로 센다.
+interface ExtractionFailureCode : ErrorCode {
+    val bucket: ExtractionFailureBucket?
+}

src/main/kotlin/com/depromeet/piki/product/service/ProductSnapshotErrorCode.kt

@@ -1,25 +1,51 @@
 package com.depromeet.piki.product.service
 
 import com.depromeet.piki.common.exception.ErrorCategory
-import com.depromeet.piki.common.exception.ErrorCode
 
 // ProductSnapshotException 의 code 배정표(에픽 #728). 번호는 append-only — 재배치·결번 침범 금지.
 //
 // ⚠️ 이 enum 은 ErrorCodeRegistry.all 에 **의도적으로 등록하지 않는다**(AnnouncementImageErrorCode 와 같은 선례).
 // 유일한 생성 경로인 ProductSnapshot.fromExtracted · RemoteExtractionContract.translate 는 비동기 파싱
 // 워커(AsyncItemParsingWorker · AsyncImageParsingWorker)에서만 호출된다 — 워커가 예외를 잡아 item 을 FAILED 로
-// 전이시키고 메트릭 reason=not_product 로 집계할 뿐, GlobalExceptionHandler 를 거치지 않아 응답 code 로 나가지 않는다.
+// 전이시키고 메트릭 reason(아래 bucket 에서 파생)으로 집계할 뿐, GlobalExceptionHandler 를 거치지 않아 응답 code 로 나가지 않는다.
 // 클라가 절대 받을 수 없는 code 를 공개 카탈로그에 넣으면 code→문구 매핑에 노이즈만 된다.
 // 여기서 code 를 부여하는 목적은 오직 예외 클래스 모양을 다른 도메인 예외와 통일(errorCode 참조)하는 것뿐이다.
+//
+// bucket 은 그 실패를 메트릭에서 무엇으로 셀지의 정본이다(#936) — 파싱 메트릭 reason 이 여기서 파생하므로,
+// code 를 더할 때 bucket 도 함께 정한다. 원격 code → 여기의 어느 엔트리인지는 RemoteExtractionContract 가 정한다.
 enum class ProductSnapshotErrorCode(
     override val code: String,
     override val category: ErrorCategory,
     override val message: String,
-) : ErrorCode {
+    override val bucket: ExtractionFailureBucket,
+) : ExtractionFailureCode {
     // LLM 이 "상품 페이지가 아님"으로 판정. 링크 재등록·재시도 모두 무의미.
-    NOT_PRODUCT_PAGE("SNAPSHOT-001", ErrorCategory.INVALID_INPUT, "상품 페이지 링크만 등록할 수 있어요."),
+    NOT_PRODUCT_PAGE(
+        "SNAPSHOT-001",
+        ErrorCategory.INVALID_INPUT,
+        "상품 페이지 링크만 등록할 수 있어요.",
+        ExtractionFailureBucket.NOT_PRODUCT,
+    ),
 
     // 추출값이 유효 범위(가격 음수, 컬럼 길이 초과 등)를 벗어남. 추출 결과를 신뢰할 수 없다.
     // 구체 사유(어느 필드가 왜)는 message 에 담지 않고 로그로 남긴다.
-    UNTRUSTWORTHY_VALUE("SNAPSHOT-002", ErrorCategory.INVALID_INPUT, "상품 정보를 확인하지 못했어요. 직접 입력해 주세요."),
+    // bucket 이 not_product 가 아닌 이유(#936): "상품 아님"과 성격이 다르고 — 추출 자체는 됐는데 값을 못 믿는 것 —
+    // 대응도 모델·프롬프트·검증 규칙 쪽이라, 한 통에 두면 "상품 아님" 지표가 두 배로 부풀어 판단을 흐린다.
+    UNTRUSTWORTHY_VALUE(
+        "SNAPSHOT-002",
+        ErrorCategory.INVALID_INPUT,
+        "상품 정보를 확인하지 못했어요. 직접 입력해 주세요.",
+        ExtractionFailureBucket.EXTRACT_QUALITY,
+    ),
+
+    // 우리가 그 페이지에서 읽어낼 본문을 얻지 못함(데이터 없는 CSR 셸·가시 텍스트 부재). 상품이 아닌 게 아니라
+    // **지금 우리 구성으로 못 읽는** 것이라 도메인 허가 후보를 찾는 신호다.
+    // message 는 UNTRUSTWORTHY_VALUE 와 같다 — 사용자가 취할 행동(직접 입력)이 같고, 구분은 detail 이 아니라
+    // bucket·로그가 진다(CLAUDE.md 메시지 톤).
+    NO_EXTRACTABLE_CONTENT(
+        "SNAPSHOT-003",
+        ErrorCategory.INVALID_INPUT,
+        "상품 정보를 확인하지 못했어요. 직접 입력해 주세요.",
+        ExtractionFailureBucket.UNREADABLE,
+    ),
 }

src/main/kotlin/com/depromeet/piki/product/service/ProductSnapshotException.kt

@@ -23,5 +23,9 @@ class ProductSnapshotException private constructor(
 
         // 추출값이 유효 범위(가격 음수, 컬럼 길이 초과 등)를 벗어남. 추출 결과를 신뢰할 수 없다.
         fun untrustworthyValue(): ProductSnapshotException = ProductSnapshotException(ProductSnapshotErrorCode.UNTRUSTWORTHY_VALUE)
+
+        // 읽어낼 본문이 없어 추출이 성립하지 않음(데이터 없는 CSR 셸·가시 텍스트 부재). 상품이 아닌 것과 구분한다 —
+        // 같은 URL 을 지금 구성으로 다시 읽어도 결과가 같으므로 재시도는 무의미하다.
+        fun noExtractableContent(): ProductSnapshotException = ProductSnapshotException(ProductSnapshotErrorCode.NO_EXTRACTABLE_CONTENT)
     }
 }