Add md file features in region, route, store, fleet, pricing, procurement, SFA, promotions, returns, finance, reporting, notifications, integration, and mobile capabilities

2026-08-19 15:18:31 +05:30
parent 45f374133f
commit d2390e7b12
25 changed files with 1565 additions and 88 deletions
@@ -0,0 +1,75 @@
+# 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](./mainPlan.md#13-finance--accounting) beyond
+what [06_sale_ride.md](./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](./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](./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](./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](./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](./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.