# Purchasing / Goods Receipt Foundation v25

## Scope

v25 introduces the first Purchasing domain boundary:

- suppliers
- draft goods receipts
- receipt lines
- posting goods receipts into Inventory
- supplier acquisition cost flowing into weighted-average valuation

This is intentionally smaller than the full purchasing lifecycle.

## Supplier

A supplier is tenant-scoped master data.

Initial fields:
- code
- name
- tax number
- phone
- email
- active/inactive status
- metadata

## Goods receipt lifecycle

A goods receipt begins in `draft`.

Draft receipts can accept lines.

Posting is final for this foundation:
- status -> posted
- received_at captured
- business_date captured
- inventory movements generated

Posted receipts cannot be edited.

## Receipt line

Each line stores:
- variant
- optional variant unit
- optional lot
- received quantity
- supplier unit cost
- line total cost

The line total is validated by PostgreSQL.

## Inventory integration

Posting a receipt generates `purchase_receipt` movements.

The Inventory ledger receives the supplier unit cost through `unitCostAmount`.

This updates:
- quantity balance
- inventory value
- weighted-average cost
- optional lot balance

Example:

Opening:
10 units @ 5

Second receipt:
10 units @ 7

Result:
20 units
inventory value 120
weighted average 6

## Idempotency

Goods receipt creation is tenant-scoped idempotent.

Inventory posting is additionally protected by the immutable ledger source identity:
- source_type = goods_receipt
- source_public_id = receipt
- source_line_public_id = receipt line

Posting the same receipt again cannot duplicate stock.

## APIs

Suppliers:
- GET  /api/v1/purchasing/suppliers
- POST /api/v1/purchasing/suppliers

Goods receipts:
- POST /api/v1/purchasing/goods-receipts
- GET  /api/v1/purchasing/goods-receipts/{receiptId}
- POST /api/v1/purchasing/goods-receipts/{receiptId}/lines
- POST /api/v1/purchasing/goods-receipts/{receiptId}/post

## Permissions

- purchasing.supplier.view
- purchasing.supplier.manage
- purchasing.receipt.view
- purchasing.receipt.manage
- purchasing.receipt.post

## Next

v26:
- Purchase Orders
- PO lines
- ordered vs received quantities
- partial receipts
- receipt linkage to PO
- foundation for 3-way match