# SalesOrderRevision

## Description

SalesOrderRevision is the envelope record for one amendment event on a `SalesOrder`. Each row corresponds to one amendment: the first amendment creates revisionNumber 1, and each subsequent amendment increments by one. Confirmation 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 `SalesOrderFieldChange`, joined by `revisionId`. Together the two tables form the audit trail of all post-confirmation modifications to the order.

## Domain Model Definitions

### Model type

AppendOnly

### Command Definitions

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

### Query Definitions

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

### Models

- SalesOrderRevision

### Invariants

- Each revision belongs to exactly one sales 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 `salesOrderId`, starting at 1 on the first amendment and incrementing by 1 for each subsequent amendment; the pair (`salesOrderId`, `revisionNumber`) is unique
- The first envelope is created by the first call to `amendConfirmedSalesOrder`; confirmation does not create an envelope
- Each envelope has at least one attached `SalesOrderFieldChange` row (an empty amendment is rejected at the command layer)
- Envelope rows are immutable once written

### Relationships

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