헤드리스 WooCommerce API (headless-woocommerce-api)

헤드리스 WooCommerce API (headless-woocommerce-api)은(는) 무엇을 하나요?

WooCommerce 백엔드 API(WPGraphQL 및 REST)를 구성, 쿼리 및 보호하여 디커플드 프론트엔드 애플리케이션(Next.js, Remix, 모바일)을 구동하기 위한 오케스트레이션 가이드입니다.

---

사전 요구 사항

• WordPress가 설치되어 있고 WooCommerce 플러그인이 활성화되어 있어야 합니다.
• GraphQL 엔드포인트에 접근 가능해야 합니다 (기본값: https://your-store.com/graphql).
• 심층 쿼리 및 기술 예제는 headless-api-reference.md를 검토하세요.
• 프론트엔드 클라이언트 설정은 storefront-client.ts를 확인하세요.

---

단계별 실행 체크리스트

flowchart TD
    S1["1. WPGraphQL & WooGraphQL 설치"] --> S2["2. Mock / 라이브 카탈로그 데이터 시드"]
    S2 --> S3["3. 인증 구성 (JWT / OAuth)"]
    S3 --> S4["4. GraphiQL로 스키마 검증"]
    S4 --> S5["5. Next.js에서 클라이언트 쿼리 연결"]

1단계: 백엔드 플러그인 배포

• WPGraphQL 코어 설치:
  • WordPress 플러그인 디렉토리에서 wp-graphql을 설치하고 활성화합니다.
  • 엔드포인트가 활성화되었는지 확인합니다: GET/POST /graphql.
• WooGraphQL 확장 설치:
  • wp-graphql-woocommerce를 다운로드하여 설치합니다.
  • Product, ProductCategory, Cart, Customer 타입이 GraphQL 스키마에 나타나는지 확인합니다.
• 테스트 데이터 시드:
  • 도구 → 가져오기 → WooCommerce 상품 (CSV)를 통해 CSV 임포터를 실행하여 sample-data/sample_products.csv 파일을 가져옵니다.

2단계: 헤드리스 인증 구성

• 옵션 A: JWT 인증 (wp-graphql-jwt-authentication):
  • wp-graphql-jwt-authentication을 업로드하고 활성화합니다.
  • 64자 시크릿 키를 생성합니다 (openssl rand -base64 48 | tr -dc 'A-Za-z0-9_#%+=@!' | head -c 64 또는 PowerShell 동등 명령어).
  • 컨테이너에 주입하거나 (docker exec -it <container> sed -i ... /var/www/html/wp-config.php), .env 파일에 추가하거나 (GRAPHQL_JWT_AUTH_SECRET_KEY), wp-config.php에 직접 추가합니다:

    define( 'GRAPHQL_JWT_AUTH_SECRET_KEY', 'your-strong-random-secret' );
    

• 옵션 B: 헤드리스 로그인 (wp-graphql-headless-login):
  • 외부 OAuth 2.0 / 소셜 로그인(Google, GitHub)이 필요한 경우 사용합니다.
  • 필터 또는 관리자 설정을 통해 제공자를 구성합니다.

3단계: 상점 데이터 쿼리

• 공개 카탈로그: 유니온 프래그먼트(... on SimpleProduct, ... on VariableProduct)를 사용하여 카테고리와 제품을 쿼리합니다.
• 고객 세션: 장바구니 변이 요청 시 woocommerce-session 헤더를 캡처하고 이후 요청에서 전달합니다.
• 보호된 프로필: 고객 주문 및 주소 업데이트를 위해 Authorization: Bearer <authToken>을 전달합니다.

4단계: 프론트엔드 통합 (Next.js)

• 공개 GraphQL 쿼리를 사용하여 정적 제품 페이지에 대해 SSG/ISR을 구현합니다.
• 장바구니 토큰을 클라이언트 측 상태(Zustand / LocalStorage)로 유지하여 Next.js 페이지의 캐시 가능성을 유지합니다.
• 네이티브 체크아웃 브리지 구현: 로컬 결제 게이트웨이 및 전자상거래 규정 준수를 위해 WordPress /checkout으로 리디렉션합니다.

---

엣지 케이스 및 알려진 AI 함정

1. 제품 쿼리의 유니온: WooCommerce 제품은 다형성입니다. products { nodes { price } } 와 같이 직접 price를 쿼리하지 마십시오. 반드시 타입 조건(... on SimpleProduct { price }, ... on VariableProduct { price })을 사용해야 합니다.
2. 세션 헤더 누락: 서버가 반환한 woocommerce-session 토큰이 프론트엔드 클라이언트에 의해 저장되고 재전송되지 않으면 장바구니 항목이 다음 요청에서 사라집니다.
3. 관리자 React 비호환성: 사용자 지정 빌드 단계가 없는 엄격한 코어 WordPress를 사용하는 경우 레거시 Gutenberg 관리 번들이 있는 플러그인(예: wp-graphql-headless-login 설정 패널)을 피하고 상수 기반 플러그인(예: wp-graphql-jwt-authentication)을 고수하십시오.
4. CORS 헤더: 헤더 또는 리버스 프록시를 구성하여 WordPress가 프론트엔드 출처의 요청을 허용하는지 확인하십시오.

---

검증 및 자체 점검

• /graphql에 대한 테스트 쿼리를 실행하여 productCategories와 products가 노드를 반환하는지 확인합니다.
• login 변이를 실행하여 유효한 authToken이 생성되는지 확인합니다.
• 장바구니에 아이템을 추가할 때 woocommerce-session 헤더가 반환되는지 확인합니다.