19 — Finance & Accounting

Status: Not Started Depends On: 05 — Delivery Ride Execution, 06 — Sale Ride Execution, 18 — Returns & Claims Management

Goal

Covers mainPlan.md §13 beyond what 06_sale_ride.md already scoped for field invoices (createInvoice/recordPayment there are the van-sale-specific case; this step is the general warehouse-fulfilled-order invoicing path plus GL posting and reporting).

Background / Context

convertOrderToInvoice is referenced from 05_delivery_ride.md but has no home until this step. There is no invoice, payment, or GL entity for warehouse-fulfilled (non-field-sale) orders today.

Data Model Changes

Invoice

OrderId (nullable if it originates from a field invoice instead), StoreId, TotalAmount, TaxAmount, Status (Issued, PartiallyPaid, Paid), IssuedAt.

Payment

InvoiceId, Amount, Method, CollectedAt — same shape as the Payment Record in 06_sale_ride.md; consider whether to unify into one table keyed by a generic InvoiceId covering both field invoices and warehouse invoices.

GL Posting

TransactionId, Account, DebitAmount, CreditAmount, PostedAt.

API Endpoints

Function reference	Endpoint intent
`createInvoice(orderId)`	`POST /api/orders/{id}/invoice` — the warehouse-fulfilled counterpart to 06_sale_ride.md's field invoice creation
`recordPayment(invoiceId, amount, method)`	`POST /api/invoices/{id}/payments`
`postToGeneralLedger(transactionId)`	Internal — triggered on invoice/payment/credit-note events
`generateTaxInvoice(invoiceId, jurisdiction)`	`GET /api/invoices/{id}/tax-invoice?jurisdiction=...`
`getFinancialReport(entityId, period, reportType)`	`GET /api/finance/reports?entityId=...&period=...&reportType=...`

Business Rules

Store.OutstandingBalance (from 12_store_management.md) is maintained by this step's invoice/payment events, not edited directly.
postToGeneralLedger must be idempotent per TransactionId — replays must not double-post.

Open Questions

Should field invoices (06_sale_ride.md) and warehouse invoices share one Invoice table, or stay as separate entities that both feed the same GL posting logic?
Is e-invoicing (generateTaxInvoice for a specific jurisdiction like GST/VAT) an actual near-term requirement, or speculative until a specific market is targeted?

Implementation Notes

Fill this section in during planning discussion before writing any code.

2.7 KiB Raw Permalink Blame History