Shop API Schema Mismatch Report

Generated: 2026-03-31 Source: pnpm --filter @makitt/api verify-schemas Total: 64 resources | PASS: 0 | WARN: 38 | FAIL: 12 | SKIP: 14

FAIL 요약 (수정 필요)

#	리소스	문제 유형	수정 방향
1	blog (4개 리소스)	SEO 필드명 불일치	서버 or 클라이언트 통일
2	collection (2개 리소스)	SEO 필드명 불일치	서버 or 클라이언트 통일
3	customer.fieldConfig	타입 불일치	Zod 스키마 수정
4	product.facets	options 구조 불일치	서버 or 클라이언트 통일
5	review.mediaFeed/Modal	count vs cursor	Zod 스키마 수정
6	review.stats	distribution 타입	Zod 스키마 수정
7	action:checkout.create	필드명 대량 불일치	Zod 스키마 전면 수정

1. Blog SEO 필드명 불일치

영향 리소스: blog.blogs, blog.search, blog.blog, blog.detail

Zod (클라이언트)	서버 (OpenAPI)	수정 방향
`seo.title`	`seo.metaTitle`	서버를 `title`로 변경 권장 (HCS 바인딩 간결)
`seo.description`	`seo.metaDescription`	서버를 `description`으로 변경 권장
`seo.canonical`	`seo.canonicalUrl`	서버를 `canonical`로 변경 권장

추가로 서버가 보내지만 Zod에 없는 필드:

blog 목록에서 contentUrl — BlogSchema (목록용)에 없음. BlogDetailSchema에만 있음 → 서버에서 목록 응답 시 contentUrl 제외하거나, BlogSchema에 optional 추가

2. Collection SEO 필드명 불일치

영향 리소스: collection.collection, collection.bySlug

Zod (클라이언트)	서버 (OpenAPI)	수정 방향
`seo.title`	`seo.metaTitle`	Blog과 동일 — 서버를 `title`로 통일
`seo.description`	`seo.metaDescription`	서버를 `description`으로 통일
—	`seo.ogTitle`	Zod에 추가
—	`seo.ogDescription`	Zod에 추가

3. customer.fieldConfig 타입 불일치

필드	Zod	서버	수정 방향
`markets`	`z.record(z.string(), ...)` → 추출 시 `string`	`Map<String, Object>` → `object`	Zod 스키마를 `z.record(z.string(), ShippingFieldConfigSchema)`로 수정

4. product.facets — options 구조 불일치

서버는 ProductDiscoverySectionDto.options에 OptionDto (optionName, optionType, sortOrder, values)를 반환. 클라이언트는 ProductDiscoveryOptionSchema (value, label, count, selected)를 기대.

Zod (클라이언트)	서버 (OpenAPI)	설명
`options[].value`	없음	서버에 없는 필드
`options[].label`	없음	서버에 없는 필드
`options[].count`	없음	서버에 없는 필드
`options[].selected`	없음	서버에 없는 필드
없음	`options[].optionName`	Zod에 없는 필드
없음	`options[].optionType`	Zod에 없는 필드
없음	`options[].sortOrder`	Zod에 없는 필드
없음	`options[].values`	Zod에 없는 필드

수정 방향: 서버 DTO가 HCS 친화적이지 않음. 서버에서 ProductDiscoverySectionDto를 {value, label, count, selected} 구조로 개선하거나, 클라이언트 스키마를 서버에 맞추기. 서버 개선 권장.

5. review.mediaFeed — count vs cursor

Zod (클라이언트)	서버 (OpenAPI)	수정 방향
`count` (number)	없음	Zod에서 제거
없음	`cursor` (object)	Zod에 `cursor: CursorSchema` 추가

추가로 배열 아이템에서 서버만 보내는 필드:

items[].productName, items[].storeItemName, items[].thumbnailUrl, items[].productPrice → ReviewSchema에 4개 필드 추가

6. review.stats — distribution 타입

필드	Zod	서버	수정 방향
`distribution`	`z.record(z.string(), z.number())` → 추출 시 `string`	`Map<Integer, Long>` → `object`	Zod 타입 자체는 맞음. 검증 도구의 `z.record()` 추출 로직 개선 필요 (record를 object로 인식하도록)

7. action:checkout.create — 필드명 대량 불일치

Zod CheckoutResponseSchema (27 필드) vs 서버 CheckoutResponse (34 필드)

클라이언트에만 있는 필드 (서버에 없음 → 삭제)

필드	수정
`shippingMethod`	삭제
`paymentMethodType`	`paymentProcessor`로 변경
`processorType`	삭제 (paymentProcessor와 중복)
`providerType`	삭제

서버에만 있는 필드 (Zod에 추가)

필드	타입
`appliedCoupons`	`array`
`couponDiscountAmount`	`number`
`appliedPromotions`	`array`
`promotionDiscountAmount`	`number`
`appliedPoints`	`number`
`pointsDiscountAmount`	`number`
`rewardSummary`	`object`
`deliveryMemo`	`string`
`entranceMethod`	`string`
`paymentProcessor`	`EnumDto`
`paymentMethod`	`EnumDto`

WARN 주요 항목 (참고)

서버에만 있는 필드 (Zod 추가 권장)

리소스	누락 필드
`product.products/search`	`reviewSummary`, `purchaseInfoSections`, `recommendationSections`
`review.reviews`	`productName`, `storeItemName`, `thumbnailUrl`, `productPrice`
`cart.cart`	`rewardSummary.availablePoints`, `rewardSummary.redeemUnit`, `rewardSummary.maximumRedeemPercent`

nullable_mismatch (서버 @Schema 보강 필요)

대부분의 WARN은 서버 DTO에 @Schema(requiredMode = REQUIRED) 미지정으로 OpenAPI에서 모든 필드가 optional로 표시되는 문제. 서버에서 annotation 보강하면 노이즈 제거됨.

SKIP 14개 (z.any() 스키마)

리소스	사유
`checkout.detail`	`z.any()` (passthrough)
`checkout.availableCoupons`	`z.any()`
`order.list`	`z.any()`
`order.detail`	`z.any()`
`order.statusCounts`	`z.any()`
`customer.stats`	`z.any()`
`customer.membership`	`z.any()`
`customer.search`	`z.array(z.any())`
`blog.tags`	array response
기타	OpenAPI path 매칭 실패

→ 실제 Zod 스키마를 정의하면 자동으로 검증 대상에 포함됨

수정 우선순위 제안

checkout — HCS 체크아웃 플로우에 직접 영향. 필드명 전면 수정
blog/collection SEO — 서버 필드명 통일 (meta prefix 제거)
review — 누락 필드 추가 (productName 등)
product.facets — 서버 DTO 구조 개선 (HCS 친화적으로)
z.any() 스키마 정의 — checkout.detail, order 등