# 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.