Docs: SDL description 보강 — enum 값·스칼라 인자 (소형, 우선)

[chanwoo7]

배경

SpectaQL(yarn graphql:docs)로 생성되는 GraphQL 문서에서 엔드포인트 요약은 100%인데 그 아래 계층의 설명이 비어 있다. 2026-08-31 SDL AST 전수 측정 결과:

문서에 렌더되는 요소	커버리지
Query/Mutation 필드	100% (113/113)
input 타입 선언	68% (42/62)
input 필드	16% (42/259)
출력 type 선언	73% (82/113)
출력 type 필드	25% (159/648)
enum 선언	72% (13/18)
enum 값	6% (4/62)
스칼라 루트 인자	0%

이 이슈는 그중 개수가 적고 오해 위험이 큰 두 가지만 다룬다. 나머지(input/출력 필드 대량 보강)는 별도 이슈.

항목

1. enum 값 설명 (58개)

값의 의미를 문서만 보고 알 수 없다. 특히 상태 전이가 있는 enum이 위험하다.

• OrderStatusType — SUBMITTED/CONFIRMED/MADE/PICKED_UP/CANCELED. MADE가 "제작 완료"인지 "주문 생성됨"인지 문서상 구분 불가
• HomeBannerLinkType — NONE/URL/PRODUCT/STORE/CATEGORY (각 타입일 때 어떤 필드를 참조해야 하는지)
• CategoryType — EVENT/STYLE (홈 칩 노출 정책과 연결됨)
• 나머지 enum 값 전수 보강

2. 설명이 유일한 자리인 스칼라 인자

루트 인자 102개 중 64개는 input: XxxInput 형태라 설명이 input 타입 쪽에 있으면 되지만, 38개 스칼라/ID 인자는 인자 설명 외에 의미를 적을 자리가 없다. 그중 이름만으로 형식을 알 수 없는 것들:

• pickupCalendar(yearMonth: String) — "2026-09" / "202609" 중 무엇인지 문서에 없음
• pickupTimeSlots(date: String) — 형식 불명
• storePickupCalendar(yearMonth: String) / storePickupTimeSlots(date: String) — 동일
• checkNicknameAvailability(nickname: String) — 길이·문자 제약 불명

productId: ID 류는 이름으로 충분하므로 대상에서 제외한다.

수행 조건

• .graphql 수정 후 yarn graphql:codegen (생성물 diff 확인)
• yarn graphql:docs로 렌더 결과 육안 확인
• 값의 의미를 정책 근거와 함께 적는다 (예: MADE는 셀러가 제작 완료 처리한 상태)

참고

측정 방법: src/**/*.graphql을 graphql 패키지로 파싱해 description 유무를 요소별로 집계. 스크립트는 레포에 남기지 않았으므로, 게이트 이슈에서 scripts/로 정식화할 때 재작성한다.

관련: 대량 보강은 별도 이슈, 커버리지 게이트도 별도 이슈.