추출 계약 문서를 부분값 성공 규약으로 갱신

[m-a-king]

Situation

• 추출 응답 계약이 바뀌었는데 정본 문서가 옛 규약을 그대로 말하고 있었다. core 는 부분값을 INCOMPLETE 상태로 수용하고(추출 부분값을 INCOMPLETE 로 수용하고 유저 입력으로 완성한다 core#945), extractor 는 값이 하나라도 있으면 200 으로 내려보낸다(추출 부분값을 200 으로 반환하고 크롭 불가 포맷의 위장 업로드를 고친다 extractor#37).
• 계약 정본이 구현과 어긋난 채 남으면, 이 문서를 근거로 삼는 다음 작업이 틀린 가정을 하게 된다. 정본을 공용 repo 로 올린 이유 자체가 사본이 조용히 어긋나는 것을 막기 위해서였다.

Task

• 응답 규약을 "세 필드 non-null 보장" 에서 실제 동작으로 맞춘다.
• 이미지 경로 서술도 함께 낡았다. 크롭 불가 포맷의 위장 업로드를 고치면서 업로드 object key 가 항상 .png 가 아니게 됐다.

Action

네 자리를 고쳤다.

자리	전	후
link 성공 규약	세 필드 non-null 을 Extractor 가 보장, 못 채우면 422	하나라도 채우면 200, 하나도 못 채우면 422
책임 소재	Extractor 단독 보장	Extractor 가 채운 만큼 + 사용자가 나머지
이미지 업로드 key	items/{uuid}.png 고정	결과물을 따름: 크롭했으면 png, 원본 그대로면 원본 확장자·content-type
UNTRUSTWORTHY_VALUE 설명	non-null 보장을 못 채웠다	값을 하나도 못 채웠다 (일부만 채운 결과는 200)

• 왜 규약을 풀었는지도 문서에 남겼다. 사진에 가격이 박혀 있지 않은 것은 정상 입력이라, 셋을 다 요구하면 "쇼핑몰 화면 캡처" 만 통과하는 계약이 된다. 규칙만 바꾸고 이유를 안 남기면 다음 사람이 되돌리기 쉽다.
• 이미지 경로의 imageUrl 은 여전히 항상 non-null 이라는 점을 명시했다. 업로드 결과라 크롭에 실패해도 원본이 올라가서, 그 경로가 값 0개로 422 가 되는 일은 사실상 없다.
• contracts/extraction-error-codes.yaml 은 code 집합과 disposition 이 그대로라 건드리지 않았다. 각 repo 의 메타 테스트가 이 카탈로그와 코드를 대조하므로, 불필요하게 만지면 양쪽 CI 만 흔든다.

Result

• 세 repo 의 서술이 한 방향으로 맞는다. 이 문서, core 의 상태 모델, extractor 의 응답 경계가 같은 규약을 말한다.
• 이 PR 은 문서만 바꾸므로 배포 순서와 무관하다. 다만 구현 PR 두 개(core 먼저, extractor 나중)가 머지되기 전에 이 문서가 먼저 머지되면, 짧은 기간 문서가 구현보다 앞선 상태가 된다.

---

연관 이슈

• close 추출 계약 문서를 부분값 성공 규약으로 갱신한다 #47

[coderabbitai]

Important

Review available on request

• 🔍 Trigger review

Reviews should be triggered manually for repositories with fewer than 10 stars. Select Trigger review above or comment @coderabbitai review to review the latest changes. For a full review, comment @coderabbitai full review.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: eb988a35-0510-47d5-b2fe-56869fa69a55

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}