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,74 @@
+# 15 — Procurement / Purchasing
+
+**Status**: Not Started
+**Depends On**: 01 — Item Catalog, 14 — Pricing & Supplier Master Data
+
+---
+
+## Goal
+
+Covers [mainPlan.md §9](./mainPlan.md#9-procurement--purchasing) in full
+— an entirely new subsystem, nothing in this area exists in the current schema.
+
+---
+
+## Background / Context
+
+Inbound stock (`createGoodsReceipt` in [04_loading_event.md](./04_loading_event.md)/
+[mainPlan.md §6](./mainPlan.md#6-warehouse-management)) currently has no
+purchase order to receive against — this step is what creates that PO in the first place.
+
+---
+
+## Data Model Changes
+
+### Purchase Requisition
+
+`RequestedByUserId`, `Status` (`Draft`, `Submitted`, `Approved`, `Rejected`), line items
+(`ItemId`, `Quantity`).
+
+### Purchase Order
+
+`SupplierId`, `RequisitionId` (nullable — a PO can be raised without a prior requisition), `Status`
+(`Issued`, `PartiallyReceived`, `Received`, `Closed`), line items (`ItemId`, `Quantity`, `UnitCost`).
+
+### Purchase Return
+
+`PurchaseOrderId`, reason, line items — goods sent back to the supplier post-receipt.
+
+---
+
+## API Endpoints
+
+| Function reference | Endpoint intent |
+|---|---|
+| `createPurchaseRequisition(items[], requestedBy)` | `POST /api/purchase-requisitions` |
+| `createPurchaseOrder(supplierId, items[])` | `POST /api/purchase-orders` |
+| `matchInvoiceToPO(invoiceId, poId, grnId)` | `POST /api/purchase-orders/{id}/match-invoice` |
+| `evaluateSupplier(supplierId, criteria)` | `POST /api/suppliers/{id}/evaluate` |
+| `createPurchaseReturn(poId, items[], reason)` | `POST /api/purchase-orders/{id}/returns` |
+
+---
+
+## Business Rules
+
+- `createGoodsReceipt` (§6, [04_loading_event.md](./04_loading_event.md)'s warehouse-inbound
+  counterpart) must reference an `Issued`/`PartiallyReceived` Purchase Order — no receipts against
+  a closed or nonexistent PO.
+- `matchInvoiceToPO` (3-way match) must block payment posting in
+  [19_finance_accounting.md](./19_finance_accounting.md) until PO, GRN, and invoice quantities/
+  amounts reconcile within a configurable tolerance.
+
+---
+
+## Open Questions
+
+- Is procurement in scope for this project at all right now, or is inbound stock assumed to be
+  seeded/manual for the foreseeable future? Confirm before investing in this step — it's the
+  largest net-new subsystem in the reference doc.
+
+---
+
+## Implementation Notes
+
+> Fill this section in during planning discussion before writing any code.