Kalana B. Thilakarathna
2.8 KiB
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) |
Current implemented path is POST /api/sales/{saleId:guid}/payments for field-sale collections; POST /api/invoices/{id}/payments remains the target endpoint for this future invoice-based finance step |
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.postToGeneralLedgermust be idempotent perTransactionId— replays must not double-post.
Open Questions
- Should field invoices (06_sale_ride.md) and warehouse invoices share one
Invoicetable, or stay as separate entities that both feed the same GL posting logic? - Is e-invoicing (
generateTaxInvoicefor 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.