> ## 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

# 電商

工作區商品與訂單，單向推進的生命週期。

## 初學者演練

先決條件：閱讀下面的兩個初學者指南，完成 Web 本地設定，並在編輯器的根目錄中開啟此 monorepo。網頁設定屬於`apps/web/.env.local`； Next.js不讀取根`.env`。預設fake模式下的`/dashboard`是無資料庫演示； `/auth` 需要遷移資料庫。

簡而言之：工作區是一個團隊的單獨使用者、資料和設定。伺服器是可信後端；讓提供商金鑰遠離瀏覽器和電話程式碼。遷移是建立或更新表的版本化資料庫更改。人工智慧模型是回答的引擎；型號目錄是伺服器上可用型號 ID 和價格的列表。提供商是一種外部服務，例如人工智慧、電子郵件或計費服務。權利是允許工作區使用某項功能的授權。 Webhook 是一個服務傳送到另一個服務的 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/zh-tw/docs/web/before-you-start.md)

[終端基礎知識](https://supastack.dev/zh-tw/docs/web/terminal-basics.md)

[網路本地設定](https://supastack.dev/zh-tw/docs/web/ship-in-5-minutes.md)

[座席提示和專案記憶體](https://supastack.dev/zh-tw/docs/web/agents.md)


## 管理產品和庫存

`/commerce` 為工作區產品提供所有者/管理員管理。產品狀態為草稿/活動/存檔；價格使用次要貨幣單位，並且可以選擇跟蹤庫存。共享的永續性存在於 `packages/db` 中。

這是一個產品構建模組。它不包括購買該套件、源儲存庫交付或賣方許可證履行。


## 遵循訂單生命週期

訂單提前待處理 → 已付款 → 已履行，具有取消/補貨和退款行為。伺服器計算總計並儲存專案產品名稱/單價快照，因此對產品的編輯不會重寫歷史訂單。 `commerce.order_*` 事件支援下游整合。

刻意連線真實的產品支付流程。僅管理狀態轉換並不能驗證支付提供商的收費或退款。


## 測試庫存和狀態轉換

驗證庫存不足、併發訂單、客戶價格篡改、無效向後轉換、取消補貨、退款行為和跨工作空間訪問。

[出境商務活動](https://supastack.dev/zh-tw/docs/web/project-structure.md)

[產品網格塊](https://supastack.dev/zh-tw/docs/web/project-structure.md)

[記錄表塊](https://supastack.dev/zh-tw/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 webhook 以及審計行。


## 驗證與排障

驗證 admin 以下的 member 無法建立商品或移動訂單，反向與橫向轉換被拒絕，已支付訂單不可取消。確認總價來自服務端——絕不信任客戶端提交的金額——並確認取消後庫存會回補。


## 下一篇

[營銷頁面](https://supastack.dev/zh-tw/docs/web/marketing-site.md)