PETSHOP (pet) Sektörü — FirsatGO POS Entegrasyon Geliştirici Dokümanı

Bu doküman yalnızca petshop (sector=pet, engine=pet) sektörüne özgü alanları ve davranışları açıklar. Ortak sözleşme (HMAC imza, idempotency, finansal kırılım, retry/dead-letter, tenant-izolasyon) için ana POSYOU_INTEGRATION_SPEC dokümanına bakın; burada yalnızca sektör-farkları vurgulanır.

Genel Bakış

Petshop, hızlı-ticaret (retail) modelinde çalışan bir perakende sektörüdür: müşteri sepete SKU bazlı ürün ekler, işletme siparişi toplar/paketler, kargoya/kuryeye verir, teslim edilir. Restoran/market modelinden farkı iki noktadadır: (1) ürünler lot/SKT (son-kullanma-tarihi) takipli olabilir ve stok FEFO (en-erken-SKT-önce) tüketilir; (2) sipariş, evcil-hayvan bağlamı (pet) ve mama aboneliği niteliğinde tekrar-alış (is_repeat/repeat_interval_days) alanları taşıyabilir. State-machine, perakende (retail) ile birebir aynıdır.

Profil (as-built seed):

profile_key=petshop, sector=pet, fulfillment_engine=pet, commission_rate=0.10
order_features: ['cart','stock','repeat_purchase','pet_profile','appointment']
item_attributes: ['barcode','sku','brand','lot','expiry_date','weight']
default_capabilities: ['delivery','pickup'] (ayrıca appointment izinli — bakım/kuaför)
dashboard widget'ları: low_stock, expiring_lots (SKT'si yaklaşan lotlar)

Sipariş Yaşam-Döngüsü

Petshop engine'i pet → state-machine olarak retail haritasını kullanır (ENGINE_TRANSITIONS.pet = RETAIL). OrderStatus enum'u ortaktır; yalnızca durum semantiği perakendeye göre etiketlenir.

Durum (`status`)	Anlam (pet/retail)	Aktör
`pending`	Onay bekliyor	system
`confirmed`	Onaylandı	merchant
`preparing`	Toplanıyor / paketleniyor	merchant
`ready`	Paketlendi	merchant
`on_the_way`	Kargoda / yola çıktı	courier
`delivered`	Teslim edildi	courier
`completed`	Tamamlandı (settlement post)	system
`cancelled`	İptal (stok/kupon iadesi + ledger ters-kayıt)	—

İzinli geçişler (RETAIL):

{
  "pending":    ["confirmed", "preparing", "cancelled"],
  "confirmed":  ["preparing", "cancelled"],
  "preparing":  ["ready", "cancelled"],
  "ready":      ["on_the_way", "completed", "cancelled"],
  "on_the_way": ["delivered", "cancelled"],
  "delivered":  ["completed"],
  "completed":  [],
  "cancelled":  []
}

Restoran (food) engine'inde bulunan payment_pending ara durumu pet akışında yoktur. Akışı/etiketleri canlı sorgulamak için: GET /orders/lifecycle/pet.

POS→FG inbound durum (POS otoriter): confirmed/preparing/ready/on_the_way/delivered/completed/cancelled — order_id veya external_order_id ile. İleri-atlama (ör. pending→completed) izinli ara geçişleri sırayla uygular; erişilemez/geri hedef → gerçek desync (inbox FAILED).

Sektöre-Özel Sipariş Alanları

Pet siparişlerinde fulfillment{} bloğu, profilin order_features'ına göre sunucu-tarafı fail-closed doldurulur. Profilin desteklemediği bir alan gönderilirse istek reddedilir.

fulfillment{} — petshop'ta geçerli alanlar (kaynak: pet_profile + repeat_purchase order-feature'ları):

Alan	Tip	order_feature	Açıklama
`engine`	string	(otomatik)	Siparişe damgalanan engine = `"pet"` (state-machine seçimi).
`pet`	object	`pet_profile`	Evcil-hayvan bilgisi — aşağıdaki alt-alanlar.
`pet.name`	string		Hayvanın adı.
`pet.species`	string		Tür (kedi/köpek/kuş…).
`pet.breed`	string		Cins.
`pet.weight`	number		Ağırlık (mama porsiyonu/öneri için).
`pet.note`	string		Serbest not (alerji vb.).
`is_repeat`	boolean	`repeat_purchase`	Tekrar-alış (mama aboneliği) siparişi mi.
`repeat_interval_days`	number	`repeat_purchase`	Tekrar aralığı (gün) — örn. 30 günde bir mama.
`substitution_policy`	string	`substitution_policy`*	İkame politikası: `none` \| `similar` \| `call_first` \| `refund`.
`delivery_slot`	object	`delivery_slot`*	`{ date, window }` — planlı teslimat (geçmiş-değil, ≤90 gün).

