Feature Specifications

Billing (Core)

Billing is the primary feature of AquaDealers. Every bill creates a cascade of data changes across multiple tables in a single atomic transaction.

Atomic Save: create_bill_v2 RPC

A single PostgreSQL function that performs all of the following in one transaction. If any step fails, the entire transaction is rolled back — no partial state.

Offline Sync

When the device is offline, bills are saved locally and synced when connectivity returns. The sync mechanism uses create_bill_offline_sync RPC with client_ref idempotency.

Draft Tabs

Up to 5 concurrent drafts stored in sessionStorage. Each draft preserves:

• Selected farmer
• Added products with quantities, rates, discounts
• Payment amount and method
• Any notes

Drafts survive page refreshes within the same browser tab but not across tabs or after closing the browser.

Invoice Templates

5 invoice template designs available:

Configurable Columns

Each template supports toggling these columns on/off via Settings:

• HSN code
• Rate per unit
• Discount (% or amount)
• GST breakdown
• MRP
• Expiry date
• Signature area

Templates are branch-specific — different branches can use different templates.

PDF Generation

• Bills: html2canvas renders the invoice DOM to a canvas, converts to PNG, then embeds in a jsPDF document. This ensures the PDF matches the on-screen invoice pixel-for-pixel.
• Reports/Statements: Programmatic jsPDF — directly draws text, tables, and lines for consistent layout regardless of screen rendering.

Bill Numbering

Format: AD-{YYYYMMDD}-{sequence}

The sequence is a branch-specific auto-incrementing counter. Example: AD-20260909-042 is the 42nd bill from this branch on September 9, 2026.

Estimates

Estimates (quotations) use the same billing flow but with no side effects.

When an estimate is converted to a bill, the system creates a new bill using the estimate's items and runs the full create_bill_v2 transaction. The estimate record is updated with a reference to the new bill.

Returns

Returns handle the reversal of sold goods. The system restores stock to the original FIFO lots using LIFO (last-in-first-out) — the most recently consumed lot is refilled first.

Database Tables

• bill_returns — header: linked to original bill, return date, total return amount, reason
• bill_return_items — line items: product, quantity returned, lot references

Stock Restoration

Returns use LIFO for lot restoration. If a bill consumed 50 units from Lot A and 30 from Lot B (in that FIFO order), a return of 20 units restores to Lot B first (the last lot consumed), then Lot A if the return quantity exceeds what came from Lot B.

Excess Returns and Credit

If a return exceeds the remaining unpaid balance on the bill, the excess becomes return_credit_balance on the farmer record. This credit is automatically applied to the farmer's next bill.

Audit Trail

Every return creates inventory movement records with reference_type = 'bill_return' and reference_id pointing to the return. This ensures complete traceability of every unit in and out.

RPCs

Stock Transfers

Transfer stock between branches while preserving FIFO lot data. Each transfer creates movement records at both ends.

How It Works

What the RPC Does

• Deducts from source lot(s) using FIFO order
• Creates new lot(s) at destination with the same cost, expiry, and supplier data
• Creates inventory movement at source: type = 'transfer_out'
• Creates inventory movement at destination: type = 'transfer_in'
• Both movements reference each other via reference_id

Bill Editing

RPC: edit_bill_v1

What Can Be Edited

• Quantities (increase or decrease)
• Unit prices
• Discounts (per-item)
• Bill date
• Payment amount
• Payment type

Stock Adjustment Logic

• Quantity decreased: Stock is restored using LIFO (same as returns)
• Quantity increased: Additional stock is consumed using FIFO (same as new billing)
• Product removed: Full stock restoration for that item
• Product added: Full FIFO consumption for the new item

Audit Trail

Every edit creates a record in bill_audit_logs with:

• Before state: Complete snapshot of the bill before the edit (items, amounts, payments)
• After state: Complete snapshot after the edit
• Changed by: User/staff who made the edit
• Timestamp

The bill record itself is flagged with is_edited = true so edited bills are visually distinguished in bill history.

Bill Cancellation

RPC: cancel_bill_v1

Constraints

What Cancellation Does

1. Sets bill status = 'cancelled'
2. Restores all stock to original FIFO lots (LIFO restoration)
3. Reduces farmer outstanding balance by the bill amount
4. Creates inventory movements with reference_type = 'cancellation'
5. Records transaction event for audit

Transaction Undo

A universal undo system that covers all financial transactions in the application.

Supported Transaction Types

How It Works

• Table: transaction_events records every financial transaction with type, reference ID, timestamp, and actor
• Window: 48 hours from creation. After 48 hours, the undo option disappears.
• RPC: undo_transaction_v1
• Method: Soft-delete using deleted_at or cancelled_at timestamps rather than hard deletion. This preserves the audit trail — undone transactions are still visible but marked as undone.