load-lifecycle-patterns_skill

Overview

This skill documents the critical business logic for load lifecycle and billing workflows in laneweaverTMS. It codifies valid status transitions, cancellation and TONU handling, billing milestones, quick pay behavior, and core financial calculations. Use it as a single-source reference when implementing or reviewing load, billing, and payment flows.

How this skill works

The skill defines the canonical load status lifecycle and valid transitions, including required triggers and terminal states. It specifies cancellation rules, TONU evaluation and recording, and the post-delivery billing pipeline from POD to customer invoice and carrier payment. It also provides financial formulas and implementation patterns (views, calculated columns) for gross/net profit and margin calculations, plus quick pay fee handling.

When to use it

• Implementing load status transitions and validation logic
• Building post-delivery billing workflows (POD → invoice → payment)
• Implementing TONU charge evaluation, recording, and billing
• Adding quick pay support and fee calculation for carrier payments
• Calculating financial metrics (gross profit, net profit, margins)

Best practices

• Validate every status change against the allowed transitions table and record timestamps
• Store money fields as NUMERIC(10,2) and handle NULL carrier_rate safely
• Track POD and carrier bill receipt separately; use a generated invoice_ready flag to gate customer invoicing
• Record cancellations in a dedicated table and sync loads.is_cancelled via a trigger
• Treat quick pay as carrier-initiated: calculate fee, deduct from carrier payment, and index quick_pay_requested for fast querying

Example use cases

• Enforce uncovered→assigned→dispatched→delivered lifecycle with guards preventing uncovered→delivered transitions
• When a load is cancelled after assignment, create load_cancellations with TONU amount and bill customer for TONU
• Only create a customer_invoice when invoice_ready = pod_received AND carrier_bill_received
• Calculate grossProfit and grossMarginPct in a view used by reporting and dashboard logic
• Process a carrier quick pay request by computing fee_pct, storing quick_pay_fee_amount, and scheduling expedited payment