Akaunting modül geliştirme: güncellemelerden sağ çıkan özelleştirme

Akaunting modül geliştirme, ihtiyacınız olan özelliği çekirdek dosyalara dokunmadan, uygulamanın kendi genişletme noktaları üzerine kurmak demektir. Modül; kendi rotaları, görünümleri, dil dosyaları, migration'ları ve module.json tanım dosyası olan, Laravel paketine benzeyen bağımsız bir klasördür. Doğru kurulan bir modül sürüm güncellemesinde silinmez; ama her yeni sürümde bir kez test edilmesi gerekir. Bu yazı hem geliştiriciler hem de geliştirme yaptırmayı düşünen işletme sahipleri için.

Çekirdekte yapılan değişiklik neden kaybolur?

Akaunting güncellendiğinde, çekirdek dosyalar yeni sürümün dosyalarıyla değiştirilir. Fatura şablonunu düzenlemek için bir Blade dosyasını değiştirdiyseniz, giriş sayfasına bir alan eklediyseniz ya da bir denetleyiciye birkaç satır koyduysanız, güncelleme bu değişikliklerin üzerine yazar.

Bu bir hata değil, güncellemenin doğası. Sonuç ise genellikle şu sırayla yaşanır:

1. Özelleştirme bugün çalışıyor ve kimse onu hatırlamıyor.
2. Bir güncelleme yapılıyor; değişiklik sessizce kayboluyor ya da yeni kodla çakışıp hata veriyor.
3. Birinin neyin değiştirildiğini hatırlaması, eski dosyayla yenisini karşılaştırması ve değişikliği zaman baskısı altında yeniden yapması gerekiyor.

Veritabanına doğrudan eklenmiş bir kolon da benzer bir sorun: uygulama o kolonu tanımadığı için ona hiçbir şey yazmaz, bir sonraki migration da onunla çakışabilir. Çekirdeği değiştirmek bir kez ucuz, her güncellemede ise yeniden pahalıdır. Modül ise bir kez daha pahalı, sonrasında çok daha öngörülebilirdir.

Bir Akaunting modülünün yapısı

Akaunting modülleri, uygulamanın kullandığı modül paketi üzerine kurulu ve arayüzde "App" olarak görünüyor. Akaunting'in geliştirici dokümanına göre yeni bir modülün iskeleti şu komutla oluşturuluyor:

php artisan module:make my-blog

Komut, modules/MyBlog/ altında aşağıdakine benzer bir yapı üretir:

modules/MyBlog/
├── Console/
├── Database/
│   ├── Migrations/
│   └── Seeds/
├── Http/
│   ├── Controllers/
│   └── Requests/
├── Jobs/
├── Listeners/
├── Models/
├── Providers/
│   ├── Event.php
│   └── Main.php
├── Resources/
│   ├── assets/
│   ├── lang/
│   └── views/
├── Routes/
│   ├── admin.php
│   └── portal.php
├── composer.json
├── module.json
└── package.json

Modül bir şirket için şu komutla kurulur; buradaki 1, şirketin kimliğidir:

php artisan module:install my-blog 1

Bu ayrıntı önemli: Akaunting çok şirketli bir uygulama ve modüller şirket bazında etkinleştiriliyor. Modülün oluşturduğu her kaydın hangi şirkete ait olduğunu taşıması ve sorguların bunu gözetmesi gerekiyor.

module.json

Modülün kimlik kartı. Dokümanda geçen başlıca alanlar:

• alias: modülün benzersiz kısa adı; uygulamanın her yerinde bu adla anılır
• version, active, icon
• providers: modülün servis sağlayıcıları (örneğin Main)
• requires: bağımlı olduğu diğer modüller
• settings, reports, widgets: modülün ayarlar ekranı, raporları ve gösterge paneli bileşenleri

Ayarların, raporların ve widget'ların burada bildirimsel olarak tanımlanması, çekirdeğe dokunmadan bu yüzeylere girebilmenizi sağlıyor.

Rotalar ve iki ayrı yüzey

Routes/admin.php yönetim paneli için, Routes/portal.php müşteri portalı için. İkisi farklı kullanıcılara, farklı yetkilere hitap ediyor; menü girişleri de her yüzey için ayrı olaylar dinlenerek ekleniyor.

Genişletme noktaları: çekirdeğe dokunmadan davranış eklemek

Bir modülün değeri, çekirdeğin davranışını onu değiştirmeden genişletebilmesinden geliyor. Başlıca mekanizmalar:

• Olaylar ve dinleyiciler: Akaunting birçok işlem sırasında olay yayımlıyor. Modül, Providers/Event.php içinde bu olaylara dinleyici bağlayarak araya girer; menüye giriş eklemek bunun en yaygın örneği.
• Observer'lar: "Bir fatura oluşturulduğunda şunu da yap" türü mantık için. Modülün servis sağlayıcısında kaydedilir ve çekirdek modelin yaşam döngüsüne bağlanır.
• View composer'lar: bir ekranın bir bölümüne içerik eklemek ya da bir şablonu değiştirmek için. Çekirdek Blade dosyası olduğu gibi kalır.
• Job'lar: Akaunting kayıt oluşturma, güncelleme ve silme işlerini job sınıflarıyla yapıyor. Modülün de aynı yolu izlemesi, mantığın ekrandan, API'den ve konsoldan aynı şekilde çalışmasını sağlıyor.
• Kendi tabloları: modülün ihtiyaç duyduğu veriler, çekirdek tablolara kolon eklemek yerine modülün kendi migration'larıyla oluşturduğu tablolarda tutulmalı.

Yetkiler

