> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 커머스

단방향 라이프사이클 위의 워크스페이스 상품과 주문.

## 초보자 연습

전제 조건: 아래 두 개의 초보자 가이드를 읽고, 웹 로컬 설정을 완료하고, 편집기의 루트에서 이 모노레포를 엽니다. 웹 설정은 `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/` 미러를 읽도록 요청하세요. 여기에 이름이 지정된 정확한 소스 파일을 검사하십시오. 편집하기 전에 파일을 나열하고 확인합니다. 작업 공간 소유권과 서버 전용 비밀을 보존합니다. 차이점을 보여주세요. 원하는 동작, 입력 및 출력 필드, 허용된 역할, 예상되는 성공 및 오류, 테스트 계정, 공급자 또는 장치를 알려주십시오. 샘플 값을 사용하십시오. 절대 진짜 비밀을 붙여넣지 마세요.

[시작하기 전에](https://supastack.dev/ko/docs/web/before-you-start.md)

[단말기 기본사항](https://supastack.dev/ko/docs/web/terminal-basics.md)

[웹 로컬 설정](https://supastack.dev/ko/docs/web/ship-in-5-minutes.md)

[에이전트 프롬프트 및 프로젝트 메모리](https://supastack.dev/ko/docs/web/agents.md)


## 제품 및 재고 관리

`/commerce`는 작업 공간 제품에 대한 소유자/관리자 관리 기능을 제공합니다. 제품 상태는 초안/활성/보관됨입니다. 가격은 소수 통화 단위를 사용하며 재고는 선택적으로 추적됩니다. 공유 지속성은 `packages/db`에 있습니다.

이것은 제품 구축 모듈입니다. 이 키트 구매, 소스 리포지토리 전달 또는 판매자 라이센스 이행은 포함되지 않습니다.


## 주문 수명주기를 따르세요

주문 보류 → 결제 → 이행, 취소/재입고 및 환불 동작이 발생합니다. 서버는 총계를 계산하고 항목 제품 이름/단가 스냅샷을 저장하므로 제품을 편집해도 기록 주문이 다시 작성되지 않습니다. `commerce.order_*` 이벤트는 다운스트림 통합을 지원합니다.

실제 상품 결제 흐름을 의도적으로 연결해보세요. 관리자 상태 전환만으로는 결제 제공업체의 청구 또는 환불을 확인할 수 없습니다.


## 테스트 재고 및 상태 전환

재고 부족, 동시 주문, 고객 가격 변조, 잘못된 이전 전환, 재입고 취소, 환불 동작 및 작업공간 간 액세스를 확인합니다.

[아웃바운드 커머스 이벤트](https://supastack.dev/ko/docs/web/project-structure.md)

[제품 그리드 블록](https://supastack.dev/ko/docs/web/project-structure.md)

[레코드 테이블 블록](https://supastack.dev/ko/docs/web/project-structure.md)


## 설치 및 설정

/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 미만 멤버가 상품을 만들거나 주문을 옮길 수 없는지, 역방향·측방향 전환이 거부되는지, 결제된 주문이 취소될 수 없는지 확인하세요. 합계가 서버에서 오는지 — 클라이언트 제공 금액을 신뢰하지 말 것 — 그리고 취소 후 재고가 돌아오는지 확인하세요.


## 다음

[마케팅 페이지](https://supastack.dev/ko/docs/web/marketing-site.md)