# PurchaseOrderRevision

## Description

PurchaseOrderRevision is the envelope record for one amendment event on a `PurchaseOrder`. Each row corresponds to one amendment: the first amendment creates revisionNumber 1, and each subsequent amendment increments by one. Approval itself does not create an envelope — an order that has never been amended has zero envelopes, and the current revision count is derived from `MAX(revisionNumber)` of the attached envelopes (or 0 when none exist). The envelope holds amendment-level metadata that is independent of which fields changed — currently the amendment author, reason, and timestamps; aggregate values like total amount are intentionally not stored because they are derivable from line state and the field-change history.

The detailed per-field changes belonging to each envelope live in `PurchaseOrderFieldChange`, joined by `revisionId`. Together the two tables form the audit trail of all post-approval modifications to the order.

## Domain Model Definitions

### Model type

AppendOnly

### Command Definitions

None — envelope rows are created exclusively as a side effect of [amendOrderedPurchaseOrder](../command/AmendOrderedPurchaseOrder.md). They have no dedicated commands.

### Query Definitions

None — no dedicated query exists; envelopes are reachable via the `revisions` backward relation on PurchaseOrder.

### Models

- PurchaseOrderRevision

### Invariants

- Each revision belongs to exactly one purchase order
- `amendedByUserId` records the user who initiated the amendment and is optional for backward compatibility with rows written before the field existed
- `revisionNumber` is sequential per `purchaseOrderId`, starting at 1 on the first amendment and incrementing by 1 for each subsequent amendment; the pair (`purchaseOrderId`, `revisionNumber`) is unique
- The first envelope is created by the first call to `amendOrderedPurchaseOrder`; approval does not create an envelope
- Each envelope has at least one attached `PurchaseOrderFieldChange` row (an empty amendment is rejected at the command layer)
- Envelope rows are immutable once written

### Relationships

- **Belongs To PurchaseOrder**: Each envelope references one [PurchaseOrder](./PurchaseOrder.md) via `purchaseOrderId`
- **Amended By User**: Each envelope optionally references the [User](../../../user-management/docs/model/User.md) who initiated the amendment via `amendedByUserId`
- **Has Many PurchaseOrderFieldChanges**: Each envelope has one or more child [PurchaseOrderFieldChange](./PurchaseOrderFieldChange.md) rows describing the modified header / line fields