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

# コマース

前進のみのライフサイクル上のワークスペース商品と注文。

## 初心者向けのウォークスルー

前提条件: 以下の 2 つの初心者向けガイドを読み、Web ローカルのセットアップを完了し、エディターでルートにあるこのモノリポジトリを開きます。 Web 設定は `apps/web/.env.local` に属します。 Next.js はルート `.env` を読み取りません。デフォルトのフェイク モードの `/dashboard` はデータベースなしのデモです。 `/auth` には移行されたデータベースが必要です。

簡単に説明すると、ワークスペースは 1 つのチームの個別のユーザー、データ、設定です。サーバーは信頼できるバックエンドです。プロバイダー キーがブラウザーや電話コードに含まれないようにします。移行は、テーブルを作成または更新する、バージョン管理されたデータベースの変更です。 AI モデルは答えを返すエンジンです。モデル カタログは、使用可能なモデル ID と価格のサーバーのリストです。プロバイダーは、AI、電子メール、請求サービスなどの外部サービスです。資格は、ワークスペースで機能を使用できるようにする付与です。 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/ja/docs/web/before-you-start.md)

【端末の基本】(/docs/web/terminal-basics)

[Webローカル設定](https://supastack.dev/ja/docs/web/ship-in-5-minutes.md)

[エージェント プロンプトとプロジェクト メモリ](https://supastack.dev/ja/docs/web/agents.md)


## 商品と在庫を管理する

`/commerce` は、ワークスペース製品の所有者/管理者管理を提供します。製品の状態はドラフト/アクティブ/アーカイブです。価格にはマイナー通貨単位が使用され、在庫はオプションで追跡されます。共有永続性は `packages/db` にあります。

これは製品構築モジュールです。これには、このキットの購入、ソース リポジトリの配信、販売者ライセンスの履行は含まれません。


## 注文のライフサイクルに従ってください

注文は事前に保留中→支払い済み→履行され、キャンセル/再入荷および返金動作が行われます。サーバーは合計を計算し、商品の製品名/単価のスナップショットを保存するため、製品を編集しても注文履歴が書き換えられることはありません。 `commerce.order_*` イベントは、ダウンストリーム統合をサポートします。

実際の商品の支払いフローを意図的に接続します。管理状態の遷移だけでは、支払いプロバイダーの請求や払い戻しは検証されません。


## ストックと状態遷移をテストする

不十分な在庫、同時注文、クライアント価格の改ざん、無効な後方移行、キャンセルの補充、返金動作、クロスワークスペース アクセスを検証します。

[アウトバウンドコマースイベント](https://supastack.dev/ja/docs/web/project-structure.md)

【製品グリッドブロック】(/docs/web/project-structure)

[レコードテーブルブロック](https://supastack.dev/ja/docs/web/project-structure.md)


## インストールとセットアップ

/commerce サーフェスはアクティブなワークスペースの商品カタログと注文を管理します。商品は名前、slug、整数セントの価格、3 文字の通貨、任意の画像 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 未満のメンバーが商品を作成したり注文を動かしたりできないこと、後退・横方向の遷移が拒否されること、支払い済み注文がキャンセルできないことを検証してください。合計がサーバー由来であること — クライアント提供の金額を信頼しないこと — そしてキャンセル後に在庫が戻ることを確認します。


## 次へ

[マーケティングページ](https://supastack.dev/ja/docs/web/marketing-site.md)