For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ko/docs/web/commerce.md (or send Accept: text/markdown).
커머스
단방향 라이프사이클 위의 워크스페이스 상품과 주문.
초보자 연습
전제 조건: 아래 두 개의 초보자 가이드를 읽고, 웹 로컬 설정을 완료하고, 편집기의 루트에서 이 모노레포를 엽니다. 웹 설정은 apps/web/.env.local에 속합니다. Next.js는 루트 .env를 읽지 않습니다. 기본 가짜 모드의 /dashboard는 데이터베이스가 없는 데모입니다. /auth에는 마이그레이션된 데이터베이스가 필요합니다.
빠른 용어: 작업 영역은 한 팀의 별도 사용자, 데이터 및 설정입니다. 서버는 신뢰할 수 있는 백엔드입니다. 제공업체 키를 브라우저 및 전화 코드에 보관하세요. 마이그레이션은 테이블을 생성하거나 업데이트하는 버전이 지정된 데이터베이스 변경입니다. AI 모델은 응답하는 엔진입니다. 모델 카탈로그는 서버의 사용 가능한 모델 ID 및 가격 목록입니다. 공급자는 AI, 이메일, 청구 서비스와 같은 외부 서비스입니다. 자격은 작업 영역에서 기능을 사용할 수 있도록 하는 부여입니다. 웹훅은 한 서비스가 다른 서비스의 URL에 보내는 메시지입니다.
1. 워크스페이스 소유자 또는 관리자로서 /commerce를 열고 제품 양식을 사용하여 이름, 통화, 정수 소단위 가격 및 선택적 추적 재고(USD의 경우 1299는 $12.99를 의미)가 포함된 초안을 만듭니다.
2. 활성화하고 로컬 테스트 주문을 생성합니다. 서버가 총계를 계산하고 제품 스냅샷을 저장하는지 확인합니다.
3. 실시간 결제 제공업체에 연결하거나 실제 구매자에게 비용을 청구하지 마세요. 주문을 진행할 수 없는 경우 다시 시도하기 전에 사용 가능한 재고와 문서화된 주문 상태를 확인하세요.
사용자 정의 코드의 경우 제공된 prompts/README.md로 시작하고 가장 가까운 프롬프트(앱 화면의 경우 prompts/new-app-screen.md, 공개 페이지의 경우 prompts/new-landing-page.md)를 복사합니다. 서버, 데이터베이스 또는 공급자 작업의 경우 코딩 에이전트에게 이 가이드의 작업을 제공하고 AGENTS.md, .ai/PROJECT_CONTEXT.md 및 일치하는 .ai/ 미러를 읽도록 요청하세요. 여기에 이름이 지정된 정확한 소스 파일을 검사하십시오. 편집하기 전에 파일을 나열하고 확인합니다. 작업 공간 소유권과 서버 전용 비밀을 보존합니다. 차이점을 보여주세요. 원하는 동작, 입력 및 출력 필드, 허용된 역할, 예상되는 성공 및 오류, 테스트 계정, 공급자 또는 장치를 알려주십시오. 샘플 값을 사용하십시오. 절대 진짜 비밀을 붙여넣지 마세요.
제품 및 재고 관리
/commerce는 작업 공간 제품에 대한 소유자/관리자 관리 기능을 제공합니다. 제품 상태는 초안/활성/보관됨입니다. 가격은 소수 통화 단위를 사용하며 재고는 선택적으로 추적됩니다. 공유 지속성은 packages/db에 있습니다.
이것은 제품 구축 모듈입니다. 이 키트 구매, 소스 리포지토리 전달 또는 판매자 라이센스 이행은 포함되지 않습니다.
주문 수명주기를 따르세요
주문 보류 → 결제 → 이행, 취소/재입고 및 환불 동작이 발생합니다. 서버는 총계를 계산하고 항목 제품 이름/단가 스냅샷을 저장하므로 제품을 편집해도 기록 주문이 다시 작성되지 않습니다. commerce.order_* 이벤트는 다운스트림 통합을 지원합니다.
실제 상품 결제 흐름을 의도적으로 연결해보세요. 관리자 상태 전환만으로는 결제 제공업체의 청구 또는 환불을 확인할 수 없습니다.
테스트 재고 및 상태 전환
재고 부족, 동시 주문, 고객 가격 변조, 잘못된 이전 전환, 재입고 취소, 환불 동작 및 작업공간 간 액세스를 확인합니다.
설치 및 설정
/commerce 표면은 활성 워크스페이스의 상품 카탈로그와 주문을 관리합니다. 상품은 이름, slug, 정수 센트 가격, 세 글자 통화, 선택적 이미지 URL, 선택적 재고 추적을 갖고, 주문은 commerce_order_item에 라인 아이템을 저장하며 합계는 서버에서 계산됩니다.
주문 상태는 앞으로만 이동합니다 — pending → paid → fulfilled, 결제 전 취소와 결제 후 환불이 가능합니다. evaluateOrderStatusChange는 유효하지 않거나, 변화 없거나, 금지된 전환을 거부하므로 취소되거나 환불된 주문은 다시 열 수 없습니다.
/commerce owner/admin console
src/commerce.ts money math + lifecycle
src/commerce-actions.ts owner/admin mutations
commerce_product/order/order_item구현 워크플로
owner와 admin만 쓸 수 있습니다 — 모든 액션이 requireWorkspaceManager를 통해 세션과 워크스페이스를 확인합니다. createCommerceOrderAction은 라인 아이템을 검증하고(1–9999의 정수 수량, 중복 상품은 합산), 라인을 활성 상품으로 제한하며, 합계를 서버에서 재계산하고, 주문을 단일 통화로 유지합니다.
추적 재고는 주문 생성 시 감소하고 취소 시 복원됩니다. 재고 필드가 비어 있으면 미추적입니다. 주문 생성과 모든 상태 변경은 commerce.order_created와 commerce.order_status_changed 웹훅과 감사 행을 발생시킵니다.
검증 및 문제 해결
admin 미만 멤버가 상품을 만들거나 주문을 옮길 수 없는지, 역방향·측방향 전환이 거부되는지, 결제된 주문이 취소될 수 없는지 확인하세요. 합계가 서버에서 오는지 — 클라이언트 제공 금액을 신뢰하지 말 것 — 그리고 취소 후 재고가 돌아오는지 확인하세요.