feat: robust Transaction model — five polymorphic roles, full monetary breakdown, lifecycle timestamps#197
Open
feat: robust Transaction model — five polymorphic roles, full monetary breakdown, lifecycle timestamps#197
Conversation
added 2 commits
March 1, 2026 20:05
…y breakdown, lifecycle timestamps - Add five agnostic polymorphic roles: subject, payer, payee, initiator, context (replaces owner_uuid/owner_type and customer_uuid/customer_type) - Add direction (credit|debit), balance_after (wallet running balance snapshot) - Add monetary breakdown: fee_amount, tax_amount, net_amount (all in cents) - Add multi-currency settlement: exchange_rate, settled_currency, settled_amount - Add idempotency: reference (unique), parent_transaction_uuid (refund/reversal linkage) - Add gateway enrichment: gateway_response JSON, payment_method, last4, brand - Add traceability: ip_address, notes, failure_reason, failure_code - Add reporting: period (YYYY-MM), tags JSON - Add lifecycle timestamps: settled_at, voided_at, reversed_at, expires_at - Add SoftDeletes trait (was missing from model despite column existing in migration) - Add STATUS_*, DIRECTION_*, TYPE_* constants covering platform-wide taxonomy - Add scopeCredits, scopeDebits, scopeSuccessful, scopePending, scopeFailed, scopeOfType, scopeForPeriod, scopeForSubject, scopeForPayer, scopeForPayee, scopeForContext, scopeRefunds - Add isCredit, isDebit, isSuccessful, isPending, isFailed, isRefund, isVoided, isReversed, isSettled, isExpired helpers - Add formatted_amount accessor - Add parentTransaction BelongsTo and childTransactions HasMany relationships - Backfill subject_* from owner_*, payer_* from customer_*, period from created_at - Deprecate owner() and customer() relationships (kept for backward compat) - Improve TransactionItem: add HasPublicId, SoftDeletes, quantity, unit_price, tax_rate, tax_amount, description, sort_order; fix amount type string -> integer; add transaction() BelongsTo, getLineTotal(), calculateTax() helpers
…ed_amount getters - Replace 'integer' cast with Fleetbase\Casts\Money on all monetary columns (amount, fee_amount, tax_amount, net_amount, balance_after, settled_amount on Transaction; amount, unit_price, tax_amount on TransactionItem) - Remove getFormattedAmountAttribute() from both models - Remove 'formatted_amount' from $appends on both models - Money cast handles all currency symbol stripping and integer normalisation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
Upgrades the
transactionstable andTransactionmodel to serve as the platform-wide financial transaction primitive.Key Changes
Five agnostic polymorphic roles
subject— primary owner of the transaction recordpayer— funds flow FROMpayee— funds flow TOinitiator— what triggered or authorised the transactioncontext— related business object (Order, Invoice, etc.)owner_uuid/owner_typeandcustomer_uuid/customer_typeare kept as deprecated nullable aliases, backfilled from the new columns.Monetary breakdown (all integers in cents)
fee_amount,tax_amount,net_amount,exchange_rate,settled_currency,settled_amount,balance_afterIdempotency and linkage
reference(unique idempotency key),parent_transaction_uuid(self-referential FK for refunds/reversals/splits)Gateway enrichment
gateway_responseJSON,payment_method,payment_method_last4,payment_method_brandTraceability
ip_address,notes,failure_reason,failure_codeReporting
period(YYYY-MM, denormalised),tagsJSONLifecycle timestamps
settled_at,voided_at,reversed_at,expires_atModel additions
SoftDeletestrait (was missing)DIRECTION_*,STATUS_*,TYPE_*constantsparentTransaction+childTransactionsTransactionItem improvements
HasPublicId,SoftDeletesamounttype: string → integer (cents)quantity,unit_price,tax_rate,tax_amount,description,sort_ordertransaction()BelongsTo,getLineTotal(),calculateTax()Breaking Changes
None — all changes are additive. Deprecated columns remain in place.