@ry459219
# Modüler Saha Dağıtım & Ticaret Platformu — Ürün Vizyonu & Tasarım Rehberi > **Bu belgenin amacı:** Bu doküman bir teknik şartname değildir. Yapılacak ürünün **ruhunu, ihtiyaçlarını ve kısıtlarını** tanımlar. Mimari kararlar, modül tasarımları, veri modelleri ve uygulama detayları **sana** bırakılmıştır. Sen en iyi, en uygulanabilir ve en sürdürülebilir mimariyi tasarla. > > **Nasıl kullan:** Bu belgeyi oku, projenin ne yapmaya çalıştığını anla, sonra kendi mimari kararlarını vererek uçtan uca bir platform inşa et. --- ## 1. Problem & Vizyon ### Hangi Problemi Çözüyoruz? Türkiye'de (ve benzer pazarlarda) binlerce küçük-orta ölçekli işletme her gün saha dağıtımı yapıyor: fırınlar ekmek dağıtıyor, manavlar restoranlara sebze götürüyor, toptancılar marketlere ambalajlı ürün taşıyor. Bu işletmelerin çoğu hâlâ kağıt-kalem, WhatsApp mesajları ve kafa karıştıran Excel tablolarıyla çalışıyor. Bu işletmelerin **ihtiyaçları birbirinden çok farklı**. Bir fırının en büyük derdi bayat ekmek iadesi iken, bir toptancının derdi barkodla envanter takibi. Mevcut yazılımlar ya çok genel (herkes için aynı 50 menü) ya da çok niş (sadece bir sektöre özel). ### Ne İnşa Ediyoruz? **Tek bir platform, farklı iş modelleri.** Her işletmenin kendi iş modeline göre şekillenen modüler bir saha dağıtım ve ticaret platformu. İşletme sahibi kayıt olurken işinin doğasını tanımlar, sistem ona göre kurulur. ### Temel Felsefe - **Bir işletme kayıt olduğunda, sistem o işletmenin ihtiyacına göre şekillenmeli.** Kullanmayacağı ekranları, menüleri, veri akışlarını görmemeli. - **Modülerlik dogma değil, araçtır.** Modüller mantıklı iş yeteneklerini temsil etmeli. Hangi modüller olmalı, nasıl ayrılmalı, birbirlerine nasıl bağlanmalı — bunları sen belirle. - **Basitlik karmaşıklıktan önemlidir.** Küçük bir fırın sahibi bu sistemi açtığında bunalmış hissetmemeli. --- ## 2. Kullanıcı Dünyası — Kimler Kullanacak? ### İşletme Tipleri (Örnekler — Sınırlayıcı Değil) Platform farklı sektörlerden işletmelere hitap edecek. Aşağıdaki örnekler vizyonu anlamak içindir, bunlarla sınırlı değildir: **🏭 Fırın / Unlu Mamul Üreticisi** - Her sabah 3-5 araçla 30-80 dükkana ekmek/unlu mamul dağıtımı - Sabit rotalar, sabit müşteriler, sabit siparişler - Akşamüstü bayat ürünleri toplama (iade en kritik süreç) - Şoför gün sonunda kasayı ve kalan ekmeği sayar - Genelde barkod kullanmaz (adet bazlı çalışır) **🥬 Manav / Yaş Meyve-Sebze Toptancısı** - Halden aldığı ürünü 1-2 araçla restoranlar ve bakkallara dağıtır - Sabit rota yok — sipariş geldikçe, müşteri müşteri gezer - Çürük/bozuk ürün iade alır ama iadeleri daha informal yönetir - Tartıyla çalışır, barkod yok - Hızlı anlık satış fişi ve fatura ihtiyacı **🏪 Büyük Toptancı / Ambalajlı Gıda Dağıtıcısı** - 5-20 araçla 100+ noktaya dağıtım - Her ürünün barkodu var, sıkı envanter kontrolü - Sabit haftalık siparişler, teslimat kanıtı (imza/fotoğraf) gerekli - Profesyonel muhasebe ekibi, e-fatura entegrasyonu - Gün sonu kasa ve stok mutabakatı kritik **🚰 Su Dağıtıcısı, 🧊 Buz Dağıtıcısı, 🥛 Süt Dağıtıcısı vb.** - Benzer dağıtım mantığı, farklı ürün ve iş akışı detayları ### Kullanıcı Rolleri Sistemde farklı roller olmalı. En az şu temel roller düşünülmeli (ama bununla sınırlı kalma, daha fazla veya daha az rol mantıklıysa sen karar ver): - **İş Yeri Sahibi / Yönetici** — Web panelinden her şeyi yönetir. Rota planlar, raporlara bakar, personel yönetir. - **Muhasebeci** — Web panelinde yalnızca finansal verileri görür. Faturalar, ödemeler, iadeler, kasa mutabakatı. - **Saha Personeli (Şoför / Satış Temsilcisi)** — iOS uygulamasını kullanır. Sahada dağıtım yapar, ödeme alır, iade toplar. > [!IMPORTANT] > Aynı "saha personeli" rolü, işletmenin yapısına göre **çok farklı** deneyimler yaşamalı. Rotalı bir fırında bu kişi "şoför" olarak sabah yükleme → rota takibi → gün sonu sayım akışı yaşarken, rotasız bir manavda "satış temsilcisi" olarak müşteri listesinden seçerek serbest satış yapar. Bu fark, rol değişikliğiyle değil, işletmenin modül yapısıyla belirlenmeli. --- ## 3. Platform Gereksinimleri — Ne Olmalı? ### 3.1 Modüler Yapı Bu platformun kalbi modüler yapıdır. Ama **hangi modüller olmalı, sınırları ne olmalı, birbirleriyle nasıl konuşmalı — bunları sen tasarla.** Benim beklentilerim: - **Bir çekirdek olmalı.** Her işletmenin ihtiyaç duyduğu temel yetenekler (ürün yönetimi, müşteri yönetimi, temel satış/teslimat, ödeme alma vb.) her zaman aktif olmalı. - **Çekirdeğin üstüne eklenen modüller olmalı.** Bu modüller belirli iş yeteneklerini temsil etmeli. Örneğin rota yönetimi, iade toplama, barkod tarama gibi. - **Modüller arasında mantıklı bağımlılıklar olabilir.** Örneğin "gün sonu kasa mutabakatı" ancak "rota yönetimi" açıksa mantıklı olabilir — çünkü mutabakat bir vardiya sonunda yapılır. Ama bu tür bağımlılıkları sen belirle. - **Modül seçimi kayıt anında yapılmalı ve sabitlenmeli.** İşletme sahibi kaydolurken iş modelini tanımlar, modüller ona göre belirlenir. Sonradan değiştirilmez (en azından v1 için). Aşağıda ihtiyaç duyulabilecek **iş yetenekleri** listesi var. Bunları doğrudan modül olarak kullanmak zorunda değilsin. Birleştirebilir, ayırabilir, yenilerini ekleyebilir veya bazılarını gereksiz bulabilirsin: | İş Yeteneği | Açıklama | |---|---| | Rota & Araç Dağıtım | Araçla sabit güzergahta dükkan dükkan gezme. Sabah yükleme, durak sıralama, rota takibi. | | Bayat / Bozuk İade & Kredi | Müşteriden fiziksel ürün geri toplama. Kredi notu oluşturma. | | Barkod Tarama | Kamera veya Bluetooth okuyucu ile ürün tanıma. Yükleme ve teslimat doğrulama. | | Gün Sonu Mutabakat | Şoförün vardiya sonunda nakit sayımı ve kalan stok sayımı yapması. | | Sabit Siparişler | Her hafta aynı müşteriye aynı ürünleri otomatik sipariş olarak oluşturma. | | Teslimat Kanıtı | Müşteri imzası veya teslimat fotoğrafı ile dijital kanıt saklama. | | Fatura & Kredi Notu | Resmi fatura / e-fatura / kredi notu oluşturma. | > [!TIP] > **Modül tasarımında düşünmen gereken sorular** (bunlar senin kararın): > - Her modül hangi veri yapılarını yönetir? > - Bir modül kapalıyken ne olur? O modüle ait UI tamamen mi gizlenir? > - Modül kapalıyken o modüle ait veriler telefona hiç inmemeli mi (bant genişliği tasarrufu)? > - Modüller arası bağımlılıklar nasıl enforce edilir? (Veritabanı seviyesinde mi? Uygulama seviyesinde mi? İkisi birden mi?) > - İşletme profili (hangi modüller açık) bilgisi istemcilere nasıl aktarılır? Her istekte mi sorgulanır, token'a mı gömülür, başka bir yol mu? ### 3.2 Offline-First Mimari Bu platform saha personeli tarafından **sahada** kullanılacak. İnternet bağlantısı her zaman güvenilir değil. Telefon her an bağlantı kaybedebilir — dağ köyünde, bodrum katta, yolda. **Temel beklentiler:** - Saha personeli internet olmadan **tam fonksiyonel** çalışabilmeli. Satış yapabilmeli, ödeme alabilmeli, iade toplayabilmeli. - Veriler offline oluşturulup, bağlantı geldiğinde senkronize edilmeli. - Çakışma yönetimi düşünülmüş olmalı (aynı veri hem sahada hem ofiste değiştirilirse ne olur?). - Telefona indirilen veri miktarı akıllıca yönetilmeli — işletmenin kullanmadığı modüllerin verileri gereksiz yere indirilmemeli. > [!NOTE] > Offline-first mimarisinin detayları (sync stratejisi, çakışma çözümü, veri formatı, cache yapısı) tamamen sana bırakılmıştır. En iyi ve en güvenilir yaklaşımı sen belirle. ### 3.3 Web Paneli (Yönetim Arayüzü) - İş yeri sahibi ve muhasebeci bu paneli kullanır. - Panel, işletmenin aktif modüllerine göre şekillenmeli. Kapalı modüllerin menüleri, sayfaları, metrikleri **görünmemeli**. - URL ile bypass edilememeli — kapalı bir modülün sayfasına doğrudan URL yazarak erişim engellenmiş olmalı. - Dashboard, işletmenin aktif modüllerine göre dinamik metrikler göstermeli. ### 3.4 iOS Uygulaması (Saha Arayüzü) - Saha personeli bu uygulamayı kullanır. - Uygulama, işletmenin modül yapısına göre **tamamen farklı bir deneyim** sunmalı: - Rotalı bir işletmede: sabah yükleme → rota takibi → durak durak teslimat → gün sonu sayım - Rotasız bir işletmede: müşteri listesi → seç → anlık satış → tamamla - Offline çalışabilmeli (bkz. 3.2). - Barkod tarama, imza alma, fotoğraf çekme gibi donanım özellikleri yalnızca ilgili modüller açıksa aktif olmalı. ### 3.5 Kayıt (Onboarding) Akışı - İşletme sahibi web üzerinden kaydolur. - Kayıt sırasında, basit ve anlaşılır sorularla işletmenin iş modeli belirlenir (sorular "Araçlarınız sabit rota mı geziyor?" gibi olmalı, teknik değil). - Bu cevaplara göre modül profili oluşturulur ve **kilitlenir**. - Kilit mekanizmasının teknik detayı sana bırakılmıştır (veritabanı constraint mi, uygulama mantığı mı, başka bir yol mu). --- ## 4. Teknik Kısıtlar & Tercihler ### Kesin Kısıtlar (Bunlara uy) | Kısıt | Açıklama | |---|---| | **iOS native** | Mobil uygulama Swift/SwiftUI ile native yazılmalı. React Native, Flutter vb. değil. | | **PostgreSQL** | Ana veritabanı PostgreSQL olmalı (Supabase üzerinde veya doğrudan). | | **Offline-first** | Saha uygulaması internet olmadan çalışabilmeli. Bu pazarlık edilemez. | | **Multi-tenant** | Tek bir veritabanı ve uygulama, birden fazla işletmeye hizmet verecek. Veri izolasyonu kritik. | | **Modüller kayıtta sabitlenir** | İşletmenin modül profili kayıt anında belirlenir ve v1'de değiştirilmez. | ### Tercihler (Bunları değerlendirip kendi kararını ver) | Tercih | Açıklama | |---|---| | **Supabase** | Backend olarak Supabase tercih ediyorum (Auth, Realtime, Edge Functions, Storage). Ama eğer daha iyi bir yaklaşım varsa öner. | | **Next.js** | Web panel için Next.js (App Router) tercih ediyorum. Ama alternatif daha mantıklıysa açığım. | | **Monorepo** | Tüm kod tek bir repoda olabilir — ama bu bir zorunluluk değil. | | **TypeScript** | Web tarafında TypeScript tercih ediyorum. | --- ## 5. İlham Kaynağı — WholesaleDelivery V1 Bu projenin fikri, daha önce geliştirdiğimiz **WholesaleDelivery V1** (offline-first saha dağıtım sistemi) deneyiminden geliyor. O projeden öğrenilen dersler: - Offline-first gerçekten çalışıyor ve sahada hayat kurtarıyor. Ama sync motoru iyi düşünülmeli. - Rotalı dağıtım (sabah yükleme → rota → gün sonu) akışı fırınlar için mükemmel çalışıyor ama manavlar için gereksiz karmaşık. Her işletme aynı akışa zorlanmamalı. - İade süreci (bayat toplama) fırınlar için en kritik özellik. Ama her sektör iade yapmıyor. - Gün sonu kasa mutabakatı güven oluşturuyor ama küçük işletmeler için gereksiz olabiliyor. > [!CAUTION] > Bu yeni proje WholesaleDelivery V1'in bir uzantısı veya migration'ı **değildir**. Tamamen bağımsız, sıfırdan tasarlanacak yeni bir üründür. V1'den domain bilgisi ve deneyim alınmıştır ama kod, şema veya mimari taşınmayacaktır. --- ## 6. Başarı Kriterleri Bu platformun başarılı sayılması için: 1. **Bir fırın sahibi** kayıt olup, 10 dakika içinde ilk rotasını planlayabilmeli ve şoförü sahaya çıkarabilmeli. 2. **Bir manav** kayıt olup, rotasız, basit bir şekilde müşteriye satış yapabilmeli. 3. **Saha personeli** internet kesildiğinde bile satış yapıp ödeme alabilmeli. 4. **Farklı işletmeler** aynı platformda, birbirlerinin verilerini görmeden, kendi iş modeline uygun bir deneyim yaşamalı. 5. **Modül kapalıysa** — ne UI'da görünmeli, ne veri akmalı, ne gereksiz karmaşıklık yaratmalı. --- ## 7. Sana Bırakılan Kararlar Aşağıdaki konularda **sen** en iyi kararı ver. Ben bu konularda seninle aynı fikirde olacağım — yeter ki **uygulanabilir, sürdürülebilir ve kullanıcı dostu** olsun: ### Mimari - Genel sistem mimarisi nasıl olmalı? - Backend nasıl yapılandırılmalı? - Veritabanı şeması nasıl tasarlanmalı? - Multi-tenancy nasıl sağlanmalı? (RLS? Ayrı şema? Ayrı veritabanı? Başka?) ### Modüler Yapı - **Hangi modüller olmalı?** Yukarıdaki "iş yetenekleri" tablosunu referans al ama bağlı kalma. - **Modül sınırları nerede çizilmeli?** İki yeteneği birleştirmek daha mantıklıysa birleştir, birini ikiye bölmek gerekiyorsa böl. - **Modüller arası bağımlılıklar neler olmalı?** Bağımlılık ağacını sen çiz. - **Modüller arası iletişim nasıl olmalı?** Doğrudan referans mı, event sistemi mi, shared kernel mi? - **Modül açık/kapalı bilgisi istemcilere nasıl ulaşmalı?** - **Bir modül kapalıyken veri katmanında ne olur?** Tablolar var ama boş mu kalır? Tablolar hiç oluşturulmaz mı? Başka? ### Offline & Sync - Sync stratejisi nedir? (Timestamp-based? Event sourcing? CRDT? Başka?) - Çakışma çözümü nasıl yapılır? - Telefonun local veritabanı ne olmalı? (CoreData? SQLite? SwiftData? Başka?) - Telefona hangi veriler ne zaman indirilir? ### Güvenlik & Yetkilendirme - Rol bazlı erişim kontrolü nasıl yapılır? - Modül bazlı yetkilendirme nasıl enforce edilir? - Token yönetimi nasıl yapılır? ### Kullanıcı Deneyimi - Onboarding akışı nasıl tasarlanmalı? - Web panel navigasyonu nasıl dinamik hale getirilir? - iOS uygulamasında farklı iş modelleri için farklı deneyimler nasıl sunulur? - Dashboard metrikleri modüllere göre nasıl filtrelenir? --- ## 8. Geliştirme Yaklaşımı - **Önce düşün, sonra yaz.** Koda başlamadan önce mimariyi, modül yapısını ve veri modelini detaylıca planla. - **Aşamalı inşa et.** Her şeyi aynı anda yapmaya çalışma. Çekirdeği sağlam kur, sonra modülleri ekle. - **Test edilebilir yaz.** Modüler yapı doğru çalışıyor mu doğrulanabilmeli. - **Basit tut.** Over-engineering'den kaçın. İhtiyaç olan kadar karmaşık, mümkün olduğunca basit. --- > **Son söz:** Bu belge sana ne yapacağını değil, **ne istediğimi** anlatıyor. Nasıl yapacağını sen biliyorsun. En iyi mimariyi, en temiz kodu ve en kullanılabilir ürünü sen tasarla.
