Özellikler

Billing (fx-billingapp)

Paketle gelen fatura uygulaması, telefona nasıl kurulduğu, ana ayarları ve server export'ları.

#Nedir

fx-billingapp bir fatura uygulamasıdır. Oyuncular ve şirketler fatura gönderir, alıcılar bunları uygulamadan öder, patronlar da şirketlerinin faturalandırmasını yönetir.

Oyuncuların elde ettikleri:

  • Ana Sayfa: ne kadar borçlu oldukları, ne kadarının vadesinin geçtiği, ne kadarının yakında ödenmesi gerektiği, onları bekleyen itirazlar, Tümünü Öde ve başkalarının onlara olan borcu.
  • Geçmiş: durumuyla birlikte alınan ve gönderilen faturalar, arama, tarih ve tutar filtreleri ve gönderilen faturalar için toplu iptal.
  • Yeni: yakındaki alıcılar, miktarlarıyla şirket fiyat listesi, göndermeden önce gösterilen KDV, taksitler, ödeme süresi, tekrarlayan faturalar ve ekler.
  • Fatura: kalemleri, KDV'si, gecikme ücretleri, taksit ilerlemesi, son ödeme zamanı, ekleri, itirazı ve tüm zaman çizelgesiyle bir makbuz.
  • İşletme (patronlar ve yöneticiler): tahsil edilen, bekleyen, KDV ve komisyon toplamları, en iyi çalışanlar, çözülecek itirazlar, fiyat listesi, marka rengi ve logosu, ayrıca rütbe bazında komisyonla birlikte gönderme ve yönetme yetkileri.
  • Sorgu (Config.Lookup içindeki meslekler): bir vatandaşın açık faturaları ve borcu; yalnızca okunur ve loglanır.

#Gereksinimler

Resource Zorunlu Notlar
oxmysql Evet Veritabanı erişimi
QBCore, Qbox veya ESX Evet Otomatik algılanır; diğer her şey için adaptör server/frameworks/standalone.lua
fx-phone Hayır Telefon yoksa uygulama bir tuşla bağımsız açılır (varsayılan F7)
Bir şirket bankası Yalnızca şirket faturaları için Aşağıya bak

Oyuncular arasındaki faturalar her bankacılık script'iyle çalışır, çünkü kişisel para framework üzerinden geçer. Config.CompanyMoneySystem yalnızca şirket (society) hesaplarını etkiler. qb-banking, Renewed-Banking, okokBanking, qb-management, esx_addonaccount ve tgiann-bank otomatik algılanır. Başka bir banka için server/company-money/custom.lua dosyasını doldur ve Config.CompanyMoneySystem = "custom" olarak ayarla.

#Kurulum

cfgensure oxmysql
ensure fx-phone
ensure fx-billingapp

Config.CheckDatabase = true (varsayılan) olduğunda tablolar başlangıçta oluşturulur. Konsol bir şema hatası bildirirse setup/sql/install.sql dosyasını elle çalıştır. Birden fazla kez çalıştırmak güvenlidir.

Sorunsuz bir başlangıç; framework'ü, şirket para sistemini, uygulama id'sini ve dil dosyasını yazan tek bir satır basar.

#Telefona nasıl kaydolur

Resource'ta client/phone/ içinde her telefon için bir adaptör dosyası vardır. Config.Phone.Resource = "auto" olduğunda FX Phone çalışıyorsa FX Phone'u kullanır.

  • FX Phone adaptörü exports['fx-phone']:AddCustomApp export'unu identifier = Config.AppIdentifier (varsayılan fx-billing), ad, açıklama, geliştirici, defaultApp, kategori, boyut, fiyat, bir ekran görüntüsü, ui ve icon ile çağırır.
  • fx-phone:client:phoneLoaded üzerinde yeniden kaydolur, böylece FX Phone yeniden başlatıldığında da sorun olmaz.
  • Bildirimler server tarafında exports['fx-phone']:SendNotification üzerinden gider; Config.Phone.BankHistory = true olduğunda ödemeler AddTransaction ile telefonun banka geçmişine yazılır.
  • fx-billingapp çalışırken FX Phone'un kendi Faturalar uygulaması Ana Ekran'dan kalkar; böylece iki değil, tek bir fatura uygulaması olur.

Uygulamanın hiç başlamamasını istiyorsan FX Phone'un configs/config_apps.lua dosyasındaki Config.BundledApps içinde ['fx-billingapp'] = false yap. Bkz. Uygulamalar.

#Öne çıkan config ayarları

config.lua:

Ayar Varsayılan Anlamı
Config.AppIdentifier "fx-billing" Telefondaki uygulama id'si
Config.DefaultApp true Her telefonda kurulu gelir
Config.Phone.Resource "auto" Hangi telefona kurulacağı
Config.Phone.BankHistory true Ödemeleri telefonun banka geçmişine yazar
Config.DefaultKeybind "f7" Bağımsız arayüzün tuşu
Config.Framework "auto" Algılama yanlış framework'ü seçerse ayarla
Config.CompanyMoneySystem "auto" Algılama yanlış bankayı seçerse ayarla
Config.Locale, Config.Currency Dil dosyası ve para birimi simgesi
Config.CanIndividualsSend false Oyuncular birbirine kişisel olarak fatura kesebilir
Config.EmployedSendAsCompanyOnly true Bir işte çalışan herkes yalnızca şirket adına fatura keser
Config.MaxDistance 5.0 Alıcının ne kadar yakında durması gerektiği
Config.MinSummaryLength 8 En kısa açıklama uzunluğu; 0 kapatır
Config.LogRetentionDays 7 Denetim kayıtlarının ne kadar tutulacağı; 0 sonsuza dek tutar
Config.Grades boş Bir mesleğin fatura kesmesini belirli rütbelerle sınırlar
Config.Commission boş Meslek ve rütbe başına çalışan payı
Config.Enforcement açık Ödenmemiş faturalar varken araç kilidi (GraceMinutes, DuplicateWindowSeconds, NotifyMessage)
Config.Vat kapalı Şirket faturalarında KDV, meslek başına oran, isteğe bağlı devlet hesabı
Config.Disputes açık Alıcılar faturaya itiraz edebilir; ExpireHours yanıtlanmayanları kapatır
Config.PayAll true Tümünü Öde düğmesi
Config.Lookup Bir vatandaşın açık faturalarını sorgulayabilen meslekler
Config.Business hepsi açık Fiyat listesi, rütbe düzenleyici ve marka ayarları
Config.EnforceNearbyOnExports, Config.EnforceSummaryOnExports false Mesafe ve açıklama kurallarını export'larla oluşturulan faturalara da uygular
Config.Functions boş fonksiyonlar Her biri (source, invoice) ile çağrılan SentInvoice, PaidInvoice, CancelledInvoice hook'ları