Gözden en çok kaçan adım bu. Dokümana göre modülün yetkileri, kurulum sırasında çalışan FinishInstallation dinleyicisinde, attachPermissionsToAdminRoles ile yönetici rollerine bağlanıyor. Kontrol ise rol adıyla değil yetkiyle yapılmalı, çünkü kullanıcılar kendi rollerini oluşturabiliyor. Bu adım atlanırsa menü girişi görünür ama tıklanınca 403 hatası döner; "modül bozuk" şikâyetlerinin önemli bir kısmının arkasında bu var.

Dil dosyaları

Resources/lang altında Türkçe ve İngilizce dosyaları ilk günden birlikte yazmak, sonradan çevirmekten ucuz. Modül PDF üretiyorsa, Türkçe karakterleri içeren bir yazı tipinin gömülmesi de gerekiyor; aksi halde ı, ş, ğ gibi harfler bozuk çıkabiliyor.

App Store uygulaması mı, özel modül mü?

Teknik olarak ikisi aynı yapıda. Fark, kimin için yazıldığında.

İhtiyacınız App Store'da zaten bir uygulama olarak duruyorsa, çoğu zaman en ucuz yol onu satın almak. Özel modül; ihtiyacın gerçekten size özgü olduğu, mevcut uygulamaların karşılamadığı ya da başka iç sistemlerle entegrasyon gerektiği durumlarda anlam kazanıyor. Türkiye'de bunun tipik örnekleri tevkifat, cari ekstre, çek-senet takibi ve e-Belge bağlantıları; e-Fatura tarafındaki seçenekleri Akaunting e-Fatura yazımızda ayrıca ele aldık.

Modülü sürümler boyunca ayakta tutmak

Akaunting'in sürüm politikası, kullanıcıların çekirdek sürümüyle birlikte yayımlanan modül sürümünü kullandığını varsayıyor ve modül geliştiricilerinden geriye dönük uyumluluk beklemiyor. Bu, özel bir modülün bakım ihtiyacı olduğu anlamına geliyor. Pratikte işe yarayan alışkanlıklar:

• Bağımlılık listesi tutun. Modülün kullandığı çekirdek sınıfları, dinlediği olayları, değiştirdiği görünümleri ve job'ları yazılı bir listede toplayın. Güncellemeden sonra kontrol edilecek liste budur.
• Hangi çekirdek sürümüne karşı test edildiğini not edin. Her modül sürümünün yanında "şu Akaunting sürümüyle doğrulandı" bilgisi olsun.
• Otomatik testler yazın. Laravel'in test altyapısıyla, modülün temel akışlarını (kayıt oluşturma, rapor, yetki) kapsayan birkaç test, her yükseltmede elle tıklamaktan çok daha güvenilir.
• Migration'ları eklemeli yazın. Mevcut migration'ları değiştirmek yerine, her değişiklik için yeni bir migration ekleyin.
• Önce kopya ortam. Çekirdeği yükseltmeden önce, modülü yeni sürümde bir kopya ortamda çalıştırın ve bağımlılık listesini kontrol edin.
• Kaynak kodu sizin repo'nuzda tutun. Modülü yazan kişiyle yollarınız ayrılsa bile, kod ve kurulum talimatları elinizde kalmalı.

Büyük sürüm geçişlerinde bu alışkanlıkların değeri daha da artıyor; 2.x'ten 3.x'e geçen bir kurulumda çekirdek değişiklikleri ve modüller nasıl ele alınmalı, Akaunting 2.x'ten 3.x'e geçiş yazımızda anlattık.

İşletme sahibi için: bir modül teklifinde neye bakmalı?

Kodu kendiniz okumayacak olsanız bile, bir modül teklifini değerlendirirken sorabileceğiniz net sorular var:

• Çekirdek dosyalara dokunulacak mı? Cevap "evet" ise, her güncellemede bu değişikliğin yeniden yapılması gerekeceğini bilin. Doğru cevap, yalnızca modül içinde çalışılacağıdır.
• Kaynak kod kimde kalacak? Modül sizin hesabınızdaki bir repo'da durmalı ve telif hakkı size ait olmalı.
• Hangi Akaunting sürümüne karşı test edilecek? Teslimde bu bilgi yazılı olmalı.
• Yetkiler ve dil dosyaları kapsamda mı? İkisi de sonradan eklendiğinde pahalıya patlayan işler.
• Bir sonraki güncellemede ne olacak? Modülün yeni sürümlerde kim tarafından, hangi koşullarla doğrulanacağı baştan konuşulmalı. "Bakımı gerekmez" diyen bir teklif, Akaunting'in sürüm politikasıyla uyuşmuyor.
• "Bitti" ne demek? Kabul kriterleri sıfatlarla değil, test edilebilir cümlelerle yazılmalı.

Nereden başlamalı?

Bir özelleştirme ihtiyacınız varsa önce iki soruyu cevaplayın: Bu ihtiyaç App Store'daki bir uygulamayla karşılanabiliyor mu? Karşılanmıyorsa, modül tam olarak ne yapmalı ve neyi yapmamalı? İkinci sorunun cevabını kabul kriterleriyle yazıya dökmek, geliştirmeyi kim yaparsa yapsın işin en değerli kısmı. Halihazırda çekirdek dosyalarda yapılmış değişiklikleriniz varsa, onların listesini çıkarmak da iyi bir ilk adım.

Bu işi birlikte yapmak isterseniz, Akaunting modül geliştirme hizmetimizde ücretli bir keşifle başlıyor, modülü yalnızca belgelenmiş genişletme noktaları üzerine kuruyor ve kendi repo'nuzda teslim ediyoruz. İhtiyacınızı iletişim sayfamızdan kısaca anlatabilirsiniz.