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 /tr/docs/web/commerce.md (or send Accept: text/markdown).
E-ticaret
İleri yönlü yaşam döngüsünde çalışma alanı ürünleri ve siparişleri.
Başlangıç seviyesinde izlenecek yol
Önkoşullar: Aşağıdaki iki başlangıç kılavuzunu okuyun, Web yerel kurulumunu tamamlayın ve bu monorepo'yu düzenleyicinizde kökünden açın. Web ayarları apps/web/.env.local'ye aittir; Next.js, .env kökünü okumaz. Varsayılan sahte modda /dashboard, veritabanı olmayan bir demodur; /auth'nin taşınan bir veritabanına ihtiyacı var.
Kısa terimler: Çalışma alanı, bir ekibin ayrı kullanıcıları, verileri ve ayarlarıdır. Sunucu güvenilir arka uçtur; sağlayıcı anahtarlarını tarayıcı ve telefon kodundan uzak tutun. Geçiş, tabloları oluşturan veya güncelleyen sürümlü bir veritabanı değişikliğidir. Yapay zeka modeli yanıt veren motordur; model kataloğu, sunucunun mevcut model kimlikleri ve fiyatlarının listesidir. Sağlayıcı yapay zeka, e-posta veya faturalandırma hizmeti gibi bir dış hizmettir. Yetki, bir çalışma alanının bir özelliği kullanmasına olanak tanıyan bir yetkidir. Web kancası, bir hizmetin başka bir hizmetin URL'sine gönderdiği bir mesajdır.
1. Çalışma alanı sahibi veya yöneticisi olarak /commerce'yi açın ve ürün formunu kullanarak ad, para birimi, tamsayı küçük birim fiyatı ve isteğe bağlı takip edilen stok (USD için 1299, 12,99 ABD doları anlamına gelir) içeren bir taslak oluşturun.
2. Etkinleştirin ve yerel bir test siparişi oluşturun; sunucunun toplamı hesapladığını ve ürünün anlık görüntüsünü sakladığını onaylayın.
3. Canlı ödeme sağlayıcısına bağlanmayın veya gerçek bir alıcıdan ücret talep etmeyin. Bir sipariş ilerleyemiyorsa yeniden denemeden önce mevcut stoğu ve belgelenen sipariş durumunu kontrol edin.
Özel kod için, sağlanan prompts/README.md ile başlayın ve en yakın istemi kopyalayın: Bir uygulama ekranı için prompts/new-app-screen.md veya genel bir sayfa için prompts/new-landing-page.md. Sunucu, veritabanı veya sağlayıcı çalışması için kodlama temsilcinize bu kılavuzun görevini verin ve ondan AGENTS.md, .ai/PROJECT_CONTEXT.md ve eşleşen .ai/ aynalarını okumasını isteyin; burada adı geçen kaynak dosyaların tamamını inceleyin; düzenlemeden önce dosyaları ve kontrolleri listeleyin; çalışma alanı sahipliğini ve yalnızca sunucuya ait sırları koruyun; ve size farkı göstereceğim. İstediğiniz davranışı, giriş ve çıkış alanlarını, izin verilen rolleri, beklenen başarıyı ve hataları ve test hesabını, sağlayıcıyı veya cihazı ona bildirin. Örnek değerleri kullanın; asla gerçek bir sırrı yapıştırmayın.
Ürünleri ve envanteri yönetin
/commerce, çalışma alanı ürünleri için sahip/yönetici yönetimi sağlar. Ürün durumları taslak/etkin/arşivlenmiştir; fiyatlarda küçük para birimleri kullanılır ve envanter isteğe bağlı olarak takip edilir. Paylaşılan kararlılık packages/db'de yaşıyor.
Bu bir ürün oluşturma modülüdür. Bu kitin satın alınması, kaynak deposu teslimatı veya satıcı lisansının yerine getirilmesi buna dahil değildir.
Sipariş yaşam döngüsünü takip edin
İptal/yeniden stoklama ve geri ödeme davranışıyla birlikte ön siparişler beklemede → ödendi → yerine getirildi. Sunucu toplamları hesaplar ve öğenin ürün adı/birim fiyatı anlık görüntülerini saklar, böylece üründe yapılan düzenlemeler geçmiş siparişleri yeniden yazmaz. commerce.order_* olayları aşağı yönlü entegrasyonları destekler.
Gerçek bir ürün ödeme akışını bilinçli olarak bağlayın. Yönetici durumu geçişi tek başına ödeme sağlayıcı ücretini veya geri ödemesini doğrulamaz.
Stok ve durum geçişlerini test edin
Yetersiz envanteri, eşzamanlı siparişleri, müşteri fiyatına müdahaleyi, geçersiz geriye dönük geçişleri, iptal edilen yeniden stoklamayı, geri ödeme davranışını ve çalışma alanları arası erişimi doğrulayın.
Kurulum ve yapılandırma
/commerce yüzeyi, etkin çalışma alanı için bir ürün kataloğu ve siparişleri yönetir. Ürünler ad, slug, tam sayı sent fiyatı, üç harfli para birimi, isteğe bağlı görsel URL'si ve isteğe bağlı stok takibi taşır; siparişler kalemleri commerce_order_item içinde saklar ve toplamlar sunucuda hesaplanır.
Sipariş durumu yalnızca ileri gider — pending → paid → fulfilled; ödemeden önce iptal, ödemeden sonra iade. evaluateOrderStatusChange geçersiz, değişmemiş veya yasak geçişleri reddeder; böylece iptal edilmiş ya da iade edilmiş bir sipariş asla yeniden açılamaz.
/commerce owner/admin console
src/commerce.ts money math + lifecycle
src/commerce-actions.ts owner/admin mutations
commerce_product/order/order_itemUygulama iş akışı
Yalnızca owner ve admin'ler yazar — her eylem requireWorkspaceManager üzerinden oturumu ve çalışma alanını çözer. createCommerceOrderAction kalemleri doğrular (1–9999 arası tam sayı miktarları, yinelenen ürünler birleştirilir), kalemleri aktif ürünlerle sınırlar, toplamları sunucuda yeniden hesaplar ve siparişi tek para biriminde tutar.
Takip edilen stok sipariş oluşturulduğunda azalır ve iptalde geri yüklenir; boş stok alanı takipsiz demektir. Sipariş oluşturma ve her durum değişikliği commerce.order_created ve commerce.order_status_changed webhook'ları ile audit satırları çıkarır.
Doğrulama ve sorun giderme
Admin altındaki bir üyenin ürün oluşturamayacağını veya sipariş taşıyamayacağını, geriye ve yana geçişlerin reddedildiğini ve ödenmiş bir siparişin iptal edilemeyeceğini doğrulayın. Toplamların sunucudan geldiğini — istemciden gelen tutara asla güvenmeyin — ve iptalden sonra stokun geri döndüğünü kontrol edin.