15 — Procurement / Purchasing

Status: Not Started Depends On: 01 — Item Catalog, 14 — Pricing & Supplier Master Data

Goal

Covers mainPlan.md §9 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/ mainPlan.md §6) 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'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 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.

2.4 KiB Raw Blame History