*substitution_policy ve delivery_slot checkout-feature olarak destek altındadır; seed'lenen petshop profilinin order_features'ında yalnızca cart,stock,repeat_purchase,pet_profile,appointment açıktır → standart petshop kurulumunda yalnızca pet/is_repeat/repeat_interval_days gönderilebilir. İkame/slot alanları, ilgili feature işletme profiline eklenmedikçe reddedilir (fail-closed).

İşletme tarafı (operasyon) fulfillment patch'i: petshop için MERCHANT_FEATURE_FIELDS içinde shipment/delivery_proof/route gibi alanlar yalnızca ilgili feature (shipment vb.) profile açıksa kabul edilir; varsayılan petshop seed'inde bu operasyon alanları açık değildir.

items[] — pet kalemleri: Ortak kasa-fişi kalem şekliyle aynıdır (reference_id, name, quantity, original_unit_price(_minor), discounted_price(_minor), extra_price, line_total(_minor), line_discount(_minor), notes). Pet ürünleri menü-malzeme grupları kullanmadığı için selected_ingredients/added_ingredients/removed_ingredients dizileri boş gelir. Lot/SKT bilgisi kalem payload'ında taşınmaz — lot, işletme-içi product_lots stok katmanında tutulur ve FEFO ile tüketilir (aşağıya bakın).

Katalog / Ürün

Pet ürünü RestaurantProduct üzerinde item_kind='pet_product' olarak modellenir. Sektör-özel nitelikler sector_attributes{} içinde, profilin item_attributes'ına göre valide edilir.

Petshop sector_attributes (izinli alanlar):

Attribute	Tip	Açıklama
`barcode`	string	EAN/UPC — POS hızlı arama + FEFO lot ilişkilendirme.
`sku`	string	Stok birim kodu.
`brand`	string	Marka.
`lot`	string	Parti/lot numarası (SKT takibi için).
`expiry_date`	date	Son-kullanma (SKT) — FEFO sıralama + düşük-stok/SKT uyarısı tetikler.
`weight`	number	Ağırlık (kg/g) — kargo maliyeti + FEFO lot takibi.

Lot / SKT stok katmanı (product_lots) — petshop/market/tekel'e özgü:

Her teslim-alım bir lot kaydıdır: lot_no (zorunlu), expiry_date (SKT, opsiyonel), quantity, initial_quantity, barcode, cost_price, status (active/depleted/expired).
FEFO tüketim: sipariş anında en-erken-SKT'li aktif ve süresi-geçmemiş lottan düşülür (decrementFEFO); iptal/iade'de geri yüklenir (incrementFEFO, best-effort).
Süresi geçmiş lot tüketilmez ve kullanılabilir-stoğa sayılmaz (hayalet-stok/oversell önlenir).
Tüm lot işlemleri restaurant_id ile scope'ludur (IDOR-güvenli). Lot-takipli olmayan ürünlerde davranış değişmez (no-op).

Katalog senkronu (NormalizedProduct, POS↔FG ortak şekil): external_id, name, description, price, discounted_price, external_category_id, is_available, stock, images[]. Lot/SKT alanları bu normalize katalog kontratında taşınmaz — lot bilgisi FG iç stok katmanında yönetilir. POS→FG fiyat/stok için: POST /integration/products/:productId/price ve POST /integration/products/:productId/availability (işletme-kapsamlı). stock.* / inventory.* / catalog.product.upserted webhook olayları katalog işleyicisine yönlendirilir.

Akış Notları

State-machine retail ile aynıdır: pet'e özel ayrı geçiş yoktur; preparing=toplama/paketleme, ready=paketlendi, on_the_way=kargo/yolda olarak yorumlanır.
FEFO otoriter claim: lot-takipli ürünlerde stok, sipariş kaydedilmeden önce atomik olarak claim edilir (oversell engellenir); claim edilmişse tekrar-düşüm yapılmaz (çift-düşüm koruması).
SKT görünürlüğü: expiring_lots widget'ı + expiringSoon (varsayılan 30 gün) ile SKT'si yaklaşan lotlar işletmeye gösterilir.
Mama aboneliği: is_repeat=true + repeat_interval_days mama/altlık gibi periyodik tüketimler için tipiktir (supports_repeat_purchase: true). Bunlar fulfillment{} içinde POS'a iletilir; tekrar-tetikleme platform tarafında yönetilir.
Pet bağlamı zorunlu değildir: pet alanı opsiyoneldir; gönderildiğinde profil pet_profile feature'ını açık tutmalıdır, aksi halde fail-closed reddedilir.
Yaş-doğrulama petshop'ta yoktur: age_verification, tekel/alkol profiline aittir. Reçeteli/yaş-kısıtlı pet ürünleri için bu feature ayrıca açılmadıkça age_verified gönderilmez.
appointment kapasitesi: bakım/kuaför hizmeti veren petshop'lar için izinlidir (setup-question offers_grooming), ancak randevu akışı sipariş state-machine'inden ayrıdır.
Finansal kırılım, idempotency (X-FirsatGo-Delivery-Id/event_id), ±5dk replay penceresi, HMAC sha256= imza ve INTEGRATION_LIVE_DISPATCH kill-switch ortak kuralların aynısıdır.