config_server.lua yalnızca server tarafındadır. Config.Webhook (Discord loglaması: açma anahtarı, webhook adresi, sunucu adı ve isteğe bağlı bir bot token'ı), Config.RateLimit ve Config.Limits buradadır. Bütün gizli bilgileri buraya koy.

#Server export'ları

Bütün export'lar server tarafındadır. source = 0 "server olarak çalıştır" anlamına gelir ve belirtilen yerlerde yetki kontrolünü atlar.

#SendInvoice

Şu adla da kullanılabilir: CreateInvoice

Faturayı kesen oyuncu adına bir fatura oluşturur.

lua---@param source number  Player who issues the invoice
---@param data table  { sender, recipient, amount, summary, sender_label?, recipient_label?, payments_num?, payments_period?, recurring_interval_days?, attachments? }
---@param callback? fun(ok: boolean, invoice: table|nil, reason: string|nil)
---@return boolean ok
---@return table|string invoiceOrReason
exports['fx-billingapp']:SendInvoice(source, data, callback)
lualocal ok, invoice = exports['fx-billingapp']:SendInvoice(source, {
    sender = 'mechanic', recipient = 'ABC12345', amount = 2500, summary = 'Engine repair and oil change',
})
  • sender bir meslek adı ya da faturayı kesenin citizen id'sidir. recipient bir citizen id'dir; bir şirkete fatura kesmek için meslek adı da olabilir.
  • Yetki kontrolü atlanmaz: source, sender içinde adı geçen meslekte ve mesaide olmalıdır.
  • payments_num taksit sayısıdır. payments_period taksitler arasındaki gün sayısıdır (0, 1, 7, 14, 30, 90); diğer değerler bilinen en yakın süreye eşlenir.
  • recurring_interval_days 0'dan büyükse fatura tamamen ödendikten sonra yeniden kesilir.
  • Mesafe ve açıklama kuralları yalnızca Config.EnforceNearbyOnExports / Config.EnforceSummaryOnExports açıkken uygulanır. KDV yalnızca Config.Vat.OnExports = true olduğunda eklenir.
  • Başarısızlık nedenleri: invalidData, noSendPermissions, invalidRecipient, tooFar, invalidAmount, summaryTooShort, summaryInvalid.

#CancelInvoice

Bekleyen bir faturayı iptal eder.

lua---@param source number  Player, or 0 to run as the server
---@param data number|table  Invoice id, or { id, actor? }
---@return boolean ok
---@return string|nil reason
exports['fx-billingapp']:CancelInvoice(source, data)
luaexports['fx-billingapp']:CancelInvoice(0, 42)
  • source = 0 ile yetki kontrolü atlanır ve fatura, onu kesen hesap adına iptal edilir.
  • Başarısızlık nedenleri: invalidData, notFound, noPermission.

#PayInvoice

Bir faturayı ya da sıradaki taksitini öder.

lua---@param source number  Player, or 0 to run as the server
---@param data number|table  Invoice id, or { id, payer?, fullAmount? }
---@return boolean ok
---@return table|string resultOrReason  { fullyPaid: boolean } on success
exports['fx-billingapp']:PayInvoice(source, data)
lualocal ok, result = exports['fx-billingapp']:PayInvoice(0, { id = 42, fullAmount = true })
  • source = 0 ile ödeme alıcı hesabından alınır ve yetki kontrolü atlanır.
  • Gerçek bir oyuncu source'u ile ödeme, o oyuncunun ödeyebileceği tutarla sınırlıdır.

#GetInvoices

Bir oyuncu ya da şirket için bir sayfa fatura döndürür.

lua---@param source number  Player, or 0 to run as the server
---@param params table  { tab = 'received'|'sent', viewer, status?, query?, lastId? }
---@return table result  { rows: table[], nextCursor: any }
exports['fx-billingapp']:GetInvoices(source, params)
lualocal result = exports['fx-billingapp']:GetInvoices(0, { tab = 'received', viewer = 'mechanic', status = 'pending' })
  • viewer bir meslek adı ya da citizen id'dir.
  • status değeri pending, completed, cancelled, scheduled veya disputed olur.
  • Sonraki sayfa için result.nextCursor değerini params.lastId olarak geri gönder.
  • Görüntüleyen çözümlenemezse sonuç { rows = {} } olur.

#GetStats

Bir oyuncu ya da şirket için fatura toplamlarını döndürür.

lua---@param source number  Player, or 0 to run as the server
---@param viewer string  Job name or citizen id
---@return table|nil stats  stats.totals has owedByMe, owedToMe, totalPaid, totalReceived, penaltiesOwed, pendingCount, sentPendingCount
exports['fx-billingapp']:GetStats(source, viewer)
lualocal stats = exports['fx-billingapp']:GetStats(0, 'mechanic')

Görüntüleyen çözümlenemezse nil döndürür.

#HasUnpaidInvoices

Bir oyuncunun ek süreyi geçmiş ödenmemiş faturası olup olmadığını söyler. Garaj kilidi bunu kullanır.

lua---@param identifier string  Citizen id
---@param notifyIfBlocked? boolean  Send the player a phone and framework notification when blocked
---@return boolean blocked
---@return number owedTotal
exports['fx-billingapp']:HasUnpaidInvoices(identifier, notifyIfBlocked)
lualocal blocked, owed = exports['fx-billingapp']:HasUnpaidInvoices(citizenid, false)
  • Config.Enforcement.Enabled kapalıysa ya da veritabanı hazır değilse false, 0 döndürür.
  • Yalnızca Config.Enforcement.GraceMinutes süresinden eski faturalar sayılır. DuplicateWindowSeconds içinde aynı gönderen ve tutara sahip faturalar bir kez sayılır.

#GetVersionStatus

Güncelleme kontrolünün sonucunu döndürür.

lua---@return table status  { state: string, current: string, latest: string|nil, behind: number|nil }
exports['fx-billingapp']:GetVersionStatus()
lualocal status = exports['fx-billingapp']:GetVersionStatus()

#İsteğe bağlı entegrasyonlar

setup/integration/garage.lua bir garaj script'inin ödenmemiş faturalar varken araçları nasıl engellediğini, setup/integration/exports_example.lua ise yukarıdaki export'ları gösterir. İkisi de başvuru dosyasıdır: ihtiyacın olanı kendi resource'una kopyala ve bunları bir manifest'e ekleme.

#Sorun giderme

Belirti Neden veya çözüm
Uygulama telefonda görünmüyor Telefon bu resource'tan önce başlamalı. Konsolda kurulum hatası var mı bak
Şirket faturaları ödenemiyor Ayarlanan banka resource'u çalışmıyor. Oyuncudan oyuncuya faturalar etkilenmez
Alıcı listesi hep boş Config.ShowOnlyNearbyPlayers = true yalnızca Config.MaxDistance metre içindeki oyuncuları listeler
"Bu kişi yanında değil" Config.EnforceNearbyOnSend mesafeyi server tarafında yeniden kontrol eder. Gerekirse Config.MaxDistance değerini artır
Discord logu yok config_server.lua içinde Config.Webhook.Enabled true olmalı ve adres doldurulmalı