Ö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.Lookupiç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']:AddCustomAppexport'unuidentifier = Config.AppIdentifier(varsayılanfx-billing), ad, açıklama, geliştirici,defaultApp, kategori, boyut, fiyat, bir ekran görüntüsü,uiveiconile ç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 = trueolduğunda ödemelerAddTransactionile 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',
})
senderbir meslek adı ya da faturayı kesenin citizen id'sidir.recipientbir citizen id'dir; bir şirkete fatura kesmek için meslek adı da olabilir.- Yetki kontrolü atlanmaz:
source,senderiçinde adı geçen meslekte ve mesaide olmalıdır. payments_numtaksit sayısıdır.payments_periodtaksitler 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_days0'dan büyükse fatura tamamen ödendikten sonra yeniden kesilir.- Mesafe ve açıklama kuralları yalnızca
Config.EnforceNearbyOnExports/Config.EnforceSummaryOnExportsaçıkken uygulanır. KDV yalnızcaConfig.Vat.OnExports = trueolduğ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 = 0ile 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 = 0ile ö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' })
viewerbir meslek adı ya da citizen id'dir.statusdeğeripending,completed,cancelled,scheduledveyadisputedolur.- Sonraki sayfa için
result.nextCursordeğeriniparams.lastIdolarak 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.Enabledkapalıysa ya da veritabanı hazır değilsefalse, 0döndürür.- Yalnızca
Config.Enforcement.GraceMinutessüresinden eski faturalar sayılır.DuplicateWindowSecondsiç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ı |