Örnek

Lot-takipli mama (tekrar-alış/abonelik) + pet bağlamı içeren gerçekçi order.created payload'ı (POST {posBase}/orders):

{
  "_event": "order.created",
  "_delivery_id": "evt_pet_8c41a9",
  "order_id": "665fa1c2e9b4d20012ab77f1",
  "order_number": "PET-240628-0042",
  "status": "confirmed",
  "type": "delivery",

  // Finansal kırılım (ortak) — major + *_minor
  "original_subtotal": 540.00, "original_subtotal_minor": 54000,
  "item_discount": 40.00,      "item_discount_minor": 4000,
  "additional_discount": 0,    "additional_discount_minor": 0,
  "discount_amount": 40.00,    "discount_amount_minor": 4000,
  "coupon_code": null,
  "tax": 0,                    "tax_minor": 0,
  "delivery_fee": 0,           "delivery_fee_minor": 0,
  "service_fee": 0,            "service_fee_minor": 0,
  "tip_amount": 0,             "tip_amount_minor": 0,
  "total": 500.00,            "total_minor": 50000,
  "currency": "TRY", "currency_minor_unit": "kurus",

  "customer": { "user_id": "6650...e1", "name": "Elif Demir", "phone": "+905551234567" },
  "delivery_address": {
    "street": "Bağdat Cad. No:120 D:4", "city": "İstanbul", "district": "Kadıköy",
    "directions": "Apartman girişi sağda, zil: Demir", "name": "Elif Demir", "phone": "+905551234567",
    "coordinates": { "lat": 40.9701, "lng": 29.0610 }
  },
  "delivery_directions": "Apartman girişi sağda, zil: Demir",

  "payment_method": "cash", "payment_method_label": "Nakit",
  "notes": "Maması bitmeden teslim edilsin.",
  "scheduled_for": null, "estimated_time": "45dk",

  // ───── SEKTÖRE-ÖZEL: pet bağlamı + mama aboneliği ─────
  "fulfillment": {
    "engine": "pet",
    "pet": {
      "name": "Boncuk",
      "species": "köpek",
      "breed": "Golden Retriever",
      "weight": 28,
      "note": "Tahıl alerjisi var — grain-free."
    },
    "is_repeat": true,
    "repeat_interval_days": 30
  },

  "items": [
    {
      "reference_id": "665f...mama1",
      "name": "Grain-Free Köpek Maması 12kg",
      "quantity": 1,
      "original_unit_price": 540.00, "original_unit_price_minor": 54000,
      "discounted_price": 500.00,   "discounted_price_minor": 50000,
      "extra_price": 0, "extra_price_minor": 0,
      "line_total": 540.00, "line_total_minor": 54000,
      "line_discount": 40.00, "line_discount_minor": 4000,
      "notes": null,
      "selected_ingredients": [], "added_ingredients": [], "removed_ingredients": []
    }
  ],

  "created_at": "2026-06-28T09:12:44.000Z",
  "updated_at": "2026-06-28T09:12:44.000Z"
}

İlgili as-built kaynak dosyalar (mutlak yol):

/home/firsatgo/firsatgo-backendv2/src/orders/lifecycle/lifecycle-registry.ts — pet→RETAIL state-machine + etiketler
/home/firsatgo/firsatgo-backendv2/src/orders/fulfillment/fulfillment.util.ts — pet/is_repeat/repeat_interval_days fulfillment doğrulama (fail-closed)
/home/firsatgo/firsatgo-backendv2/src/inventory/inventory.service.ts + /home/firsatgo/firsatgo-backendv2/src/inventory/schemas/product-lot.schema.ts — lot/SKT/FEFO
/home/firsatgo/firsatgo-backendv2/src/merchants/seed/sector-definitions.data.ts (petshop profili, satır ~61-76)
/home/firsatgo/firsatgo-backendv2/src/integrations/utils/order-receipt.util.ts — kasa-fişi/sipariş payload üretimi
/home/firsatgo/firsatgo-backendv2/src/restaurant-products/schemas/restaurant-product.schema.ts — item_kind='pet_product' + sector_attributes

Genel Bakış​

Sipariş Yaşam-Döngüsü​

Sektöre-Özel Sipariş Alanları​

Katalog / Ürün​

Akış Notları​

Örnek​