コマース

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

前提条件: 以下の 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/ ミラーを読み取るように依頼します。ここで指定されている正確なソース ファイルを調べてください。ファイルをリストし、編集前にチェックします。ワークスペースの所有権とサーバーのみの秘密を保持します。そして差分を見せてください。必要な動作、入力フィールドと出力フィールド、許可されるロール、予想される成功とエラー、テスト アカウント、プロバイダー、またはデバイスを指定します。サンプル値を使用します。絶対に本当の秘密を貼り付けないでください。

• 始める前に

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

• Webローカル設定
• エージェント プロンプトとプロジェクト メモリ

商品と在庫を管理する

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

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

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

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

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

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

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

• アウトバウンドコマースイベント

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

• レコードテーブルブロック

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

/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 未満のメンバーが商品を作成したり注文を動かしたりできないこと、後退・横方向の遷移が拒否されること、支払い済み注文がキャンセルできないことを検証してください。合計がサーバー由来であること — クライアント提供の金額を信頼しないこと — そしてキャンセル後に在庫が戻ることを確認します。